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-area	Long text input field with formula mode option.
plain-text	Simple text input field without formula mode option.
plain-text-area	Long text input field with formula mode option. This input field can be expanded using the adjust icon.
number	Simple number field with icon to indicate either an integer or float value. This control type has formula mode option.
url	Text field with icon to indicate a URL value. This control type has formula mode option.
select	Control type to provide a predefined list of values to choose from. Make sure to include the `pick_list` property.
checkbox	Simple Yes/No select interface. This control type adds an implicit toggle to text mode (for dynamic mapping and formula mode option).
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.
date	Control type indicating date value. This control type has formula mode option.
date_time	Control type indicating date with time value. This control type has formula mode option.
phone	Control type indicating phone value. This control type has formula mode option.
email	Control type indicating email value. This control type has formula mode option.
subdomain	Control type to indicate a subdomain of a particular site. Typically used in connection fields. Make sure to include the `url` property.
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`.

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
  }
}

Object definition