Deliver Data Step

The Deliver Data step lets you write data collected during a workflow back to one or more of your organization's datasets. For each dataset, you define which entity to write to, what operation to perform, and how workflow fields map to dataset properties.

Datasets

A Deliver Data step contains one or more dataset operations.

name	type	required	description
`datasetId`	string	yes	The `id` of the target dataset, as returned by the Data Set Management endpoints.
`selectedSearchDataStep`	string	no	The `description` of a Data Search step that provides a record to update.
`stepDatasetInstanceId`	string	yes	A stable unique identifier you assign to this dataset entry within the step. It is used internally to link field mappings to their dataset. Any non-empty string works; the Streamline UI generates a short random value (e.g. `"fg4z6aiy"`). Must not change once field mappings have been created against it.
`entities`	array	yes	One or more entity operations. See Entities below.

Entities

Each entity operation targets a specific entity type within the dataset.

name	type	required	description
`linkId`	string	no	The `linkId` of a traversal route entry in the dataset, used when writing to a linked (non-primary) entity. Corresponds to the same `linkId` used as a key in the Data Search step's `linkedEntitiesFilters`.
`entityId`	string	yes	Identifier of the entity type to write to.
`operation`	string	yes	Operation to perform. See Operations below.
`mappings`	array	yes	Field mappings from workflow data to entity properties. See Mappings below.

Operations

INSERT: Create a new record in the dataset.
UPDATE: Modify an existing record (requires a key field match).
UPSERT: Insert if no matching record exists; update if one does.
SKIP: Perform no operation—useful in conditional branches.

Mappings

Each mapping connects a workflow value to a field in the dataset entity.

name	type	required	description
`fieldId`	string	yes	The `id` of the dataset field to write to, as returned by the Data Catalog field endpoints.
`value`	string	yes	The value to write. Supports mapping placeholders (e.g. `{{`Form`.`email`}}`).
`isKeyField`	boolean	yes	Whether this field is part of the entity's primary key (used for UPDATE/UPSERT).
`primitiveType`	string	yes	Primitive data type hint: `string`, `number`, or `boolean`.
`complexType`	string	no	Complex type hint for advanced transformations (e.g. `email`, `datetime`, `integer`).

Examples

Let's start with the simplest valid configuration: inserting a single record with one field.

{
  "datasets": [
    {
      "datasetId": "ds1b2c3d-e5f6-7890-1234-567890abcdef",
      "selectedSearchDataStep": null,
      "stepDatasetInstanceId": "ab1c2d3e",
      "entities": [
        {
          "linkId": null,
          "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
          "operation": "INSERT",
          "mappings": [
            {
              "fieldId": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
              "value": "[email protected]",
              "isKeyField": true,
              "primitiveType": "string",
              "complexType": null
            }
          ]
        }
      ]
    }
  ]
}

Building on that, here's a more complete example. It upserts a customer record using mapped form values (including a combined name and a numeric field), and also inserts an audit log entry in the same step.

{
  "datasets": [
    {
      "datasetId": "ds2b3c4d-e5f6-7890-1234-567890abcdef",
      "selectedSearchDataStep": "Search Customers",
      "stepDatasetInstanceId": "ab1c2d3e",
      "entities": [
        {
          "linkId": null,
          "entityId": "e2b3c4d5-e5f6-7890-1234-567890abcdef",
          "operation": "UPSERT",
          "mappings": [
            {
              "fieldId": "f2b3c4d5-e5f6-7890-1234-567890abcdef",
              "value": "{{`Form`.`customer_id`}}",
              "isKeyField": true,
              "primitiveType": "string",
              "complexType": null
            },
            {
              "fieldId": "f3c4d5e6-e5f6-7890-1234-567890abcdef",
              "value": "{{`Form`.`first_name`}} {{`Form`.`last_name`}}",
              "isKeyField": false,
              "primitiveType": "string",
              "complexType": null
            },
            {
              "fieldId": "f4d5e6f7-e5f6-7890-1234-567890abcdef",
              "value": "{{`Form`.`email`}}",
              "isKeyField": false,
              "primitiveType": "string",
              "complexType": "email"
            },
            {
              "fieldId": "f5e6f7a8-e5f6-7890-1234-567890abcdef",
              "value": "{{`Form`.`subscriptions.length`}}",
              "isKeyField": false,
              "primitiveType": "number",
              "complexType": "integer"
            },
            {
              "fieldId": "f6f7a8b9-e5f6-7890-1234-567890abcdef",
              "value": "true",
              "isKeyField": false,
              "primitiveType": "boolean",
              "complexType": null
            }
          ]
        },
        {
          "linkId": null,
          "entityId": "e3c4d5e6-e5f6-7890-1234-567890abcdef",
          "operation": "INSERT",
          "mappings": [
            {
              "fieldId": "f7a8b9c0-e5f6-7890-1234-567890abcdef",
              "value": "{{`Session metadata`.`__session_start_date`}}",
              "isKeyField": false,
              "primitiveType": "string",
              "complexType": "datetime"
            },
            {
              "fieldId": "f8b9c0d1-e5f6-7890-1234-567890abcdef",
              "value": "customer_updated",
              "isKeyField": false,
              "primitiveType": "string",
              "complexType": null
            }
          ]
        }
      ]
    }
  ]
}