Workato Connector SDK

https://github.com/workato/custom_connector_docs
Admin
Workato Connector SDK is a Ruby-based framework that allows developers to build custom application...
Tokens:40,199
Snippets:473
Trust Score:8.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Webhook Trigger Implementation Example

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/triggers.md

A complete example demonstrating how to define a webhook trigger with subscription, unsubscription, notification handling, and output field definitions.

```ruby
new_message: {
  type: :paging_desc,

  input_fields: lambda do
    [
      { name: 'room_id', optional: false }
    ]
  end,

  poll: lambda do |connection, input|
    # Fallback for webhook-only trigger
    { events: [] }
  end,

  webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
    post("https://api.example.com/webhooks").
      payload(
        name: "Workato recipe #{recipe_id}",
        target_url: webhook_url,
        resource: 'messages',
        event: 'created',
        filter: "room_id=#{input['room_id']}"
      )
  end,

  webhook_unsubscribe: lambda do |webhook|
    delete("https://api.example.com/webhooks/#{webhook['id']}")
  end,

  webhook_notification: lambda do |input, payload|
    payload['data']
  end,

  dedup: lambda do |message|
    message['id']
  end,

  output_fields: lambda do
    [
      { name: 'id', type: 'integer' },
      { name: 'room_id', type: 'integer' },
      { name: 'text' },
      { name: 'user', type: 'object', properties: [
        { name: 'id', type: 'integer' },
        { name: 'name' }
      ]},
      { name: 'created_at', type: 'datetime' }
    ]
  end
}
```

--------------------------------

### Connection Fields Configuration

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/connection-definition.md

Examples of defining input fields for user authentication.

```ruby
connection: {
  fields: [
    {
      name: 'subdomain',
      control_type: 'subdomain',
      url: '.harvestapp.com',
      hint: 'The subdomain found in your Harvest URL'
    },
    {
      name: 'username',
      label: 'Username'
    },
    {
      name: 'password',
      control_type: 'password'
    }
  ]
}
```

```ruby
connection: {
  fields: [
    {
      name: 'api_key',
      control_type: 'password',
      optional: false,
      hint: 'Available in account settings'
    }
  ]
}
```

--------------------------------

### SDK method usage examples

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Commonly used SDK methods for data manipulation and request configuration.

```ruby
[1, 2, 3].each { |i| puts i }
```

```ruby
.headers(Authorization: "Bearer HTB674HJK1")
```

```ruby
.params(api_key: "HTB674HJK1")
```

```ruby
.payload(id: "345")
```

```ruby
object_definition["user"].ignored("id", "created_at")
```

```ruby
object_definition["user"].only("id", "name")
```

```ruby
object_definition["user"].required("id", "created_at")
```

```ruby
[{"id": 1, "name": "David"},{"id": 2, "name": "Peter"}].pluck("id")
```

--------------------------------

### Define a Full Featured Connector

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

A complete example demonstrating the structure of a connector including connection, object definitions, actions, and triggers.

```ruby
{
  title: 'Full Featured App',

  connection: {
    fields: [
      {
        name: 'subdomain',
        control_type: 'subdomain',
        url: '.api.example.com',
        optional: false
      },
      {
        name: 'api_key',
        control_type: 'password',
        optional: false
      }
    ],

    authorization: {
      type: 'api_key',
      credentials: lambda do |connection|
        params(api_key: connection['api_key'])
      end
    },

    base_uri: lambda do
      'https://api.example.com/v2'
    end
  },

  object_definitions: {
    user: {
      fields: lambda do |connection|
        [
          { name: 'id', type: 'integer' },
          { name: 'name' },
          { name: 'email', control_type: 'email' },
          { name: 'role' },
          { name: 'created_at', type: 'datetime' },
          { name: 'updated_at', type: 'datetime' }
        ]
      end
    }
  },

  pick_lists: {
    roles: lambda do |connection|
      [
        ['Admin', 'admin'],
        ['User', 'user'],
        ['Guest', 'guest']
      ]
    end
  },

  test: lambda do |connection|
    get("https://#{connection['subdomain']}.api.example.com/account")
  end,

  methods: {
    parse_timestamp: lambda do |timestamp|
      Time.parse(timestamp).iso8601
    end
  },

  actions: {
    create_user: {
      input_fields: lambda do |object_definitions|
        [
          { name: 'name', optional: false },
          { name: 'email', control_type: 'email', optional: false },
          { name: 'role', control_type: 'select', pick_list: 'roles' }
        ]
      end,

      execute: lambda do |connection, input|
        post("https://api.example.com/users").
          payload(
            name: input['name'],
            email: input['email'],
            role: input['role']
          )
      end,

      output_fields: lambda do |object_definitions|
        object_definitions['user']
      end
    },

    list_users: {
      execute: lambda do |connection, input|
        users = get("https://api.example.com/users")
        { users: users }
      end,

      output_fields: lambda do |object_definitions|
        [
          {
            name: 'users',
            type: 'array',
            of: 'object',
            properties: object_definitions['user']
          }
        ]
      end
    }
  },

  triggers: {
    new_user: {
      input_fields: lambda do
        [
          {
            name: 'since',
            type: 'timestamp',
            optional: false
          }
        ]
      end,

      poll: lambda do |connection, input, last_updated_since|
        since = last_updated_since || input['since']
        
        users = get("https://api.example.com/users").
                params(created_since: since.to_time.iso8601, limit: 100)

        {
          events: users,
          next_poll: users.last['created_at'] unless users.empty?,
          can_poll_more: users.length >= 100
        }
      end,

      dedup: lambda do |user|
        user['id']
      end,

      output_fields: lambda do |object_definitions|
        object_definitions['user']
      end
    }
  }
}
```

