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).
|
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.![]() |
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
}
}