# Object Definitions and structuring input and output fields
Object Definitions are an important component of the SDK. It allows you to define your schema for objects to be used in the actions and triggers. While we have gone through examples on how to do this directly from inside your input_fields: and output_fields: blocks, object_definitions allow you to declare it once and reuse it multiple times in various areas of your connector code.
Object definitions are a key indicator of well written code. It makes your custom connector more maintainable and easier to read.
After that, we will dive deeper into the details of how you can clearly define your input and output fields. This will have important effects on what end users see when building recipes using your connector.
# Static object definitions
The most basic way to build an object definition is to define the field name and type
# Sample code snippet
{
title: 'My close.io connector',
connection: {
# Some code here
},
test: {
# Some code here
},
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
}
},
triggers: {
# Some code here
},
object_definitions: {
lead: {
fields: lambda do
[
{ name: "name", type: :boolean },
{ name: "email" },
{ name: "number"}
]
end
}
}
picklists: {
# Some code here
},
methods: {
# Some code here
},
}
In this example, the object leads is being defined in the fields lambda function. This can then be easily referenced in the action above. Defined as an array of objects. Each field object corresponds to a field in the lead object.
# Dynamic object definitions
Object definitions can also be used to dynamically generate input and output schemas. This is often done by a HTTP requests to metadata endpoints which return data about what fields to expect. Below we go through a simple example of using a GET request to a metadata endpoint to know what fields to expect in a form.
# Sample code snippet
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
}
}
Remember that the ultimate output of the lambda function would still have to be in the format that Workato expects. This often means using ruby methods like map to transform the response from an HTTP call.
# Testing
Testing and debugging your object definitions can be done in the same way that you would for your actions or triggers. Make sure that your object definition is being used in a specific action and test that action in the code editor. HTTP calls from the object definition should be recorded in the Network tab and any puts functions in your object definition block should be displayed in the Console tab as well.
# Structuring input and output fields
Up until now, our sample code snippets have largely only included the basic parameters such as name when defining input and output fields. Workato allows you to define a much larger set of variables that affect the way your fields are displayed to end users.
| 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. |
| hint | An optional key. This allows you to add some hints below the input field to guide the user. Links to documentation can be given using HTML syntax. |
| type |
The data type of this field. Default value is "string".
Should be given the symbol notation (prepend colon).
|
| of |
When defining arrays, you need to declare of where of: "object". Only the type object is compatible with this parameter. Primitive data types like string and integer are not yet supported.
|
| properties |
When defining nested objects, use the properties key to define the fields in the object or array of objects.
|
| control_type |
This field relates only to input fields and it dictates the input field type to expose in a recipe. Refer to the list of Control types supported.
If this is declared for output fields, whether as an object definition or if it is hardcoded, it would be ignored. |
| default | Allows you to set a default value for that input field. This is useful in defaulting certain inputs to values that you believe most customers would choose and improve the usability of your connector. |
| pick_list |
If control_type is :select or :multiselect, this property is required.
See more in Pick List chapter.
|
| sticky | Use this property to make the optional field visible on the Input section. For example: Since is optional field but to be displayed always under Input fields. Use sticky: true.
|
| render_input | An optional key. This must be accompanied with `parse_output`. Since our payloads are normally JSON objects, they are normally represented as strings. This field helps to convert them to other data types such like integers.
|
| parse_output | An optional key. This must be accompanied with `render_output`. Since our payloads are normally JSON objects, they are normally represented as strings. This field helps to convert them to other data types such like integers.
|
| change_on_blur | An optional boolean key. When true, config fields and dependent fields only evaluate the value when the user blurs out of the field instead of after every keystroke. This parameter often doesn't need to be configured. |
| support_pills | An optional boolean key. When true, this field doesn't allow datapills to be mapped to it. This parameter often doesn't need to be configured. |
| custom | An optional boolean key. When true, a special marker is introduced to indicate to the user that this field is custom. Normally used when dynamically generating object definitions which may contain custom fields. |
| extends_schema |
Defines whether this specific input field can influence other input or output fields. Setting this field to extends_schema: true makes this input field act as if it were a configuration field. Learn more about how to use the extends_schema field here |
| list_mode |
Used when working with arrays. Workato defaults to dynamic lists but this parameter allows you to set configure this input field to a static array input field. Defaults to dynamic
Used by setting list_mode: "static" or list_mode: "dynamic" |
| list_mode_toggle |
Used when working with arrays. Workato allows users to toggle between static and dynamic lists when working with arrays. Defaults to true.
Set list_mode_toggle: false to disallow users to toggle list modes.
|
| item_label |
Only used with control_types schema_designer and key_value.
This allows you to configure the item name stated in the modal popup. Setting item_label: "Item Label" will result in the following:
 |