--------------------------------

### Example API Response Structure

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Sample JSON response format for a descending order API request.

```json
{
  "current": "https://api.sample.com/records?order=desc&from=2016-12-09T22%3A57%3A13Z&page=1",
  "next": "https://api.sample.com/records?order=desc&from=2016-12-09T22%3A57%3A13Z&page=2",
  "data: [
    {
      "checkid": 123,
      "time": "2016-12-13T19:09:01Z",
      ...
    },
    {
      "checkid": 124,
      "time": "2016-12-10T06:20:00Z",
      ...
    }
  ]
}
```

--------------------------------

### Implement Basic Authentication Variations

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Examples of adapting basic authentication for APIs that require specific credential formats like API keys as usernames.

```ruby
connection: {
  fields: [
    {
      name: "api_key",
      optional: false,
      hint: "Profile (top right) > Settings > Your API Keys"
    }
  ],

  authorization: {
    type: "basic_auth",

    # close.io uses api key only for authentication. treats apikey as username and password left blank
    # curl -u "{your api_key}:" "https://app.close.io/api/v1/me/"
    credentials: lambda do |connection|
      user(connection["api_key"])
      password("")
    end
  }
}
```

```ruby
connection: {

  fields: [
    {
      name: "api_token",
      control_type: "password",
      label: "API token",
      optional: false,
      hint: "Available in 'My Profile' page"
    }
  ],

  authorization: {
    type: "basic_auth",

    # Toggl API expect the token to be sent as user name and the string 'api_token' as the password
    # curl -u "{your api_token}:api_token" "https://www.toggl.com/api/v8/me"
    credentials: lambda do |connection|
      user(connection["api_token"])
      password("api_token")
    end
  }
}
```

--------------------------------

### Implement a Classic Trigger with Timestamp Cursor

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/triggers.md

A complete example of a classic trigger using a timestamp-based cursor for pagination.

```ruby
new_ticket: {
  input_fields: lambda do
    [
      {
        name: 'since',
        type: 'timestamp',
        optional: false,
        hint: 'Pull tickets updated after this time'
      }
    ]
  end,

  poll: lambda do |connection, input, last_updated_since|
    page_size = 100
    updated_since = (last_updated_since || input['since']).to_time.utc.iso8601

    tickets = get("https://#{connection['helpdesk']}.freshdesk.com/api/v2/tickets.json").
              params(
                order_by: 'updated_at',
                order_type: 'asc',
                per_page: page_size,
                updated_since: updated_since
              )

    next_updated_since = tickets.last['updated_at'] unless tickets.blank?

    {
      events: tickets,
      next_poll: next_updated_since,
      can_poll_more: tickets.length >= page_size
    }
  end,

  dedup: lambda do |ticket|
    ticket['id']
  end,

  output_fields: lambda do |object_definitions|
    [
      { name: 'id', type: 'integer' },
      { name: 'subject' },
      { name: 'status' },
      { name: 'created_at', type: 'datetime' },
      { name: 'updated_at', type: 'datetime' }
    ]
  end
}
```

--------------------------------

### HTTP Query Parameters Definition

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Demonstrates how to define query parameters for GET operations using the connector SDK.

```APIDOC
## GET Query Parameters

### Description
Defines the query parameters appended to a GET request URL.

### Code Example
```ruby
execute: lambda do |connection, input|
  get("https://api.example.com/users").
    params(
      limit: input['limit'],
      offset: input['offset'],
      sort_by: 'created_at'
    )
end
```
```

--------------------------------

### Define a basic GET action

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Defines a simple action that retrieves a lead by ID from the Close.io API.

```ruby
actions: {

  get_lead_by_id: {

    input_fields: lambda do
      [
        { name: "lead_id", optional: false }
      ]
    end,

    execute: lambda do |connection, input|
      get("https://app.close.io/api/v1/lead/#{input["lead_id"]}/")
    end,

    output_fields: lambda do |object_definitions|
      object_definitions["lead"]
    end
  }
}
```

--------------------------------

### Defining Trigger Cursors

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Examples of standard pagination cursor formats for triggers.

```ruby
next_poll: "2024-01-15T15:30:00Z"  # Usually a timestamp
```

```ruby
next_page: 2  # Usually a page number
```

--------------------------------

### Perform GET requests

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/methods-and-helpers.md

