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

• Downloading the BRM REST Services Manager Package

• Generating the SSL Certificate for BRM REST Services Manager

• Installing BRM REST Services Manager

• BRM REST Services Manager Post-Installation Tasks

• Troubleshooting SSL Connection Errors

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

Downloading the BRM REST Services Manager Package

To download the BRM REST Services Manager package, go to the Oracle support website (https://support.oracle.com). Search for and download the Oracle Communications Billing and Revenue Management 12.0.0.x.0 software, where x is 1 for Patch Set 1, 2 for Patch Set 2, and so on.

Unzip the pPatchNumber_12.0.0.x.0_Generic.zip file. The Zip file includes the BRM_REST_Services_Manager-12.0.0.x.0.jar file for installing BRM REST Services Manager.

Generating the SSL Certificate for BRM REST Services Manager

You must generate an SSL certificate before you install BRM REST Services Manager.

The following shows the steps for generating a sample SSL certificate:

1. Create a directory for storing your SSL certificate, such as rsm_keystore.

2. Generate an SSL certificate. For example:

   openssl req -x509 -newkey rsa:4096 -keyout openSSLKey.pem -out cert.pem -days 365 -nodes

3. Generate a PKCS12 KeyStore file. For example, this creates a KeyStore file named keystore.p12:

   openssl pkcs12 -export -out keyStore.p12 -inkey openSSLKey.pem -in cert.pem

4. Copy your SSL certificate file to the directory you created it step 1.

Installing BRM REST Services Manager

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

You can install BRM REST Services Manager in the following modes:

• GUI mode: Use GUI mode when you want to interact with the BRM REST Services Manager installer GUI during installation. See "Installing BRM REST Services Manager in GUI Mode".

• Silent mode: Use silent mode when you install BRM REST Services Manager using the same configuration repeatedly. Silent install mode does not use the GUI, and it runs in the background. See "Installing BRM REST Services Manager in Silent Mode" .

Installing BRM REST Services Manager in GUI Mode

To install BRM REST Services Manager in GUI mode:

1. Go to the temp_dir directory and run one of these commands:

   • To start the GUI installer:

     Java_home/bin/java -jar BRM_REST_Services_Manager-12.0.0.x.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 BRM_REST_Services_Manager-12.0.0.x.0.jar -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 BRM_REST_Services_Manager-12.0.0.x.0.jar -record -destinationFile path

     where path is the absolute path to the response file.

   Tip:

   You can run BRM_REST_Services_Manager-12.0.0.x.0.jar with the -Help option to get more details about the commands.

2. In the Welcome screen, click Next.

   Note:

   If the oraInst.loc file is corrupt or not present, the Specify Inventory Directory and Credentials screen appears next. Otherwise, the Installation Location screen appears.

3. (Optional) In the Specify Inventory Directory and Credentials screen, enter the details listed in Table 10-1 and then click Next.

   Table 10-1 Specify Inventory Directory and Credentials

   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 Name	The name of the operating system group that has write permission to the inventory directory.

4. In the Installation Location screen, enter the full path or browse to the directory in which you want to install BRM REST Services Manager and then click Next.

5. In the Feature Sets Selection screen, select the feature set options that you want to install and then click Next.

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

   Table 10-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 in "Generating the SSL Certificate for BRM REST Services Manager".
   KeyStore Password	The password used for accessing the KeyStore file.

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

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

   Table 10-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.
   Use SSL?	Do one of the following: If you have not enabled SSL for BRM, deselect this checkbox. If you have enabled SSL for BRM, select this checkbox.
   Wallet Password	The password for the BRM wallet.
   Confirm Wallet Password	Enter the password for the BRM wallet again.

9. In the Security Details screen, do one of the following for the Configure Security option and then click Next.

   • If you want to configure BRM REST Services Manager securely, select Yes, select the IDCS or OAM option based on your security requirements, and then click Next.

     If you select IDCS, the IDCS Details screen appears. Enter the following details for authorizing with Oracle Identity Cloud Service (IDCS):

     • Client ID: The client ID of the application.

     • Client Secret: The client secret of the application.

     • Identity URL: The base URL of the IDCS server. For example, https://tenant-base-url.

     • Scope Audience: The primary audience registered for the application which is appended for scopes.

     • Audience: The primary audience registered for the application.

     If you select OAM, the OAM Details screen appears. Enter the following details for authorizing with Oracle Access Management:

     • OAuth Identity Domain Name: The OAuth identity domain name hosting artifacts such as the resource server and client.

     • OAuth Resource Server Name: The OAuth server name hosting protected resources.

     • OAuth Token Introspection Endpoint: The OAuth REST endpoint that validates the access token.

     • OUD Host Name: The host name where the Oracle Unified Directory server is installed.

     • OUD Root User DN: The root user assigned with read and write access to all data in the server. For example: cn=Directory Manager.

     • OUD Root user password: The password for the root user.

     • OUD HTTP Port: The HTTP port where Oracle Unified Directory is configured to listen. This port hosts the Oracle Unified Directory REST endpoints.

     • OUD HTTPS Port: The HTTPS port where Oracle Unified Directory is configured to listen. This port hosts the Oracle Unified Directory REST endpoints with HTTPS protocol.

     • OUD users directory base DN: The base directory name where users are created in Oracle Unified Directory. Example: ou=people,dc=tmf,dc=com.

     • OUD groups directory base DN: The base directory name where roles or groups are created in Oracle Unified Directory. For example: ou=Groups,dc=tmf,dc=com.

   • If you want to configure BRM REST Services Manager in a test installation mode, select No.

10. In the Installation Summary screen, review the selections you made in the preceding screens and then click Install.

11. The Installation Progress screen appears. When the installation completes, click Next.

    Note:

    After the installation begins, you cannot stop or cancel the installation.

12. The Installation Complete screen 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.

13. Click Finish to complete the installation.

    The BRM REST Services Manager installer exits.

Installing BRM REST Services Manager in Silent Mode

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:

1. 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 BRM_REST_Services_Manager-12.0.0.x.0.jar -record -destinationFile path

2. Open the response file in a text editor.

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

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

5. Save and close the response file.

Installing BRM REST Services Manager in Silent Mode

Tip:

You can run BRM_REST_Services_Manager-12.0.0.x.0.jar with the -Help option to get more details about the commands.

To install BRM REST Services Manager in silent mode:

1. Create a response file. See "Creating a Response File".

2. Copy the response file you created to the machine on which you run the silent installation.

3. 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 BRM_REST_Services_Manager-12.0.0.x.0.jar -debug -invPtrLoc Inventory_home/oraInventory/oraInst.loc [parameter=value] -responseFile path -silent

   where:

   • Java_home is the directory in which you installed the latest supported Java version.

   • parameter refers to the installation parameters in the response file. You can override these parameters with any of the available parameters in the response file. For example, INSTALL_TYPE.

   • value is the value of the installation parameter. The value allows to override the response file entries at run time. For example, you can set INSTALL_TYPE=Custom. This value overrides the existing value in the response file for the same parameter.

   • path is the absolute path to the response file.

   For example:

   Java_home/bin/java -jar BRM_REST_Services_Manager-12.0.0.x.0.jar -debug -invPtrLoc Inventory_home/oraInventory/oraInst.loc INSTALL_TYPE=Complete -responseFile /tmp/BRM_REST_Services_Manager.rsp -silent

   The installation runs silently in the background.

4. Open the REST_home/install/readme.txt file, where REST_home is the directory in which you installed BRM REST Services Manager.

5. Copy the URL and paste it in your browser's address field.

   You can now access the BRM REST Services Manager.

BRM REST Services Manager Post-Installation Tasks

After you install BRM REST Services Manager, perform these post-installation tasks:

1. Excluding the BRM REST Services Manager SDK
2. Importing Java KeyStore Certificates
3. Updating BRM Connection Details
4. Updating the Base URL
5. Modifying BRM REST Services Manager Properties
6. Setting Up Zipkin Tracing in BRM REST Services Manager
7. Connecting BRM REST Services Manager to BI Publisher
8. Configuring BRM REST Services Manager for High Availability

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.

Importing Java KeyStore Certificates

When installing BRM REST Services Manager, if you select OUD HTTPS Port, you must import the Java KeyStore certificates in the Java KeyStore for a secure connection to Oracle Unified Directory.

To import the Java KeyStore certificates into the Java KeyStore:

1. Log on to the machine where you have installed BRM REST Services Manager.

2. Go to the Java_home/bin directory, where Java_home is the directory in which you installed the latest supported Java version.

3. Run the following command:

   keytool -import -alias AliasName -file CertificateFileLocation -keystore cacerts

   where:

   • AliasName is a unique name of an entity.

   • CertificateFileLocation is the path where you have stored the Oracle Unified Directory SSL Certificate.

   The keytool command prompts you for a Java KeyStore password. When prompted whether to trust the certificate, enter yes.

The Java KeyStore certificates are imported into the default Java KeyStore.

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:

1. Navigate to the REST_home/Wallet directory, where REST_home is the BRM REST Services Manager installation directory.

2. Run the following command to update the BRM connection details:

   java -cp ".;oraclepkijarLocation;osdtcertjarlocation;osdtcorejarLocation;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.

3. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

4. 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 BRM_home/scripts/app_external.properties file.

Note:

You don't need to restart the BRM REST Services Manager server after editing the app_external.properties file.

Modifying BRM REST Services Manager Properties

To modify the BRM REST Services Manager properties:

1. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

2. Open the REST_home/scripts/brm_rsm.properties file in a text editor.

3. Modify the properties based on your requirements. For example, changing the port number and log level.

4. Save the brm_rsm.properties file.

5. 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:

1. Install Zipkin. See the Zipkin Quickstart documentation: https://zipkin.io/pages/quickstart.html.

2. (Optional) To use secure SSL Zipkin, perform these steps:

   1. Generate a client SSL Certificate for connecting BRM REST Services Manager to Zipkin.

   2. Use the client SSL Certificate to create a PKCS12 TrustStore file.

   3. Go to the REST_home/Wallet directory, where REST_home is the BRM REST Services Manager installation directory.

   4. To use secure Zipkin, pass the TrustStore file you created with the TRUST_STORE_FILE_PATH key and set the password in your client wallet:

      java -cp '.:oraclepki.jar:osdt_cert.jar:osdt_core.jar:cet.jar' com.portal.cet.ConfigEditor -setconf -wallet clientWalletLocation/wallet -parameter TRUST_STORE_PASSPHRASE -value password

      where:

      • clientWalletLocation is the path to the client wallet.

      • password is the TrustStore password in Base64 format.

3. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

4. Open the REST_home/scripts/brm_rsm.properties file in a text editor.

5. Enable tracing in BRM REST Services Manager by setting the following parameter:

   TRACING_ENABLED=true

6. Set the following parameters to the host name and port number of the machine on which Zipkin tracing collector is installed:

   ZIPKIN_HOST_NAME=hostname
   ZIPKIN_PORT=portNumber

7. Set the following parameter to the protocol of the Zipkin tracing collector, which is either HTTP or HTTPS:

   ZIPKIN_PROTOCOL=HTTPS

8. Save the brm_rsm.properties file.

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

Connecting BRM REST Services Manager to BI Publisher

To enable BRM REST Services Manager to retrieve PDF invoices generated by BI Publisher, do one of the following:

• Create an Infranet.properties file in your user's home directory (User_home) and then add these parameters:

  • BIP_USERID: Set this to the BI Publisher user that has web access.

  • BIP_PASSWORD: Set this to the password for the BI Publisher user.

  • BIP_URL: Set this to the URL for accessing the BI Publisher instance. For example: http://hostname:port/xmlpserver/services/PublicReportService_v11.

• Update the BI Publisher connection details in the BRM REST Services Manager wallet. For more information, see the REST_home/Wallet/README file.

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 NGINX, 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:

1. 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.
2. 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.
3. 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. For example, a NGINX load balancer configuration might include the following:

   http {
   
   	upstream brmrsm{
   		server brm_rsm_host:9992;
   		server brm_rsm_host:9993;
   		server brm_rsm_host:9994;
   	}
   	server {
   		listen 3000;
   		server_name brm_rsm_host;
   
   		location / {
   			proxy_pass http://brmrsm/;
   		}
   
   		location /brm/customerBillManagement/v4/customerBill/ {
   			proxy_pass http://brmrsm/brm/customerBillManagement/v4/customerBill/;
   
   		}
   	}
   }

   where brm_rsm_host is the host server for BRM REST Services Manager instances.

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 10-4 describes the possible SSL connection errors and solutions.

Table 10-4 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. Note: You should not use the Oracle WebLogic Demo certificates as SSL certificates.
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. See "Importing Java KeyStore Certificates" for more information.