# SDK Reference - connection

This section enumerates all the possible keys available when defining your connection.

Quick Overview

To put it simply, the connection hash contains all the instructions your connector needs to establish a successful connection.

  • The fields key tells your connector what input fields to show so it can collect information for authorization.
  • The extended_fields key allows you to dynamically show more connection fields based on previous inputs. This field is optional to define.
  • The authorization key tells your connector what to do with the information it has collected - use that to exchange it for an access_token.
  • The base_urikey tells your connector what to prepend to every HTTP request after connection is successful. This allows you to use relative paths in your connector code when defining actions and triggers.

# Structure

  connection: {
    fields: Array,

    extended_fields: lambda do |connection|
      Array
    end,

    authorization: Hash,

    base_uri: lambda do |connection|
      String
    end
  }

# fields

Attribute Description
Key fields
Type Array
Required False
Description Accepts an array of hashes. Each hash in this array corresponds to a separate input field. To know more about how to define input fields in Workato, click here.
Note about picklists in connection fields

For fields with control_type defined as select or multiselect, you should use the options attribute to define a static picklist instead of the pick_list attribute. Take note that references to any picklists you have defined in your connector are not accessible in the connection hash as no credentials have been received at this time.

Example: Connection fields with picklist nested in advanced settings

    fields: [
      {
        name: 'api_key',
        control_type: 'password',
        hint: 'You can find your API key final change3' \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: 'Your API Key',
        default: "helloaaaabbb",
        optional: false
      },
      {
        name: 'domain',
        control_type: 'subdomain',
        url: 'chargebee.com'
      },
      {
        name: "advanced_settings",
        type: "object",
        optional: "true",
        properties: [
          {
            name: "environment",
            optional: true,
            control_type: "select",
            options: [
              ["Development", "dev"],
              ["Production", "prod"]
            ]
          }
        ]
      }
    ],

# extended_fields

Attribute Description
Key extended_fields
Type lambda function
Required False
Description Allows you to optionally display more input fields based on your connection. The output is expected to be valid Workato schema. Find out more about Workato schema.
How to use extended_fields

Extended fields allows you to dynamically display additional fields based on previous input fields. If your connection setup is complex and consist of many input fields, consider limiting how many fields a user can see. Use extended fields to control how many fields are shown to the user initially and when to display additional fields, rather than displaying all of them at once.

In this case, extended_fields provides you with the added benefit of controlling which fields are shown to users during connection setup and guiding them through the experience. In some cases, you may also restrict some fields from being shown if they are not relevant.

Example: Connection fields with extended_fields - Simple

    fields: [
      {
        name: "api_key",
        control_type: "password",
        hint: "You can find your API key " \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: "Your API Key"
      },
      {
        name: "custom_domain",
        label: "Are you using a custom domain?",
        extends_schema: true,
        control_type: "checkbox"
      }
    ],
    
    extended_fields: lambda do |connection|
      if connection['custom_domain'] == "true"
        [
          {
            name: "domain",
            control_type: "subdomain",
            extends_schema: true,
            url: ".acme.com"
          }
        ]
      end
    end,

The connection hash will be passed to all other lambdas, including authorization and execute. The connection hash will contain values from both fields and extended_fields.

Example: Connection fields with extended_fields - Advanced

The example below showcases how you can use extends_schema even within extended_fields to create a connection setup that has multiple steps.

  connection: {
    fields: [
      {
        name: "api_key",
        control_type: "password",
        hint: "You can find your API key " \
          "under 'Settings'=>'Configure Chargebee'=>'API Keys and Webhooks'" \
          " in Chargebee's web console.",
        label: "Your API Key"
      },
      {
        name: "custom_domain",
        label: "Are you using a custom domain?",
        extends_schema: true,
        control_type: "checkbox"
      }
    ],
    
    extended_fields: lambda do |connection|
        [
          (
            if connection['custom_domain'] == "true"
              {
                name: "domain",
                control_type: "subdomain",
                optional: false,
                url: ".acme.com"
              }
            end 
          ),
          (
            if connection['custom_domain'] == "true"
              {
                name: "instance_type",
                control_type: "select",
                extends_schema: true,
                optional: false,
                options: [ ["Production", "production"], ["Sandbox", "sandbox"]]
              }
            end 
          ),
          (
            if connection['instance_type'] == "sandbox"
              {
                name: "protocol",
                control_type: "select",
                optional: false,
                options: [ ["HTTPS", "https://"], ["HTTP", "http://"]]
              }
            end
          )
        ].compact
    end,

    authorization: {
      type: 'basic',

      apply: lambda { |connection, access_token|
        headers("x-api-key": "#{connection['api_key']}")
      }
    },

    base_uri: lambda do |connection|
        if connection['custom_domain'] == "true"
          "#{connection['protocol']}#{connection['domain']}.acme.com/"
        else
          "https://api.acme.com/"
        end
    end
  },

# authorization

Attribute Description
Key authorization
Type Hash
Required True
Description Accepts an object with child keys corresponding to different types of authentication

Find out more about authorization hash here


# base_uri

Attribute Description
Key base_uri
Type lambda function
Required False (but recommended)
Description Defines the base URI for all future HTTP requests.
Possible Arguments connection - Hash representing user given inputs defined in Connection
Expected Output String i.e. "https://#{connection['host']}.com/" or "https://api.acme.com"
Configuring your Base URI

When you define your base_uri: key, do take note of the final URI you provide. There are two scenarios when using base_uri in conjunction with any downstream HTTP requests.

  1. if you have a preceding / in the verb method - get('/hello/there') We ignore any path paramters in your base_uri. i.e. https://api.hubapi.com/test/ defined as your base_uri effectively becomes https://api.hubapi.com effectively. Request is sent to https://api.hubapi.com/hello/there.

  2. If you don’t have a preceding / in the verb method - get('hello/there') We adopt the path paremters in your base_uri. i.e. https://api.hubapi.com/test/ defined as your base_uri remains as https://api.hubapi.com/test/. Request is sent to https://api.hubapi.com/test/hello/there.