Retrieve data from an endpoint using the get method, optionally including parameters or headers.

```ruby
execute: lambda do |connection, input|
  get("https://api.example.com/users/#{input['user_id']}")
end
```

```ruby
get("https://api.example.com/users").
  params(limit: 50, offset: 0, sort: 'name')
```

```ruby
get("https://api.example.com/users").
  headers(Authorization: "Bearer #{connection['token']}")
```

--------------------------------

### Classic Trigger Implementation

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

A complete example of a classic trigger definition including input fields, polling logic, deduplication, and output fields.

```ruby
updated_ticket: {
  input_fields: lambda do
    [
      {
        name: 'since',
        type: :timestamp,
        optional: false
      }
    ]
  end,

  poll: lambda do |connection, input, last_updated_since|
    page_size = 100
    updated_since = (last_updated_since || input['since']).to_time.utc.iso8601

    tickets = get("https://#{connection['helpdesk']}.freshdesk.com/api/v2/tickets.json").
              params(order_by: 'updated_at',
                     order_type: 'asc',
                     per_page: page_size,
                     updated_since: updated_since)

    next_updated_since = tickets.last['updated_at'] unless tickets.blank?

    {
      events: tickets,
      next_poll: next_updated_since,
      can_poll_more: tickets.length >= page_size
    }
  end,

  dedup: lambda do |ticket|
    ticket['id']
  end,

  output_fields: lambda do |object_definitions|
    object_definitions['ticket']
  end
}
```

--------------------------------

### Descending Trigger with Pagination Example

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/triggers.md

A complete implementation of a descending trigger, including input fields, poll logic, document identification, and sorting.

```ruby
new_alert: {
  type: :paging_desc,

  input_fields: lambda do
    [
      {
        name: 'since',
        type: 'timestamp',
        optional: false,
        hint: 'Pull alerts created after this time'
      }
    ]
  end,

  poll: lambda do |connection, input, page|
    limit = 100
    page ||= 0
    created_since = (input['since'] || Time.now).to_i
    offset = limit * page

    response = get("https://api.example.com/alerts").
               params(
                 from: created_since,
                 limit: limit,
                 offset: offset
               )

    {
      events: response['data'],
      next_page: (response['data'].length >= limit) ? page + 1 : nil
    }
  end,

  document_id: lambda do |alert|
    alert['check_id']
  end,

  sort_by: lambda do |alert|
    alert['created_at']  # Must be in descending order
  end,

  output_fields: lambda do
    [
      { name: 'check_id', type: 'integer' },
      { name: 'name' },
      { name: 'status' },
      { name: 'created_at', type: 'datetime' }
    ]
  end
}
```

--------------------------------

### Example JSON Response

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Sample JSON structure returned by the API during a poll request.

```ruby
[
  {
    "id": 1,
    "updated_at": "2016-08-13T00:53:44Z"
  },
  {
    "id": 2,
    "updated_at": "2016-09-14T02:25:00Z"
  },
  ...
]
```

--------------------------------

### Search Action Pattern

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Implements a search action with input parameters, an HTTP GET request, and a structured array output.

```ruby
search_users: {
  input_fields: lambda do
    [
      { name: 'name', optional: false },
      { name: 'limit', type: 'integer', optional: true }
    ]
  end,
  
  execute: lambda do |connection, input|
    results = get("https://api.example.com/users").
              params(q: input['name'], limit: input['limit'] || 10)
    { results: results }
  end,
  
  output_fields: lambda do
    [
      {
        name: 'results',
        type: 'array',
        of: 'object',
        properties: [
          { name: 'id', type: 'integer' },
          { name: 'name' },
          { name: 'email' }
        ]
      }
    ]
  end
}
```

--------------------------------

### Define Query Parameters for GET

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Uses the get method to append query parameters to the request URL based on input values.

```ruby
execute: lambda do |connection, input|
  get("https://api.example.com/users").
    params(
      limit: input['limit'],
      offset: input['offset'],
      sort_by: 'created_at'
    )
end
```

--------------------------------

### Add GET request parameters

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Appends search parameters to a GET request URL.

```ruby
execute: lambda do |connection, input|
  {
    'companies': get("https://#{connection['deployment']}.api.accelo.com/api/v0/companies.json").
                 params(_search: input["company_name"])["response"]
  }
end
```

--------------------------------

### Validate Credentials in Workato Connectors

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Use the test block to verify credentials immediately upon connection setup.

```ruby
test: lambda do |connection|
  response = get("https://api.example.com/account")
  
  # Return truthy value to indicate success
  response.present? && response['id'].present?
end
```

--------------------------------

### Add query parameters

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/methods-and-helpers.md

Use the params method to add query string parameters to GET requests.

```ruby
get("https://api.example.com/search").
  params(
    q: 'example',
    limit: 100,
    offset: 0
  )
```

--------------------------------

### Define Connection Test Endpoints

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Use a lambda function to perform a simple GET request that verifies connection success.

