Link

Actions and Triggers

As laid out in the development example, actions and triggers are the part of any component, that really defines what you can do with it. Most parts like credentials or the component.json are fairly standard and reusable. Actions and triggers however have to be specifically adapted to your solutions API.

This guide helps to classify your API and derive a set of functionalities that can be performed by an Adapter. We focus on the Adapter, as the Transformer is even simpler. So once you understand the Adapter, the rest is a piece of cake.

The Adapter is a single, reusable piece of functionality that stands between your solution’s API and the Transformer. To enable communication between you and Open Integration Hub, the Adapter syntactically normalizes and transforms your applications data into a JSON object. For example, transforming CSV-, JS-, XML- files into JSON objects. The Adapter exposes the endpoint of your SaaS solution’s API via pre-defined actions and triggers. Those make sure that the four basic operations of persistent storage are available, such as create, read, update and delete a file.

Table of Contents

Given an API how should an Adapter behave

The expected actions and triggers of an adapter depend on the behavior of the API. If the API supports CRUD operations the following diagram explains which triggers and actions should exist in the adapter. The triggers and actions should aim at covering 100% of the objects provided by the API.

Note: Although RESTful APIs are preferred, the API does not necessarily have to be a REST API. It is possible for the above functionality to be exposed via a SOAP API, a SQL (or other) DB connection, etc.

Is the list of business objects dynamic?
Is the list of business objects dynamic?
XOR
XOR
Does the API support webhooks?
Does the API support webhooks?
Is the structure of objects dynamic?
Is the structure of objects dynamic?
Does the API support webhooks?
Does the API support webhooks?
Does the API support webhooks?
Does the API support webhooks?
XOR
XOR
Case 5
Case 5
Case 6
Case 6
XOR
XOR
Case 3
Case 3
Case 4
Case 4
XOR
XOR
Case 1
Case 1
Case 2
Case 2
XOR
XOR
YES
YES
NO
NO
YES
YES
NO
NO
YES
YES
NO
NO
YES
YES
NO
NO
YES
YES
NO
NO

Questions

Question 1: Is the list of business objects dynamic

Some systems have a fixed list of objects (and corresponding API endpoints) which exist in the system. Other systems allow users and admins to create new types of objects (which result in the system dynamically creating API endpoints). In this case, it is common for the system to provide an API endpoint which can provide a list of all dynamic objects as well as the structure of every object.

If the system has a fixed list of objects, then the adapter developer can provide a hardcoded list of objects that the adapter can interact with. If the list of objects is dynamic and it is possible to use the API to learn the list of existing objects, the developer should write code to fetch that list and provide that as dynamic configuration. Furthermore, in the case of a dynamic list of business objects, since the list of objects is unknown, the structure of objects is also unknown. This means that an answer of yes to Question 1 implies an answer of yes to Question 2.

Question 2: Is the structure of objects dynamic

As explained above, an answer of yes to Question 1 implies an answer of yes to Question 2.

Some systems have a fixed list of fields on every object. Other systems allow users and admins to customize the structure of each object. In this case, it is common for the system to provide an API endpoint which can provide the structure of any object in the system.

If the objects have a fixed structure, then the adapter developer can hard code the schema of the objects produced. Otherwise, the developer should write code to fetch the dynamic structure of that object.

Question 3: Does the API support Webhooks

Some external systems support the concept of Webhooks. The idea of a hook is that when a change occurs to an object in that external system, that external system proactively informs other systems about this change. Webhooks are hooks where the information is transferred by having the system reporting the change make a REST API call to the system making the change. See here for more information about elastic.io webhooks. This can be more efficient (both in terms of speed and machine resources) than having a scheduled job periodically make calls for changes that may or may not have occurred.

Desired Adapter Behavior

Case 1

  • The list of business objects is dynamic
  • The structure of the objects is dynamic (Implied by above statement)
  • The API supports webhooks

Triggers

  • getObjectsPolling including functionality to
  • supply the list of readable objects
  • getObjectsWebhook including functionality to
  • supply the list of readable objects
  • supply the structure of the incoming objects
  • getDeletedObjectsWebhook including functionality to
  • supply the list of deletable objects

Actions

  • upsertObject including functionality to
  • supply the list of writable objects
  • supply the structure of the incoming object
  • deleteObject including functionality to
  • supply the list of deletable objects
  • lookupObjectByField including functionality to
  • supply the list of readable objects
  • supply the list of fields that can be searched

Case 2

  • The list of business objects is dynamic
  • The structure of the objects is dynamic (Implied by above statement)
  • The API does not support webhooks

Triggers

Actions

  • upsertObject including functionality to
  • supply the list of writable objects
  • supply the structure of the incoming object
  • deleteObject including functionality to
  • supply the list of deletable objects
  • lookupObjectByField including functionality to
  • supply the list of readable objects
  • supply the list of fields that can be searched

Case 3

  • The list of business objects is static
  • The structure of the objects is dynamic
  • The API supports webhooks

Triggers

Actions

  • upsertObject including
    • the static list of writable objects
    • functionality to supply the structure of the incoming object
  • deleteObject including
    • the static list of deletable objects
  • lookupObjectByField including functionality to
    • the static list of readable objects
    • supply the list of fields that can be searched

Case 4

  • The list of business objects is static
  • The structure of the objects is dynamic
  • The API does not support webhooks

Triggers

Actions

  • upsertObject including
    • the static list of writable objects
    • functionality to supply the structure of the incoming object
  • deleteObject including
    • the static list of deletable objects
  • lookupObjectByField including functionality to
    • the static list of readable objects
    • supply the list of fields that can be searched

Case 5

  • The list of business objects is static
  • The structure of the objects is static
  • The API supports webhooks

Triggers

Actions

  • upsertObject including
    • the static list of writable objects
    • the static structure of the incoming object
  • deleteObject including
    • the static list of deletable objects
  • lookupObjectByField including functionality to
    • the static list of readable objects
    • the static list of fields that can be searched

Case 6

  • The list of business objects is static
  • The structure of the objects is static
  • The API does not support webhooks

Triggers

Actions

  • upsertObject including
    • the static list of writable objects
    • the static structure of the incoming object
  • deleteObject including
    • the static list of deletable objects
  • lookupObjectByField including functionality to
    • the static list of readable objects
    • the static list of fields that can be searched

Table of contents