The Datamapper can be thought of as a key-value store for cross-system references. This can be useful for long running workflows that need to handle both creating and updating across external systems.

Use Cases

Imagine you are managing an ecommerce integration into an ERP system. You have a workflow that creates a new product in the ERP system, and then updates the product with additional information from the ecommerce system when those updates happen at a later date.

If Switchboard isn’t aware of what products are the same product across both systems - how can it know which product to update? This is where the datamapper comes in.

How it Works

The Datamapper has two modes - Check and Put. The Check mode is used to check if a reference exists in the Datamapper storage. The Put mode is used to store a new reference in the Datamapper.

If in Check mode - the Datamapper has two outputs - one for if the reference exists, and one for when it doesn’t:

Multiple outputs if reference exists

If in Put mode - the Datamapper has one output - this is to allow the flow to carry on after creating the reference.

Configuration

Value Type is the expected type of value to be saved.

A single saved reference in the Datamapper consists of a Key and a Value.

Key

The Key is typically the source system’s ID for the entity to be saved.

App Version should be defined as something unique to your organisation - for example: ecommerce-app.v1. This allows this reference to also be used across other boards in your integration - if this app is used elsewhere.

Kind should be the type of entity being saved - for example: product. This allows you to save references for multiple types of entities in the same Datamapper app version.

Value From - this is the actual value from your board data that you wish to save a reference for. This could be a field from a previous action, or a value from a previous step in your workflow. Typically this will be an ID.

Key configuration form

Value

The Value is only available to set in Put mode - seeing as we are creating a new reference in the Datamapper.

The configuration for Value is the same as Key - this is the partner stored against the key and will typically be the ID of your entity in your target system.

For example, App Version might be erp-app.v1, Kind might be Item, and Value From might be the ID of the Item in your ERP system.

Value configuration form

Using Datamapper with Selectors

The output of the data mapper will be on object in the form of:

{
  "key": {
    "appVersion": "string",
    "kind": "string",
    "value": (Selected Value)
  },
  "value": {
    "appVersion": "string",
    "kind": "string",
    "value": (Value Type)
  }
}

This allows you to use the saved values in further selectors also.

FilterBatch