Integrating with Your BRM Cloud Native Deployment

16 Integrating with Your BRM Cloud Native Deployment

Learn how to integrate the Oracle Communications Billing and Revenue Management (BRM) cloud native deployment with external systems, such as Oracle Analytics Publisher.

Topics in this document:

Integrating with Thick Clients

You can integrate BRM cloud native with thick clients, such as Customer Center and Pricing Center. To do so:

Set these entries in the override-values.yaml file for oc-cn-helm-chart:
- ocbrm.cm.serviceFqdn: Set this to the CM's TLS certificate Subject Alternative Name, such as dns:node1.brm.com.
- ocbrm.isSSLEnabled: Set this to 1.
Copy the client wallet from the CM service to your thick client's wallet on Windows.

Note:

All thick clients installed in standard mode (that is, in non-WebStart mode) can be integrated with the BRM cloud native deployment. This is not relevant for self-care applications.
Run the helm upgrade command to update the BRM Helm release:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace
```
where:
- BrmReleaseName is the release name for oc-cn-helm-chart and is used to track this installation instance.
- OverrideValuesFile is the file name and path to your override-values.yaml file.
- BrmNameSpace is the namespace in which to create BRM Kubernetes objects for the BRM Helm chart.

Using a Custom TLS Certificate

You can secure connections between your BRM cloud native deployment and external service providers, such as payment processors and tax calculators, by using Secure Sockets Layer (SSL) certificates. By default, the BRM cloud native deployment uses the TLS certificate provided with the BRM cloud native deployment package.

You can configure the BRM cloud native deployment to use your custom TLS certificate instead. You might do this, for example, to allow client applications outside of the cloud environment to access the BRM cloud native Connection Manager (CM). In this case, the CM is exposed as a Kubernetes NodePort service.

To use a custom TLS certificate, do this:

When you generate your custom TLS certificate, ensure that its Subject Alternative Name (SAN) includes these:
```
dns:cm
dns:HostName
```
where HostName is the host name used to connect to the CM from outside the Kubernetes cluster.

For example, if your CM is running on the ocbrm.example.com server and you use the Java keytool utility to generate the custom SAN certificate, you'd enter this command:
```
keytool -genkey -keyalg RSA -alias brm -keystore brm_custom.jks -validity 365 -keysize 2048 -ext san=dns:cm,dns:ocbrm.example.com
```
Create an Oracle wallet named brm_custom_wallet in the staging area and then copy it to the top level of oc-cn-helm-chart:
```
mkdir brm_custom_wallet
orapki -nologo wallet create -wallet brm_custom_wallet -auto_login -pwd Password
```

Convert the Java KeyStore to the Oracle wallet:

orapki wallet jks_to_pkcs12 -wallet brm_custom_wallet -pwd Password -keystore brm_custom.jks -jkspwd Password

Verify the contents of the wallet:

orapki wallet display -wallet brm_custom_wallet

Move your custom TLS certificate to oc-cn-helm-chart/brm_custom_wallet.

The wallet containing the custom certificate will be mounted at /oms/wallet/custom.
Update these keys in your override-values.yaml file for oc-cn-helm-chart and oc-cn-op-job-helm-chart:
- ocbrm.isSSLEnabled: Set this to 1.
- ocbrm.cmSSLTermination: Set this to true.
- ocbrm.isSSLEnabled: Set this to true.
- ocbrm.customSSLWallet: Set this to true.
- ocbrm.wallet.client_location: Set this to /oms/wallet/custom.
- ocbrm.wallet.server_location: Set this to /oms/wallet/custom.
Install BRM cloud native services by entering this command from the helmcharts directory.
```
helm install BrmReleaseName oc-cn-helm-chart --namespace BrmNameSpace --values OverrideValuesFile
```
where:
- BrmReleaseName is the release name for oc-cn-helm-chart and is used to track this installation instance.
- OverrideValuesFile is the path to a YAML file that overrides the default configurations in the chart's values.yaml file.
- BrmNameSpace is the namespace in which to create BRM Kubernetes objects for the BRM Helm chart.

Integrating with JCA Resource Adapter

You can deploy the BRM JCA Resource Adapter in WebLogic Server and use it to run opcodes in the BRM cloud native deployment. For more information about JCA Resource Adapter, see BRM JCA Resource Adapter.

Note:

To allow the JCA Resource Adapter to communicate with the BRM cloud native deployment, expose the CM service as NodePort. For information, see "Integrating with Thick Clients".

To deploy JCA Resource Adapter in your BRM cloud native deployment:

Enable the brm-sdk pod by setting these keys in your override-values.yaml file for oc-cn-helm-chart:

brm_sdk:
   isEnabled: true
   deployment:  
      imageName: brm_sdk
      imageTag: 15.0.x.0.0
   pvc:             
      storage: 50Mi

Run the helm upgrade command for oc-cn-helm-chart:

helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace

Find the name of the brm-sdk pod:

kubectl get pods -n BrmNameSpace | grep brm-sdk

You should see something similar to this:

NAME                       READY    STATUS     RESTARTS    AGE
brm-sdk-f67b95777-bf8j5    1/1      Running    0           18m

Enter the brm-sdk pod:

kubectl exec -n BrmNameSpace -it BrmSdkPodName bash

where BrmSdkPodName is the name of the pod from step 3.

For example:

kubectl exec -n MyNameSpace -it brm-sdk-f67b95777-bf8j5 bash

Go to the apps/brm_integrations/jca_adapter/ directory and copy the OracleBRMJCA15Adapter.rar file to a new staging directory:
```
cd apps/brm_integrations/jca_adapter/
mkdir staging
cp OracleBRMJCA15Adapter.rar staging/
```
Go to your staging directory and extract the files from the OracleBRMJCA15Adapter.rar archive file:
```
cd staging
jar xvf OracleBRMJCA15Adapter.rar
```
Update the following parameters in your META-INF/weblogic-ra.xml file:
- ConnectionString: Set this to the string for connecting to the BRM service in the format:
```
protocol host port
```
  For example: ip cm 11960.
- Password: Set this to the password for the BRM root user.
- JavaPcmSSL: Set this to true if SSL is enabled for BRM.
- SslWalletLocation: Set this to the location of the Oracle wallet that contains the BRM client TLS certificate. This can be copied from the BRM installation.
From your staging directory, delete the OracleBRMJCA15Adapter.rar file and then build a new archive file using the updated META-INF/weblogic-ra.xml file:
```
rm OracleBRMJCA15Adapter.rar
jar cvf OracleBRMJCA15Adapter.rar  .
```
Copy the new OracleBRMJCA15Adapter.rar into the brm-sdk PVC storage class:
```
cp OracleBRMJCA15Adapter.rar /oms/ext/
```
Copy the client wallet to the brm-sdk PVC storage class:
```
cp -r /oms/wallet/client/ /oms/ext/wallet/
```
Exit the brm-sdk pod.

Retrieve the name of the PVC volume for the brm-sdk pod:

kubectl get pvc -n BrmNameSpace | grep brm-sdk

You should see something similar to this:

NAME      STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGE CLASS  AGE
brm-sdk   Bound    pvc-094feae0-4d11-4887-83a0-b47a0fc6a3f4   50Mi       RWX            myclass        24h

Copy the OracleBRMJCA15Adapter.rar archive file from the PVC to the working directory
```
cp NfsMountPath/BrmNameSpace/BrmSdkPvc/OracleBRMJCA15Adapter.rar  .
```
where BrmSdkPvc is the name of the PVC volume from step 12.

For example:
```
cp -r /mnt/oke_test/MyNameSpace/pvc-094feae0-4d11-4887-83a0-b47a0fc6a3f4/OracleBRMJCA15Adapter.rar .
```

Copy the client wallet from the PVC to the working directory:

cp -r NfsMountPath/BrmNameSpace/BrmSdkPvc/WalletFolder .

For example:

cp -r /mnt/oke_test/MyNameSpace/pvc-094feae0-4d11-4887-83a0-b47a0fc6a3f4/wallet .

Copy the client wallet to the appropriate path and deploy OracleBRMJCA15Adapter.rar on AIA.

Integrating with Kafka Servers

You can integrate your BRM cloud native system with a Kafka server to keep data synchronized between BRM cloud native and your external applications that are connected to the Kafka server. To synchronize account, pricing, and other data, BRM cloud native takes data from internal notification events and constructs a business event that is published to a topic in your Kafka server. Your external applications can then retrieve and process the data from the Kafka topic. For more information, see "About Integrating BRM with an Apache Kafka Server" in BRM Developer's Guide.

You integrate BRM cloud native with a Kafka server and configure it to publish data to a Kafka server using the CM, Kafka DM, and Enterprise Application Integration (EAI) framework.

To integrate BRM cloud native with a Kafka Server:

(Optional) Configure the KeyStores required for secure communication between the Kafka DM and Kafka Server.
1. Create the client certificate, client KeyStore, and client TrustStore. See "Security" in the Apache Kafka documentation.
2. Verify that the server KeyStore and TrustStore are set up properly by running the following command:
```
openssl s_client -debug -connect DomainName:PortNumber -tls1_2
```
  If successful, the certificate is displayed. If the certificate isn't displayed or if there are any other error messages, the KeyStore isn't set up properly.
3. Move the client's KeyStore files, such as identity.p12 and trust.p12, under the oc-cn-helm-chart/keystores directory.
Open your override-values.yaml file for oc-cn-helm-chart.
Enable and configure the Kafka DM by editing the following keys:
- ocbrm.dm_kafka.is_enabled: Set this to true.
- ocbrm.dm_kafka.kafkaAsyncMode: Specify whether to use asynchronous mode (true), in which the Kafka DM records all business events that fail to publish to a log file. In synchronous mode (false), the Kafka DM returns errors to BRM when a business event fails to publish to the Kafka server.
- ocbrm.dm_kafka.deployment.kafka_bootstrap_server_list: Set this to a comma-separated list of addresses for the Kafka brokers in this format: hostname1:port1, hostname2:port2. The default is ece-kafka:9093.
- ocbrm.dm_kafka.deployment.poolSize: Set this to the number of threads that can run in the JS server to accept requests from the CM. Enter a number from 1 through 2000. The default is 64.
- ocbrm.dm_kafka.deployment.topicName: Set this to the name of the default Kafka topic. The default name is BRM.
- ocbrm.dm_kafka.deployment.topicFormat: Set this to the format of the payload that is published to the default Kafka topic: XML or JSON.
- ocbrm.dm_kafka.deployment.topicStyle: Set this to the style of all field names in XML payloads:
  - ShortName: The XML field names are in all capitals, such as <POID>, <ACCOUNT_OBJ>, and <SUBSCRIBER_PREFERENCES_INFO>. This is the default.
  - CamelCase: The XML field names are in CamelCase, such as <Poid>, <AccountObj>, and <SubscriberPreferencesInfo>.
  - NewShortName: The XML field names are in CamelCase and are prefixed with fld, such as <fldPoid>, <fldAccountObj>, and <fldString>.
  - OC3CNotification: The input is transformed to match the field and formatting requirements of Oracle Communications Convergent Charging Controller. Use this style if Convergent Charging Controller is your external notification application.
- ocbrm.dm_kafka.deployment.isSecurityEnabled: Specifies whether SSL is enabled between the Kafka DM and Kafka Server.
- ocbrm.dm_kafka.deployment.trustStorePassword: Specifies the TrustStore password in Base64 format.
- ocbrm.dm_kafka.deployment.keyStorePassword: Specifies the KeyStore password in Base64 format.
- ocbrm.dm_kafka.deployment.keyPassword: Specifies the key password in Base64 format.
- ocbrm.dm_kafka.deployment.password: Specifies the password in Base64 format.
Configure the EAI Java Server (JS) to use the Kafka DM event notification file by setting the ocbrm.eai_js.deployment.eaiConfigFile key to payloadconfig_ifw_kafka_sync_merged.xml.
Save and close the file.
To create additional Kafka topics or configure the Kafka DM to publish different business events to a Kafka topic, edit the dm-kafka-config ConfigMap.

For more information about editing this ConfigMap, see "Mapping Business Events to Kafka Topics" in BRM Developer's Guide.
Run the helm upgrade command to update your BRM Helm release:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace
```
where:
- BrmReleaseName is the release name for oc-cn-helm-chart and is used to track this installation instance.
- OverrideValuesFile is the file name and path to your override-values.yaml file.
- BrmNameSpace is the namespace in which to create BRM Kubernetes objects for the BRM Helm chart.

