Installing BRM REST Services Manager

11 Installing BRM REST Services Manager

Learn how to use the Oracle Communications Billing and Revenue Manager (BRM) REST Services Manager package to install both the BRM REST Services Manager API and the BRM REST Services Manager SDK on your system.

Topics in this document:

For more information about the BRM REST Services Manager API and SDK, see REST API Reference for Billing and Revenue Management.

Downloading the BRM REST Services Manager Package

You can download and install the BRM REST Services Manager software from one of the following locations:

For BRM 16.26.0.0 or any 16.26.0.x maintenance release: From the Oracle software delivery website (https://edelivery.oracle.com)
For any 16.26.0.x.y patch set release: From the Oracle support website (https://support.oracle.com)

Search for and download the Oracle Communications Billing and Revenue Management 16.26.0.x.y.0 software, where x refers to the maintenance release and y refers to the patch set release of BRM that you are installing.

The Zip archive includes the BRM REST Services Manager installer: BRM_REST_Services_Manager-16.26.0.x.y.0.jar

Installing BRM REST Services Manager in GUI Mode

To install BRM REST Services Manager in GUI mode:

Go to the temp_dir directory and run one of these commands:
- To start the GUI installer:
```
Java_home/bin/java -jar jarFile
```
  where:
  - Java_home is the directory in which you installed the latest compatible Java version.
  - jarFile is the BRM installer file. For example:
```
BRM_REST_Services_Manager-16.26.0.0.0.jar
```
- To start the GUI installer and install BRM REST Services Manager using the oraInventory directory in a different location:
```
Java_home/bin/java -jar jarFile -invPtrLoc FilePath/oraInst.loc
```
  where FilePath is the path to the directory in which the oraInst.loc file is located.
- To start the GUI installer and create a silent installer response file during the installation:
```
Java_home/bin/java -jar jarFile -record -destinationFile path
```
  where path is the absolute path to the response file.
Tip:

You can run the following command to get more details about the options.
```
Java_home/bin/java -jar jarFile -help
```
In the Welcome window, click Next.

Note:

If the oraInst.loc file is corrupt or not present, the Installation Inventory window appears next. Otherwise, the Installation Location window appears.

(Optional) In the Installation Inventory window, enter the details listed in Table 11-1 and then click Next.

Table 11-1 Installation Inventory

Field	Description
Inventory Directory	The full path of the inventory directory. The default oraInventory directory is located in the /etc/oraInst.loc (Linux) file.
Operating System Group	The name of the operating system group that has write permission to the inventory directory.

Field

Description

Inventory Directory

The full path of the inventory directory.

The default oraInventory directory is located in the /etc/oraInst.loc (Linux) file.

Operating System Group

The name of the operating system group that has write permission to the inventory directory.

In the Installation Location window, enter the full path or browse to the directory in which you want to install BRM REST Services Manager and then click Next.
In the Feature Sets Selection window, select the components to install, deselect any components that you do not want to install, and then click Next.

Note:

You cannot deselect a component if it is required to install any of the selected components.

If you are installing an optional component for the first time after an upgrade, and you see an error similar to the following, see "Problem: An Error Occurred When Selecting an Optional Component to Install".
```
The distribution Billing Revenue Management 16.26.0.0.0 contains incompatible features with the following:
Billing Revenue Management 15.0.1.0.0 [CORE 16.26.0.0.0->CORE 15.0.1.0.0 (CORE 16.26.0.0.0->[CORE 15.0.1.0.0])]
```

In the Server Details window, enter the details listed in Table 11-2 for the server on which you want to deploy BRM REST Services Manager and then click Next.

Table 11-2 Server Details

Field	Description
Host Name	The host name of the computer on which the server is configured.
Port Number	The port number available on the host.
SSL Port Number	The SSL port number on which you want to install BRM REST Services Manager.
KeyStore Location	The path of the client-side keystore file you generated.
KeyStore Password	The password used for accessing the keystore file.

In the Base URL Details window, enter the base URL to include in the response of BRM REST Services Manager requests. Click Next.

In the BRM Connection Details window, enter the details listed in Table 11-3 for connecting to the BRM server and then click Next.

Table 11-3 BRM Connection Details

Field	Description
User Name	The user name for connecting to BRM.
Password	The password of the BRM user.
Host Name	The host name of the computer on which the primary BRM Connection Manager (CM) or CM Master Process (CMMP) is running.
Port Number	The TCP port number of the CM or CMMP on the host computer. The default value is 11960.
Service Type	The BRM service type. The default value is /service/pcm_client.
Service POID Id	The POID of the BRM service. The default value is 1.
SSL Wallet Location	The full path to the BRM wallet file (cwallet.sso). If the field is empty, BRM has disabled SSL and RSM is proceeding with it.

In the Application Wallet Details window, enter the details listed in Table 11-4 and then click Next.

Table 11-4 Application Wallet Details

Field	Description
Application Wallet Password	The password for the application wallet. This wallet stores the BRM REST Services Manager connection secret, Infranet connections, and keystore and truststore passphrases.
Confirm Application Wallet Password	Enter the password for the application wallet again.

Field

Description

Application Wallet Password

The password for the application wallet.

This wallet stores the BRM REST Services Manager connection secret, Infranet connections, and keystore and truststore passphrases.

Confirm Application Wallet Password

Enter the password for the application wallet again.

In the Security Details window, do one of the following and then click Next.
- If you want to configure BRM REST Services Manager securely, select Yes.
- If you want to configure BRM REST Services Manager in a test installation mode, select No and go to step 12.

In the Identity Provider Details window, enter the details listed in Table 11-5 and then click Next.

Table 11-5 Identity Provider Details

Field	Description
Identity URL	The base URL of your Identity Provider (IdP) server.
Scope Audience	The primary audience registered for the application which is appended for scopes.
Audience	The name of the Oracle Access Manager OAuth server.
Client Id	The client ID of the application.
Client Secret	The client secret of the application.

In the Installation Summary window, review the selections you made in the preceding windows and then click Install.
The Installation Progress window appears. When the installation completes, click Next.

Note:
After the installation begins, you cannot stop or cancel the installation.
The Installation Complete window appears. Make note of the BRM REST Services Manager base URL. You use this URL to access BRM REST Services Manager.

Note:
You can find the BRM REST Services Manager logs in the REST_home/logs directory, where REST_home is the BRM REST Services Manager installation directory.
Click Finish to complete the installation.

The BRM REST Services Manager installer exits.
(For Security-Enabled Installations) Configure the JWT claim that contains the user groups or roles used by BRM REST Services Manager. In your application.yaml file, add or update the following configuration:
```
jwt-groups-path: groups
```
The jwt-groups-path configuration specifies the JWT claim from which BRM REST Services Manager retrieves group or role information. The default value is groups.

If your Identity Provider (IdP) includes group or role information in a different JWT claim, set jwt-groups-path to the name of that claim. For example, if your IdP uses the roles claim instead of groups, configure:
```
jwt-groups-path: roles
```
Ensure that your IdP includes the specified claim in the JWT.
(For Security Enabled with Identity Provider) If your IdP requires an introspection endpoint to validate the JWT, uncomment the introspect-endpoint-uri entry in your application.yaml file and set it to the introspection endpoint.

Note:

For example, if you are using Oracle Access Management as your IdP, you need to uncomment and set the introspect-endpoint-uri entry.
After installation completes, run the REST_home/scripts/start-brm-rsm.sh script to bring up BRM REST Services Manager.

Installing BRM REST Services Manager in Silent Mode

Use silent mode when you want to install BRM REST Services Manager using the same configuration repeatedly. The silent installation uses a response file in which you have set installation information. To obtain the response file, you run the GUI installer for the first install. The GUI installer generates a response file that contains the key-value pairs based on the values that you specify during the GUI installation. You can then copy and edit the response file to create additional response files for installing the BRM REST Services Manager on different machines.

Creating a Response File

To create a response file:

Create a copy of the response file that was generated during the GUI installation. See "Installing BRM REST Services Manager in GUI Mode" for more information.
Note:

A response file was created only if you ran the GUI installer with this command:
```
Java_home/bin/java -jar jarFile -record -destinationFile path
```
Open the response file in a text editor.
Manually add all passwords to the response file. The GUI Installer does not store the passwords that you provided during installation in the response file.
Modify the key-value information for the parameters you want in your installation.

Note:

The Installer treats incorrect context, format, and type values in a response file as if no value were specified.
Save and close the response file.

Performing a Silent Installation

To install BRM REST Services Manager in silent mode:

Create a response file. See "Creating a Response File".
Copy the response file you created to the machine on which you run the silent installation.
On the machine on which you run the silent installation, go to the temp_dir directory and run the following command:
```
Java_home/bin/java -jar jarFile -debug -invPtrLoc Inventory_home/oraInventory/oraInst.loc -responseFile path -silent
```
where:
- Java_home is the directory in which you installed the latest supported Java version.
- jarFile is the BRM installer file. For example:
```
BRM_REST_Services_Manager-16.26.0.0.0.0.jar
```
- path is the absolute path to the response file.
For example:
```
Java_home/bin/java -jar BRM_REST_Services_Manager-16.26.0.0.0.0.jar -debug -invPtrLoc Inventory_home/oraInventory/oraInst.loc -responseFile /tmp/BRM_REST_Services_Manager.rsp -silent
```
The installation runs silently in the background.
Tip:

You can run the following command to get more details about the options.
```
Java_home/bin/java -jar jarFile -help
```
After installation completes, run the REST_home/scripts/start-brm-rsm.sh script to start BRM REST Services Manager.
Open the BRM REST Services Manager URL (https://hostname:port/) in a browser.

Note:

You can find the port number in the REST_home/scripts/application.yaml file. The HTTPS port is in the server.port entry, and the HTTP port is in the server.sockets.plain.port entry.

BRM REST Services Manager Postinstallation Tasks

After you install BRM REST Services Manager, perform these postinstallation tasks:

Setting Up a Custom Truststore

If you want to use a custom truststore instead of the Java truststore, do the following:

Stop BRM REST Services Manager by running the REST_home/scripts/stop-brm-rsm.sh script.
In the REST_home/scripts/brm_rsm.properties file, configure the path to the truststore file in the TRUST_STORE_FILE_PATH key.
Store the truststore passphrase in the TRUST_STORE_PASSPHRASE configuration entry in the client wallet by running the following command:
```
java -cp ".:oraclepkijarLocation:cetjarLocation"com.portal.cet.ConfigEditor -setconf -wallet clientWalletLocation –parameter configEntry -value value
```
where:
- oraclepkijarLocation: The path to the oraclepki.jar file.
- cetjarLocation: The path to the cet.jar file.
- clientWalletLocation: The full path to the client wallet.
- value: The truststore password in Base64-encoded format.
By default, BRM REST Services Manager uses the keystore password to access the truststore. If the truststore password differs from the keystore password:
1. Open REST_home/scripts/start-brm-rsm.sh in a text editor.
2. Locate the code that retrieves the truststore password from the client wallet, and replace its reference to KEY_STORE_PASSPHRASE with TRUST_STORE_PASSPHRASE, the wallet entry you populate in step 3.
3. Save the file.
Start BRM REST Services Manager by running the REST_home/scripts/start-brm-rsm.sh script.

Configuring Policies for API Authorization

To configure the policies for API authorization:

Stop BRM REST Services Manager by running the REST_home/scripts/stop-brm-rsm.sh script.
Define the API authorization rules in a policy file.

You can use the sample authorization policy file (REST_home/scripts/authorization-policy.yaml) as a template for defining API authorization rules.
For any new BRM REST Services Manager API endpoints, ensure that appropriate policy statements are added to the file. This is essential for enforcing proper authorization and access restrictions for each new API.
Start BRM REST Services Manager by running the REST_home/scripts/start-brm-rsm.sh script.

Configuring External ID Mapping in BRM REST Services Manager

BRM REST Services Manager supports external identification code mapping in place of POID mapping for non-master resources. You can enable or disable this functionality by setting the externalIdMappingEnabled property in the REST_home/scripts/application.yaml file.

To configure external ID mapping:

Stop BRM REST Services Manager by running the REST_home/scripts/stop_brm_rsm.sh script.
Open the REST_home/scripts/application.yaml file in a text editor.
Set externalIdMappingEnabled to true to enable external ID mapping or false to disable it.
```
externalIdMappingEnabled: value
```
Save the application.yaml file.
Start BRM REST Services Manager by running the REST_home/scripts/start_brm_rsm.sh script.

Note:

For event mappings, identification code mapping is always enabled, regardless of the value of externalIdMappingEnabled.

Excluding the BRM REST Services Manager SDK

The BRM REST Services Manager package installs both the BRM REST Services Manager API and the BRM REST Services Manager SDK on your system.

If you do not want to include the BRM REST Services Manager SDK in your deployment, remove this entry from the REST_home/scripts/brm_rsm.properties file: EXTENSION_LIB_PATH.

Updating BRM Connection Details

By default, the BRM REST Services Manager installer stores sensitive information such as passwords in the Oracle wallet, and BRM REST Services Manager retrieves the passwords from the Oracle wallet. However, you can update this sensitive information after the installation.

To update the BRM connection details:

Stop BRM REST Services Manager using this command:
```
REST_home/scripts/stop_brm_rsm.sh
```
Navigate to the REST_home/wallet directory, where REST_home is the BRM REST Services Manager installation directory.
Run the following command to update the BRM connection details:
```
java -cp ".:oraclepkijarLocation;cetjarLocation"com.portal.cet.ConfigEditor -setconf -wallet clientWalletLocation –parameter configEntry -value value
```
where:
- clientWalletLocation is the path to the client wallet.
- configEntry is the configuration entry in the client wallet.
- value is the appropriate value for the respective entry in the client wallet.
Start BRM REST Services Manager using this command:
```
REST_home/scripts/start_brm_rsm.sh
```

Updating the Base URL

After installation, you can update the base URL with the resource details to return in the response of BRM REST Services Manager requests. To do so, edit the REST_home/scripts/application.yaml file.

Modifying BRM REST Services Manager Properties

To modify the BRM REST Services Manager properties:

Stop BRM REST Services Manager using this command:
```
REST_home/scripts/stop_brm_rsm.sh
```
Open the REST_home/scripts/brm_rsm.properties file in a text editor.
Modify the properties based on your requirements. For example, changing the port number and log level.
Save the brm_rsm.properties file.
Start BRM REST Services Manager using this command:
```
REST_home/scripts/start_brm_rsm.sh
```

Setting Up Zipkin Tracing in BRM REST Services Manager

You can trace the flow of API calls made to BRM REST Services Manager by using Zipkin, which is an open-source tracing system. For more information, see the Zipkin website: https://zipkin.io/.

To set up Zipkin tracing for BRM REST Services Manager:

Install Zipkin. See the Zipkin Quickstart documentation: https://zipkin.io/pages/quickstart.html.
Stop BRM REST Services Manager using this command:
```
REST_home/scripts/stop_brm_rsm.sh
```

In your application.yaml file, update the following entries, as necessary:

otel:
   traces:
      exporter: zipkin
   sdk:
      disabled: true
   service:
      name: brm-rest-service-manager
   exporter:
      zipkin:
         endpoint: ${traces.protocol}://${traces.host}:${traces.port}/api/v2/spans

Start BRM REST Services Manager using this command:
```
REST_home/scripts/start_brm_rsm.sh
```

Afterward, you can start tracing the flow of API calls to BRM REST Services Manager by using the Zipkin UI or Zipkin API.

Using Correlation IDs for End-to-End Tracing

BRM REST Services Manager supports correlation IDs for end-to-end tracing of API requests and Kafka events through BRM REST Services Manager and the BRM opcode layer.

For API requests, specify the correlation ID in the X-Correlation-ID HTTP request header.
For Kafka events, specify the correlation ID in either the X-Correlation-ID Kafka message header or the correlationId property in the event payload.

Using Correlation IDs for End-to-End Tracing explains how BRM REST Services Manager determines the correlation ID.

Table 11-6 How Correlation IDs are Determined

Condition	Behavior
The correlation ID is present in both the event payload and Kafka message header.	The value in the event payload takes precedence.
The correlation ID is present only in the Kafka message header.	The value in the message header is used.
The correlation ID is absent from both locations.	The correlation ID remains empty.

Connecting BRM REST Services Manager to Oracle Analytics Publisher

To enable BRM REST Services Manager to retrieve PDF invoices generated by Oracle Analytics Publisher:

Update the following Oracle Analytics Publisher connection details in the BRM REST Services Manager wallet:
- BIP_USERID: Set this to the Oracle Analytics Publisher user that has web access.
- BIP_PASSWORD: Set this to the password for the Oracle Analytics Publisher user password.
- BIP_URL: Set this to the URL for accessing the Oracle Analytics Publisher instance. For example: http://hostname:port/xmlpserver/services/PublicReportService_v11.

To store the connection details in the wallet, enter the following command:

java -cp ".:oraclepkijarLocation:cetjarLocation"com.portal.cet.ConfigEditor -setconf -wallet clientWalletLocation –parameter configEntry -value value

Configuring BRM REST Services Manager for High Availability

You can optionally configure BRM REST Services Manager for high availability.

Because BRM REST Services Manager is a relatively simple API service, you can support high availability by using the open-source load balancer of your choice, such as Apache HTTP Server or HAProxy. The load balancer automatically routes requests to whichever server is available, which enables greater scalability by sharing the traffic among servers, and also lets processing continue if an instance is down.

The basic steps for configuring BRM REST Services Manager for high availability are:

Install and configure BRM REST Services Manager. You can install multiple instances on the same server by using a different port or install different instances on different servers.
Install a load balancer. You can install the load balancer on the same server as one of your BRM REST Services Manager instances, or a different server with access to the BRM REST Services Manager servers.
Add the details of the BRM REST Services Manager servers to the load balancer, using a proxy to pass traffic to the group of servers.

Allowing the Use of Deprecated Cyphers

According to security best practices, by default BRM Rest Services Manager restricts less-secure cyphers from being used. These restricted cyphers are listed in REST_home/scripts/security.properties. You can change this configuration if you are willing to take the risk of allowing less-secure cyphers.

To allow individual restricted cyphers:

Stop BRM REST Services Manager using this command:
```
REST_home/scripts/stop_brm_rsm.sh
```
Back up the REST_home/scripts/security.properties file.
Open the REST_home/scripts/security.properties file in a text editor.
Remove the names of any cyphers you would like to allow.
Save the security.properties file.
Start BRM REST Services Manager using this command:
```
REST_home/scripts/start_brm_rsm.sh
```

To remove all cypher restrictions:

Stop BRM REST Services Manager using this command:
```
REST_home/scripts/stop_brm_rsm.sh
```
Open the REST_home/scripts/brm_rsm.properties file in a text editor.
Set the value of the OVERRIDE_SECURITY_PROPERTIES property to false.
Save the brm_rsm.properties file.
Start BRM REST Services Manager using this command:
```
REST_home/scripts/start_brm_rsm.sh
```

Customizing REST Services with the Mapper Framework

Learn how to customize REST service payload mapping for Oracle Communications REST Services Manager using the Mapper Framework in a cloud native environment. You can use the mapper file to control how REST API payloads are transformed to and from internal BRM data structures (FLIST). By customizing the mapper file, you can extend or override out-of-the-box mappings, adapt to business requirements, and enable advanced field transformations.

Topics in this document:

Introduction to the Mapper File

The mapper file defines the transformation logic for each REST API endpoint and the event framework. It maps fields in incoming JSON requests to BRM FLIST fields and maps FLIST response fields back to outgoing JSON. Customizing the mapper file provides flexibility without requiring changes to underlying service code.

You can use the mapper file to:

Implement custom REST API payload logic.
Extend or override default field mappings.
Support multiple API versions and endpoints.
Add custom business rules, data validation, and type conversions.

Sample Events Configuration:

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"
                  Product:
                     request:
                        - "mapper.brm.v5.tmf637.post.request.product"
                        - "mapper.brm.v5.tmf637.post.request.extendedProduct"
                     response:
                        - "mapper.brm.v5.tmf637.post.response.product"
                        - "mapper.brm.v5.tmf637.post.response.extendedProduct"

where:

ProductCreateEvent defines the type of event.
mapper-specification-keys specifies logical profiles or mapping variants.
default is the fallback mapping key used if no specific match for schema type is found from the request payload.
execute, request, and response designate the mapping configuration files to be applied for execution opcode, request transformation, and response transformation respectively.

Understanding the Mapper File Structure

The mapper file defines the transformation logic for each REST API endpoint. It maps fields in incoming JSON requests to BRM FLIST fields and maps FLIST response fields back to outgoing JSON. Customizing the mapper file provides flexibility without requiring changes to underlying service code.

You can use the mapper file to:

Implement custom REST API payload logic.
Extend or override default field mappings.
Support multiple API versions and endpoints.
Add custom business rules, data validation, and type conversions.

Mapper files are written in YAML format and contain these key sections:

request: Defines how incoming JSON fields are mapped to BRM FLIST fields.
response: Defines how FLIST response fields are mapped to outgoing JSON.
execute: Contains BRM opcode and opcode flag information.

Note:

Mapper files do not contain a top-level validation section. Use optional on a per-field basis as needed.

Examples and Supported Field Attributes

The order in which mapper keys are defined determines the order of overrides: if a key is defined last, it will override any common keys present earlier. You must ensure that your custom mapper keys are referenced correctly in your configuration (such as in application.yaml or through deployment values).

Example configuration snippet:

config:
  paths:
    apiSpecifications:
      brm/productInventory/v5/product:
        post:
          mapper-specification-keys:
            default: Product
            Product:
              execute:
                - "mapper.brm.v5.tmf637.post.execute.product"
              request:
                - "mapper.brm.v5.tmf637.post.request.product"
                - "mapper.brm.custom.v5.tmf637.post.request.product"
              response:
                - "mapper.brm.v5.tmf637.post.response.product"
                - "mapper.brm.custom.v5.tmf637.post.response.product"

where:

config is the top-level configuration object containing all Mapper Framework settings.
paths is the section that defines REST API endpoint path specifications.
apiSpecifications is the mapping of API specifications to their endpoints.
brm/productInventory/v5/product is the specific API resource path being mapped.
post is the HTTP POST method being specified for mapping.
mapper-specification-keys is the list specifying which mappers to use for the endpoint and method.
default is the fallback mapping key used if no specific match for schema type is found from the request payload.
Product is the schema type for the request and response mapping obtained from request payload.
request is the listing of request-mapping keys or files to handle incoming API payload mapping.
response is the listing of response-mapping keys or files to handle returned API payload mapping.

Example 1: Simple Mapping

request:
  product:
    Product:
      field: PIN_FLD_PRODUCT
      optional: false
      dataFields:
        id:
          field: PIN_FLD_POID
          fieldValue: ""
          optional: false
response:
  product:
    PIN_FLD_PRODUCT:
      field: product
      type: array
      dataFields:
        PIN_FLD_POID:
          field: id
          type: string

where:

request is the top-level section defining how incoming JSON is mapped to BRM fields.
Product is the logical identifier/object being mapped in the request or response.
field is the target field within the payload or mapping output/input location.
dataFields is the grouping of child fields requiring mapping under the main object.
id is the attribute or subfield (such as a product identifier) being mapped.
PIN_FLD_POID is the BRM internal field for Portal Object Identifier (the mapped field in BRM).

Example 2: Array and Substructure Mapping

request:
  product:
    orderItems:
      field: PIN_FLD_ORDER_ITEMS
      optional: false
      arrayIndex: 0
      dataFields:
        price:
          field: PIN_FLD_PRICE
          fieldValue: ""
          optional: true

where:

orderItems is an array field within the product object, representing line items in the order.
PIN_FLD_ORDER_ITEMS is the BRM array field for order items; square brackets indicate an array.
arrayIndex specifies the array position used for mapping (for example, zero is the first element).
price is the field representing the price for each order item.
PIN_FLD_PRICE is the BRM field for price, the mapping destination for the price data.

Example 3: Dynamic FieldValue Calculation

fieldValue: "${(getVal(context[3], 'PIN_FLD_BASE_AMOUNT') + getVal(context[3], 'PIN_FLD_FEE')) * getVal(context[2], 'PIN_FLD_MULTIPLIER') - getVal(context[5], 'PIN_FLD_DEDUCTION')}"

where:

PIN_FLD_PRICE is the BRM field for price, where the calculated value is stored.
fieldValue is the value assigned to this field; in this case, it uses Jakarta Expression Language (EL).
getVal is a Jakarta EL function that retrieves the value of a given field from the specified context/hierarchy level.
context is an array representing the hierarchical path through the payload or FLIST object at different levels; context[n] refers to a specific depth in the hierarchy.
base, supportFee, multiplier, and deduction are field names within the corresponding context objects used in the calculation formula.

Mapper Features

The Mapper Framework allows you to map and transform REST API payloads to and from BRM data structures. You can use these features to handle complex mapping scenarios.

API-Based Mapping

You can define mapping rules for each REST API endpoint and HTTP method, tailoring the mapping logic to each business operation. This enables you to ensure each API’s request and response format properly aligns with the required BRM data structure. For example, you can configure separate mappings for /productInventory/v5/product for POST and GET methods, ensuring the request and response structures match each API’s requirements.

Example:

mapper:
   brm:
      v5:
         tmf637:
            post:
               execute:
                  product:
                     brmOpcode: PRODUCT_INVENTORY_POST
                     opcodeFlag: 0
               request:
               response:
            get:
               execute:
                  product:
                     brmOpcode: PRODUCT_INVENTORY_GET
                     opcodeFlag: 0
               request:
               response:

Versioning Support

You can create and define separate mappings for different versions of APIs. You can use the corresponding mappings based on the version of the API being invoked.

Example:

mapper:
   brm:
      v5:
         tmf637:
            productCreateEvent:
            productDeleteEvent:
            productAttributeValueChangeEvent:
            productStateChangeEvent:
            delete:
            post:
            patch:
            get:
      v6:
         tmf637:
            productCreateEvent:
            productDeleteEvent:
            productAttributeValueChangeEvent:
            productStateChangeEvent:
            delete:
            post:
            patch:
            get:

Opcode, Schema, and Flags

Each mapping can specify a BRM opcode. The opcode determines which internal BRM operation runs for a request. You can also attach schema information to control FLIST structure validation, and apply flags to influence how the opcode is executed.

Note:

The BRM opcode supports Jakarta expressions. You can use Jakarta expression for opcode evaluation aswell

Example:

mapper:
  brm:
    v5:
      tmf637:
        productCreateEvent: ...
        productDeleteEvent: ...
        productAttributeValueChangeEvent: ...
        productStateChangeEvent: ...
        delete: ...
        post:
          execute:
            product:
              brmOpcode: PRODUCT_INVENTORY_POST
              opcodeFlag: 0
          request: ...
          response: ...
        patch:
          execute: ...
          request: ...
          response: ...
        get:
          execute:
            product:
              brmOpcode: PRODUCT_INVENTORY_GET
              opcodeFlag: 0

Sample Expression:

brmOpcode: "${getVal(context[0], 'operation') == 'edit' ? 'SUSPENSE_SEARCH_EDIT' : (getVal(context[0], 'operation') == 'recycle' ? 'SUSPENSE_SEARCH_RECYCLE' : (getVal(context[0], 'operation') == 'writeoff' ? 'SUSPENSE_SEARCH_WRITE_OFF' : 'SUSPENSE_SEARCH_DELETE'))}"

In this case, the brmOpcode is determined depending on the value of the operation field in the request payload.

Request and Response Mapping

Easily map REST API JSON fields to corresponding BRM FList fields for both requests and responses. You can handle simple or complex (nested, array) structures. Each mapping file contains a request block and a response block.

In the request block, you define how fields in the incoming JSON map to BRM FLIST fields.
In the response block, you map BRM FLIST fields back to JSON for the API output.

Mappings can be simple (one field to one field), or complex, including arrays and nested structures.

Example:

request:
  productName:
    field: PIN_FLD_NAME
    optional: false
response:
  PIN_FLD_NAME:
    field: productName
    type: string

Field Enumeration

Field enumeration is a way to restrict a field’s value to a specific set of allowed options. When you define an enumeration for a field, only the listed values are considered valid, and any other input will be rejected during validation. This ensures data consistency between API payloads and BRM, and helps prevent errors from invalid or unexpected values. In the following example, you can use different string values from request and to convert it to corresponding values accepted by BRM. For example, Credit Card changes to 10001 for FList population. This is applicable for both request and response.

Example (Enumeration):

payType:
  field: PIN_FLD_PAY_TYPE
  fieldValue: "${{'Credit Card': 10001, 'Cash': 10011, 'Check': 10012}[getMapKey(context[0], 'payType')]}"

Validation Rules for Map

For the validation key in a request, you can use the following rules:

To specify the type of a field, use one of the supported types: string, int, double, boolean, object, array, long, date.
```
validation: "type:[string]"
```
To specify a date format (the format must be readable by Java):
```
validation: "format:[yyyy-MM-dd]"
```
For enumerated values, define a list of permissible values:
```
validation: "enum:[value1,value2,value3]"
```
To restrict the range of any numerical field:
```
validation: "range:[min=1,max=1000]"
```
To use regex pattern matching on a field:
```
validation: "pattern:[^[a-zA-Z0-9]+$]"
```
To use multiple validation rules at once, provide them as a comma-separated list:
```
validation: "range:[min=1000,max=5000],pattern:[^\\d+$],enum:[3000,2000,2048]"
```

Note:

Enclose all rule values within square brackets [ ], as shown in the examples above.

Mapper Expressions (Jakarta EL)

You can use Jakarta Expression Language (EL) within field and fieldValue to evaluate values at runtime in your mapping files. These expressions use context objects to refer to fields at different levels of the JSON or FLIST structure.

You can use these built-in expressions inside the ${...} blocks in your YAML mapping files to reference fields, perform lookups, and create URLs during mapping.

Mapper Expression Functions

The Mapper Framework supports three primary mapper expression functions by default:

getVal: Use getVal to extract the value of a specific key from a JSON object or FList. In request mappings, getVal(context[index], 'key') retrieves a field from the JSON payload. In response mappings, it fetches a value from the flist object.
```
fieldValue: "${getVal(context[0], 'accountId')}"
```
getMapKey: Use getMapKey for field enumeration and value mapping. It looks up the appropriate BRM code or value based on a key from the context and an inline map definition.
```
fieldValue: "${{'Credit Card': 10001, 'Cash': 10011, 'Check':10012}[getMapKey(context[0], 'payType')]}"
```
generateResourceUrl: Use generateResourceUrl to generate an href or URL reference for a BRM resource. This is commonly used to set the href field in API responses.
```
href:
  fieldValue: "${generateResourceUrl('paymentMethods/v4/paymentMethod/')}"
```
isIndexInRange: Checks whether a numeric index falls within the inclusive range defined by the given lower and upper bounds for an flist field in the PIN_FLD_BILL_STRUCTURE_INFO array. This maps indexes 0 and 1 to billStructure, and all other indexes to serviceBillStructure.
```
field: "${isIndexInRange(0, 1, arrayIndex) ? 'billStructure' : 'serviceBillStructure'}"
```

Object Support (Request and Response)

The Object parameter supports two types of objects for both request and response processing:

context is a list that stores data based on hierarchy. You must specify the index to indicate which level of the object you are referring to. If you do not reference an index, context at the same level where the expression exists will be used.
- On the request side, context contains JsonNode objects representing the request payload.
- On the response side, context contains FList objects representing the response payload.
rootContext stores the complete payload during processing and you can use it directly without specifying an index.
- On the request side, rootContext is a JsonNode object that holds the entire request payload.
- On the response side, rootContext is an FList object that holds the entire response payload.

When you process a bundled product, the system creates a new hierarchy. rootContext allows you to access data outside the current context. Once processing is complete, it restores the original hierarchy. You may use context[index], context, or rootContext as the Object.

Understanding the Hierarchy

Consider this request mapping:

productPrice:
  field: PIN_FLD_PRODUCT_PRICE
  validation: ""
  optional: true
  dataFields:
    description:
      field: ""
      fieldValue: "ProductPrice"
      validation: ""
      optional: true
    priceAlteration:
      field: PIN_FLD_VALUES
      validation: ""
      optional: true
      dataFields:
        _attype:
          field: ""
          fieldValue: "PriceAlteration"
          validation: ""
          optional: true
        price:
          field: ""
          validation: ""
          optional: true
          dataFields:
            dutyFreeAmount:
              field: PIN_FLD_PRICING_INFO
              validation: ""
              optional: true
              dataFields:
                unit:
                  field: PIN_FLD_UNIT_STR
                  validation: ""
                  optional: true
                value:
                  field: PIN_FLD_AMOUNT
                  validation: ""
                  optional: true
            taxIncludedAmount:
              field: ""
              fieldValue: ""
              validation: ""
              dataFields:
                unit:
                  field: PIN_FLD_UNIT_STR
                  validation: ""
                  optional: true
                value:
                  field: PIN_FLD_AMOUNT
                  validation: ""
                  optional: true

In this mapping:

context[0] holds the entire payload.
At any dataFields of dutyFreeAmount, the hierarchy objects are:
- context[0] is the entire JSON payload as JsonNode
- context[1] is the productPrice as JsonNode
- context[2] is the price as JsonNode
- context[3] is the dutyFreeAmount as JsonNode
For dataFields of taxIncludedAmount, the hierarchy objects are:
- context[0] is the entire JSON payload as JsonNode
- context[1] is the productPrice as JsonNode
- context[2] is the price as JsonNode
- context[3] is the taxIncludedAmount as JsonNode

The response side maintains a similar hierarchy structure.

Removing Inherited or Obsolete Fields

You can override or delete fields inherited from a base mapping by specifying action: delete for that field in your custom mapper file. Example:

obsoleteField:
  action: delete

This removes the inherited mapping for obsoleteField in your endpoint configuration.

Advanced Mapping Scenarios

You can use the features listed above for solutions to common mapping scenarios:

Handling Data Fields

You map deeply nested structures using the dataFields attribute. Example:

account:
  field: PIN_FLD_ACCOUNT
  dataFields:
    firstName:
      field: PIN_FLD_FIRST_NAME
    lastName:
      field: PIN_FLD_LAST_NAME

This maps account.firstName and account.lastName in the payload to the appropriate BRM fields.

If a base field is nested, you can omit the keyword dataFields from a substruct or array field in the base mapper file to use the base schema and that if a nested field is encountered, it is an instance of the same object. For example:

product:
    field: PIN_FLD_PRODUCTS
    fieldValue: ""
    optional: false
    validation: ""

In this case, the schema applicable for the product field is assumed to be the same as that used for the base request, and is a nested field of the same schema. This is applicable for both the request and the response.

Assigning Default Values

You can use the fieldValue attribute to specify a default value for a field in a mapper file. If the source data does not contain the field, REST Services Manager uses the specified default value.

For example:

quantity:
  field: PIN_FLD_QUANTITY
  fieldValue: "1"
  optional: true

If the API request payload omits quantity, REST Services Manager uses 1 as the default value.

Note:

If fieldValue contains a Jakarta EL expression, REST Services Manager evaluates the expression. Otherwise, it treats the specified literal value as a default value.

Assigning Default Values in Request Mappings

You can specify default values for fields within arrays and objects in request mappings. When a request payload omits an array or object, REST Services Manager considers whether the field is optional and whether default values are available for its child fields.

For example, consider the following request mapping:

productCharacteristic:
  field: PIN_FLD_PRODUCT_CHARACTERISTIC
  fieldValue: ""
  optional: false
  validation: ""
  dataFields:
    name:
      field: PIN_FLD_NAME
      fieldValue: ""
      optional: false
      validation: ""

defaultProductCharacteristic:
  field: PIN_FLD_PRODUCT_CHARACTERISTIC
  fieldValue: ""
  optional: false
  validation: ""
  dataFields:
    name:
      field: PIN_FLD_NAME
      fieldValue: "DefaultName"
      optional: false
      validation: ""

optionalProductCharacteristic:
  field: PIN_FLD_PRODUCT_CHARACTERISTIC
  fieldValue: ""
  optional: true
  validation: ""
  dataFields:
    name:
      field: PIN_FLD_NAME
      fieldValue: ""
      optional: false
      validation: ""

REST Services Manager handles omitted fields in this example as follows:

productCharacteristic: If the request payload omits this field, REST Services Manager returns an error because the field is not optional and no applicable child default value is specified.
defaultProductCharacteristic: If the request payload omits this field, REST Services Manager does not return an error. Although the field is not optional, its child field name has a default value of DefaultName, which REST Services Manager uses to populate the mapping.
optionalProductCharacteristic: If the request payload omits this field, REST Services Manager does not return an error because the field is optional.

This behavior allows REST Services Manager to populate array and object fields from configured default values even when the corresponding data is absent from the request payload.

Assigning Default Values in Response Mappings

You can use the isDefault attribute to specify default entries in a response mapper.

Set isDefault to true on a parent field to treat all its child fields as default response entries. Alternatively, you can set isDefault to true on an individual field to specify a default value for that field.

If you omit the isDefault attribute, REST Services Manager treats its value as false.

For example, the following response mapping uses isDefault: true to populate an array and its child fields with default values:

response:
  productChar:
    field: "productChar"
    fieldValue: ""
    isDefault: true
    type: array
    dataFields:
      id:
        field: "id"
        fieldValue: "def_id"
        type: string
      name:
        field: "name"
        fieldValue: "name_1"
        type: string
      isBundle:
        field: "isBundle"
        fieldValue: "false"
        type: boolean
      amount:
        field: "amount"
        fieldValue: "10.3"
        type: float
      quantity:
        field: "quantity"
        fieldValue: "${getVal(context, 'PIN_FLD_SCENARIO_INFO.PIN_FLD_ENTRY_DAYS')}"
        type: integer
      data:
        field: "data"
        fieldValue: ""
        type: object
        dataFields:
          login:
            field: "login"
            fieldValue: "login_1"
            type: string
          amount:
            field: "amount"
            fieldValue: "11.2"
            type: double

In this example, isDefault: true is specified for productChar. Therefore, its child fields, including those within the nested data object, are treated as default response entries.

The quantity field uses a Jakarta EL expression to retrieve the value of PIN_FLD_ENTRY_DAYS from PIN_FLD_SCENARIO_INFO in the BRM FLIST.

For example, if the FLIST contains the following data:

0 PIN_FLD_SCENARIO_INFO  SUBSTRUCT [0]
1     PIN_FLD_ENTRY_DAYS  INT [0] 2

REST Services Manager generates the following JSON response:

{
  "productChar": [
    {
      "id": "def_id",
      "name": "name_1",
      "isBundle": false,
      "amount": 10.3,
      "quantity": 2,
      "data": {
        "login": "login_1",
        "amount": 11.2
      }
    }
  ]
}

The response includes the configured default values. The quantity field contains 2, which is obtained by evaluating the Jakarta EL expression.

Note:

Jakarta EL expressions are evaluated even when the fields are configured as default response entries.

Changing BRM Field Values

You use fieldValue or mapper expressions (Jakarta EL) to set or transform BRM field values based on input, context, or calculations. Example:

price:
  field: PIN_FLD_PRICE
  fieldValue: "${getVal(context[1], 'base') * 1.07}"

This multiplies the base price by 1.07 (such as to apply tax).

Mapping Arrays and Array Indexes

You use arrayIndex to place or retrieve data at a specific index in a BRM array field. Example:

aliases:
  field: PIN_FLD_ALIAS_LIST
  arrayIndex: 0
  dataFields:
    name:
      field: PIN_FLD_NAME

This places the name value into the first element of the BRM alias list.

Handling Empty or Optional Fields

You use optional: true to indicate a field may be absent in the request or response. If the field exists but is empty, REST Services Manager omits it to the BRM FLIST unless prevented by additional validation. Example:

nickname:
  field: PIN_FLD_NICKNAME
  optional: true

Handling href Fields

You generate URL links (href) for resources in the response using static values or by running helper functions, allowing you to provide links back to created or referenced resources. Example:

href:
  field:
  fieldValue: "${generateResourceUrl('productInventory/v5/product/')}"
  type: string

Class Reference for Response Payloads:

To define fields such as @type and @referredType which are not present anywhere in FList but are required in the json field to reference classes:

_attype:
    field: ""
    type: string
    fieldValue: "Product"

where,

type is a string value.
fieldValue is the class name to populate into response payload.
_attype is the defined key, where _at is used instead of @ to prevent YAML syntax issues.

Note:

These classes mentioned above are for reference only; the actual data is taken from request payload.

Specifying Data Types in Response

You control data type in the response using the type key—for instance, mapping an integer to a string or a date. The supported key types are:

date
string
float
double
integer
boolean
json

Example:

PIN_FLD_START_T:
  field: startDate
  type: date

Using Dot Notation

You reference nested fields in request or response mappings using dot notation, such as parentField.childField. Example:

"contact.email":
  field: PIN_FLD_CONTACT_INFO.PIN_FLD_EMAIL

Handling Query Parameters, Path Parameters, and Storable Classes

You access HTTP query or path parameters by including their mapped names as top-level fields in your mapping. For advanced scenarios requiring additional object types or extended models (storable class), use custom handlers and reference them in your mapping definitions.

Example (Query Parameter):

queryParameter:
    field: PIN_FLD_ARGS
    dataFields:
         id:
             field: PIN_FLD_IS_BUNDLE
             fieldValue: ""
             validation: ""

Example (Path Parameter):

pathParameter:
  field: PIN_FLD_ARGS
  dataFields:
    id:
      field: PIN_FLD_POID

Example (StorableClass):

paymentMethod:
  storableClass: "/payinfo"

Note:

Query Parameters, Path Parameters, and Storable Classes are only applicable for GET.

Mapping Child Data from Unmapped Parent Objects

When there's an object/array in the JSON payload but there's no corresponding FList to map it to, yet the data inside the object/array is required for FList creation. You can handle this as follows:

price:
  field: PIN_FLD_PRICING_INFO
  validation: ""
  optional: true
  dataFields:
    _attype:
      field: ""
      fieldValue: "Price"
      validation: ""
      optional: true
    dutyFreeAmount:
      field: ""
      validation: ""
      optional: true
      dataFields:
        unit:
          field: PIN_FLD_UNIT_STR
          validation: ""
          optional: true
        value:
          field: PIN_FLD_AMOUNT
          validation: ""
          optional: true

Sample JSON:

{
  "price": {
    "@type": "Price",
    "dutyFreeAmount": {
      "unit": "USD",
      "value": 29.99
    }
  }
}

Sample FList:

0 PIN_FLD_PRICING_INFO    SUBSTRUCT [0] allocated 20, used 2
1     PIN_FLD_AMOUNT        DECIMAL [0] 29.99
1     PIN_FLD_UNIT_STR      STR [0] "USD"

Splitting and Mapping Composite JSON Fields to Multiple BRM Fields

There can be a case where you need to pass multiple BRM fields and multiple Jakarta EL expressions for a JSON entry. For this case, you can pass a comma-separated list of values as shown in the example.

contact:
  field: PIN_FLD_NAMEINFO
  fieldValue: ""
  validation: ""
  dataFields:
    contactName:
      field: PIN_FLD_FIRST_NAME, PIN_FLD_MIDDLE_NAME, PIN_FLD_LAST_NAME
      fieldValue: "${getVal(context, 'contactName').split(' ')[1]!=null ? getVal(context, 'contactName').split(' ')[0]: null}, ${getVal(context, 'contactName').split(' ')[2]!=null ? getVal(context, 'contactName').split(' ')[1] : null}, ${getVal(context, 'contactName').split(' ')[2] != null ? getVal(context, 'contactName').split(' ')[2] : (getVal(context, 'contactName').split(' ')[1] != null  ? getVal(context, 'contactName').split(' ')[1] : getVal(context, 'contactName').split(' ')[0])}"
      validation: ""

JSON PATCH Features

When you prepare a JSON Patch, you form a JSONPath expression and include it in the JSON Patch payload. The payload is an array of operations. Each object in the array contains these attributes:

op: Specifies the operation. Possible values are:
- replace: Replaces the value at the specified path with a new value.
- add: Adds a value at the path.
- remove: Removes the attribute at the path.
path: Contains the JSONPath expression for the operation.
value: Specifies the value for the "replace" and "add" operations.

JSONPath Expressions

lists the supported JSONPath expressions and describes how each one is used to access or modify elements within a JSON payload.

Table 11-7 Rules for Writing JSONPath Expressions

Expression	Description
$.	The expression starts with $. to refer to the root of the payload.
$.status	Refers to the status key in the root object.
$.productOffering.id	Refers to the id property inside the productOffering object.
$.productCharacteristic[?(@.name=='ServiceAlias' && @.id=='235' && @.valueType=='array')]	Selects elements from the productCharacteristic array that match all specified conditions. Use conditional statements inside square brackets to filter elements.
?(@.name=='ServiceAlias' && @.id=='235' && @.valueType=='array')	This is a conditional subexpression. It starts with a ? and uses @. before JSON keys. Only == and && operators are supported in JSON Patch. Enclose the condition in parentheses.
$.productCharacteristic[?(@.name=='ServiceAlias' && @.id=='235' && @.valueType=='array')].value	Accesses the value attribute of the selected productCharacteristic element.

Configuring and Adding Custom Mapper Files

By default, BRM REST Services Manager uses predefined mapper files to translate between JSON payload objects and BRM opcode flists for the latest versions of account and inventory management. However, you can customize this mapping by creating and adding your own mapper files. This allows you to extend or override the default mappings to meet your specific integration needs.

To extend or override the mapping between BRM REST Services Manager JSON objects and BRM opcode flists:

Create YAML files containing your custom mapping definitions. You can review sample files in the REST_home/referenceMappers directory for guidance.
Copy your custom YAML files to REST_home/extendedMappers.
Update the BRM REST Services Manager configuration so your custom YAML files are loaded at runtime. Open the REST_home/scripts/application.yaml file. Provide the path from your custom mapper files as requests, responses, or execute respectively. Update the application.yaml:
```
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 the fallback mapping key used if no specific match for schema type is found from the request payload.
- execute, request, and response designate the mapping configuration files to be applied for execution opcode, request transformation, and response transformation respectively.
  
  Note:
  
  For more information on custom mapper keys, see "Adding BRM REST Services Manager Keys" in the BRM Cloud Native Deployment Guide

Restart BRM REST Services Manager to load your changes. Run:

REST_home/scripts/stop_brm_rsm.sh
REST_home/scripts/start_brm_rsm.sh

Configuring the REST Services Manager Notification Service

Configure the REST Services Manager Notification Service and validate your deployment. See the relevant topics for more information.

(Optional) Review the overview and prerequisites before proceeding with configuration. See "Overview and Prerequisites for REST Services Manager Notification Service" for more information.
Follow the REST Services Manager Notification Service configuration process to ensure all components are set up correctly. See "REST Services Manager Notification Service Configuration Process" for more information.
Set up the required connection profiles for secure integration. See "Setting Up Connection Profiles" for more information.
Complete any outstanding post-installation tasks as described. See "Completing Post-Installation Tasks" for more information.
Perform verification and sanity checks to ensure your installation is functional. See "Performing Verification and Sanity Checks" for more information.
Apply the recommended security best practices before moving to production. See "Security Best Practices for REST Services Manager Notification Service" for more information.

Overview and Prerequisites for REST Services Manager Notification Service

Before you begin configuration, ensure that your environment satisfies all prerequisites for the REST Services Manager Notification Service. This section lists the required Kafka infrastructure, Oracle database wallet setup, and configuration file requirements.

Note:

In order to get event notifications, uncomment or add the required configurations as shown in this document.

Kafka Cluster and Topic requirements

Provision a Kafka cluster with sufficient brokers to meet your throughput and high availability requirements.
Define all topics required for the REST Services Manager Notification Service, including source, sink, retry, and dead-letter queue (DLQ) topics.
Ensure topics are created with the desired number of partitions and that appropriate access control lists (ACLs) are applied.
Record the hostnames and port numbers of all Kafka brokers.
Monitor Kafka server logs from time to time to validate if the connections are established.

Oracle Database Wallet Setup for Sensitive Values

Configure an Oracle database wallet to securely store sensitive credentials, such as SSL passphrases, keystore/truststore files, and database schema credentials.
The population of the Oracle database wallet with security certificates is dependent on the database listener and instance being pre-configured for SSL/TLS. Ensure that the database encryption layer is active before attempting to map Keystore and Truststore locations within the wallet.
Store the necessary wallet files and keystore/truststore files for secure connection to the database in a location secured with appropriate file permissions.
Do not place passwords or secrets in plain configuration files.

Tip:

Maintain separate folders for keystores, truststores, and the Oracle database wallet.

Note:

Review the default REST_home/scripts/application.yaml supplied with the deployment package and familiarize yourself with the configuration block structure.

REST Services Manager Notification Service Configuration Process

This section outlines the end-to-end workflow for configuring and setting up the Notification Service. Steps include extracting delivery packages, editing configuration files, and securely applying SSL/SASL parameters are needed for Kafka broker connectivity.

To configure and deploy Kafka, Oracle database consumers, and kafka producers:

Open the REST_home/scripts/application.yaml file for editing.
Uncomment the sections relevant to your deployment:
- Specify the active connection profiles.
- Specify the active consumer and producer profiles.
Populate connection parameters for Kafka and any required databases.
Apply the appropriate SSL/SASL parameters to secure broker access.
If your Kafka broker requires OAuth authentication over SASL_SSL, configure the Kafka connection profile as follows:
1. In the REST_home/scripts/application.yaml file, locate the Kafka connection profile under connection-profiles.
2. Under properties, set security.protocol to SASL_SSL.
3. Add the following properties to configure OAuth authentication:
  - sasl.jaas.config
  - sasl.login.callback.handler.class
  - sasl.mechanism
  - sasl.oauthbearer.token.endpoint.url
4. Set sasl.mechanism to OAUTHBEARER. Specify the OAuth client ID, client secret, scope, and token endpoint URL.
5. Retain the existing ssl.keystore.* and ssl.truststore.* configurations to enable SSL communication.
6. Store the OAuth client secret in the wallet and reference it in sasl.jaas.config using the corresponding wallet key.
The following example shows the SASL_SSL OAuth authentication properties for a Kafka connection profile in the REST_home/scripts/application.yaml file.
```
connection-profiles:
  - id: "cp1"
    profile-type: "kafka"
    host: "host"
    port: port
    properties:
      security.protocol: SASL_SSL
      sasl.jaas.config: 'org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required clientId="client_id" clientSecret="${WALLET.CP1_SASL_PASSPHRASE_KEY}" scope="scope";'
      sasl.login.callback.handler.class: org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginCallbackHandler
      sasl.mechanism: OAUTHBEARER
      sasl.oauthbearer.token.endpoint.url: "token_url"
```
Note:

When using SASL_SSL, retain the SSL properties specified in the sample Kafka connection profile configurations. See "Setting Up Connection Profiles" for the SSL configuration example.

Store secrets in the wallet using a key-value format. Use the corresponding keys within your configuration to retrieve the passwords at runtime.

java -cp ".;oraclepkijarLocation;cetjarLocation" com.portal.cet.ConfigEditor -setconf -wallet clientWalletLocation –parameter configEntry -value value

Save the configuration and verify all folder paths referenced in REST_home/scripts/application.yaml exist and are accessible by the REST Services Manager process.
Start REST Services Manager application to start the notification services.

To apply broker SSL/SASL parameters and store passphrases securely:

Enter SSL configurations (keystore, truststore locations and types, passwords) in REST_home/scripts/application.yaml, using wallet references.
Do not write plain credentials in configuration files. Reference them via wallet lookup.

Note:

When using SASL_SSL, retain the SSL properties specified in the sample Kafka connection profile configurations. See "Setting Up Connection Profiles" for the SSL configuration example.
Configure all Kafka SASL and SSL security properties under the properties section of the Kafka connection profile in REST_home/scripts/application.yaml. Specify the appropriate keystore and truststore file paths and use wallet references for passwords.

Setting Up Connection Profiles

Configure Kafka and database connection profiles in REST_home/scripts/application.yaml. Specify the connection details and reference credentials stored in the Oracle wallet.

To configure connection profiles and set up consumers and producers, see the following topics:

Kafka Connection Profiles

Set security.protocol to SSL or SASL_SSL under properties, according to your Kafka broker configuration.
Configure the keystore and truststore properties under properties.
Reference the wallet entries that contain the keystore and truststore passwords.

The following example shows Kafka and database connection profiles in the REST_home /scripts/application.yaml file:

connection-profiles:
  - id: "cp1"
    profile-type: "kafka"
    host: "kafka.example.com"
    port: 9093
    properties:
      auto.offset.reset: latest
      enable.auto.commit: false
      session.timeout.ms: 60000
      heartbeat.interval.ms: 10000
      connections.max.idle.ms: 3600000
      max.poll.records: 10
      max.poll.interval.ms: 600000
      max.partition.fetch.bytes: 1048576
      security.protocol: SSL
      ssl.keystore.type: PKCS12
      ssl.keystore.location: "/home/keystore.p12"
      ssl.keystore.password: "${WALLET.CP1_KEYSTORE_PASSPHRASE_WALLET_KEY}"
      ssl.truststore.type: PKCS12
      ssl.truststore.location: "/home/truststore.p12"
      ssl.truststore.password: "${WALLET.CP1_TRUSTSTORE_PASSPHRASE_WALLET_KEY}"
      acks: all
      retries: 3
      batch.size: 16384
      linger.ms: 1
      buffer.memory: 33554432
      compression.type: none

where:

id identifies the connection profile. Consumers and producers reference this identifier to select the profile.
profile-type specifies the connection type. Set this property to kafka for Kafka connections or database for database connections.
host specifies the host name or IP address of the Kafka broker or database server.
port specifies the connection port of the Kafka broker or database server.
properties contains connection properties for the selected profile type. For Kafka profiles, specify the following Kafka client properties under this section:
- auto.offset.reset determines where the consumer starts reading messages when no valid committed offset exists. Set this property to earliest to start with the earliest available messages or latest to start with new messages.
- enable.auto.commit controls whether the consumer automatically commits offsets. Always set this property to false in REST Services Manager.
- session.timeout.ms specifies the timeout, in milliseconds, that the broker uses to detect consumer failures.
- heartbeat.interval.ms specifies the interval, in milliseconds, between consumer heartbeats to the broker.
- connections.max.idle.ms specifies how long a connection can remain idle, in milliseconds, before the client closes it.
- max.poll.records specifies the maximum number of records that a single poll returns.
- max.poll.interval.ms specifies the maximum interval, in milliseconds, between poll calls before the broker considers the consumer to have failed.
- max.partition.fetch.bytes specifies the maximum amount of record data, in bytes, that the consumer requests per partition in a fetch request.
- security.protocol specifies the protocol for communicating with the broker. Set this property to SSL or SASL_SSL, according to your broker configuration.
- ssl.truststore.type specifies the truststore file format, such as PKCS12 or JKS.
- ssl.truststore.location specifies the path to the truststore file containing the certificates that the client uses to verify the broker’s identity.
- ssl.truststore.password specifies the password for accessing the truststore. Use the supported wallet reference mechanism to retrieve the password.
- ssl.keystore.type specifies the keystore file format, such as PKCS12 or JKS.
- ssl.keystore.location specifies the path to the keystore file containing the client certificate and private key. Configure this property when the broker requires client certificate authentication.
- ssl.keystore.password specifies the password for accessing the keystore. Use the supported wallet reference mechanism to retrieve the password.
- acks specifies the acknowledgments that the producer requires before considering a request successful. Set this property to all to require acknowledgment from all in-sync replicas.
- retries specifies the maximum number of retries for potentially recoverable failures when the producer sends records.
- batch.size specifies the default batch size, in bytes, for records that the producer sends to the same partition.
- linger.ms specifies how long the producer waits, in milliseconds, for additional records before sending a batch.
- buffer.memory specifies the total memory, in bytes, that the producer uses to buffer records before sending them.
- compression.type specifies the compression algorithm that the producer uses, such as none or gzip.

To configure client certificate authentication, set ssl.client.auth in the Kafka broker configuration. This property accepts the following values:

none (default): The broker does not require a client certificate.
requested: The broker requests a client certificate but allows clients to connect without one.
required: The broker requires each client to provide a valid certificate that it trusts. Set this value to enforce client certificate authentication for mutual TLS (mTLS).

Database Connection Profile

Configure a database connection profile in REST_home /scripts/application.yaml. Specify the database connection details, configure the SSL/TLS settings, and reference the wallet entries that contain the keystore and truststore passwords.

The following example defines the cp2 database connection profile. If you also configure a Kafka profile, add both profiles as separate list entries under a single connection-profiles key.

connection-profiles:
  - id: "cp2"
    profile-type: "database"
    host: "database.example.com"
    port: 1521
    properties:
      javax.net.ssl.keyStoreType: PKCS12
      javax.net.ssl.keyStore: "/home/keystore.p12"
      javax.net.ssl.keyStorePassword: "${WALLET.CP2_KEYSTORE_PASSPHRASE_WALLET_KEY}"
      javax.net.ssl.trustStoreType: PKCS12
      javax.net.ssl.trustStore: "/home/truststore.p12"
      javax.net.ssl.trustStorePassword: "${WALLET.CP2_TRUSTSTORE_PASSPHRASE_WALLET_KEY}"
    configuration:
      service-name: "pindb.example.com"

where:

id identifies the connection profile. Use this identifier when you reference the profile from a consumer.
profile-type specifies the connection type. Set this property to database.
host specifies the database server’s host name or IP address.
port specifies the database listener port for SSL/TLS connections. Replace 1521 with the port configured for your database listener.
properties contains the SSL/TLS settings that the application uses to establish the database connection:
- javax.net.ssl.keyStoreType specifies the keystore file format. Set this property to PKCS12 for a PKCS12 keystore.
- javax.net.ssl.keyStore specifies the absolute path to the keystore containing the client certificate and private key for client authentication.
- javax.net.ssl.keyStorePassword references the application wallet entry containing the keystore password. Replace CP2_KEYSTORE_PASSPHRASE_WALLET_KEY with the alias of your wallet entry, and retain the ${WALLET.…} syntax.
- javax.net.ssl.trustStoreType specifies the truststore file format. Set this property to PKCS12 for a PKCS12 truststore.
- javax.net.ssl.trustStore specifies the absolute path to the truststore containing the trusted certificates that the client uses to verify the database server’s certificate.
- javax.net.ssl.trustStorePassword references the application wallet entry containing the truststore password. Replace CP2_TRUSTSTORE_PASSPHRASE_WALLET_KEY with the alias of your wallet entry, and retain the ${WALLET.…} syntax.
configuration contains the database connection settings:
- service-name specifies the database service name for the connection. Replace pindb.example.com with the service name registered with your database listener.

Setting Up Consumers

Configure consumers in REST_home/scripts/application.yaml. Each consumer references a connection profile and defines the settings that REST Services Manager uses to retrieve and process events.

Add each consumer as a separate list entry under consumers. If you configure both Kafka and database consumers, place their entries under a single consumers key.

Kafka Consumers

Configure consumers in REST_home/scripts/application.yaml. Each consumer references a connection profile and defines the settings that REST Services Manager uses to retrieve and process events. Add each consumer as a separate list entry under consumers. If you configure both Kafka and database consumers, place their entries under a single consumers key.

The following example uses the cp1 Kafka connection profile. It enables strict ordering, uses Kafka buffering, and defines a downstream consumer for retries. Both consumers publish structured error details to their configured error topics.

consumers:
  - connection-profile-id: "cp1"
    properties:
      group.id: "brm-product-events"
    configuration:
      max-retries: 3
      retry-delay-interval-ms: 1000
      record-fetch-timeout-ms: 1000
      brm-connection-retry-interval-ms: 30000
      strict-ordering: true
      buffer-strategy: kafka
    topic-event-config:
      source-topic: "product-events"
      sink-topic: "product-events-retry"
      error-topic: "product-events-errors"
      key-state-topic: "product-events-key-state"
      consumer-thread-count: 1
      worker-thread-count: 1
      events:
        - ProductCreateEvent
        - ProductStateChangeEvent
        - ProductDeleteEvent
      downstream-consumers:
        - connection-profile-id: "cp1"
          properties:
            group.id: "brm-product-events"
          configuration:
            max-retries: 1
            record-fetch-timeout-ms: 1000
            brm-connection-retry-interval-ms: 30000
          topic-event-config:
            source-topic: "product-events-retry"
            sink-topic: "product-events-dlq"
            error-topic: "product-events-retry-errors"
            consumer-thread-count: 1
            worker-thread-count: 1
            events:
              - ProductCreateEvent
              - ProductStateChangeEvent
              - ProductDeleteEvent

Replace the example topic names and processing values with the values for your deployment. Create the referenced Kafka topics before you start the consumers.

where:

connection-profile-id identifies the connection profile that the consumer uses. In this example, cp1 references the Kafka connection profile.
properties contains Kafka client properties for the consumer. These properties override matching properties in the referenced connection profile.
- group.id identifies the Kafka consumer group. Use a distinct group identifier for each independent consumer chain. Consumers within the same chain can use the same group identifier.
configuration contains REST Services Manager processing settings:
- max-retries specifies the maximum number of retry attempts for a failed event before the consumer routes it to the next processing stage.
- retry-delay-interval-ms specifies the interval, in milliseconds, between retry attempts.
- record-fetch-timeout-ms specifies the maximum time, in milliseconds, that the consumer waits for records during a fetch operation.
- brm-connection-retry-interval-ms specifies the interval, in milliseconds, between attempts to reconnect to BRM services.
- strict-ordering controls whether the consumer preserves processing order for events with the same message key. Set this property to true to enable strict ordering.
- buffer-strategy specifies the buffering strategy for strict ordering. Set this property to in-memory or kafka when strict-ordering is true.
topic-event-config contains topic names, thread counts, supported event types, and downstream consumer definitions:
- source-topic specifies the Kafka topic from which the consumer reads events.
- sink-topic specifies the Kafka topic to which the consumer routes failed events for further processing, such as retry or dead-letter handling.
- error-topic specifies the optional Kafka topic to which REST Services Manager publishes structured error details for failed events. Configure this property for each consumer that needs error reporting, including downstream consumers. If you omit this property or leave it blank, REST Services Manager does not publish error details to an error topic for that consumer.
- key-state-topic specifies the Kafka topic that tracks message-key state when strict-ordering is true and buffer-strategy is kafka. This combination requires a key-state topic. A downstream consumer can inherit the topic from its parent.
- consumer-thread-count specifies the number of threads that retrieve records from the source topic.
- worker-thread-count specifies the number of threads that process events.
- events lists the event types that the consumer processes.
- downstream-consumers defines subsequent processing stages, such as retry handling. Each downstream consumer defines its connection profile, consumer properties, processing settings, and topic configuration. Downstream consumers inherit retry settings from their parent when they omit those settings. They also use their parent’s strict-ordering and buffer-strategy settings.

In this example, the downstream consumer overrides max-retries and inherits retry-delay-interval-ms from its parent. It also uses its parent’s strict-ordering and buffering settings and inherits the parent’s key-state topic.

Use the exact property names record-fetch-timeout-ms and brm-connection-retry-interval-ms in every consumer configuration, including downstream consumers.

Database Consumers

Configure a database consumer to retrieve events from a database queue. Reference the database connection profile and specify the queue, authentication details, and wallet location.

The following example uses the cp2 database connection profile:

consumers:
  - connection-profile-id: "cp2"
    properties:
      username: "notification_user"
      password-key: "CP2_SCHEMA_WALLET_KEY"
      queue-name: "OPEN_API_QUEUE"
      oracle.net.wallet_location: "/home/db-wallet"
    wallet-location: "/home/db_wallet"
    configuration:
      worker-thread-count: 1

Replace the example user name, wallet entry name, queue name, and wallet path with the values for your deployment.

where:

connection-profile-id identifies the database connection profile that the consumer uses. In this example, cp2 references the database connection profile.
properties contains the database consumer’s authentication and queue settings:
- username specifies the user name for accessing the database queue.
- password-key specifies the wallet entry that contains the user’s password.
- queue-name specifies the database queue from which the consumer retrieves events.
- oracle.net.wallet_location specifies the absolute path to the directory containing the Oracle database wallet for the secure database connection. Replace /home/db-wallet with the wallet directory on the REST Services Manager host. Grant the operating-system user that runs REST Services Manager read access to the directory and its wallet files.
wallet-location specifies the path to the wallet containing the credentials for the database connection.
configuration contains the database consumer’s processing settings:
- worker-thread-count specifies the number of threads that process events.

Note:

When you configure oracle.net.wallet_location, the Oracle database wallet takes precedence over the SSL keystore and truststore settings. REST Services Manager ignores javax.net.ssl.keyStore, javax.net.ssl.trustStore, and their associated type and password properties for the database connection.

Setting Up Producers

Configure a producer in REST_home/scripts/application.yaml to publish supported TM Forum (TMF) event notifications to Kafka topics. Reference a Kafka connection profile and map each event type to one or more destination topics.

The following example uses the cp1 connection profile. Replace the topic names with the Kafka topics for your deployment.

producer:
    connection-profile-id: "cp1"
    properties:
    configuration:
      retry-delay-interval-ms: 1000
    event-topics-config:
      - event-name: "ProductCreateEvent"
        topic-names: [ "productCreateTopic", "productCreateTopic2" ]
      - event-name: "ProductDeleteEvent"
        topic-names: [ "ProductDeleteTopic" ]
      - event-name: "ProductAttributeValueChangeEvent"
        topic-names: [ "productAttributeValueTopic" ]
      - event-name: "ProductStateChangeEvent"
        topic-names: [ "productStateChangeTopic" ]
      - event-name: "PartyAccountCreateEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "PartyAccountAttributeValueChangeEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "PartyAccountStateChangeEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "PartyAccountDeleteEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "BillingAccountCreateEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "BillingAccountAttributeValueChangeEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "BillingAccountStateChangeEvent"
        topic-names: [ "partyAccountNotificationTopic" ]
      - event-name: "BillingAccountDeleteEvent"
        topic-names: [ "partyAccountNotificationTopic" ]

where:

connection-profile-id identifies the Kafka connection profile that the producer uses.
properties contains Kafka producer settings, such as acks, retries, and batch.size. Settings in this section override matching properties in the referenced connection profile.
configuration contains REST Services Manager processing settings:
- retry-delay-interval-ms specifies the interval, in milliseconds, between retry attempts. In this example, 1000 sets a one-second interval.
event-topics-config is a list that maps each event name to one or more Kafka topics to which the event will be published.
- event-name specifies the supported event type to publish.
- topic-names lists the destination Kafka topics for that event type. Specify one or more topic names. REST Services Manager publishes the event to each topic in the list.

After you save your changes, restart REST Services Manager to load the updated configuration.

Completing Post-Installation Tasks

After deployment, validate the service using logs and functional checks. Customize event handling with mapper overrides if required and follow the correct procedure for restarting the REST Services Manager Notification Service after any configuration change.

To validate deployment and check logs:

Inspect the log directory for startup messages.
Confirm the service connects to Kafka brokers and joins the expected consumer group(s).
Verify correct topic subscriptions and successful offset commits.

To customize using customMapperDirectory:

To override default event mappers, place custom mapping files in the customMapperDirectory defined in application.yaml. See "Configuring and Adding Custom Mapper Files" for more information.
Restart the REST Services Manager Notification Service after adding or modifying custom mapper files to apply changes.

To restart REST Services Manager:

After any configuration or credential change, restart the REST Services Manager Notification Service to load the updated settings and wallet entries.
Use the supplied service management commands or scripts for safe restart procedures. Stop the BRM REST Services Manager by running the REST_home/scripts/stop-brm-rsm.sh script. Start the BRM REST Services Manager by running the REST_home/scripts/start-brm-rsm.sh script.

Performing Verification and Sanity Checks

Conduct a series of checks to ensure all topics, partitions, security settings, and service connections are correct. This section includes procedures for performing functional connectivity testing and verifying end-to-end message flow.

Perform checks to validate the REST Services Manager Notification Service deployment:

Confirm all topics, partitions, and ACLs are present in Kafka.
Ensure consumers join the correct consumer group and receive partition assignments.
Check that the service successfully establishes SSL or SASL connections to brokers.
Run test messages through the pipeline to validate end-to-end message flow.
Use built-in scripts to verify wallet entry references and keystore integrity.

Security Best Practices for REST Services Manager Notification Service

Adhere to recommended security practices for storage and handling of credentials. This section summarizes wallet usage, credential rotation, file permissions, and compliance alignment.

To maintain a secure deployment:

Store all credentials, passphrases, and secrets in the Oracle wallet. Never use plain text or version control for secret values.
Limit file permissions on wallet and keystore files to only necessary service accounts.
Rotate credentials and certificates periodically, updating the wallet, and restart services after changes.
Do not disable SSL endpoint identification unless explicitly required and with a formal risk assessment.
Ensure your deployment always aligns with Oracle security and compliance policies.

Troubleshooting SSL Connection Errors

BRM REST Services Manager can use SSL connections for invoking OAuth Token Introspection Endpoint and Oracle Unified Directory REST APIs. Table 11-8 describes the possible SSL connection errors and solutions.

Table 11-8 SSL Connection Errors and Solutions

SSL Connection Errors	Solutions
javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching hostname found	Ensure that the Common Name (CN) in the SSL certificate is the fully qualified domain name of the server where endpoints are hosted.
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target	Ensure that the SSL certificate of the endpoint is imported into the Java KeyStore.