```ruby
test: lambda do |connection|
  get("https://person.clearbit.com/v1/people/email/eeshansim@gmail.com")
end
```

```ruby
test: lambda do |connection|
  get("https://app.clicktime.com/api/1.3/session")
end
```

--------------------------------

### Define a field object structure

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Example of a field definition using a Ruby hash, specifying type, control, and validation properties.

```ruby
{
  name: 'user_id',
  type: :integer,
  label: 'User ID',
  hint: 'The numeric ID of the user',
  control_type: 'number',
  optional: false,
  pick_list: 'users'
}
```

--------------------------------

### Dedup Block Variants

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Examples of deduplication logic, including a simple ID-based check and a timestamp-appended check for updated records.

```ruby
dedup: lambda do |ticket|
  ticket["id"]
end
```

```ruby
dedup: lambda do |ticket|
  ticket["id"] + "@" + ticket["`updated_at"]
end
```

--------------------------------

### GET /users/{id}

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/endpoints-reference.md

Retrieves user data from the specified endpoint.

```APIDOC
## GET /users/{id}

### Description
Retrieve data from an endpoint.

### Method
GET

### Endpoint
https://api.example.com/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.
```

--------------------------------

### Use Consistent Naming Conventions

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Maintain uniform action naming to improve connector usability and predictability.

```ruby
# ✓ Consistent
actions: {
  create_user: { ... },
  update_user: { ... },
  delete_user: { ... }
}

# ✗ Inconsistent
actions: {
  new_user: { ... },
  update_user: { ... },
  remove_user: { ... }
}
```

--------------------------------

### Object Definitions

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Demonstrates how to reference predefined object schemas to define output fields.

```APIDOC
## Output Object Definitions

### Description
Uses predefined object schemas to structure the output fields of an action.

### Code Example
```ruby
output_fields: lambda do |object_definitions|
  [
    {
      name: 'user',
      type: 'object',
      properties: object_definitions['user']
    }
  ]
end
```
```

--------------------------------

### Configure Authorization Credentials

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Sets up authentication headers, such as OAuth access tokens.

```ruby
credentials: lambda do |connection, access_token|
  # For OAuth, access_token is provided
  headers(Authorization: "Bearer #{access_token}")
end
```

--------------------------------

### Add Clear Labels and Hints

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Provide descriptive labels and hints for input fields to improve user experience.

```ruby
input_fields: lambda do
  [
    {
      name: 'account_id',
      label: 'Account ID',
      hint: 'Numeric identifier, not email. Found in Settings > Account',
      optional: false
    }
  ]
end
```

--------------------------------

### Implement API Key as Username

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Configures basic authentication by passing the API key as the username and an empty string as the password.

```ruby
connection: {
  fields: [
    {
      name: 'api_key',
      optional: false,
      hint: 'Your API key from settings'
    }
  ],

  authorization: {
    type: 'basic_auth',
    credentials: lambda do |connection|
      user(connection['api_key'])
      password("")
    end
  }
}
```

```ruby
credentials: lambda do |connection|
  user(connection['api_key'])
  password("")
end
# curl -u "api_key:" https://app.close.io/api/v1/lead/
```

--------------------------------

### Create Pick List

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Returns an array of [display, value] pairs for dropdown selection fields.

```ruby
pick_list_name: lambda do |connection, config_fields|
  # Returns array of [display, value] pairs
  [
    ['Option 1', 'opt1'],
    ['Option 2', 'opt2']
  ]
end
```

--------------------------------

### POST /users

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/endpoints-reference.md

Creates a new user resource.

```APIDOC
## POST /users

### Description
Create a new resource.

### Method
POST

### Endpoint
https://api.example.com/users

### Request Body
- **name** (string) - Required - The name of the user.
- **email** (string) - Required - The email address of the user.

