Custom data

Background

Each Integration Platform record type has a set of fields representing that particular record and its properties, like Product, Order, Invoice all have their own pre-defined properties. The Integration Platform record can be interchanged with remote systems via Connection´s. Each Connection has transformation logic (via its inherited Connector to interpret that particular remote system’s representation of the record into a Integration Platform specific record. In both directions.

When data exists on a record in an remote system, there might be situations where the data has no corresponding logical placement in the Integration Platform record. In such cases Custom data can be used.

Illustration

If we zoom in between the Connector and Manipulator chain in the below example we notice an Order record. For example, we can look at importing orders from remote system:

1. Integration Platform reads orders from remote systems, via Connections.
2. Connections interpret the order from the remote system into an Integration Platform record.
3. Some additional data not possible to hold in the generic Integration Platform record are stored as Custom data.
4. The record is then processed by the Manipulator chain.
5. Finally the order is stored in the Integration Platform.

Technical details

Many records allow custom data to be attached to them. The custom data is formatted as a dictionary, where the dictionary key is the custom data field and the value is a record containing information about the field.

Custom data is separated into modules, and modules themselves have different keys. If a custom key is needed the moduleId must begin with x- so as not to cause conflicts. The moduleId and key must not contain pipe (|) characters.

The dictionary key used in the customData field is comprised of connectionId + | + moduleId + | + key.

Field descriptions

The connectionId, moduleId and key field are all case sensitive.

connectionId (optional)

If this item is specific to a particular connection only. (This value is optional)

moduleId (mandatory)

The module id this record belongs to.

key (mandatory)

Unique key within the module.

type (mandatory)

The data type of the value. Might be one of the following;

• string
• bool
• integer
• decimal
• json

value (mandatory)

The specific value for the custom data to hold.

Anatomy by example

Just to give a more technical example how custom data might look like one can look at the following example. Each available custom data record is living inside the customData node with the unique dictionary key for access.

{
    "customData": {
        "5377568eb7e165e3b38af6eece4a0001|connector.woocommerce|meta._wc_klarna_environment": {
            "connectionId": "5377568eb7e165e3b38af6eece4a0001",
            "moduleId": "connector.woocommerce",
            "key": "meta._wc_klarna_environment",
            "type": "string",
            "value": "test"
        },
        "5377568eb7e165e3b38af6eece4a0001|connector.woocommerce|meta._wc_klarna_country": {
            "connectionId": "5377568eb7e165e3b38af6eece4a0001",
            "moduleId": "connector.woocommerce",
            "key": "meta._wc_klarna_country",
            "type": "string",
            "value": "SE"
        }
    }
}

Best practises

An API-integration should avoid modifying custom data that has been created by another integration. The API-integrations are allowed to read all custom data but should only update custom data owned by its own API-connection.

It is highly recommended to use the endpoints /customdata e.g /order/{localId}/customdata to modify a custom data field. This endpoint will update the custom data if the key already exists, otherwise it will create a new custom data value.