> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# Map connector data fields

> Map Banking OS Unified API fields to target system fields with JOLT and XSLT transformations, and extend the APIs with custom fields.

Map data fields in the Banking OS Unified API specification to the fields that your integrated systems use, such as core banking platforms, third-party services, or fintech APIs. Accurate mapping helps with data transfer and interoperability between Banking OS and those systems.

The following sections describe how to edit the mappings that a connector provides. To add custom fields, see [Custom fields](#custom-fields).

## Prerequisites

Before you start mapping, complete the following tasks:

* Verify whether the integrated system supports adding custom fields.
* Review the available fields in both Banking OS and the integrated system to identify gaps or discrepancies.
* Determine whether you need any additional fields in the integrated system, then integrate them.
* Identify which custom fields are necessary and map them in the Banking OS transformation source file.

## Map fields

To map data fields, connectors use JOLT or XSLT transformations depending on the inbound data format accepted by each target system:

* **JOLT transformations**: JSON inbound data. See [JSON fields](#json-fields).
* **XSLT transformations**: XML inbound data. See [XML fields](#xml-fields).

Some pre-built connectors include reusable XSLT fragments on the Java classpath. For example, transformations in some Jack Henry Symitar and Fiserv DNA connectors import the `common-templates.xslt` or `credentials-and-device-info.xslt` file. The available files depend on the connector you use. Add the transformation file content that your deployment needs to the `values.yaml` file in the `sources` section of your live project repository. For more information about the `values.yaml` file, see [Connector repository and configuration](https://agenticbanking.backbase.io/banking-os-connectors/repository-and-configuration.md#values-yaml-file).

## JSON fields

To map data fields that use JSON data formats, use the [JOLT transformation library](https://github.com/bazaarvoice/jolt). To add or update a mapping, edit the JOLT transformation source file.

### Example mapping scenarios

The following table shows example mapping scenarios for fields in Banking OS and the integrated system:

| Scenario | Banking OS field | Target system field | Mapping |
| - | - | - | - |
| Field available in both Banking OS and the target system | `branchId` | `assignedBranchKey` | `"branchId": "assignedBranchKey"` |
| Field available in Banking OS only | `emails.type["work"].address` | `_Custom_Fields.work_email` | See [Field available in Banking OS only](#field-available-in-banking-os-only) |
| Field available in the target system only | `customFields.daysLate` | `daysLate` | See [Field available in the target system only](#field-available-in-the-target-system-only) |
| Field unavailable in both Banking OS and the target system | `customFields.newField` | `_Custom_Fields.new_field` | See [Field unavailable in both systems](#field-unavailable-in-both-systems) |

### Field available in Banking OS only

The following JOLT mapping sends the work email address from Banking OS to a custom field in the target system:

```json theme={"system"}
"emails": {
  "*": {
    "type": {
      "WORK": {
        "@(2,address)": "_Custom_Fields.work_email"
      }
    }
  }
}
```

### Field available in the target system only

The following JOLT mapping reads the `daysLate` field from the target system into the Banking OS `customFields` object:

```json theme={"system"}
"customFields": {
  "daysLate": "daysLate"
}
```

### Field unavailable in both systems

The following JOLT mapping maps a new Banking OS custom field to a new custom field that you add in the target system:

```json theme={"system"}
"customFields": {
  "newField": "_Custom_Fields.new_field"
}
```

### Custom JOLT transformations

The Banking OS custom JOLT transformation operation is available in the Banking OS generic connector library. You can use it to build custom data transformations that align JSON data from the integrated system with the Banking OS output format.

The following table lists the available Banking OS custom JOLT transformation operations:

| Operation type | Target system format | Banking OS format | Operation | Description |
| - | - | - | - | - |
| DateTime | `uuuu-MM-dd'T'HH:mm:ssXXXXX` | `yyyy-MM-dd'T'HH:mm:ss'Z'` | `com.backbase.grandcentralgeneric.transformer.DateTimeTransformer` | Converts incompatible DateTime values from target systems to UTC format |

The DateTime transformation converts incompatible DateTime values from target systems to UTC format in the Banking OS output. To use this transformation, specify the source date fields that require conversion and provide the preferred DateTime format.

The following example shows a DateTime transformation:

```json theme={"system"}
{
  "operation": "default",
  "spec": {
    "dateTimeFields": [
      "creationDate"
    ],
    "incomingDateTimeFormat": "uuuu-MM-dd'T'HH:mm:ssXXXXX"
  }
},
{
  "operation": "com.backbase.grandcentralgeneric.transformer.DateTimeTransformer"
}
```

## XML fields

To map data fields that use XML data formats, use the [XSLT transformation library](https://www.w3.org/TR/xslt20/). To add or update a mapping, edit the XSLT transformation source file.

### XML mapping scenarios

The following table shows example mapping scenarios for fields in Banking OS and the integrated system:

| Scenario | Banking OS field | Target system field | Mapping |
| - | - | - | - |
| Field available in both Banking OS and the target system | `notes` | `Description` | See [XML field in both systems](#xml-field-in-both-systems) |
| Field available in Banking OS only | `gcField` | Not available | XML-based request/response transformation doesn't support custom fields. |
| Field available in the target system only | `customFields.createdByUser` | `CreatedByUser` | See [XML field in the target system only](#xml-field-in-the-target-system-only) |
| Field unavailable in both Banking OS and the target system | `customFields.gcNewField` | Not available | XML-based request/response transformation doesn't support custom fields. |

### XML field in both systems

The following XSLT mapping writes the Banking OS `notes` field to the `Description` element in the target system:

```xml theme={"system"}
<Description>
  <xsl:value-of select="LinkedHashMap/notes"/>
</Description>
```

### XML field in the target system only

The following XSLT mapping writes the Banking OS `customFields.createdByUser` field to the `CreatedByUser` element in the target system:

```xml theme={"system"}
<CreatedByUser>
  <xsl:value-of select="LinkedHashMap/customFields/createdByUser"/>
</CreatedByUser>
```

## Custom fields

Custom fields let you access data or attribute values that the Banking OS Unified API may not cover. Use custom fields to extend the APIs to suit your specific requirements.

Banking OS core banking connectors include predefined fields with a wide range of attributes for each core banking system. If you need more fields than the predefined fields, add them to the `customFields` object.

### Supported data types

A custom field is a `Map<String, Object>` that supports the following data types:

| Data type | Description |
| - | - |
| `Long` | Integer numeric values |
| `Double` | Decimal numeric values |
| `Boolean` | True or false values |
| `String` | Text values |
| `Date` | Date and time values |
| `List<String>` | List of text values |

> [!WARNING]
>
> Avoid using and sending complex objects as values.

### Link custom attributes

To link your custom attributes to core attributes, edit the mapping files. Manage this configuration in the `values.yaml` file in the `sources` section of your live project repository. For instructions about mapping custom fields between Banking OS and the core banking system, see [Map fields](#map-fields).

### Valid custom field structure

The following example includes five custom field attributes and their corresponding values:

```json theme={"system"}
"customFields": {
  "firstName": "John",
  "lastName": "Smith",
  "preferredLanguage": "ENGLISH",
  "approvedDate": "2023-06-21T06:15:07Z",
  "groupKeys": [
    "8a19a39a8b12rt5t618b143139f056aa",
    "8a19ca6d8b36d567818b373e021209d8",
    "8a19acda8b1er123018b1e00760d03ee"
  ]
}
```

### Invalid custom field structure

The following example is invalid because the `address` field contains a nested object, which custom fields don't support:

```json theme={"system"}
"customFields": {
  "address": {
    "addressLine": "Perry Cross",
    "buildingNumber": "Perry Cross",
    "country": "IN",
    "postalCode": "404040",
    "townName": "Mumbai"
  }
}
```