| add_field_label |
Only used with control_types schema_designer and key_value.
This allows you to configure the label of the add button. Setting add_field_label: "Custom Add Label" will result in the following:
 |
| empty_schema_message |
Only used with control_types schema_designer and key_value.
This allows you to configure the message when the input field is empty. Setting empty_schema_message: 'Custom empty schema message that allows to and ' will result in the following:
 |
| sample_data_type |
Only used with control_types schema_designer
This allows you to configure the type of data the schema_designer input field will accept. Setting sample_data_type: 'csv' will result in the following:
Other possible inputs are json_input and xml. The schema_designer defaults to json_input.
|
# Control types
Control types are a way for you to declare how input fields are displayed to users of your connector.
| 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. It is advisable to add a toggle field 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. |
| schema_designer |
Control type that allows you to collect schema information from users. This is useful when you need users to give your input during recipe design time to create input or output fields. This requires extends_schema: true to take effect.
 |
| key_value |
Control type that allows you to collect key and value pairs from users. This is useful when you need users to give your input during recipe design time for URL query parameters. Must be accompanied with `properties:` defined and two inputs given.
 |
# Variations
# Nested objects
Often, data returned from API request is not a simple one-level JSON. More often than not, the returned JSON object is much more complex, with multiple levels of nesting. This section aims to illustrate how to define nested fields.
# Sample code snippet
{
"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.
# Sample code snippet
{
"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
}
}
# Using fields with extends_schema
Sometimes, what input fields to show in an action depend on the answer to an input field in the same action. Rather than using config fields, extends_schema is an advanced way of introducing even more dynamic behaviour into your action.
# Sample code snippet
object_definitions:
schema_input: {
fields: lambda do |connection, config_fields|
input_schema = parse_json(config_fields.dig('schema') || '[]')
[
{
name: "schema",
extends_schema: true,
schema_neutral: false,
control_type: 'schema-designer',
label: 'Schema designer label',
hint: 'Hint for schema designer field',
item_label: 'button',
add_field_label: 'Custom Add Label',
empty_schema_message: 'Custom empty schema message that allows to <button type="button" data-action="addField">add field</button> and <button type="button" data-action="generateSchema">generate schema</button>',
sample_data_type: 'csv' # json_input / xml
},
if input_schema.present?
{ name: 'data', type: 'object', properties: input_schema }
end
].compact
end
}
In the code sample above, we use an input field with the control_type schema_designer. When extends_schema is set to true, any inputs by an end user immediately cause the object_definitions block to re-evaluate itself with the inputs given being passed as config_fields again. In this example, we see that the input schema is referenced at the beginning of the object_definition block. When users give inputs for the schema field, it can be referenced as a config_field which use to build the data input field.
# Arrays of primitive data types
Arrays in Workato input and output schema currently only work with objects. In cases where you need to collect an array of primitive datatypes such as strings or integers, consider the code below. In this example, we hope to send an array of strings to a target API in the format ["column1","column2","column3"]. This can be done by declaring an array of objects with the declaration for the column names input field wrapped inside the object layer.
# Sample code snippet
object_definitions: {
columns: {
fields: lambda do
[
{
label: 'Column Names',
name: 'columnNames',
type: :array,
of: :object,
properties: [
{
name: 'columnName'
}
]
}
]
end
}
}
When users design their recipes, we expect the input from this to look like this:
{
"columnNames": [
{
"columnName": "column1"
},
{
"columnName": "column2"
},
{
"columnName": "column3"
}
]
}
This input can be massaged into our desired format with a simple .pluck method.
actions:{
get_column_names:{
input_fields: lambda do |object_definitions|
object_definitions["columns"]
end,
execute: lambda do |connection, input|
column_names = input["columnNames"]&.pluck("columnName") # This gives us ["column1","column2","column3"]
post("Target_URL", column_names)
end
}
}
# Next section
The next section goes through some additional concepts related to object definitions which we call picklists. Pick lists allow you to declare dropdowns for your users instead of have to enter text. Go to our picklist documentation or check our our best practices for some tips on how to use object definitions.