### Request Example
{
  "name": "John Doe",
  "email": "john@example.com"
}
```

--------------------------------

### Configure OAuth 2.0 with Refresh Token

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Sets up OAuth 2.0 flow including authorization/token URLs and automatic token refresh logic on 401 errors.

```ruby
connection: {
  fields: [
    {
      name: 'client_id',
      optional: false
    },
    {
      name: 'client_secret',
      optional: false,
      control_type: 'password'
    }
  ],

  authorization: {
    type: 'oauth2',

    authorization_url: lambda do |connection|
      'https://oauth.example.com/authorize'
    end,

    token_url: lambda do |connection|
      'https://oauth.example.com/token'
    end,

    client_id: 'your_client_id',
    client_secret: 'your_client_secret',

    credentials: lambda do |connection, access_token|
      headers(Authorization: "Bearer #{access_token}")
    end,

    refresh_on: [401],
    detect_on: [/invalid_token/]
  }
}
```

--------------------------------

### Implement Dependent Pick Lists

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Return an empty array if prerequisite configuration fields are missing to handle dependencies gracefully.

```ruby
pick_lists: {
  projects: lambda do |connection, config_fields|
    # Return empty if prerequisite missing
    return [] if config_fields.blank? || config_fields['workspace_id'].blank?
    
    get("https://api.example.com/workspaces/#{config_fields['workspace_id']}/projects").
      map { |proj| [proj['name'], proj['id']] }
  end
}
```

--------------------------------

### Custom API Key Parameter Name

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Demonstrates how to map the API key to a custom parameter name instead of the default.

```ruby
authorization: {
  type: 'api_key',
  credentials: lambda do |connection|
    params(key: connection['api_key'])  # Uses 'key' instead of 'api_key'
  end
}
```

--------------------------------

### Create Action Pattern

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Implements a create action using an HTTP POST request to send payload data.

```ruby
create_user: {
  input_fields: lambda do
    [
      { name: 'name', optional: false },
      { name: 'email', control_type: 'email', optional: false },
      { name: 'role' }
    ]
  end,
  
  execute: lambda do |connection, input|
    post("https://api.example.com/users").
      payload(
        name: input['name'],
        email: input['email'],
        role: input['role']
      )
  end,
  
  output_fields: lambda do
    [
      { name: 'id', type: 'integer' },
      { name: 'name' },
      { name: 'email' },
      { name: 'created_at', type: 'datetime' }
    ]
  end
}
```

--------------------------------

### Implement Search Action with Pagination

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/common-patterns.md

Defines input fields for query parameters and handles pagination logic using limit and offset. Returns a structured object containing records, total count, and a boolean flag for further pages.

```ruby
search_records: {
  input_fields: lambda do
    [
      { name: 'query', optional: false, hint: 'Search term' },
      { name: 'limit', type: 'integer', optional: true, hint: 'Max results (default 50)' },
      { name: 'offset', type: 'integer', optional: true, hint: 'Offset for pagination' }
    ]
  end,

  execute: lambda do |connection, input|
    limit = input['limit'] || 50
    offset = input['offset'] || 0

    results = get("https://api.example.com/search").
              params(
                q: input['query'],
                limit: limit,
                offset: offset
              )

    {
      records: results['data'],
      total: results['meta']['total'],
      has_more: (offset + limit) < results['meta']['total']
    }
  end,

  output_fields: lambda do
    [
      {
        name: 'records',
        type: 'array',
        of: 'object',
        properties: [
          { name: 'id', type: 'integer' },
          { name: 'name' },
          { name: 'email' },
          { name: 'created_at', type: 'datetime' }
        ]
      },
      { name: 'total', type: 'integer' },
      { name: 'has_more', type: 'boolean' }
    ]
  end
}
```

--------------------------------

### Connector Project File Structure

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/README.md

The standard directory layout for a Workato custom connector project.

```text
output/
├── README.md                        (this file)
├── overview.md                      (project overview)
├── quick-reference.md               (syntax cheat sheet)
├── types.md                         (data types reference)
├── configuration.md                 (connector structure)
├── authentication-patterns.md       (auth examples)
├── common-patterns.md               (real-world patterns)
├── best-practices.md                (development guidelines)
├── endpoints-reference.md           (HTTP request reference)
└── api-reference/
    ├── connection-definition.md     (connection setup)
    ├── actions.md                   (action definitions)
    ├── triggers.md                  (trigger types)
    ├── object-definitions.md        (data schemas)
    ├── pick-lists.md                (dropdown options)
    └── methods-and-helpers.md       (utilities & methods)
