Data Search Step

The Data Search step lets you query one or more of your organization's datasets during a workflow. You define what to search for, how results are selected (automatically or by the user), and which fields to display. The selected record is then available for mapping in later steps.

You can also keep every matching record instead of a single one (see Repeating Records), and retrieve files linked to the found records (see File search).

Datasets

A Data Search step contains one or more dataset configurations.

Setup

The setup object defines how the dataset is queried and how a result is selected.

Selection modes

• AUTOMATIC: The first matching record is selected without user input.
• MANUAL: The user chooses from the matching results before the workflow continues.

Search criteria

Search criteria define how results are filtered and sorted.

Linked entity filters

Datasets can include more than one entity — for example, an "Account & Contacts" dataset might have Accounts as the primary entity and Contacts as a linked entity. primarySearchCriteria filters the primary entity. linkedEntitiesFilters lets you apply additional search criteria to each linked entity in the dataset.

linkedEntitiesFilters is a plain object where:

• Each key is the linkId of a linked entity, as found in the dataset's linkAliases array (returned by GET /v1/activation/dataset/{datasetId}).
• Each value is a search criteria object with the same structure as primarySearchCriteria — sortFieldId, sortDirection, joinLogic, filters, and optionally fileToEntityConfigs. The fieldId values inside filters must belong to that linked entity, not the primary entity.

Each linked entity also accepts its own Repeating Records settings:

If the dataset has no linked entities, or you do not need to filter them, pass an empty object: "linkedEntitiesFilters": {}.

Filters

Each filter narrows the search to records that match a specific condition.

fieldId, operator, and value accept null so a filter can be saved before it is fully set up. A filter needs all three to narrow the search.

Operators

The available operators depend on the scalar type of the field being filtered. You can check the field's type from the Data Catalog field endpoints.

• EQUALS: Exact match. Available for all field types.
• NOT_EQUALS: Not equal to the value. Available for all field types.
• CONTAINS: Field value contains the string as a substring. Available for text fields only.
• STARTS_WITH: Field value begins with the string. Available for text fields only.
• ENDS_WITH: Field value ends with the string. Available for text fields only.
• GREATER_THAN: Field value is greater than the filter value. Available for number, date, and time fields.
• GREATER_THAN_OR_EQUALS: Greater than or equal. Available for number, date, and time fields.
• LESS_THAN: Field value is less than the filter value. Available for number, date, and time fields.
• LESS_THAN_OR_EQUALS: Less than or equal. Available for number, date, and time fields.

Repeating Records

By default, a Data Search step passes a single record to later steps. Set repeatedRecords to true to keep every matching record instead. The results become Repeating Records that later steps can map as a collection — for example, to write one record per result in a Deliver Data step, or to build an array in an Outbound Webhook body.

You can enable Repeating Records at two levels:

• Primary entity — setup.repeatedRecords keeps every matching primary record.
• Linked entity — repeatedRecords inside a linkedEntitiesFilters entry keeps every matching linked record for each primary record.

Use maxResults to cap how many records are kept. maxResults is accepted even when repeatedRecords is false, but it has no effect in that case.

File search

Use fileToEntityConfigs to retrieve files linked to the records the step finds — for example, documents attached to a patient record. You can add file searches to primarySearchCriteria (files linked to the primary entity) or to any linkedEntitiesFilters entry (files linked to that linked entity).

Each enabled file search becomes a file field (array<file>) that later steps can map. The field's id is the config's rowId, and its label is mappingLabel.

File search configuration

Each item in filters combines one or more conditions:

Results

The results object controls how matching records are presented.

Results fields

Share notifications

A participant can share the session by email or SMS from the Data Search step — for example, to send the search results page to a colleague. shareNotificationSettings sets the default content of those messages. When the participant provides their own subject, message, or button text, theirs is used instead. Any setting you leave out falls back to Streamline's default.

The email object accepts:

The sms object accepts a single optional message string: the text message body.

Examples

Let's start with the simplest valid setup: one dataset, automatic selection, no filters, and all fields shown by default.

{
  "datasets": [
    {
      "datasetId": "ds1b2c3d-e5f6-7890-1234-567890abcdef",
      "setup": {
        "required": true,
        "selectionMode": "AUTOMATIC",
        "primarySearchCriteria": {
          "sortFieldId": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
          "sortDirection": "ASCENDING",
          "joinLogic": "AND",
          "filters": []
        },
        "linkedEntitiesFilters": {}
      },
      "results": {
        "showConfirmationPage": false,
        "tableMode": "DEFAULT",
        "fields": []
      }
    }
  ]
}

Building on that, here's a more complete example with multiple filters (including a mapped value from a previous form step), a linked entity filter, manual selection, a custom results table, and share notification defaults.

