objects Array
App Studio supports defining Custom Object schemas and saving inbound data as records. Custom Object schemas and records offer an extremely flexible way to store custom data in ActiveCampaign.
The top-level App Studio config objects
property is an array of object
definitions. Each object
defines the schema, fields, relationships, data transformations, and other configuration information needed to support your integration's storage requirements.
There are two types of objects: core objects and custom objects. A core object describes and connects your inbound data to a core object in the ActiveCampaign platform, such as a Contact. A custom object defines how your inbound data will be stored as a record attached to the core object.
Core and Custom Objects
A minimum of two objects are required for a valid configuration. One object must be defined as a core object using the
ac_object
property (more on this later), and one or more objects defined as custom objects (noac_object
property).
For concrete examples, please refer to the Zendesk Support Custom Objects Example and Calendly Custom Objects Example.
Key | JSON Type | Required for Core Object | Required for Custom Objects |
---|---|---|---|
name | string | yes | yes |
labels | object | yes | yes |
description | string | yes | yes |
external_id | string | yes | yes |
ac_object | string | yes | no |
fields | array of objects | yes (however, the value will be an empty array) | yes |
relationships | object | no | yes |
transform | object | no | no |
event_type_field | string | no | no |
event_types | array of objects | no | no |
from_reference | object | no | no |
prepare_to_transform | object | no | no |
The name of the object, such as "order", "submission", or "event." This value must be unique across all objects defined in the same application. For example, you cannot have two objects named "order" in the same app config. Once set, this name will be used by the ActiveCampaign platform to identify the object during the lifecycle of the object.
These are the customer-facing labels of the object. For example, a label might be "Stripe Order", "Typeform Submission", or "Calendly Event." The labels
object must include a singular
and plural
property. The following is an example of a labels
object.
"labels": {
"singular": "Ticket",
"plural": "Tickets"
},
The description
property is a short sentence describing what the object is, such as "Orders through Stripe", "Form submissions from Typeform", or "Ticket Created in Zendesk Support."
The external_id
is used to specify how records are uniquely identified in the integrating system. The value can either be a simple field id reference (e.g. id
or record.id
) or a valid jq
expression. Object records are already guaranteed to be unique per ActiveCampaign account, per CX app, and per Custom Object definition. If a record id is already unique in the integrating system, then an id field is sufficient. Otherwise, you may need to combine multiple fields for cases where a record does not have one uniquely identifying value in your system, or its identifier is not unique across your system’s accounts.
An object defined as a core object must include the ac_object
property. The value of this property must be one of the supported ActiveCampaign core objects. "Contact"
is the only value supported at this time.
The fields
array is a list of field
objects that describe the schema of the Custom Object. Each field may include the following properties and objects.
Attribute | JSON Type | Required |
---|---|---|
id | string | yes |
labels | object | yes |
description | string | yes |
type | string | yes |
is_required | boolean | yes |
scale | number | no - optional only for "number" type |
options | array of strings | yes - only for "dropdown" and "multiselect" types |
default_currency | string | no - optional only for "currency" type |
The field id
property is a unique field identifier for the field. This value must be unique among other fields in the same Custom Object. When possible, it is recommended you use the name of the equivalent field that exists in the system you are integrating. This value is used to map fields in the inbound data to the record generated in ActiveCampaign.
User-friendly labels to display in the UI for this field. This must include both the singular and plural form of the label.
{
"singular": "Ticket ID",
"plural": "Ticket IDs"
}
A short sentence describing the purpose or values stored in the field.
The data type of the value stored in the field. Valid types are currency
, date
, datetime
, number
, text
, and textarea
.
Type Name | Description | Notes |
---|---|---|
text | A short text field | Limited to 65,535. Longer strings will not be saved. |
textarea | A text field of any length | |
number | An integer or decimal number | Number of decimals saved can be defined with the additional scale field. Scale can be set to 0 to denote integer values - this is the default. |
datetime | A valid ISO8601 date time string (e.g. 2021-08-13T17:51:44+00:00 ) | |
date | A date string in the format YYYY-MM-DD (e.g. 2011-12-23 ) | |
dropdown | A field to capture a single value from a predefined list of options. | Options need to be defined in the additional options field. |
multiselect | A field to capture multiple values from a predefined list of options. | Options need to be defined in the additional options field. |
currency | A value containing numbers representing a currency value. | Currency type can be defined via the additional default_currency field. Defaults to "USD" . |
The is_required
property is a boolean value indicating whether the field is required. If required, and a value is not provided, the record will not be created.
The scale
property is optional and only applies to the number
data type. The value represents the number of decimals to save. A value of 0 declares the number is treated as an integer.
The options
array is required for multiselect
and dropdown
data types. The expected value is an array of strings containing all possible values for this field. Any value supplied that is not in the list will not be saved.
{
"options": ["red", "orange", "yellow"]
}
The default_currency
property is only used for currency
data types. The value is a three-character ISO 4217 currency code. The value defaults to "USD"
.
The relationships
array is a list of relationship
objects. Each relationship object describes the connection the current custom object has with other objects. For a core object, the relationships
array is not required. A custom object must relate to at least one core object.
Limitations
Only one relationship is currently supported. In the future, a custom object will be able to relate to more than one core object.
Each relationship is represented by the following attributes:
Identifier of a relationship. This must be unique within the same object.
A user-friendly label for the relationship. The object must include both singular
and plural
properties.
This is the name of the related object.
This is a boolean field that describes the relationship from the current object to a related object.
false
: The custom object record is related to only one core object.true
: The custom object record can be related to more than one core object (currently not supported).
This is the field in the current payload that denotes the related object, if any. Our system will try to use the value from this field to create the related object and link it to the current object.
This field can either be a simple field reference (i.e. "id"
or "record.id"
) or a valid jq
expression.
Denotes where the data for creating this object will come from. The value can either be "data"
or "reference"
.
"data"
: The value in the field is data found in the event payload that can be used to create the related object."reference"
: The value is a reference id to look up more information about an object in the integrating system. This is the value that is used in thefrom_reference
step and can be accessed using${reference}
in that step.
The transform
object is used to pair each field
with a !jq
command that describes how to assign the field value from the incoming data.
"transform": {
"meeting_type": ".data.meeting_type.name",
"start_time": ".data.meeting.start",
"id": ".data.meeting.uuid",
"is_canceled": ".data.meeting.canceled"
},
{
"data": {
"meeting_type": {
"id": 3477,
"name": "Conference"
},
"meeting": {
"id": "9be1cb7b-c41d-4175-8af0-db8c773c1a75",
"start": "2022-02-31T13:30:00.000-05:00",
"canceled": false
}
}
}
The event_type_field
is an optional property. When the system you are integrating sends data to ActiveCampaign, it may include information about which event generated the data. The value of this property should be the path to the inbound data property that specifies the type of inbound event. Dot notation is supported.
Event types are useful to customers as they may choose to sync specific types of data from your system to ActiveCampaign or rely on the event type to trigger specific actions. If you are not sure what to provide here, leave the field out.
The event_types
array is a list of event type objects, each describing an event type and how they should appear to users. Each object contains three string properties.
key | purpose |
---|---|
value | The value to match on in the payload for the event type. |
display | The value displayed to a customer when selecting triggers or referring to the event. |
description | A short sentence describing what this event is (e.g. when it can occur). |
Example:
"event_types": [
{
"value": "ticket_created",
"display": "Ticket Created",
"description": "Occurs when a ticket is created"
},
{
"value": "ticket_updated",
"display": "Ticket Updated",
"description": "Occurs when a ticket is updated"
}
],
The optional from_reference
can be used to retrieve additional data required to process an event. An inbound event payload from the integrating system may not include all the data needed to populate your Custom Object. For example, you can use from_reference
with the !http
command to make a "lookup" request to retrieve additional data.
The response returned by from_reference
is made available to other steps using the ${reference} variable. When defined, the
from_referencestep is applied before the
prepare_to_transform` step.
This optional attribute is used to modify the shape of the data to fit the mappings in the transform step. This is useful when the incoming data has a different structure, such as nested data. Each event type can have a dedicated object. If you are not using event types or the inbound data does not match an existing event type, the default
object is used. If defined, the prepare_to_transform
is applied before the transform
.
Updated over 2 years ago