```

--------------------------------

### Define a Simple Search Action

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Implements a basic search action with static input and output field definitions.

```ruby
search_users: {
  input_fields: lambda do
    [
      { name: 'query', optional: false }
    ]
  end,

  execute: lambda do |connection, input|
    results = get("https://api.example.com/users/search").
              params(q: input['query'])
    { results: results }
  end,

  output_fields: lambda do
    [
      {
        name: 'results',
        type: 'array',
        of: 'object',
        properties: [
          { name: 'id', type: 'integer' },
          { name: 'name' },
          { name: 'email' }
        ]
      }
    ]
  end
}
```

--------------------------------

### Implement Pick Lists in Actions

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/pick-lists.md

Reference defined pick lists within action configuration fields to enable dropdown selection for users.

```ruby
actions: {
  create_task: {
    config_fields: [
      {
        name: 'workspace_id',
        label: 'Workspace',
        control_type: 'select',
        pick_list: 'workspaces',
        optional: false
      },
      {
        name: 'project_id',
        label: 'Project',
        control_type: 'select',
        pick_list: 'projects',
        optional: false
      }
    ],
    
    input_fields: lambda do |object_definitions, config_fields|
      [
        { name: 'title', optional: false },
        { name: 'description' }
      ]
    end
  }
}
```

--------------------------------

### Define a minimal connector structure

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Provides a basic template for a connector including authentication, a test lambda, and a single action with output fields.

```ruby
{
  title: 'Example App',

  connection: {
    fields: [
      {
        name: 'api_key',
        optional: false,
        control_type: 'password'
      }
    ],

    authorization: {
      type: 'api_key',
      credentials: lambda do |connection|
        params(api_key: connection['api_key'])
      end
    }
  },

  test: lambda do |connection|
    get("https://api.example.com/me")
  },

  actions: {
    list_users: {
      execute: lambda do |connection, input|
        { users: get("https://api.example.com/users") }
      end,

      output_fields: lambda do |object_definitions|
        [
          {
            name: 'users',
            type: 'array',
            of: 'object',
            properties: [
              { name: 'id', type: 'integer' },
              { name: 'name' },
              { name: 'email' }
            ]
          }
        ]
      end
    }
  }
}
```

--------------------------------

### Configure Basic Auth with Subdomain

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Uses a subdomain control type to construct the base URL and standard basic authentication credentials.

```ruby
connection: {
  fields: [
    {
      name: 'subdomain',
      control_type: 'subdomain',
      url: '.harvestapp.com',
      hint: 'Your subdomain from Harvest URL'
    },
    {
      name: 'username'
    },
    {
      name: 'password',
      control_type: 'password'
    }
  ],

  authorization: {
    type: 'basic_auth',
    credentials: lambda do |connection|
      user(connection['username'])
      password(connection['password'])
    end
  }
}
```

--------------------------------

### Configure API Key Authentication

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Implements simple API key authentication by passing the key as a parameter.

```ruby
connection: {
  fields: [
    {
      name: 'api_key',
      control_type: 'password',
      optional: false
    }
  ],

  authorization: {
    type: 'api_key',
    credentials: lambda do |connection|
      params(api_key: connection['api_key'])
    end
  }
}
```

--------------------------------

### Use Descriptive API Parameters

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Use clear, descriptive names for API parameters to improve code readability and maintainability.

```ruby
# ✓ Clear intent
get("https://api.example.com/users").
  params(
    limit: 50,
    offset: page * 50,
    sort_by: 'created_at'
  )

# ✗ Unclear
get("https://api.example.com/users").
  params(l: 50, o: page, s: 'created_at')
```

--------------------------------

### Execute Action Logic

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Handles the core execution logic for an action, receiving connection credentials and user input.

```ruby
execute: lambda do |connection, input|
  # connection — user's connection credentials hash
  # input — user's input values hash
  { /* return hash */ }
end
```

--------------------------------

### Define Action Structure

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/quick-reference.md

Implement connector actions by defining input fields, execution logic, and output schema.

```ruby
action_name: {
  input_fields: lambda do |obj_def|
    [{ name: 'param' }]
  end,

  execute: lambda do |connection, input|
    # Make API call and return hash
    { result: data }
  end,

  output_fields: lambda do |obj_def|
    [{ name: 'result' }]
  end
}
```

--------------------------------

### Implement Offset-Limit Pagination

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/endpoints-reference.md

Use this pattern for APIs that require offset and limit parameters to navigate result sets.

```ruby
params(
  limit: 50,
  offset: page * 50
)
```

--------------------------------

### Define and Call Helper Methods

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/quick-reference.md

Define reusable logic in the methods block and invoke them using the call method.

```ruby
methods: {
  format_timestamp: lambda do |ts|
    Time.parse(ts).iso8601
  end,
  
  build_url: lambda do |path|
    "https://api.example.com/#{path}"
  end
}

# Usage
call('format_timestamp', input['date'])
call('build_url', 'users')
```

--------------------------------

### Basic Authentication Configuration

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/connection-definition.md

Configures Basic Auth and its common credential variations.

```ruby
authorization: {
  type: 'basic_auth',
  credentials: lambda do |connection|
    user(connection['username'])
    password(connection['password'])
  end
}
```

```ruby
credentials: lambda do |connection|
  user(connection['api_key'])
  password("")
end
```

```ruby
credentials: lambda do |connection|
  user(connection['api_token'])
  password('api_token')
end
```

--------------------------------

### Basic Connection Structure

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/connection-definition.md

The foundational structure for defining a connection block.

```ruby
connection: {
  fields: [ /* Array of field definitions */ ],
  authorization: { /* Auth configuration */ },
  base_uri: lambda { /* Optional base URL */ }
}
```

--------------------------------

### Connection Testing

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/connection-definition.md

Verifies credentials by calling a test endpoint.

```ruby
test: lambda do |connection|
  get("https://api.example.com/account")
end
```

--------------------------------

### Define a Minimal API Key Connector

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/README.md

Uses an API key for authentication and defines a basic action to list users.

```ruby
{
  title: 'Example App',

  connection: {
    fields: [
      { name: 'api_key', optional: false, control_type: 'password' }
    ],
    authorization: {
      type: 'api_key',
      credentials: lambda { |c| params(api_key: c['api_key']) }
    }
  },

  test: lambda { |c| get("https://api.example.com/me") },

  actions: {
    list_users: {
      execute: lambda { |c, i| { users: get("https://api.example.com/users") } },
      output_fields: lambda { [{ name: 'users', type: 'array' }] }
    }
  }
}
```

--------------------------------

### Define Configuration and Dynamic Input Fields

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Uses config_fields to drive conditional logic in input_fields based on user selections.

```ruby
config_fields: [
  {
    name: 'object_type',
    label: 'Object Type',
    control_type: 'select',
    pick_list: 'object_types',
    optional: false
  }
],

