Open Integration Hub is an open and community driven project. Customization and individual implementation come with it’s nature of being a generalized framework. This also results in integration components, which are open sourced by their creators, but sometimes adjusted to fit their individual needs.

In order to make modification of such components to fit the current framework version easier, this document will list some common changes you may see.

Elastic.io Components

As one of the founding partners of the framework and contributor of several core services, elastic.io also provides many helpful integration components. Those are tailored for the elastic.io platform. To run them under the “vanilla Open Integration Hub”, check and adjust the following:

Must Have

Ferryman Dependency

Ferryman is the Node.js SDK of the Open Integration Hub. Its main role is allowing smooth communication between the component and the Open Integration Hub platform. You’ll need to add ferryman to your component’s dependencies:

"dependencies": {
  "@openintegrationhub/ferryman": "^1.1.5"
}

Elastic.io’s equivalent to the ferryman is the elasticio-sailor. If you only want to use the component in the Open Integration Hub platform, you can remove it, as well as any other elasticio-specific dependencies.

Example:

    "elasticio-node": "0.0.9",
    "elasticio-rest-node": "1.2.6",
    "elasticio-sailor-nodejs": "2.6.18",
}

Message Format

The messaging format has been adjusted over time, most recently with issue#1078.

In practice, the changes boil down to: Removed id key Removed headers key Removed body key, moved its contents to base level Content that was formerly in body.data is now in just data Content that was formerly in body.meta is now in metadata

Most connectors used to rely on a function called messageWithBody() or newMessage() to format things for the old format, which will no longer be necessary.

You may also find this PR helpful.

Dockerfile

Elastic.io uses a different mechanism to build images and deploy components for their platform. You need to add a dockerfile.

You can just copy and adjust a Dockerfile from an existing component under the Open Integration Hub Organization on GitHub.

Importantly, the Dockerfile’s entrypoint will need to point to ferryman’s runGlobal.js script. An easy way to achieve this is to point your components npm start script to it, then simply call npm start from the Dockerfile. For an example, you can refer to the contacts connector template:

Go to the template or jump straight to the line of code

IDs

In order to identify data records across the framework you will have to implement additional UIds (Check ID Linking in Open Integration Hub):

/*
      This metadata is used to identify the current object within the OIH and your application
      "oihUid" uniquely identifies it within the OIH itself
      "recordUid" is used to identify it within your application
    */
    const { oihUid, recordUid } = msg.metadata;

Please make sure that upsertFunctions point towards metadata.recordUid. For your reference please also check the general template.

For ID-linking purposes you may also want to insert an applicationUid, as seen for example here.

Optional

Transform Functions

In order to transform data from one schema to another you can either build a separate Transformer Component or use the transform function within the ferryman.

You will have to implement these functions for each action and trigger like shown in the general template

Stuff you can delete

• verifyCredentials.js is only needed for the elastic.io and not for the Open Integration Hub.
• credentials within the component.json is only needed for elastic.io UI. Depending on your implementation you may want to keep it. With regards to Open Integration Hub, it is not needed.