Ferryman Extensions

This library extends the functionality of the @openintegrationhub/ferryman library used in Open Integration Hub.

Installation

npm install @blendededge/ferryman-extensions

Usage

Passthrough Functionality Configuration

The wrapper() function can be used to enable passthrough functionality in an Open Integration Hub (OIH) flow. Passthrough allows a component to selectively forward its incoming message in addition to the standard output for the step.

There are two settings in the node's fields object related to passthrough functionality:

• enable_passthrough: Allows passthrough data from the previous step to continue flowing through this node
• passthrough_name: Specifies a name under which to save the current step's incoming message. If present the data from this step will be saved; if not present it will not be saved.

Passthrough Functionality Code

The library itself will be used within the code for the relevant component. The following example uses the Blended Edge REST Api Component. Setup details may differ depending on the component used, but should follow roughly the same pattern.

Within the processAction() function, invoke the wrapper() function, passing in this and the arguments to processAction(). The wrapper() function will return a wrapped instance of the Ferryman class. Use this wrapped instance throughout the rest of the processAction() function instead of the original unwrapped instance. (The this object is the Ferryman class.)

Example:

const { wrapper } = require('ferryman-extensions');
const { processMethod } = require('../utils.js');

function processAction(msg, cfg, snapshot, msgHeaders, tokenData) {
  // add the following line to wrap the Ferryman instance
  const wrapped = wrapper(this, msg, cfg, snapshot, msgHeaders, tokenData);

  // original version:
  // return processMethod.call(this, msg, cfg, snapshot);

  // updated version:
  return processMethod.call(wrapped, msg, cfg, snapshot);
}

exports.process = processAction;

Attachment Storage Processor

The AttachmentStorageProcessor module can be used to enable attachment storage functionality in an Open Integration Hub (OIH) flow. Attachment storage allows a component to save/retrieve attachments to/from the attachment storage service.

OpenTelemetry Configuration

Configure the OpenTelemetry tracing functionality through environment variables set in the component.

Settings:

• ELASTICIO_OTEL_CONSOLE_EXPORTER - whether to export spans to the console, TRUE or FALSE
  • default: FALSE
• ELASTICIO_OTEL_JAEGER_URL - URL of Jaeger collector
• ELASTICIO_OTEL_OTLP_EXPORTER_URL - URL to send spans to using OpenTelemetry Protocol
• ELASTICIO_OTEL_OTLP_EXPORTER_CONCURRENCY_LIMIT - concurrency limit when using OTLP exporter
  • default: 10
• ELASTICIO_OTEL_SERVICE_NAME - the service name, string
  • default: COMPONENT:UNKNOWN
  • suggested naming convention: COMPONENT:<component-type>, e.g. COMPONENT:JSONATA, COMPONENT:REST
• ELASTICIO_OTEL_TRACER_NAME - the name to use for the tracer
  • default: ferryman-extensions
• ELASTICIO_OTEL_OTLP_AUTHORIZATION_TOKEN - Value for the Authorization header sent to the OpenTelemetry OTLP endpoint. You should include the prefix as well as the token (Ex. Bearer <my token>).
• OTEL_EXCLUDE_STEP_OUTPUT - Disables logging the message emitted to the next step in the OpenTelemetry span event. Note: The event will still be logged, but will not include the message data
  • default: false
• OTEL_EXCLUDE_STEP_INPUT - Disables logging the message received by a component step from being emitted to the span as an attribute. Note: the attribute will still be added, but will not include the incoming message data Note: When setting the environment variables directly on the component image (setting in Dockerfile or with kubectl set env) use the full environment variable name beginning with ELASTICIO_. If support is added to OIH to allow components to have customized environment variables you may need to remove the ELASTICIO_ prefix from the environment variable names. (Environment variables set by the component orchestrator add ELASTICIO_).

With https://github.com/openintegrationhub/openintegrationhub/pull/1493 you will be able to specify these variables in the component repository under the descriptor property.

With https://github.com/openintegrationhub/openintegrationhub/pull/1494 an issue will be fixed where the first node rebounding creates separate traces (not an issue for subsequent steps).

Note: All of the processAction arguments must be passed into wrapper() for OpenTelemetry functionality to work.

const wrapped = await wrapper(this, msg, cfg, snapshot, msgHeaders, tokenData);