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:

Introducing the Mapper Framework

The BRM Cloud Native Mapper supports customized mapping logic, allowing organizations to tailor API-to-Flist transformations without modifying core code. Deployed as YAML files, mappers enable field-level customizations, type conversions, and conditional logic. This chapter details how to deploy, update, verify, and roll back these mapper files.

Deploying Custom Mapper Files

Custom mapper files can be deployed at any stage of the BRM Cloud Native lifecycle: 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.

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

  • 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 your override-values.yaml file. For example, setting the external ConfigMap and triggering a pod restart: 

ocrsm:
  rsm:
    externalExtendedMapper: "configmap-name"
    configEnv:
      restartVersion: version-number
where,
  • externalExtendedMapper is the name of the ConfigMap containing your custom mapper files.
  • restartVersion is a numeric or string value; increment the version in your deployment and run a Helm upgrade to apply the changes.

Note:

  • Reference your custom ConfigMap in the externalExtendedMapper key if you have created the configMap.

  • For SDK image-based extensions, ensure the custom image path is correctly defined in image configuration.

See "Configuring and Adding Custom Mapper Files" for more information on how to update the override_values.yaml with the path from your custom mapper files.

Mapper Framework Configuration Keys

Configure the Mapper Framework to enable custom field mapping and deployment settings for the 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 defines the type of event.
  • mapper-specification-keys specifies logical profiles or mapping variants.
  • default is used when no explicit profile is provided.
  • execute, request, and response designate the mapping configuration files to be applied for execution opcode, request transformation, and response transformation respectively.

Example Usage in override-values.yaml

Insert the configuration keys into your main override-values.yaml file to ensure your custom Mapper and Kafka configurations are loaded at deploy time:
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
Placement and Best Practices:
  • Place these keys at the root level, matching the main chart hierarchies.
  • For updates to mapper files, increment restartVersion and run helm upgrade command to ensure pods reload configurations.
  • Follow security best practices for handling secrets and access controls

Best Practices for Managing Mapper Files

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