Configuring Outbound API Field Mapping

Overview

You use the field mapping JSON to define how eCOA data populates fields in an external system. This configuration is unique to the rule and form combination.

Field Mapping JSON Structure

The JSON object contains a fieldMappings array. This array contains item groups. You define the mapping for specific items within these groups.

Mapping Parameters

Structural Arrays and Values

The JSON structure uses hierarchical arrays to organize how data is sent:

Parameter Type Description Example Required?
Groups Array The required outer container for all mappings in the JSON. "groups": [...] Required
Group Name String Defines the item group. "groupName": "IG_CEVT" Required
Standard Values Array Defines values sent with every call, including those that do not repeat. "standardValues": [...] Optional
Sequenced Values Array Triggers a looping call behavior, creating one call for each configured value. "sequencedValues": [...] Optional
Sequence Type String, with set options:
  • ITEM_GROUP_SEQUENCE
  • FORM_SEQUENCE
 The sequence type that is used. "FORM_SEQUENCE" Required if sequencedValues are used.
Conditional Values Array Defines values only included when referenced by a sequencedValues item. "conditionalValues": [...] Optional

Item mappings

These parameters define the source and destination for each data point.

Parameter Type Description Example Required?
Source Field String, with set options based on configured block or criteria names.
  • The eCOA data source.
  • Use criteria.<name>, survey.<block_name>.answer, score.<name>.score, or survey.datetime.
 "sourceField": "criteria_severity" Required
Target Field String
  • Defines the field in the external system that the API call will populate.
  • Must match that system’s value exactly.
 "targetField": "CEVT_SEVERITY" Required
Output Data Type String, with set options:
  • string
  • number
  • date
  • datetime
  • array
  • multiselect
  • Defines the data type the external system expects.
  • When outputDataType is set to multiselect, the targetField parameter must be moved inside the valueMap array to list items.
 "outputDataType": "string" Required
Output Unit String, with set options of units of measurement. The unit associated with a field value. "outputUnit": "mg/dL" Required when output needs a unit.
Output Data Format Date format Defines the format of the data output. For example, yyyy-MM-dd for dates or UTC24 for datetimes. "outputDataFormat": "yyyy-MM-dd" Optional
Input Date Format Date format
  • The format for eCOA date/datetime inputs.
  • The system automatically converts known formats, but you can define a custom format if needed.
  • If nothing is selected, dd MMM yyyy hh:mm a is shown by default.
 "inputDateFormat": "dd MMM yyyy hh:mm a" Optional
Character Limit Number
  • Defines the maximum number of characters a field can contain.
  • The system automatically truncates values that exceed this limit.
 "characterLimit": "260" Optional

Value Mapping

You can map specific eCOA answers to different values for the external system. Define the eCOA value as the name and the external value as the value.

Parameter Type Description Example Required?
Value Mapping Array A subarray that maps specific eCOA output values to transformed values expected by the external system. "valueMap": [...] Optional
Source Value String Within the array, this represents the expected eCOA value. Mild Required
Target Value String Within the array, this represents the transformed value sent to the external system. 1 Required
Null Target Value String
  • The value passed if the sourceValue does not appear in the results.
  • For multiselect fields, you should include the nullTargetValue parameter, to define the value passed if the source value does not appear in the results.
 2 Optional
Input Data Type String with set options:
  • The specific data type used
  • list if the result has multiple values
 The data type for the input value. Use list if the result contains multiple values. "inputDataType": "" Required to handle multi-select or array-based inputs from rules.

Example JSON

See the examples below for information on how the JSON looks for different output data types.

Single-Select outputDataType JSON

{
  "groups": [
    {
      "groupName": "IG_CEVT",
      "standardValues": [
        {
          "sourceField": "criteria.severity",
          "targetField": "CEVT_SEVERITY",
          "outputDataType": "string",
          "valueMap": [
            { "sourceValue": "Mild", "targetValue": "1" },
            { "sourceValue": "Severe", "targetValue": "3" }
          ]
        }
      ]
    }
  ]
}

Multi-Select outputDataType JSON

{
  "groups": [
    {
      "groupName": "IG_CEVT",
      "standardValues": [
        {
          "sourceField": "criteria.criteria_severity",
          "targetField": "CEVT_SEVERITY",
          "outputDataType": "string",
          "valueMap": [
            {
              "sourceValue": "Mild",
              "targetValue": "1"
            },
            {
              "sourceValue": "Severe",
              "targetValue": "3"
            }
          ]
        },
        {
          "sourceField": "criteria.criteria_CETPT",
          "outputDataType": "multiselect",
          "inputDataType": "list",
          "valueMap": [
            {
              "targetField": "edc_field_1",
              "sourceValue": "vaccination_1",
              "targetValue": "1",
              "nullTargetValue": "0"
            },
            {
              "targetField": "edc_field_2",
              "sourceValue": "vaccination_2",
              "targetValue": "1",
              "nullTargetValue": "0"
            }
          ]
        }
      ]
    }
  ]
}