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

# Get started

> Set up your environment and deploy your first Banking OS connector.

Get started with Banking OS connectors by configuring your environment, integrating the required SDKs, and authenticating your services. Follow these steps to deploy on Banking OS Connectivity.

<Info>
  **Pre-built connector vs custom connector**

  **Pre-built connectors**, also called managed connectors, provide out-of-the-box integration with core banking systems and third-party services. Backbase develops and maintains these connectors.

  **You build a custom connector** on the Banking OS platform to integrate with systems that don't have a pre-built connector available.

  For more information, see [Platform terminology](/banking-os/ipaas#platform-terminology).
</Info>

## Prerequisites

Before you begin, ensure you are comfortable with the following technologies:

<CardGroup cols={2}>
  <Card title="Infrastructure" icon="server">
    Familiarity with Kubernetes and Git/GitHub workflows.
  </Card>

  <Card title="Development" icon="java">
    Java development and XML Schema (XSD) knowledge.
  </Card>

  <Card title="Data transformation" icon="bolt">
    API request/response mapping using **JOLT** and **XSLT**.
  </Card>
</CardGroup>

You also need access to the Banking OS platform.

### Required access

Ask the **Banking OS team** to grant you:

1. **Repository access:** View and clone access to the `gc-applications-live` repository for your installation. For more information about organization and repository names, see [GitHub organization and repository structure](/platform/platform-administration/repository-structure).
2. **Azure API Management (APIM) subscription key:** A subscription key for the Banking OS Unified API and product sandbox.

## Included features

Banking OS provides platform capabilities and connector-specific resources.

### Platform capabilities

Banking OS Connectivity provides the following capabilities. For more information, see [Banking OS Connectivity](/banking-os/ipaas).

| Capability | Description |
| - | - |
| [Azure API Management](/platform/api-management) | Managed API gateway for publishing, securing, and monitoring APIs |
| [Unified APIs](/banking-os/architecture#unified-apis-and-bian) | Standardized BIAN-inspired API layer for all connector integrations |
| [Camel K runtime](https://camel.apache.org/camel-k/2.9.x/architecture/runtime.html) | Cloud-native integration runtime for connector execution |
| [Helm charts](https://helm.sh/) | Kubernetes deployment templates for consistent deployments |
| Continuous delivery | Banking OS Connectivity with [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) for GitOps-based deployments |

### Pre-built connector resources

Pre-built connectors include the following resources. These resources aren't available for custom connectors unless you build them yourself.

| Resource | Description |
| - | - |
| Source code repository | Access to pre-built connector source code. Available only with a **Premium** subscription. |
| Data mapping files | Predefined JOLT and XSLT mapping files for data transformation between the Unified API and the target system |
| Kamelets and JARs | Reusable [Kamelets](https://camel.apache.org/camel-k/2.9.x/kamelets/kamelets.html) and [JAR files](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jarGuide.html) for common integration patterns |
| Accelerators | Pre-built configuration accelerators to speed up deployment. Available only with a **Premium** subscription. |

## Configurable features

You can configure the following features for your connector deployments:

| Feature | Description |
| - | - |
| **APIM routing** | API-to-connector routing rules through Azure API Management |
| **Configuration properties** | Environment-specific connection settings, credentials, and feature flags |
| **Resource mapping files** | Transformation files for data mapping between systems |
| **Logging and monitoring** | Log levels, tracing, and telemetry settings |
| **Compute resources** | CPU and memory allocation for connector workloads |

### Pagination

You can paginate bulk data requests through the following Banking OS APIs:

* Search party
* Deposit transactions
* Loan transactions

For more information, see [Architecture](/banking-os/architecture) and [Error codes](/banking-os-apis/error-codes).

## Repository structure

The `gc-applications-live` repository holds the configuration for Banking OS Connectivity and connector deployments in `dev`, `test`, and `prod`. The GitHub organization and exact repository name follow the managed or DevHub pattern for your installation. For more information, see [GitHub organization and repository structure](/platform/platform-administration/repository-structure). The following diagram shows the typical folder structure.

### Reference architecture

```text theme={"system"}
runtimes
├── dev           # Sandbox environment for experimentation
└── test          # Integration testing environment
    ├── apps      # connector deployment configurations (YAML)
    │   └── gc-mambu.yaml
    └── values    # Environment-specific overrides
        ├── gc-mambu
        │   └── deposit-v0.values.yaml
        └── values.yaml
```

The following table describes the files and folders in the example repository:

| **File/folder** | **Description** |
| :- | :- |
| `runtimes` | The available runtimes for deployment. |
| `dev` | Development environment for experimenting and debugging. |
| `test` | Test environment. Primarily for integration. |
| `apps` | Connector configurations per product. The YAML files in this folder represent the list of deployed connectors. For more information, see [Application YAMLs](#application-yamls). |
| `gc-mambu.yaml` | Deployment configuration for Mambu connectors that run on a test environment. The `-v2` suffix refers to the `2.x` version of the Camel K runtime. |
| `values` | Deployment values. These values override the default configuration in a connector: JOLT mappings, connector properties, and traits. |
| `gc-mambu` | Override values for Mambu connectors. |
| `desposit-v0.values.yaml` | Override values for Mambu deposit account connector. |
| `values.yaml` | Override values for all connectors within the `gc-mambu` deployment file. |

## Configuration logic

Connector configuration uses a hierarchical override system that lets you define defaults and customize per environment.

### Application YAMLs

Configurations in the `/apps` directory follow a **top-down override hierarchy**. Settings are merged in order, meaning subsequent files take precedence over previous ones. This allows you to define global environment defaults and selectively override them at the connector-version level.

**A standard deployment descriptor includes:**

* **Namespace:** The Kubernetes isolation layer for the deployment.
* **Version Control:** Links to the source and Azure Container Registry (ACR) repositories.
* **Templating:** The Helm chart used to standardize the deployment.
* **Orchestration:** ArgoCD Sync Policies for automated reconciliation.
* **Data Resources:** Configurable JOLT or XSLT files for message transformation.

### Sample apps YAML file

<Accordion title="View sample application YAML (ArgoCD)">
  ```
  apiVersion: argoproj.io/v1alpha1
  kind: Application
  metadata:
    name: gc-generic
    namespace: argocd
  spec:
    project: default
    destination:
      server: https://kubernetes.default.svc
      namespace: gc-generic
    sources:
      - repoURL: https://github.com/bb-ecos-{installation}/gc-{installation}-applications-live.git
        targetRevision: gc-dev
        ref: apps-live

      - repoURL: ecosystemsgctmp.azurecr.io/charts
        chart: template-connector
        targetRevision: 1.1.3-camel-k-ci-21-SNAPSHOT
        helm:
          releaseName: template-connector-1
          valueFiles:
            - $apps-live/azure/runtimes/dev-v2/values/gc-generic/template-connector-v1.values.yaml

    syncPolicy:
      automated:
        prune: true
        allowEmpty: true
        selfHeal: true
      syncOptions:
        - CreateNamespace=true
  ```
</Accordion>

### Values YAML file

Use these files to define connector properties, telemetry, and data transformation logic.

### Sample values YAML file

<Accordion title="View sample values and Jolt transformation">
  ```yaml theme={"system"}
  connector:
    properties:
      isMockedDataNeeded: true
    traits:
      knativeservice:
        minScale: 1
        enabled: true
      logging:
        color: false
        enabled: true
        level: INFO
      addons:
        telemetry:
          auto: true
          enabled: true
    resources:
      close-account-request-transformation.json: |-
        [
          {
            "operation": "shift",
            "spec": {
              "notes": "notes",
              "closeStatus": {
                "CLOSED": {
                  "#CLOSE": "action"
                },
                "CLOSED_WRITTEN_OFF": {
                  "#CLOSED_WRITTEN_OFF": "action"
                },
                "WITHDRAWN": {
                  "#CLOSE_WITHDRAW": "action"
                },
                "CLOSED_REJECTED": {
                  "#CLOSE_REJECT": "action"
                }
              }
            }
          }
        ]
  ```
</Accordion>

## Map data fields

To ensure accurate data transfer and interoperability between Banking OS and the systems your connectors integrate with, such as core banking platforms, third-party services, or fintech APIs, map data fields in the Banking OS Unified API specification to the fields those systems use.

<Info>
  The following steps describe how to edit existing mappings. To add custom fields, see [Custom fields](#custom-fields).
</Info>

### Prerequisites

Before you start mapping, complete the following:

* 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](#json-fields)
* **XSLT transformations**: [XML inbound](#xml-fields)

Some pre-built connectors ship reusable XSLT fragments on the Java classpath. For example, transforms may import `common-templates.xslt` or `credentials-and-device-info.xslt`, as in some Jack Henry Symitar and Fiserv DNA connectors. The files available depend on the connector you use. Add the transformation file content your deployment needs to the `values.yaml` file in the `sources` section of your live project repository.

### 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 [example below](#field-available-in-banking-os-only) |
| Field available in the target system only | `customFields.daysLate` | `daysLate` | See [example below](#field-available-in-the-target-system-only) |
| Field unavailable in both Banking OS and the target system | `customFields.newField` | `_Custom_Fields.new_field` | See [example below](#field-unavailable-in-both-systems) |

#### Field available in Banking OS only

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

#### Field available in the target system only

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

#### Field unavailable in both systems

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

#### Available transformations

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.

**Example 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.

#### 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 | `notes` | `Description` | See [example below](#xml-field-in-both-systems) |
| Field available in Banking OS only | `gcField` | Not available | XML-based request/response transformation does not support custom fields. |
| Field available in the target system only | `customFields.createdByUser` | `CreatedByUser` | See [example below](#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 does not support custom fields. |

#### XML field in both systems

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

#### XML field in the target system only

```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 connectors include predefined fields with a wide range of attributes for each core. If you need additional fields beyond those predefined, add them to the `customFields` object.

### Supported data types

A custom field is represented as a `Map<String, Object>` and 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.
</Warning>

### 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 data fields](#map-data-fields).

### Examples

#### 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 due to its complexity. The `address` field contains a nested object, which is not supported:

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