**Source URL:** https://ecoa.veevavault.help/en/lr/918798/index.md

# 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:

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

### Item mappings

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

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

## 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.

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

## Example JSON

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

### Single-Select outputDataType JSON

~~~ 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

~~~ 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"
            }
          ]
        }
      ]
    }
  ]
}
~~~

## Related Resources
* [Creating a Send Survey Data Rule Template](/en/lr/918799/)
* [Working with Outbound APIs](/en/lr/918797/)