Example: Integrating BRM Cloud Native with a Kafka Server

The following shows sample override-values.yaml entries for integrating a BRM cloud native system with a Kafka Server:

ocbrm:
    dm_kafka:
        isEnabled: true
        kafkaAsyncMode: true
        deployment:
            imageName: dm_kafka
            imageTag: $BRM_VERSION
            replicaCount: 1
            kafka_bootstrap_server_list: ece-kafka:9093
            poolSize: 64
            topicName: BRMTopic
            topicFormat: XML
            topicStyle: CamelCase
            isSecurityEnabled: true
            trustStorePassword: TrustStorePassword
            keyStorePassword: KeyStorePassword
            keyPassword: KeyPassword
            password: Password
    eai_js:
        deployment:
            imageName: eai_js
            imageTag: $BRM_VERSION
            eaiConfigFile: payloadconfig_ifw_sync.xml

Integrating with Oracle Analytics Publisher

You can optionally integrate your BRM cloud native deployment with invoicing software such as Oracle Analytics Publisher. This integration enables you to generate more detailed and stylized customer invoices that can be viewed in your invoicing software or Billing Care.

To integrate your BRM cloud native deployment with Oracle Analytics Publisher:

If you have not already done so, install Oracle Analytics Publisher.

For a list of compatible software versions, see "BRM Software Compatibility" in BRM Compatibility Matrix.
Install the BRM-Oracle Analytics Publisher invoicing integration package using the OUI installer on your Oracle Analytics Publisher server. This copies invoice layout templates, such as for corporate invoices and consumer invoices, to the Oracle Analytics Publisher server.

