Deploying and Configuring the Mapper Framework

11 Deploying and Configuring the Mapper Framework

Learn how to deploy and configure the Mapper Framework to tailor Oracle Communications Billing and Revenue Management (BRM) cloud native deployments to your organization’s requirements. You can integrate custom mapping logic into your BRM Cloud Native environment, leveraging both Helm and Kubernetes tooling.

Topics in this document:

Overview of the Mapper Framework

The BRM Cloud Native Mapper framework enables you to implement custom mapping logic for your deployment. Use mapper files, defined in YAML format, to control how APIs transform data to and from flist structures. This approach lets you customize field mappings, perform type conversions, and apply conditional logic, all without modifying the core application code. You can deploy, update, verify, and roll back mapper files as needed to support your business requirements.

Deploying Custom Mapper Files

Custom mapper files can be deployed at any stage of the BRM Cloud Native life cycle: initial deployment, upgrades, or at runtime for dynamic updates. You can choose a method based on your deployment scenario and file size.

There are two primary approaches:

For files less than 1 MiB:
- Deploying Mapper Files Using Helm
  To deploy mapper files smaller than 1 MiB, place them in the oc-cn-helm-chart/rsm/extendedMappers directory. The files are automatically packaged and loaded when the relevant pods start.
- Deploying Mapper Files Using Kubernetes ConfigMaps
  You can deploy mapper files dynamically or at runtime by creating Kubernetes ConfigMaps. This method is recommended for files that require updating without restarting pods, or for YAML files that change frequently.
  To create a ConfigMap from a single YAML file, run:
```
kubectl create configmap configmap-name --from-file=yaml-file-name -n namespace
```
  where:
  - configmap-name is the name assigned to the ConfigMap.
  - yaml-file-name is the name of the custom mapper YAML file.
  - namespace is the Kubernetes namespace where the Revenue Stream Manager (RSM) is deployed.
  To create a ConfigMap from all YAML files in a directory, run:
```
kubectl create configmap configmap-name --from-file=. -n namespace
```
  where --from-file=. includes all files in the current directory.
  
  Note:
  
  Run all commands from the directory containing the files.
For files more than 1 MiB:
- Deploying Mapper Files Using Custom SDK Images
  For mapper files larger than 1 MiB, add these files to the /SDK/extendedMappers directory in your custom SDK image. Build and push the image to your container registry. Reference the new image in your REST Services Manager deployment configuration.

Configuring the Mapper in BRM Helm Charts

To enable and configure a custom mapper, update the override-values.yaml file. For example, set the external ConfigMap and trigger a pod restart:

ocrsm:
  rsm:
    externalExtendedMapper: "configmap-name"
    configEnv:
      restartVersion: version-number

where:

externalExtendedMapper specifies the name of the ConfigMap that contains your custom mapper files.
restartVersion is a numeric or string value. Increment this value in your deployment and run a Helm upgrade to apply the changes.

Note:

Reference your custom ConfigMap in the externalExtendedMapper key if you create the ConfigMap.
For SDK image-based extensions, ensure that you correctly define the custom image path in the image configuration.

See "Configuring and Adding Custom Mapper Files" for more information about updating override-values.yaml with the path to your custom mapper files.

Mapper Framework Configuration Keys

Configure the Mapper Framework to enable custom field mapping and deployment settings for BRM REST Services Manager (RSM):

ocrsm:
   rsm:
      mapperConfiguration:
         config:
            paths:
               event:
                  v5:
                     ProductCreateEvent:
                        mapper-specification-keys:
                           default: Product
                           Event:
                              execute:
                                 - "mapper.brm.v5.tmf637.productCreateEvent.execute"
                              request:
                                 - "mapper.brm.v5.tmf637.productCreateEvent.request"
                              response:
                                 - "mapper.brm.v5.tmf637.productCreateEvent.response"
                                 - "mapper.custom.v5.tmf637.productCreateEvent.response"
                           Product:
                              request:
                                 - "mapper.brm.v5.tmf637.post.request.product"
                                 - "mapper.brm.v5.tmf637.post.request.extendedProduct"
                                 - "mapper.custom.v5.tmf637.post.request.product"
                              response:
                                 - "mapper.brm.v5.tmf637.post.response.product"
                                 - "mapper.brm.v5.tmf637.post.response.extendedProduct"
                                 - "mapper.custom.v5.tmf637.post.response.product"

where:

ProductCreateEvent specifies the event type.
mapper-specification-keys defines logical profiles or mapping variants.
default applies when no explicit profile is provided.
execute, request, and response specify the mapping configuration files for the execution opcode, request transformation, and response transformation, respectively.

Example Usage in override-values.yaml

To load your custom Mapper and Kafka configurations during deployment, add the relevant configuration keys directly to your main override-values.yaml file. Place these keys at the root level of the file to align with the primary chart hierarchy.

When updating mapper files, increment the restartVersion value and run the helm upgrade command to ensure the pods reload the new configuration. Always follow security best practices by protecting sensitive values, such as passwords, and managing access controls appropriately.

The following example demonstrates how to specify these configuration settings in your override-values.yaml file:

ocrsm:
  rsm:
    isEnabled: true
    externalExtendedMapper: custom-mapper-configmap
    configEnv:
      restartVersion: 2

ocbrm:
  dm_kafka:
    isEnabled: true
    deployment:
      kafka_bootstrap_server_list: ece-kafka:9093
      topicName: BRM
      isSecurityEnabled: true
      trustStorePassword: password

Best Practices for Managing Mapper Files

To ensure reliability, traceability, and rapid recovery, follow these best practices when managing mapper files in your environment:

Version Control: Store all custom mapper YAML files in a version control system with clear branching and review policies.
Testing: Validate new or modified mappings in a non-production environment using automated or manual tests before production rollout.
CI/CD: Automate ConfigMap creation, SDK image builds, and deployment of mapper files via CI/CD pipelines.
Rollback Planning: Maintain a rollback plan to restore the last stable configuration promptly if errors occur after deployment.