Object Definition

Object Definitions is an important component of the SDK. It allows you to define your schema for objects to be used in the actions and triggers. It allows you to easily define outputs and inputs later on.

Static Definition

The most basic way to build an object definition is to define the field name and type

object_definitions: {
  push: {
    fields: lambda do
      [
        { name: "active", type: :boolean },
        { name: "body" },
        { name: "created" },
        { name: "direction" },
        { name: "dismissed", type: :boolean },
        { name: "iden" },
        { name: "modified" },
        { name: "receiver_email" },
        { name: "receiver_email_normalized" },
        { name: "receiver_iden" },
        { name: "sender_email" },
        { name: "sender_email_normalized" },
        { name: "sender_iden" },
        { name: "sender_name" },
        { name: "title" },
        { name: "type" },
      ]
    end
  }
}

In this example, the object “Push” is being defined in the fields lambda literal.

Defined as an array of objects. Each field object corresponds to a field in the comment object.

Dynamic Definition

object_definitions: {

  form: {
    fields: lambda do |connection|
      get("https://api.unbounce.com/pages/#{connection['page_id']}/form_fields")["formFields"].
        map { |field| { name: field["id"] } }
    end
  }
}

Components

Key Definition
name The name of this field. For example id or created_at
label An optional key. All fields will have default labels based on the field name. Use this to change the default value of the field label.
type The data type of this field. Default value is :string. Should be given the symbol notation (prepend colon).
  • :string
  • :integer
  • :number
  • :date_time
  • :date
  • :timestamp
  • :boolean
  • :object Must be accompanied with :properties
  • :array Must be accompanied with :properties
control_type The input field type to expose in a recipe. Refer to the list of Control types supported.
pick_list If control_type is :select or :multiselect, this property is required. See more in Pick List chapter.
properties When defining nested objects, use the properties key to define the fields in the object. Remember to define the type as :array or :object
sticky Use this property to make the optional field visible on the Input section. For Ex: Since is optional field but to be displayed always under Input fields. Use sticky: true.

Control types

Control type Description
text Simple text input field with formula mode option.
text control type
text-area Long text input field with formula mode option.
text-area control type
plain-text Simple text input field without formula mode option.
plain-text control type
plain-text-area Long text input field with formula mode option. This input field can be expanded using the adjust icon.
plain-text-area control type
number Simple number field with icon to indicate either an integer or float value. This control type has formula mode option.
number control type
url Text field with icon to indicate a URL value. This control type has formula mode option.
url control type
select Control type to provide a predefined list of values to choose from. Make sure to include the pick_list property.
select control type
checkbox Simple Yes/No select interface. This control type adds an implicit toggle to text mode (for dynamic mapping and formula mode option).
checkbox control type
multiselect Control type similar to select with additional ability to select multiple values. This control type must be accompanied with pick_list and delimiter properties.
multiselect control type
date Control type indicating date value. This control type has formula mode option. date control type
date_time Control type indicating date with time value. This control type has formula mode option. date_time control type
phone Control type indicating phone value. This control type has formula mode option.
phone control type
email Control type indicating email value. This control type has formula mode option.
email control type
subdomain Control type to indicate a subdomain of a particular site. Typically used in connection fields. Make sure to include the url property.
subdomain control type
static-list Control type for arrays where the size of the array is statically determined by the recipe designer. Remember to define item_label, add_item_label, empty_list_title and empty_list_text.
static-list control type

Nested fields

Often, data returned from API request is not a simple one-level JSON. More often than not, the object is much more complex, with multiple levels of nesting. This section aims to illustrate how to define nested fields.

Nested object

Take this sample User JSON from Okta:

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2013-07-02T21:36:25.344Z",
  "activated": null,
  "lastLogin": "2013-07-02T21:36:25.344Z",
  "profile": {
    "firstName": "Isaac",
    "lastName": "Brock",
    "email": "isaac.brock@example.com",
    "login": "isaac.brock@example.com",
    "mobilePhone": "555-415-1337"
  },
  "credentials": {
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  },
  "_links": {
    "activate": {
      "href": "https://your-domain.okta.com/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/activate"
    }
  }
}

Nested object field profile can be defined type: :object with fields nested inside using properties. Properties should be an array of fields objects (just like fields within the user object).

object_definitions: {
  user: {
    fields: lambda do
      [
        {
          name: "id"
        },
        {
          name: "status"
        },
        {
          name: "created",
          type: :timestamp
        },
        {
          name: "activated",
          type: :timestamp
        },
        {
          name: "lastLogin",
          type: :timestamp
        },
        {
          name: "profile",
          type: :object,
          properties: [
            {
              name: "firstName"
            },
            {
              name: "lastName"
            },
            {
              name: "email",
              control_type: :email
            },
            {
              name: "login",
              control_type: :email
            },
            {
              name: "mobilePhone",
              control_type: :phone
            }
          ]
        }
      ]
    end
  }
}

Nested Arrays

The other common type of nested field is array of objects. This type of field contains a list of repeated objects of the same fields. The defining such fields will be very similar to defining objects. Take the following sample user object from Asana for instance.

{
  "data": {
    "id": 12149914544379,
    "email": "eeshan@workato.com",
    "name": "Ee Shan",
    "workspaces": [
      {
        "id": 1041269201604,
        "name": "Workato"
      },
      {
        "id": 498346130780,
        "name": "Product Documentation"
      }
    ]
  }
}

The workspaces array should be given type: :array as well as of: :object. This tells the object_definitions framework that the field contains an array of objects. Similar to nested objects, you will need to define properties, which is an array of fields corresponding to the fields of each object in the workspaces array.

object_definitions: {
  user: {
    fields: lambda do
      [
        {
          name: 'id',
          type: :integer
        },
        { name: 'name' },
        {
          name: 'email',
          control_type: :phone
        },
        {
          name: 'workspaces',
          type: :array,
          of: :object,
          properties: [
            {
              name: 'id',
              label: 'Workspace ID',
              type: :integer
            },
            { name: 'name' }
          ]
        }
      ]
    end
  }
}

results matching ""

    No results matching ""