The steps for installing the package on BRM cloud native are similar to those on BRM on-premises. For more information, see "Installing the BRM-Oracle Analytics Publisher Invoicing Integration Package" in BRM Designing and Generating Invoices.
Configure how to connect your Billing Care and Billing Care REST API cloud native services with Oracle Analytics Publisher.

In your override-values.yaml file for oc-cn-op-job-helm-chart, set these keys:
- ocbc.bc.configEnv.bipUrl: The URL for PublicReportService_v11 from your Oracle Analytics Publisher instance, which Billing Care uses to show invoices.
- ocbc.bc.configEnv.bipUserId: The name of the user with access to the Oracle Analytics Publisher instance for viewing invoices from Billing Care.
- ocbc.bc.secretVal.bipPassword: The Base64-encoded password for the Oracle Analytics Publisher user.
- ocbc.bcws.configEnv.bipUrl: The URL for PublicReportService_v11 from your Oracle Analytics Publisher instance, which is used by the Billing Care REST API when accessing PDF invoices.
- ocbc.bcws.configEnv.bipUserId: The name of the user with access to the Oracle Analytics Publisher instance for accessing invoices from the Billing Care REST API.
- ocbc.bcws.secretVal.bipPassword: The Base64-encoded password for the Oracle Analytics Publisher user.
Do one of the following:
- Deploy your Billing Care and Billing Care REST API cloud native services. See "Deploying BRM Cloud Native Services" in BRM Cloud Native Deployment Guide.
- Upgrade your Billing Care and Billing Care REST API cloud native services. See "Upgrading Your Billing Care and Billing Care REST API Cloud Native Services" in BRM Cloud Native Deployment Guide.
Configure how to connect BRM cloud native with Oracle Analytics Publisher.

