Integration Anatomy
Breakdown of the internal logic for an integration
Integration Components
Integrations provide the wrapper for a set of composable logic with which to connect external systems.
Integrations
Input
: Request body provided to the integration
Input
: Request body provided to the integrationInputs begin with the request, but can be mutated throughout the life of the integration. For example, the before_hook
can set additional variables on the input.payload. Inputs are also deeply integrated with Validation Rules, Masks, and can even be used with Value Mappings.
Output
: Integration response
Output
: Integration responseIntegration outputs can be mutated throughout the life of the integration.
Integration outputs are often overwritten within calls to the service request. The
on_success_hook
,on_failure_hook
, and thefinally_hook
are the most appropriate places to update the output.
Integration outputs are useful for error handling as well as returning specific payloads or status to calling systems.
Asynchronous integrations are a unique case and return an output immediately marking the start of the integration process. Required outputs to corresponding systems must be handled explicitly within the appropriate hooks during the integration.
State
Integrations have a success / failure state. The control of this state is flexible and can be triggered at will throughout the life of the integration using the special function end. Both service requests and validation rules contain the ability to set the integration into a failure state.
Service Requests
The building blocks of an integration. Service requests are fired off in order to perform operations with connected systems. Each service is associated with an adapter creating a call to the service using the provided adapter configs. Services include external API calls and internal file transformations.
Adapter Request
the prepared request. It is available within the integration from the Service Request's{formula_variable}.request
.Adapter Response
the adapter system response. It is available within the integration from the Service Request's{formula_variable}.response
.Adapter Success
the state of the adapter service call.Adapter Messages
Optional message component of the adapter. This field is generally used for return adapter specific error messages.
Service Requests have the ability to be fired off as a list of service requests to the same system using the call_for_each
field. Given an iterable, the call_for_each
will generate
sridx: index of the service request iterable
sritem: value of the service request iterable
call_for_each | formula_variable |
---|---|
[ {"name": "sr1"}, { "name": "sr2"} ] | people_service |
Which means during an integration run, the current service request is equivalent to:
Field Mappings
Field mappings define the structure of the service request. Adapters generally have a few required field mappings such as service_path
and method
.
Field mappings contain the ability to be applied multiple times via an iterable provided to include_for_each
. This exposes the following variables to be used within the field mapping code blocks.
fidx: index of the field mapping iterable
fitem: value of the field mapping iterable
Example:
include_for_each | Value | Field |
---|---|---|
["test", "test2"] | fitem | fm_body[fidx].test_key |
Generates the following request payload
Value Mapping Sets
Value Mapping Sets define a collection of Value Mappings. These are tied to an integration and can be accessed anywhere within the integration via the map_value special function.
Value Mappings
Value mappings mutate outgoing request values from one type to another. Common use cases are for assigning statuses from a numeric value to a string representation.
Validation Rules
Validation Rules runs validation for input and response data. If a response or requested input payload fails to pass the validation rule, the integration can be put into a failure state or have other logic run based on the abort_on_failure
field. Similarly to Field Mappings and Service Requests, Validation rules can also be run multiple times with the apply_to_each
field. These fields use the context of vridx and vritem for the given iterable.
apply_to_each | ||
---|---|---|
vridx | ||
Masks
To hide sensitive information throughout the life of the integration. These are applied to either integration inputs or service request responses. Masked information will be replaced with the following "XXXXXXXXXXXX".
Run History
Each integration run creates a unique Run History set for an integration which encapsulates a set of Run History Items detailing the exact steps taken within an integration. Each service request, historize statement, or other additional logging calls will generate a Run History Item.
Last updated