> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.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 Grand Central connector.
Get started with Grand Central connectors by configuring your environment, integrating the required SDKs, and authenticating your services. Follow these steps to deploy on the iPaaS platform.
**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 Grand Central platform to integrate with systems that don't have a pre-built connector available.
For more information, see [Platform terminology](/platform/overview#platform-terminology).
## Prerequisites
Before you begin, ensure you are comfortable with the following technologies:
Familiarity with Kubernetes and Git/GitHub workflows.
Java development and XML Schema (XSD) knowledge.
API request/response mapping using **JOLT** and **XSLT**.
You also need access to the Grand Central platform.
### Required access
Ask the **Grand Central team** to grant you:
1. **Repository access:** View and clone access to the `gc-applications-live` repository.
2. **APIM subscription key:** A subscription key for the Grand Central Unified API and product sandbox.
## Included features
Grand Central provides platform capabilities and connector-specific resources.
### Platform capabilities
The Grand Central iPaaS platform provides the following capabilities. For more information, see [Grand Central iPaaS](/platform/overview).
| Capability | Description |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [Azure API Management (APIM)](/platform/api-management) | Managed API gateway for publishing, securing, and monitoring APIs |
| [Unified APIs](/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 | Integration Platform as a Service (iPaaS) 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 Grand Central APIs:
* Search party
* Deposit transactions
* Loan transactions
For more information, see [Architecture](/architecture) and [Error codes](/connectors/reference/error-codes).
## Repository structure
The `gc-applications-live` repository holds the configuration for iPaaS and connector deployments in `dev`, `test`, and `prod`. 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
```
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/baas-devops-ecos/gc-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
```
### Values YAML file
Use these files to define connector properties, telemetry, and data transformation logic.
### Sample values YAML file
```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"
}
}
}
}
]
```
## Map data fields
To ensure accurate data transfer and interoperability between Grand Central and the systems your connectors integrate with, such as core banking platforms, third-party services, or fintech APIs, map data fields in the Grand Central Unified API specification to the fields those systems use.
The following steps describe how to edit existing mappings. To add custom fields, see [Custom fields](#custom-fields).
### Prerequisites
Before you start mapping, complete the following:
* Verify whether the integrated system supports adding custom fields.
* Review the available fields in both Grand Central 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 Grand Central 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 Grand Central and the integrated system:
| Scenario | Grand Central field | Target system field | Mapping |
| ------------------------------------------------------------- | ----------------------------- | --------------------------- | --------------------------------------------------------------- |
| Field available in both Grand Central and the target system | `branchId` | `assignedBranchKey` | `"branchId": "assignedBranchKey"` |
| Field available in Grand Central only | `emails.type["work"].address` | `_Custom_Fields.work_email` | See [example below](#field-available-in-grand-central-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 Grand Central and the target system | `customFields.newField` | `_Custom_Fields.new_field` | See [example below](#field-unavailable-in-both-systems) |
#### Field available in Grand Central 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 Grand Central custom JOLT transformation operation is available in the Grand Central generic connector library. You can use it to build custom data transformations that align JSON data from the integrated system with the Grand Central output format.
#### Available transformations
The following table lists the available Grand Central custom JOLT transformation operations:
| Operation type | Target system format | Grand Central 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 Grand Central 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 Grand Central and the integrated system:
| Scenario | Grand Central field | Target system field | Mapping |
| ------------------------------------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------- |
| Field available in both Grand Central and the target system | `notes` | `Description` | See [example below](#xml-field-in-both-systems) |
| Field available in Grand Central 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 Grand Central 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"}
```
#### XML field in the target system only
```xml theme={"system"}
```
## Custom fields
Custom fields let you access data or attribute values that the Grand Central Unified API may not cover. Use custom fields to extend the APIs to suit your specific requirements.
Grand Central 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` 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` | List of text values |
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 Grand Central 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"
}
}
```