In your override-values.yaml file for oc-cn-helm-chart, set these keys under ocbrm.brm_apps.deployment.pin_inv_doc_gen:
- bipServer: The name of the server on which Oracle Analytics Publisher is installed.
- bipPort: The port number for Oracle Analytics Publisher.
- bipUsername: The name of the user with access to the Oracle Analytics Publisher instance.
- bipPassword: The Base64-encoded password for the Oracle Analytics Publisher user.
- schedulerDBServer: The name of the server on which the Scheduler database is installed.
- schedulerDBPort: The port number for communicating with the Scheduler database.
- schedulerDBService: The service name for the Scheduler database.
- schedulerDBUsername: The user name for the Scheduler database.
- schedulerDBServiceCredentials: The security credentials for connecting to the Scheduler database.
- jdbcPoolSize: The initial number of connections maintained in the pool.
- jdbcPoolMaxSize: The maximum number of connections that can be created.
- securityCredentials: The password for the Oracle wallet.
In the BRM Helm chart's configmap_pin_conf_brm_apps_1.yaml file, set the following entries:
- pin_inv_export export_dir: Set this to ./invoice_dir.
- pin_inv_export invoice_fmt: Set this to text/xml.
For example:
```
- pin_inv_export  export_dir  ./invoice_dir
- pin_inv_export  invoice_fmt  text/xml
```
Run the helm upgrade command to update the Helm release:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace
```
where BrmReleaseName is the release name assigned to your existing oc-cn-helm-chart installation.
In your bus_params_Invoicing.xml file, set the following entries:
- xsi:schemaLocation: Set this to http://www.portal.com/schemas/BusinessConfig/oms/xsd/business_configuration.xsd.
- EnableInvoicingIntegration: Set this to enabled to integrate BRM with your invoicing software.
- InvoiceStorageType: Set this to 1 to store invoices in XML format.
For example:
```
<BusinessConfiguration
    xmlns="http://www.portal.com/schemas/BusinessConfig"        
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"        
    xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig 