input_fields: lambda do |object_definitions, config_fields|
  # Fields depend on config_fields['object_type']
  if config_fields['object_type'] == 'user'
    [{ name: 'user_name' }, { name: 'email' }]
  else
    [{ name: 'account_name' }]
  end
end
```

--------------------------------

### Catch and Handle Exceptions in Ruby

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Use a begin-rescue block to catch errors during API execution and return a structured error response instead of crashing.

```ruby
execute: lambda do |connection, input|
  begin
    response = post("https://api.example.com/data").payload(input)
    { success: true, data: response }
  rescue => e
    {
      success: false,
      error: e.message,
      timestamp: Time.now.iso8601
    }
  end
end
```

--------------------------------

### Define Field Hints in Ruby

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Provide user guidance for input fields by setting the hint property.

```ruby
{
  name: 'api_key',
  label: 'API Key',
  hint: 'Found in Settings > API Keys. Click "Generate Key" if none exist',
  control_type: 'password'
}
```

--------------------------------

### Implement Standard Basic Authentication

Source: https://github.com/workato/custom_connector_docs/blob/master/README.md

Defines a connection block using basic authentication with username and password fields.

```ruby
connection: {

  fields: [
    {
      name: "username",
      hint: "Your email used for login"
    },
    {
      name: "password",
      optional: false,
      control_type: "password",
    }
  ],

  authorization: {
    type: "basic_auth",

    credentials: lambda do |connection|
      user(connection["username"])
      password(connection["password"])
    end
  }
}
```

--------------------------------

### Support Multiple Authentication Methods

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Define multiple fields in the connection block to allow users to choose between different authentication options.

```ruby
connection: {
  fields: [
    { name: 'username' },
    { name: 'password', control_type: 'password' },
    { name: 'api_key', control_type: 'password', optional: true }
  ]
}
```

--------------------------------

### Execute Block Implementation

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/actions.md

Contains the core logic for performing API requests using the provided connection and input parameters.

```ruby
execute: lambda do |connection, input|
  # Make API request(s) and return structured data
  response = get("https://api.example.com/users/#{input['user_id']}")
  { user: response }
end
```

```ruby
execute: lambda do |connection, input|
  users = get("https://api.example.com/users", input)
  {
    results: users,
    count: users.length
  }
end
```

--------------------------------

### Implement Batch Create Operation in Ruby

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/common-patterns.md

Defines a batch operation that accepts an array of objects and maps them to individual API requests. Ensure the output fields schema matches the expected API response structure.

```ruby
batch_create_users: {
  input_fields: lambda do
    [
      {
        name: 'users',
        type: 'array',
        of: 'object',
        properties: [
          { name: 'name', optional: false },
          { name: 'email', control_type: 'email', optional: false },
          { name: 'role' }
        ]
      }
    ]
  end,

  execute: lambda do |connection, input|
    responses = input['users'].map do |user|
      post("https://api.example.com/users").payload(user)
    end

    { created: responses, count: responses.length }
  end,

  output_fields: lambda do
    [
      {
        name: 'created',
        type: 'array',
        of: 'object',
        properties: [
          { name: 'id', type: 'integer' },
          { name: 'name' },
          { name: 'email' },
          { name: 'created_at', type: 'datetime' }
        ]
      },
      { name: 'count', type: 'integer' }
    ]
  end
}
```

--------------------------------

### Define Pick Lists

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/quick-reference.md

Use this structure for static dropdown options or dynamic lists that depend on other configuration fields.

```ruby
pick_lists: {
  statuses: lambda do |connection|
    [
      ['Open', 'open'],
      ['Closed', 'closed'],
      ['Pending', 'pending']
    ]
  end,
  
  # Dynamic with dependency
  projects: lambda do |connection, config_fields|
    return [] if config_fields.blank? || config_fields['workspace_id'].blank?
    get("https://api.example.com/workspaces/#{config_fields['workspace_id']}/projects").
      map { |p| [p['name'], p['id']] }
  end
}
```

--------------------------------

### OAuth 2.0 with Non-Standard Header Format

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Demonstrates how to customize the Authorization header format when the API does not use the standard Bearer prefix.

```ruby
authorization: {
  type: 'oauth2',

  authorization_url: lambda do
    'https://www.pushbullet.com/authorize?response_type=code'
  end,

  token_url: lambda do
    'https://api.pushbullet.com/oauth2/token'
  end,

  client_id: 'YOUR_PUSHBULLET_CLIENT_ID',
  client_secret: 'YOUR_PUSHBULLET_CLIENT_SECRET',

  credentials: lambda do |connection, access_token|
    # Pushbullet uses "OAuth2:" prefix instead of "Bearer"
    headers(Authorization: "OAuth2: #{access_token}")
  end
}
```

--------------------------------

### Define an Action with Config Fields

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/configuration.md

Uses config_fields to dynamically adjust input and output schemas based on user selection.

```ruby
submit_document: {
  config_fields: [
    {
      name: 'document_type',
      label: 'Document Type',
      control_type: 'select',
      pick_list: 'document_types',
      optional: false
    }
  ],

  input_fields: lambda do |object_definitions, config_fields|
    # Fields depend on selected document_type
    get_fields_for_type(config_fields['document_type'])
  end,

  execute: lambda do |connection, input|
    post("https://api.example.com/documents").payload(input)
  end,

  output_fields: lambda do |object_definitions, config_fields|
    # Output schema depends on document_type
    get_output_for_type(config_fields['document_type'])
  end
}
```

--------------------------------

### Configure base URL for connections

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/endpoints-reference.md

Define a dynamic base URI in the connection block to simplify endpoint paths in action definitions.

```ruby
connection: {
  base_uri: lambda do
    "https://#{connection['subdomain']}.api.example.com/v2"
  end
}
```

```ruby
execute: lambda do |connection, input|
  # Uses base_uri + path
  get("/users/#{input['user_id']}")
