Payload conversion

The payload conversion is a script that is used to transform an arbitrary received payload to measurements that are ingested in the Blockbax Platform. A payload conversion has an expected payload format and is defined as a plain JavaScript function.

Payload formats

Currently, four different payload formats are supported by Inbound Connectors. Payloads must always be sent to the inbound connector as bytes, but the format specifies how these bytes are decoded and passed to the payload conversion function.

Payload conversion script

The payload conversion script is a user-defined script that is used to transform the decoded payload to measurements that are to be ingested by the Blockbax Platform. Additionally, log messages can be generated to provide feedback to the user from the payload conversion script.

The payload conversion is defined as a JavaScript (ECMAScript 2022 compliant) function with required signature convertPayload(payload, context) { ... }. The web client provides a convenient editor with auto-completion and method signatures on hover. An example script is shown below:

1
2
3
4
5
6
7

function convertPayload(payload, context) {
  const ingestionIdPrefix = payload.id + "$";
  const timestamp = date(payload.timestamp);
  for (const [key, value] of Object.entries(payload.data)) {
    context.addMeasurement(ingestionIdPrefix + key, value, timestamp);
  }
}

This script takes a JSON type payload and uses a top level property for prefixing the ingestion ids. The timestamp for all measurements contained by the payload is parsed from the top level object as well. The script then iterates over all key value pairs in the data field to ingest them as measurements.

Payload parameter

The payload parameter is the decoded payload sent to the inbound connector. This parameter can be either a JavaScript object, a string or an ArrayBuffer. The type of the payload depends on the specified payload format. The payload object is immutable and will throw a TypeError on modification.

Context parameter

The context parameter is an object used to pass measurements and logs to the Blockbax Platform. The context parameter cannot be modified. Its functionalities are described below:

Optionally when the MQTT subscribe connector is selected, it will also have the following functionality:

Library functions

Several library functions are available when writing your conversion function to make writing a conversion easier and more concise. The available functions are described below.

Testing payload conversion scripts

Payload Conversion scripts can be tested in the Blockbax Web Client. Depending on the payload type a test payload can be provided, and the conversion script is then executed for that payload. For the JSON, CBOR, String and Avro types, a string can be provided as payload. For the CBOR and Bytes type, a hex string can be provided. The test payload can be saved with the conversion script. This allows doing basic regression testing when making changes to the script and verifying that the output measurements are correct for that payload. When the conversion script is executed for the payload the web client will show the measurements and logs that were produced by the payload conversion. Please note that this is only a visual representation of the outcome of the payload conversion, no actual measurements are ingested. Any problems with the script or resulting measurements are shown as log messages.