Using Business Operations Center

50 Using Business Operations Center

Learn how to set up, manage, and use Oracle Communications Billing and Revenue Management (BRM) Business Operations Center.

Topics in this document:

Before you read this document, you should be familiar with how BRM works. See "BRM System Architecture" in BRM Concepts.

About Using Business Operations Center

You use Business Operations Center to create, schedule, and view the results of the following operations:

Billing: Finds accounts that need to be billed; calculates the balance due for each bill unit in the accounts, including all usage and cycle fees; and creates a bill for the balance due.
Payment Collection: Collects the balance due for accounts that use the payment card (credit or debit card) and direct debit (cash) payment methods.
Invoicing: Generates invoices that list the events that were charged for, and the customer's total account balance.
Generating General Ledger Reports: Generates general ledger (G/L) reports to collect G/L data for G/L accounts.
Refunding payments: Finds accounts that have refund items, and makes online refund transactions.
Synchronizing product catalogs: Synchronizes the catalogs stored in the BRM server with updated values from customers.
Workflows: Runs a set of jobs in order, enabling an automated end-to-end billing process. You can choose to run two or more of these operations in order: billing, invoicing, payments, and refunds.
Your Custom Applications: Runs your custom applications and displays the results in the Business Operations screen. You must configure Business Operations Center to run your custom application. See "Defining a Custom Category" in Business Operations Center Online Help for more information.
Viewing Business Trends: Shows business trends based on data generated by the preceding operations.

If you have a multischema BRM system, you can specify whether to run a business operations job against the primary schema, a secondary schema, or all schemas. By default, jobs are run against all schemas.

For more information about running a job, see "Running Business Operations Jobs" in Business Operations Center Online Help.

Note:

Starting with BRM 12.0.0.3.0 with Interim Patch 31426340, Business Operations Center calls the PCM_OP_JOB_EXECUTE opcode to run the BRM utilities for these operations. For more information, see "How Business Operations Center Runs Jobs".
In BRM 12.0 Patch Set 3 and earlier releases, Business Operations Center calls the pin_job_executor utility to run the BRM utilities for these operations. For more information, see "pin_job_executor".

About Running Jobs in Business Operations Center

When running jobs in Business Operations Center, Oracle recommends the following:

Because the jobs that Business Operations Center can run often depend on other processes that Business Operations Center cannot run, determine whether you must supplement some of the jobs run in Business Operations Center by running additional processes elsewhere in BRM.

For example, to process off-cycle (daily, weekly, quarterly, and so on) charges, run the pin_cycle_fees utility as a custom job in Business Operations Center, from the BRM command line, as part of a daily cron job. Otherwise, a situation such as the following may occur:

Account A has a quarterly (three-month) billing cycle and receives 100 free minutes each month. The free minutes are granted by a monthly cycle forward fee, and they do not carry over to the following month. When Business Operations Center runs billing (pin_bill_accts), all pending cycle forward fees are applied. But for Account A, Business Operations Center will run billing only once every three months. At that time, three monthly cycle forward fees will be pending for Account A. Billing will apply them as follows:
- Two past monthly cycle forward fees will grant Account A a total of 200 expired free minutes.
- One current monthly cycle forward fee will grant Account A 100 free minutes that will be valid for one month.
Hence, if you do not process the monthly cycle forward fees that do not align with Account A's quarterly billing cycle, when Business Operations Center runs billing for the account once every three months and processes the two past-due monthly grants of free minutes at that time, those minutes will be unusable because they expire one month after coming due.
Do not run the BRM billing scripts (pin_bill_day, pin_bill_week, pin_bill_month) because they automatically run the same utilities (pin_bill_accts, pin_collect, pin_inv_accts, and so on) that Business Operations Center runs.

For more information about running jobs, see "Running Business Operations Jobs" in Business Operations Center Help.

How Business Operations Center Runs Jobs

Note:

Business Operations Center calls PCM_OP_JOB_EXECUTE for only BRM 12.0.0.3.0 Patch 31426340 or later releases. If you are using BRM 12.0 Patch Set 3 or an earlier release, Business Operations Center calls the pin_job_executor utility directly. See "pin_job_executor".

Business Operations Center runs jobs by doing the following:

Calling the PCM_OP_JOB_PROCESS_TEMPLATE opcode to create a /job_template object, which specifies the job details such as the type of business operations job to run and the database schema on which to run it. See "Managing Business Operations Job Templates" in BRM Opcode Guide.
Calling the PCM_OP_JOB_EXECUTE opcode to run applications in either a job context or a non-job context, depending on the PIN_FLD_FLAGS input flist setting:
- 1: Opens a job context and then internally runs a business operations utility against the target schema. This setting is used when running any business operations job. See "Running Business Operations Jobs" in BRM Opcode Guide for more information.
- 0: Runs applications in a non-job context. This setting is used when running pin_virtual_time or a custom application. See "Running BRM Applications" in BRM Opcode Guide for more information.

