Getting started

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

Prerequisites

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

Infrastructure

Familiarity with Kubernetes and Git/GitHub workflows.

Development

Java development and XML Schema (XSD) knowledge.

Data transformation

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:

Repository access: View and clone access to the gc-applications-live repository.
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.

Capability	Description
Azure API Management (APIM)	Managed API gateway for publishing, securing, and monitoring APIs
Unified APIs	Standardized BIAN-inspired API layer for all connector integrations
Camel K runtime	Cloud-native integration runtime for connector execution
Helm charts	Kubernetes deployment templates for consistent deployments
Continuous delivery	Integration Platform as a Service (iPaaS) with ArgoCD 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 and JAR files 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 and 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

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

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

View sample values and Jolt transformation

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.

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
XSLT transformations: XML inbound

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. 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 the target system only	`customFields.daysLate`	`daysLate`	See example below
Field unavailable in both Grand Central and the target system	`customFields.newField`	`_Custom_Fields.new_field`	See example below

Field available in Grand Central only

"emails": {
  "*": {
    "type": {
      "WORK": {
        "@(2,address)": "_Custom_Fields.work_email"
      }
    }
  }
}

Field available in the target system only

"customFields": {
  "daysLate": "daysLate"
}

Field unavailable in both systems

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

{
  "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. 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
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
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

<Description>
  <xsl:value-of select="LinkedHashMap/notes"/>
</Description>

XML field in the target system only

<CreatedByUser>
  <xsl:value-of select="LinkedHashMap/customFields/createdByUser"/>
</CreatedByUser>

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

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.

Examples

Valid custom field structure

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

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

"customFields": {
  "address": {
    "addressLine": "Perry Cross",
    "buildingNumber": "Perry Cross",
    "country": "IN",
    "postalCode": "404040",
    "townName": "Mumbai"
  }
}

Overview

Grand Central connectors

Release notes

Prerequisites

Infrastructure

Development

Data transformation

Required access

Included features

Platform capabilities

Pre-built connector resources

Configurable features

Repository structure

Reference architecture

Configuration logic

Application YAMLs

Sample apps YAML file

Values YAML file

Sample values YAML file

Map data fields

Prerequisites

Map fields

JSON fields

Example mapping scenarios

Field available in Grand Central only

Field available in the target system only

Field unavailable in both systems

Custom JOLT transformations

Available transformations

XML fields

Example mapping scenarios

XML field in both systems

XML field in the target system only

Custom fields

Supported data types

Link custom attributes

Examples

Valid custom field structure

Invalid custom field structure

Overview

Grand Central connectors

Release notes

​Prerequisites

Infrastructure

Development

Data transformation

​Required access

​Included features

​Platform capabilities

​Pre-built connector resources

​Configurable features

​Pagination

​Repository structure

​Reference architecture

​Configuration logic

​Application YAMLs

​Sample apps YAML file

​Values YAML file

​Sample values YAML file

​Map data fields

​Prerequisites

​Map fields

​JSON fields

​Example mapping scenarios

​Field available in Grand Central only

​Field available in the target system only

​Field unavailable in both systems

​Custom JOLT transformations

​Available transformations

​XML fields

​Example mapping scenarios

​XML field in both systems

​XML field in the target system only

​Custom fields

​Supported data types

​Link custom attributes

​Examples

​Valid custom field structure

​Invalid custom field structure

Prerequisites

Required access

Included features

Platform capabilities

Pre-built connector resources

Configurable features

Pagination

Repository structure

Reference architecture

Configuration logic

Application YAMLs

Sample apps YAML file

Values YAML file

Sample values YAML file

Map data fields

Prerequisites

Map fields

JSON fields

Example mapping scenarios

Field available in Grand Central only

Field available in the target system only

Field unavailable in both systems

Custom JOLT transformations

Available transformations

XML fields

Example mapping scenarios

XML field in both systems

XML field in the target system only

Custom fields

Supported data types

Link custom attributes

Examples

Valid custom field structure

Invalid custom field structure