Adapters and Connectors Design

Vantiq Adapters

Adapters expose data sets from 3rd party systems to Vantiq and control capabilities from those 3rd party systems to Vantiq.

Adapter Design

To support importing external data in real time, data adapters define data types that originate from 3rd party systems and provide rules to transform the data from the external form arriving through a specific connector into the appropriate Vantiq data type.

To support control actions, adapters define procedures that provide a VAIL API to trigger the control actions. Those procedures create control messages to send to the 3rd party system.

Adapters are responsible for data transformations between the Vantiq representations and the 3rd party system representations of data. However, adapaters do not provide specific connectivity to any external system. Adapters depend on connectors and may require specific connectors to function properly.

Repository

Each adapter resides in its own GitHub repository. Repositories are named using the following pattern:

vantiq-adapter-<xxx>

where <xxx> is a unique name for the adapter (e.g. vantiq-adapter-salesforce).

Components

In general, adapters consist only of Vantiq artifacts that support the import of data sets or triggering of specific control actions.

Inbound Data

Any inbound data to a specific adapter must be processed by a rule that listens on the topic:

/system/adapter/inbound/<type>

where <type> is a unique name for the Vantiq data type. As the data type within Vantiq must be globally unique, the data type name includes the 3rd party system name, e.g. Salesforce_Account.

The adapter is responsible for defining the data type and the inbound data rule creates one (or more) instances of the data type and saves it allowing the Vantiq platform to trigger data type rules.

Control Actions

Controls are exposed as Vantiq procedures with the given name:

Control_<system>_<action>(args)

where <system> is the unique name for the 3rd party system and <action> is the unique name for the action, e.g., Control_Salesforce_CreateCase. The arguments to the procedure are action-dependent.

The adapter is responsible for building the control message from the arguments and triggering the action by sending the control message to a supported connector.

Vantiq Connectors

Connectors provide system-to-system connectivity between Vantiq and external systems. A connector may provide connectivity to a specific end system or provide connectivity to an integration service that gives access to a collection of 3rd party systems.

Connector Design

Connectors typically support inbound requests either through publishing to a specific topic, which may be done through a REST API call or through a Vantiq Source. Connectors typically support outbound requests through a Vantiq Source (e.g. outbound REST call).

Connectors are responsible for publishing messages of a given type on a specific topic (i.e. inbound requests) or receiving messages on a specific topic to send to a third party system. The actual processing of those messages are the responsibility for adapters.

Connectors typically require an external component that is installed in the 3rd party system to facilitate the connectivity.

Repository

Each connector resides in its own GitHub repository. Repositories are named using the following pattern:

vantiq-connector-<xxx>

where <xxx> is a unique name for the connector (e.g. vantiq-connector-mulesoft).

Components

In general, connectors consist of code that provides the integration support on the 3rd party system as well as Vantiq artifacts that support the Vantiq side of the integration. Each connector repository has the following structure:

Directory Description
external The code/packages that are required on the 3rd party side
vantiq The artifacts required on Vantiq side to support the integration. The directory structure supports being imported through the Vantiq CLI import command.

Inbound Request Processing

Any inbound requests to a specific connector must be processed by a rule that listens on the topic:

/system/connector/<system>/inbound

where <system> is a unique name for the 3rd party system.

The 3rd party system may publish directly to this topic using the REST API. Alternatively, the connector may provide additional rules or procedures that allow requests to flow into the system. However, any separate mechanism must only transform the request to trigger this topic and must not trigger other downstream logic in the system.

Any events on this topic are processed by the connector rule with the name:

Connector_<system>_inbound

This connector rule is responsible for transforming the message into a form that is consumable by adaptersand trigger the appropriate adapter through their event topic.

Outbound Message Processing

Any outbound messages on a specific connector must be processed by a rule that listens on the topic:

/system/connector/<system>/outbound

where <system> is a unique name for the 3rd party system.

The connector may publish this message through a Vantiq Source (e.g. outbound REST API on the 3rd party system). The connector rule responsble for handling control messages must be named:

Connector_<system>_outbound