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

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

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

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

5. 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 15.1.0.0.0 contains incompatible features with the following:
   Billing Revenue Management 15.1.1.0.0 [CORE 15.1.0.0.0->CORE 15.1.1.0.0 (CORE 15.1.0.0.0->[CORE 15.1.1.0.0])]

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

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

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

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

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

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

11. In the Installation Summary window, review the selections you made in the preceding windows and then click Install.

12. The Installation Progress window appears. When the installation completes, click Next.

    Note:

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

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

14. Click Finish to complete the installation.

    The BRM REST Services Manager installer exits.

15. (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.

16. (For Security Enabled with Oracle Access Management Only) If you have not yet migrated to the latest versions of Oracle Access Management, where roles and groups are included in the JSON Web Tokens (JWTs) token, do the following:

    Note:

    This step is necessary when your JWTs do not adhere to the MicroProfile JWT RBAC v2.1 specification and lack a "groups" claim because it enables fetching user or client groups and roles. If your JWTs conform to the JWT RBAC v2.1 specification, skip this step.

    1. In your application.yaml file, uncomment the following oam-role-mapper entries.

       - oam-role-mapper:
            oud:
                 host-name:
                 admin-user-name:                   
                 http-port:    
                 https-port:               
                 users-base-dn:          
                 groups-base-dn:                 
                 msgType: urn:ietf:params:rest:schemas:oracle:oud:1.0:SearchRequest          
                 filter: (&(objectclass=*)(uniqueMember=cn=__USER_NAME__,__USER_BASE_DN__))

    2. Update the entries for your environment:

       • host-name: The Oracle Unified Directory host name.

       • admin-user-name: The administration user name for the Oracle Unified Directory.

       • http-port: The Oracle Unified Directory HTTP port.

       • https-port: The Oracle Unified Directory HTTPS port.

       • users-base-dn: The Oracle Unified Directory user domain name.

       • groups-base-dn: The Oracle Unified Directory group domain name.

       • msgType: The message type based on the schema used to search roles in the Oracle Unified Directory.

       • filter: The filter based on the user attribute.

       Note:

       The admin-password key is the administration password for the Oracle Unified Directory. Do not set this entry directly. Instead, write the password to the wallet as OAM_OUD_ROOTUSERPASS. To store the client secret password in the wallet, enter the following command:

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

17. (For Security Enabled with Oracle Identity Cloud Service Only) If IDCS is not configured to include groups or roles in JSON Web Tokens (JWTs), do the following:

    Note:

    This step is necessary when your JWTs do not adhere to the MicroProfile JWT RBAC v2.1 specification and lack a "groups" claim because it enables fetching user or client groups and roles. If your JWTs conform to the JWT RBAC v2.1 specification, skip this step.

    1. In your application.yaml file, uncomment the following idcs-role-mapper entries:

       - idcs-role-mapper:
            multitenant: false 
            oidc-config:
               client-id:  
            identity-uri:
               cache-config:
               cache-timeout-millis: 10000 

    2. Update the entries for your environment:

       • client-id: The client ID generated by the Identity Server, used to validate the token.

       • identity-uri: The URI of the Identity Server, used as the base URL to retrieve metadata from the Identity Server.

       Note:

       The client-secret key is for the client secret generated by the Identity Server, used to authenticate the application when requesting a JWT based on a code. Do not set this entry directly. Instead, write the client secret password to the wallet as CLIENT_SECRET. To store the client secret password in the wallet, enter the following command:

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

18. After installation completes, run the REST_home/scripts/start-brm-rsm.sh script to bring up BRM REST Services Manager.

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.

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

1. Stop BRM REST Services Manager by running the REST_home/scripts/stop-brm-rsm.sh script.

2. In the REST_home/scripts/brm_rsm.properties file, configure the path to the TrustStore file in the TRUST_STORE_FILE_PATH key.

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

   • clientWalletLocation is the full path to the client wallet.

   • value is the TrustStore passphrase in Base64-encoded format.

4. Start BRM REST Services Manager by running the REST_home/scripts/start-brm-rsm.sh script.

To configure the policies for API authorization:

1. Stop BRM REST Services Manager by running the REST_home/scripts/stop-brm-rsm.sh script.

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

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

4. Start BRM REST Services Manager by running the REST_home/scripts/start-brm-rsm.sh script.

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.

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. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

2. Navigate to the REST_home/wallet directory, where REST_home is the BRM REST Services Manager installation directory.

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

4. Start BRM REST Services Manager using this command:

   REST_home/scripts/start_brm_rsm.sh

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.

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

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. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

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

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

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

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

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

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:

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.

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:

1. Stop BRM REST Services Manager using this command:

   REST_home/scripts/stop_brm_rsm.sh

2. Back up the REST_home/scripts/security.properties file.

3. Open the REST_home/scripts/security.properties file in a text editor.

4. Remove the names of any cyphers you would like to allow.

5. Save the security.properties file.

6. Start BRM REST Services Manager using this command:

   REST_home/scripts/start_brm_rsm.sh

To remove all cypher restrictions:

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. Set the value of the OVERRIDE_SECURITY_PROPERTIES property to false.

4. Save the brm_rsm.properties file.

5. Start BRM REST Services Manager using this command:

   REST_home/scripts/start_brm_rsm.sh