Setting Up Custom Clients to Run Business Operations and BRM Applications

Note:

Perform this step only if you are using BRM 12.0.0.3.0 with Interim Patch 31426340 or later releases.

You can set up a custom client application to run business operation jobs or other BRM applications. To do so, you must:

Configure PCM_OP_JOB_EXECUTE to run BRM applications. See "Configuring PCM_OP_JOB_EXECUTE to Run BRM Applications".
Configure the pin_job_executor process to listen for calls from PCM_OP_JOB_EXECUTE. See "Configuring pin_job_executor to Listen for Opcode Calls".
If you upgraded from a previous release, do this:
- Remove the PASSWORDLESS_SSH_USER property from the Domain_home/lib/bocws-config.properties file, where Domain_home is the WebLogic Server domain home directory in which Business Operations Center is deployed.
- Remove the passwordless SSH set up between BRM Server and Business Operations Center.
Customize your client application to call the PCM_OP_JOB_PROCESS_TEMPLATE opcode to create or modify a /job_template object, which specifies job details such as the type of business operations job to run and the schema on which to run it. See "Managing Business Operations Job Templates" in BRM Opcode Guide.
Customize your client application to call the PCM_OP_JOB_EXECUTE opcode to do the following:
- Run business operations jobs. See "Running Business Operations Jobs" in BRM Opcode Guide.
- Run any other BRM applications. See "Running BRM Applications" in BRM Opcode Guide.
Configure Business Operations Center to not render invoices in BI Publisher. See "Rendering Invoices in a Third-Party Invoice Application".

Configuring PCM_OP_JOB_EXECUTE to Run BRM Applications

The PCM_OP_JOB_EXECUTE opcode internally calls the pin_job_executor process, which in turn calls the BRM application that you want to run.

To configure the PCM_OP_JOB_EXECUTE opcode to run BRM applications:

Open the BRM_home/apps/pin_job_executor/Infranet.properties file in a text editor.
Set the following entry to match your environment:
```
infranet.server.portNr=Port
```
where Port is the port number on which pin_job_executor is listening for calls from the CM.
Change the value of the infranet.pcp.ssl.wallet.location entry from $PIN_HOME/wallet/client to $PIN_HOME/wallet/server:
```
infranet.pcp.ssl.wallet.location=$PIN_HOME/wallet/server
```

Add the following entry:

infranet.opcode.handler.JOB_EXECUTE=com.oracle.communications.brm.pje.JobOpcodeHandler

Add the following entry:
```
infranet.pje.executable.locations=bin,apps,subDirectory
```
where subDirectory is a directory under $PIN_HOME. The PCM_OP_JOB_EXECUTE opcode runs applications only if they reside in $PIN_HOME/bin, $PIN_HOME/apps, or a $PIN_HOME subdirectory that you specify.
Specify the number of threads that the opcode can spawn to run applications on multischema systems:
```
infranet.threadpool.size=ThreadNumber
```
where ThreadNumber is the number of threads that can be run. The default is 5, but you can increase it to improve performance.
Ensure that all applications that PCM_OP_JOB_EXECUTE will run, including any custom applications, are located in $PIN_HOME/bin, $PIN_HOME/apps, or $PIN_HOME/subDirectory.
Save and close the file.
Stop and restart the pin_job_executor utility by running the following commands from the BRM_home/bin directory:
```
.\stop_pje
.\start_pje
```

Configuring pin_job_executor to Listen for Opcode Calls

You must configure pin_job_executor to run as a background process, listening at a configured port for an opcode call from PCM_OP_JOB_EXECUTE. To do so:

Open the BRM_home/sys/cm/pin.conf file in a text editor.
Add the following entry:
```
- cm em_group pje PCM_OP_JOB_EXECUTE
```
Set the following entry to match your environment:
```
- cm em_pointer pje hostname port
```
where:
- hostname is the name or IP address of the server on which pin_job_executor is running.
- port is the port on which pin_job_executor is listening.
Save and close the file.
To log audit information about commands that are run in a non-job context, do this:
1. Open the BRM_home/sys/data/config/pin_notify file in a text editor.
2. Add the following entry:
```
179 0 /event/activity/job_request
```
3. Save and close the file.
4. Load the pin_notify file into the BRM database:
```
load_pin_notify -v pin_notify
```
  See "load_pin_notify" in BRM Managing Customers for more information.
