Inputs & Outputs V1
Inputs are the data that your Action (not Events) will use to complete its designed task. The Input section of an Action defines the input fields on your Connector and provides a schema to build the object that will be passed to the Core code to process.
The object defined by the input section must follow this structure:
{
"extensible": false,
"attributes": [
{
"name": "[HeaderName1]",
"attributes": [
{
"name": "[FieldName1]",
"type": "string"
}
]
}
]
}There must be at least one “attributes” array, that contains all of the objects that represent “Headers” on your Connector card. A “Header” is a category of input fields, used to organize the variety of inputs your Connector may have. Inside of a “Header” object, there is an array, which will contain your “Field” objects. “Field” objects are where actual data is passed into your Action.
An example of a “Header” would be “User”, which contains a ‘Field” called “Username”.
This input schema would generate an input object that looks like this, after the user has entered data:
{
"[HeaderName1]": {
"[FieldName1]" : [value]
}
}To access this field in the rest of your method, you could use the Mustache template {{input.[HeaderName1].[FieldName1]}}.
Static Inputs
Most input sections are static–the user will always see the same input fields on this card, regardless of their account data. For example, the “Post Tweet” Action from Twitter will always have the same input fields.
Template:
{
"extensible": false,
"attributes": [
{
"name": "",
"attributes": [
{
"name": "",
"type": "string"
}
]
}
]
}Fields:
- “extensible”: A boolean that if ‘true’ will allow users to add their own custom input fields. This should only be used if you are unable to dynamically generate users’ custom fields using a metadata method
- “attributes”: An array that contains the header objects
- “name”: The name of the header object. This will be displayed on the card
- “attributes”: An array that contains the input fields
- “name”: the name of the input field. This will be displayed on the card.
- “type”: must be ‘string’.
Example:
{
"extensible": false,
"attributes": [
{
"name": "User",
"attributes": [
{
"name": "firstName",
"type": "string"
},
{
"name": "lastName",
"type": "string"
},
{
"name": "email",
"type": "string"
}
]
},
{
"name": "Company",
"attributes": [
{
"name": "name",
"type": "string"
},
{
"name": "revenue",
"type": "string"
}
]
}
]
}Dynamic Inputs
You can also take the user’s account information and use it to dynamically generate inputs. This should only be done if the application supports custom fields for the record type you are dealing with. You can use a Helper Function to call the API and fetch the users’ custom fields, and then build them into the card.
Template:
{
"extensible": false,
"attributes": [
{
"name": "Normal Fields",
"attributes": [
{
"name": "Field1",
"type": "string"
},
{
"name": "Field2",
"type": "string"
}
]
},
{
"name": "Custom Fields",
"attributes": [
{
"metadata": "",
"config": "",
"data": {}
}
]
}
]
}Fields:
- “extensible”: A boolean that if ‘true’ will allow users to add their own custom input fields. This should only be used if you are unable to dynamically generate users’ custom fields using a metadata method
- “attributes”: An array that contains the header objects
- “name”: The name of the header object. This will be displayed on the card
- “attributes”: An array that contains the input fields
- “name”: the name of the input field. This will be displayed on the card.
- “type”: must be ‘string’.
- “metadata”: The name of the metadata method you would like to call The metadata method should call the API to obtain data about the user’s custom fields, then return an array of strings. Each string in that array will be turned into a field.
Example:
{
"extensible": false,
"attributes": [
{
"name": "Ticket",
"attributes": [
{
"name": "Name",
"type": "string"
},
{
"name": "Description",
"type": "string"
}
]
},
{
"name": "Custom Fields",
"attributes": [
{
"metadata": "getTicketFields",
"config": "",
"data": {}
}
]
}
]
}The above example would call a metadata method called getTicketFields. getTicketFields would then run a call to the API, and render the results into an array. Then, in the Core Code, you can use modules to manipulate the input data before passing the data to the API.
Output
About Outputs
The Output section defines the output object that the Connector card expects from your method. This information is used to generate the card at design time, so the user can drag their data from one card to another without reference to the API underlying the card. If the result of the module steps is not the same as the object declared in the output schema, the data will not be passed to any following cards.
The object defined by the output section must follow this structure:
{
"extensible": false,
"attributes": [
{
"name": "[HeaderName1]",
"attributes": [
{
"name": "[FieldName1]",
"type": "string"
} ,
{
"name": "[CollectionFieldName1]",
"type": "string",
"collection": true
},
{
"name": "[ObjectFieldName1]",
"type" : "object",
"collection" : false,
//required for all outputs of type "object"
"attributes": [
"fieldOne" : value
]
}
]
}
]
}There must be at least one “attributes” array, that contains all of the objects that represent “Headers” on your Connector card. A “Header” is a category of input fields, used to organize the variety of inputs your Connector may have. Inside of a “Header” object, there is an array, which will contain your “Field” objects. “Field” objects are where actual data passed into your Action.
An example of a “Header” would be “User”, which contains a ‘Field” called “Username”.
This input schema would generate an input object that looks like this, after the user has entered data:
{
"[HeaderName1]": {
"[FieldName1]" : [value]
}
}Static Outputs
Most output objects are static–the user will see the same output fields on the card, regardless of their account data. For example, no matter the user, the “New Card in List” Event from Trello will always have the same output fields.
Template:
{
"extensible": false,
"attributes": [
{
"name": "",
"attributes": [
{
"name": "",
"type": "string"
}
]
}
]
}Fields:
- “extensible”: A boolean that if ‘true’ will allow users to add their own custom output fields. This should only be used if you are unable to dynamically generate users’ custom fields using a metadata method
- “attributes”: An array that contains the header objects
- “name”: The name of the header object. This will be displayed on the card
- “attributes”: An array that contains the output objects
- “name”: The name of the output field. This will be displayed on the card
- “type”: must be ‘string’
Example:
{
"extensible": false,
"attributes": [
{
"name": "Post",
"attributes": [
{
"name": "Text",
"type": "string"
},
{
"name": "URL",
"type": "string"
},
{
"name": "Reblogs",
"type": "string"
}
]
},
{
"name": "Author",
"attributes": [
{
"name": "Username",
"type": "string"
},
{
"name": "Followers",
"type": "string"
}
]
}
]
}This output schema would expect an output object from the modules section that looks like this:
{
"Post": {
"Text": "Bagels are just donuts without the happiness.",
"URL": "www.donutfans.com/post/1029384756",
"Reblogs": "47"
},
"Author": {
"Username": "KrullerKing",
"Followers": "189"
}
}Dynamic Outputs
You can also take the user’s account information and use it to dynamically generate outputs. This should only be done if the application supports custom fields for the record type you are dealing with. You can use Helper Functions to call the API and fetch the users’ custom fields, and then build them into the card.
Template:
{
"extensible": false,
"attributes": [
{
"name": "Normal Fields",
"attributes": [
{
"name": "Field1",
"type": "string"
},
{
"name": "Field2",
"type": "string"
}
]
},
{
"name": "Custom Fields",
"attributes": [
{
"metadata": "",
"config": "",
"data": {}
}
]
}
]
}Fields:
- “extensible”: A boolean that if ‘true’ will allow users to add their own custom input fields. This should only be used if you are unable to dynamically generate users’ custom fields using a metadata method
- “attributes”: An array that contains the header objects
- “name”: The name of the header object. This will be displayed on the card
- “attributes”: An array that contains the input fields
- “name”: the name of the input field. This will be displayed on the card.
- “type”: must be ‘string’.
- “metadata”: The name of the metadata method you would like to call The metadata method should call the API to obtain data about the user’s custom fields, then return an array of strings. Each string in that array will be turned into a field.
Example:
{
"extensible": false,
"attributes": [
{
"name": "User",
"attributes": [
{
"name": "Full Name",
"type": "string"
},
{
"name": "Email",
"type": "string"
},
{
"name": "ID",
"type": "string"
}
]
},
{
"name": "Custom Fields",
"attributes": [
{
"metadata": "getTicketFields",
"config": "",
"data": {}
}
]
}
]
}The above example would call a metadata method called getTicketFields. getTicketFields would then run a call to the API, and render the results into an Array. The result of the Core array must be the same shape as the output object defined in your schema. In the example above, if the user had two custom ticket fields, “plan_type” and “csm_owner”, the output object produced by the Core modules should look like this:
{
"User": {
"Full Name": "Pseudo Ersatzson",
"Email": "pseudo@illusory.com",
"ID": "0112358132134"
},
"Custom Fields": {
"plan_type": "Professional",
"csm_owner": "John Smith"
}
}