/oms/xsd/business_configuration.xsd">
...
<EnableInvoicingIntegration>enabled</EnableInvoicingIntegration>
<InvoiceStorageType>1</InvoiceStorageType>
```
In your bus_params_billing.xml file, set the following entries:
- RerateDuringBilling: Specify whether delayed events that arrive after the end of the accounting cycle but during the delayed billing period can borrow against the rollover of the current cycle (enabled) or not (disabled).
- EnableCorrectiveInvoices: Specify whether to enable corrective billing and corrective invoicing (enabled) or not (disabled).
- AllowCorrectivePaidBills: Specify whether to allow a corrective bill to be generated for a bill that has been fully or partially paid (enabled) or not (disabled).
- RejectPaymentsForPreviousBill: Specify whether to reject payments when the bill number associated with a payment does not match the last bill (enabled) or to accept them (disabled).
- CorrectiveBillThreshold: Specify the minimum bill amount that triggers a corrective bill.
- GenerateCorrectiveBillNo: Specify whether corrective invoices use corrective bill numbers (enabled) or the original bill numbers (disabled).
For example:
```
<RerateDuringBilling>enabled</RerateDuringBilling>
<EnableCorrectiveInvoices>enabled</EnableCorrectiveInvoices>
<AllowCorrectivePaidBills>enabled</AllowCorrectivePaidBills>
<RejectPaymentsForPreviousBill>enabled</RejectPaymentsForPreviousBill>
<CorrectiveBillThreshold>0</CorrectiveBillThreshold>
<GenerateCorrectiveBillNo>enabled</GenerateCorrectiveBillNo>
```
In your events.file file, specify which events to include in your invoices.

For more information, see "Including Payment, A/R, and Tax Details in Invoices" in BRM Designing and Generating Invoices.
In your pin_business_profile.xml file, configure your business profiles and validation templates.

For more information, see "Setting Up Business Profiles and Validation Templates" in BRM Managing Customers.
In your pin_invoice_data_map file, create or modify the data invoice templates.

For more information, see "Using Data Map Templates" in BRM Designing and Generating Invoices.

Add the following lines to the oc-cn-helm-chart/config_scripts/loadme.sh script:

#!/bin/sh 

cd /oms/sys/data/config; pin_bus_params -v /oms/load/bus_params_Invoicing.xml
cd /oms/sys/data/config; pin_bus_params -v /oms/load/bus_params_billing.xml 
cd /oms/sys/data/config; pin_load_invoice_events -reload -brand "0.0.0.1/account 1 0" -eventfile /oms/load/events.file
cd /oms/sys/data/config; load_pin_business_profile /oms/load/pin_business_profile.xml
cd /oms/sys/data/config; load_pin_invoice_data_map -dv /oms/load/pin_invoice_data_map
exit 0;

Move the following input files to the oc-cn-helm-chart/config_scripts directory:
- bus_params_invoicing.xml
- bus_params_billing.xml
- events.file
- pin_business_profile.xml
- pin_invoice_data_map
Enable the configurator job.

In your override-values.yaml file for oc-cn-helm-chart, set ocbrm.config_jobs.run_apps to true.
Run the helm upgrade command to update the Helm release:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace
```
The configurator job runs the utilities specified in the loadme.sh script.
Restart the CM because it is required by pin_bus_params.
1. Set these keys in the override-values.yaml file:
  - ocbrm.config_jobs.restart_count: Increment the existing value by 1
  - ocbrm.config_jobs.run_apps: Set this to false
2. Update the Helm release again:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile -n BrmNameSpace
```

When configuring Oracle Analytics Publisher, ensure that the Create_Xmlp_Invoice_Job.sql script is run in the schema in which the scheduler database is installed. This script creates the XMLP_INVOICE_JOB table, which should be present in the scheduler database.

Generating Invoices in Oracle Analytics Publisher

After integration is complete, you can generate your customers' invoices in Oracle Analytics Publisher by doing the following:

Creating /invoice objects for your customers by doing one of the following:
- Running an invoicing job in Business Operations Center. See "Generating Invoices" in Business Operations Center Help for more information.
- Running the pin_inv_accts utility through a brm-apps job. See "Running Applications and Utilities through brm-apps Jobs".
Generating your customer invoice documents using Oracle Analytics Publisher templates by running the pin_inv_doc_gen utility through a brm-apps job. See "Running Applications and Utilities through brm-apps Jobs".