5. Stop and restart the CM.
Stop and restart the pin_job_executor utility by running the following command from the BRM_home/bin directory:
```
.\start_pje
```

Rendering Invoices in a Third-Party Invoice Application

By default, when Business Operations Center generates invoices, it renders the invoices using Oracle Business Intelligence (BI) Publisher. If you use a third-party invoice application, you must configure Business Operations Center to not render invoices in BI Publisher.

To prevent Business Operations Center from rendering invoices in BI Publisher:

Open the BRM_home/apps/pin_job_executor/Infranet.properties file in a text editor.

Note:

Only administrators with write permissions can make changes to the Infranet.properties file.
Search for the following line:
```
- infranet.job.rendering=true
```
Change true to false.
```
infranet.job.rendering=false
```
Invoices will not be rendered in BI Publisher.
Save and close the file.
Stop and restart the pin_job_executor utility by running the following commands from the BRM_home/bin directory:
```
.\stop_pje
.\start_pje
```

Setting Up Business Operations Center to Run Custom Applications on Multischema Systems

You can set up Business Operations Center to run your custom application. To do so, you use the Business Operations Center GUI to create a custom category that defines the name and location of your script as well as the parameters associated with the script. For more information, see "Setting Up Custom Categories" in Business Operations Center Online Help.

If you want Business Operations Center to run your custom application on a BRM multischema system, you must also customize the application to do the following:

Accept the -job_id idNumber and -schema schemaNumber command-line arguments, where idNumber is the job ID and schemaNumber is the database schema on which to run the application.

Business Operations Center passes these two arguments with the command to run your application. For example, if the command-line syntax for running your application is my_custom_app -f file, Business Operations Center would run the following command:
```
my_custom_app -f file -job_id idNumber -schema schemaNumber
```
Build the POID of the /job/boc database object and then return it in its output to Business Operations Center. The format for building the POID is:
```
0.0.0.schemaNumber /job/boc idNumber
```
For example, the /job/boc POID for the following command would be 0.0.0.2 /job/boc 1234567.
```
my_custom_app -f file -job_id 1234567 schema 2
```
Update the /job/boc database object with the application's status as it runs. Set the object's PIN_FLD_STATUS field to one of the following:
- #define PIN_BOC_STATUS_APP_START 2: Indicates that the application has started.
- #define PIN_BOC_STATUS_APP_SUCCESS 3: Indicates that the application completed successfully.
- #define PIN_BOC_STATUS_APP_FAIL 4: Indicates that the application failed.
For applications that use the multithreaded application (MTA) framework, read the schema number, set it in the database number of PIN_FLD_POID_VAL, and then run the job against the specified schema,

Your application can fetch this field from app_flistp and then use it to extract the database number. For example:
```
vp = PIN_FLIST_FLD_GET (app_flistp, PIN_FLD_POID_VAL, MTA_MANDATORY, ebufp);
if ( vp ) {
   database = PIN_POID_GET_DB ((poid_t*)vp);
}
```
Also customize your application to do the following:
- Perform searches in a BRM database schema by including the database number of PIN_FLD_POID_VAL in the /job/boc POID. The POID for the search flist can be created as follows:
```
s_pdp = PIN_POID_CREATE(database, "/search", -1, ebufp);
```
- Run an opcode against a BRM database schema by setting the database portion of the opcode's PIN_FLD_POID input flist field.
- Create a /process_audit/billing object on the specified schema and then set the database portion of the object's PIN_FLD_POID field to the schema number. For example, in the following POID, the application would set only schemaNumber:
```
0.0.0.schemaNumber /process_audit/billing 123456
```
For non-MTA applications, read the -job_id idNumber and -schema schemaNumer arguments and then:
- Run against the specified database schema
- Create a /process_audit/billing object on the specified database schema

Improving Business Operations Center Performance

The PCM_OP_JOB_EXECUTE opcode internally calls the pin_job_executor process, which in turn calls the BRM application that you want to run. In a multischema environment, the pin_job_executor process runs applications on all schemas simultaneously using multiple threads. The process uses five threads by default, but you can tune the number of threads to improve performance.

To improve Business Operations Center performance:

Open the BRM_home/apps/pin_job_executor/Infranet.properties file in a text editor.

Note:

Only administrators with write permissions can make changes to the Infranet.properties file.
Set the following entry to the number of threads that can be spawned by the pin_job_executor process:
```
infranet.threadpool.size=ThreadNumber
```
Save and close the file.

Enabling Secure Communication for the pin_job_executor Utility

Note:

Perform this step only if you are using BRM 12.0.0.3.0 or earlier releases. Starting with BRM 12.0.0.3.0 Patch 31426340, Business Operations Center calls the PCM_OP_JOB_EXECUTE opcode rather than the pin_job_executor utility.

By default, the ability to use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) with the pin_job_executor utility is disabled. To enable secure communication between Business Operations Center and the Connection Manager (CM), you must configure SSL/TLS for the internal pin_job_executor utility.

To enable SSL for Business Operations Center:

Open the BRM_home/apps/pin_job_executor/Infranet.properties file in a text editor, where BRM_home is the directory in which BRM is installed.

Note:

Only administrators with write permissions can make changes to the Infranet.properties file.
Search for the following line:
```
- infranet.pcp.ssl.enabled=false
```
Change false to true.
```
- infranet.pcp.ssl.enabled=true
```

Add the following entry:

- infranet.pcp.ssl.wallet.location=$PIN_HOME/wallet/server

Add the following entry:
```
- infranet.pcp.ssl.wallet.filename=wallet_name.sso
```
where wallet_name is the name of your Oracle wallet.
Save and close the file.

About Generating Metrics to Display in Business Operations Center

You use the pin_generate_analytics utility to generate business metrics data for accounts by status, accounts by subscription, payments, billed revenue, and accounts receivable (A/R) and to load the metrics data into the BRM database. Business Operations Center displays graphs based on the business metrics data generated by the pin_generate_analytics utility.

You can run pin_generate_analytics manually or configure a scheduler, such as cron, to run it at predefined intervals. For more information, see "Generating Business Metrics Data".

The pin_generate_analytics utility generates and loads the following metrics into the BRM database:

Accounts by status: Generates metrics about the number of subscribers for each status at the time the utility is run: Active (10100), Inactive (10102), Closed (10103).
Accounts by subscription: Generates metrics about the number of subscriptions for each product at the time the utility is run based on the status of subscription: Active (1), Inactive (2), Closed (3).
Payment: Generates metrics about payments collected based on the payment type: prepaid (10000), invoice (10001), direct debit (10002), credit card (10003), cash (10011), and check (10012).

When you run the utility for the first time, data will be generated for the previous day. For subsequent runs, the start date is set to the last run date and the end date is set to the current date.
Billed revenue: Generates metrics about the amount billed and the number of bills generated.

When you run the utility for the first time, data will be generated for the previous day. For subsequent runs, the start date is set to the last run date and the end date is set to the current date.
Accounts receivable: Generates metrics about the A/R for the last one year with respect to month and the year.

When you run the utility, data will be generated for the previous 12 months from the date the utility is run.

Generating Business Metrics Data

You can generate metrics data for all business operations or just for specific business operations, such as subscriptions or payments collected, by running the pin_generate_analytics utility. For more information, see "pin_generate_analytics".

To generate metrics data for all business operations:

Go to the BRM_home/apps/pin_generate_analytics directory.
Run the following command:
```
pin_generate_analytics
```

The following sections show the commands to run for generating metrics data for specific business operations.

Generating Metrics for the Number of Subscribers

To generate business metrics data about the number of subscribers for each status at the time the utility is run, run the following command:

pin_generate_analytics -acc

Generating Metrics for the Number of Subscriptions Per Product

To generate business metrics data business metrics data about the number of subscriptions for each product based on the status of subscription at the time the utility is run, run the following command:

pin_generate_analytics -subs

Generating Metrics for Payments Collected

To generate business metrics data about the number and amount of payments collected, grouped by payment type, run the following command:

pin_generate_analytics -pymt

The first time you run this command, it generates business metrics data for the previous day. For example, if you run the command on January 2, it generates business metrics data for January 1. For subsequent runs, the start date is set to the last run date and the end date is set to the current date.

Generating Metrics for Amount Billed

To generate business metrics data about the amount billed and the number of bills generated, run the following command:

pin_generate_analytics -billing

Generating Metrics for Accounts Receivable

To generate business metrics data about the account receivable for the last one year with respect to month and the year, run the following command:

pin_generate_analytics -acc_recv

Creating Indexes to Improve Performance While Generating Metrics Data

When running the pin_generate_analytics utility to generate metrics data, you can improve performance by creating indexes.

To create indexes to improve performance while generating metrics data:

Go to the BRM_home/sys/dd/data directory.
Run the following command, which opens SQL*Plus:
```
% sqlplus login@database_alias
Enter password: password
```
where:
- login is the login name to use for connecting to the BRM database.
- password is the password for login.
- database_alias is the BRM database alias.
Run the following command:
```
SQL> @create_boc_pga_indexes.source
```
The indexes are created.
Run the following command, which exits SQL*Plus:
```
SQL> exit
```