end
```

--------------------------------

### Handle Authentication Errors in Ruby

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Wraps token validation in a begin-rescue block to provide descriptive error messages when authentication fails.

```ruby
authorization: {
  type: 'custom',
  credentials: lambda do |connection|
    begin
      validate_token(connection['api_token'])
      headers(Authorization: "Bearer #{connection['api_token']}")
    rescue => e
      # Re-raise with descriptive message
      raise "Authentication failed: #{e.message}"
    end
  end
}
```

--------------------------------

### Define Connection Field Types

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/types.md

Connection fields include metadata like control_type, url, and hint for UI rendering.

```ruby
{
  name: 'subdomain',
  control_type: 'subdomain',
  url: '.harvestapp.com',
  hint: 'The subdomain from your Harvest URL',
  optional: false
}
```

--------------------------------

### API Key Authentication Configuration

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Defines a connection using an API key passed as a query parameter. Requires a subdomain and API key field definition.

```ruby
connection: {
  fields: [
    {
      name: 'subdomain',
      control_type: 'subdomain',
      url: '.freshdesk.com',
      optional: false
    },
    {
      name: 'api_key',
      control_type: 'password',
      optional: false,
      label: 'API Key'
    }
  ],

  authorization: {
    type: 'api_key',
    credentials: lambda do |connection|
      params(api_key: connection['api_key'])
    end
  }
}
```

```http
GET /api/users.json?api_key=YOUR_KEY HTTP/1.1
```

--------------------------------

### Define Dynamic Pick Lists

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/api-reference/pick-lists.md

Fetch options from an external API by mapping response data to display and stored value pairs.

```ruby
pick_lists: {
  users: lambda do |connection|
    get("https://api.example.com/users").
      map { |user| [user['name'], user['id']] }
  end,

  projects: lambda do |connection|
    get("https://#{connection['subdomain']}.api.example.com/projects").
      map { |project| [project['title'], project['id']] }
  end
}
```

--------------------------------

### Implement Token as Username with Fixed Password

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/authentication-patterns.md

Uses a static string as the password while passing the API token as the username.

```ruby
connection: {
  fields: [
    {
      name: 'api_token',
      control_type: 'password',
      label: 'API Token'
    }
  ],

  authorization: {
    type: 'basic_auth',
    credentials: lambda do |connection|
      user(connection['api_token'])
      password('api_token')
    end
  }
}
```

```ruby
credentials: lambda do |connection|
  user(connection['api_token'])
  password('api_token')
end
# curl -u "api_token:api_token" https://www.toggl.com/api/v8/me
```

--------------------------------

### Define Authentication Types

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/quick-reference.md

Configure connector authentication using basic, API key, OAuth 2.0, or custom headers.

```ruby
# Basic Auth
authorization: {
  type: 'basic_auth',
  credentials: lambda { |c|
    user(c['username'])
    password(c['password'])
  }
}

# API Key
authorization: {
  type: 'api_key',
  credentials: lambda { |c| params(api_key: c['api_key']) }
}

# OAuth 2.0
authorization: {
  type: 'oauth2',
  authorization_url: lambda { 'https://...' },
  token_url: lambda { 'https://...' },
  client_id: 'ID',
  client_secret: 'SECRET',
  credentials: lambda { |c, t| headers(Authorization: "Bearer #{t}") }
}

# Custom
authorization: {
  type: 'custom',
  credentials: lambda { |c| headers('X-Auth': c['token']) }
}
```

--------------------------------

### Handle Null or Missing Input Values

Source: https://github.com/workato/custom_connector_docs/blob/master/_autodocs/best-practices.md

Use safe navigation and default values to prevent errors when processing missing input data.

```ruby
execute: lambda do |connection, input|
  # Check for presence before accessing
  email = input['email']&.downcase
  name = input['name'] || 'Unknown'
  
  post("https://api.example.com/contacts").
    payload(name: name, email: email)
end
```
Tokens:
Raw