{
  "datasets": [
    {
      "datasetId": "ds2b3c4d-e5f6-7890-1234-567890abcdef",
      "setup": {
        "required": true,
        "selectionMode": "MANUAL",
        "primarySearchCriteria": {
          "sortFieldId": "f2b3c4d5-e5f6-7890-1234-567890abcdef",
          "sortDirection": "ASCENDING",
          "joinLogic": "AND",
          "filters": [
            {
              "fieldId": "f3c4d5e6-e5f6-7890-1234-567890abcdef",
              "operator": "EQUALS",
              "value": "{{`Form`.`email`}}"
            },
            {
              "fieldId": "f4d5e6f7-e5f6-7890-1234-567890abcdef",
              "operator": "EQUALS",
              "value": "active"
            },
            {
              "fieldId": "f5e6f7a8-e5f6-7890-1234-567890abcdef",
              "operator": "GREATER_THAN_OR_EQUALS",
              "value": "2024-01-01"
            }
          ]
        },
        "linkedEntitiesFilters": {
          "l1b2c3d4-e5f6-7890-1234-567890abcdef": {
            "sortFieldId": "f6f7a8b9-e5f6-7890-1234-567890abcdef",
            "sortDirection": "DESCENDING",
            "joinLogic": "OR",
            "filters": [
              {
                "fieldId": "f7a8b9c0-e5f6-7890-1234-567890abcdef",
                "operator": "NOT_EQUALS",
                "value": "cancelled"
              },
              {
                "fieldId": "f8b9c0d1-e5f6-7890-1234-567890abcdef",
                "operator": "GREATER_THAN",
                "value": "100"
              }
            ]
          }
        }
      },
      "results": {
        "showConfirmationPage": true,
        "tableMode": "CUSTOM",
        "fields": [
          {
            "fieldId": "f9c0d1e2-e5f6-7890-1234-567890abcdef",
            "customLabel": "Customer ID"
          },
          {
            "fieldId": "f0d1e2f3-e5f6-7890-1234-567890abcdef",
            "customLabel": "First Name"
          },
          {
            "fieldId": "f2b3c4d5-e5f6-7890-1234-567890abcdef",
            "customLabel": "Last Name"
          },
          {
            "fieldId": "f3c4d5e6-e5f6-7890-1234-567890abcdef",
            "customLabel": "Email Address"
          },
          {
            "fieldId": "f4d5e6f7-e5f6-7890-1234-567890abcdef",
            "customLabel": "Phone Number"
          }
        ],
        "shareNotificationSettings": {
          "email": {
            "subject": "Customer lookup results",
            "message": "Please review the customer record found for this request.",
            "buttonText": "Open results",
            "fromName": "Acme Support",
            "replyTo": "[email protected]"
          },
          "sms": {
            "message": "Customer lookup results are ready for review."
          }
        }
      }
    }
  ]
}

The next example finds one Account by name, keeps up to 50 of its Contacts as Repeating Records, and retrieves the five most recent contract files attached to the Account.

{
  "datasets": [
    {
      "datasetId": "ds3c4d5e-e5f6-7890-1234-567890abcdef",
      "setup": {
        "required": true,
        "selectionMode": "AUTOMATIC",
        "primarySearchCriteria": {
          "sortFieldId": "fa1b2c3d-e5f6-7890-1234-567890abcdef",
          "sortDirection": "ASCENDING",
          "joinLogic": "AND",
          "filters": [
            {
              "fieldId": "fa1b2c3d-e5f6-7890-1234-567890abcdef",
              "operator": "EQUALS",
              "value": "{{`Form`.`accountName`}}"
            }
          ],
          "fileToEntityConfigs": [
            {
              "rowId": "account-contracts",
              "enabled": true,
              "mappingLabel": "Account contracts",
              "searchConfig": {
                "entity": {
                  "entityId": "e9f8a7b6-e5f6-7890-1234-567890abcdef",
                  "linkId": "l9f8a7b6-e5f6-7890-1234-567890abcdef"
                },
                "filters": [
                  {
                    "operator": "AND",
                    "conditions": [
                      {
                        "fieldId": "fb2c3d4e-e5f6-7890-1234-567890abcdef",
                        "operator": "CONTAINS",
                        "value": "contract"
                      }
                    ]
                  }
                ],
                "sorts": [
                  {
                    "fieldId": "fc3d4e5f-e5f6-7890-1234-567890abcdef",
                    "direction": "DESCENDING"
                  }
                ],
                "pageSize": 5
              }
            }
          ]
        },
        "linkedEntitiesFilters": {
          "l1b2c3d4-e5f6-7890-1234-567890abcdef": {
            "sortFieldId": "fd4e5f6a-e5f6-7890-1234-567890abcdef",
            "sortDirection": "ASCENDING",
            "joinLogic": "AND",
            "filters": [],
            "repeatedRecords": true,
            "maxResults": 50
          }
        }
      },
      "results": {
        "showConfirmationPage": false,
        "tableMode": "DEFAULT",
        "fields": []
      }
    }
  ]
}

A few things to note:

• The Account itself is a single record, because setup.repeatedRecords is not set.
• Only the Contacts linked entity repeats. Later steps can map its fields as a collection.
• Later steps can map the contract files through the Account contracts file field.