Configuring Business Operations Center to Run Custom Applications

About Running Custom Business Applications

You can set up Business Operations Center to run your custom applications. For example, you can create a custom invoicing job that automates the process of generating customer invoices.

You can configure Business Operations Center to

A custom application
A custom multithreaded application (MTA)
A wrapper shell script that calls one or more applications or MTAs

To do so, you use the Business Operations Center UI to create a custom category that defines the name and location of your script as well as the parameters associated with the script.

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

Customizing Your Application to Run MTA Applications

Add a note explaining that for wrapper scripts invoking multiple MTAs, BOC does not display separate result rows for each subordinate MTA. The subordinate MTAs must use the same BOC job ID so that /process_audit/billing data is associated with the BOC job and displayed as consolidated results.

When BOC launches a custom application or script, it passes a BOC job identifier and schema number to the launched command. If the launched command is a shell script that invokes one or more MTA utilities, the script must read the BOC-provided job and schema arguments and pass them to each MTA utility that creates process audit data

Explicitly state that the job ID must not be random. It must be the BOC-created /job/boc ID supplied when BOC launches the custom job.

Clarify direct MTA versus wrapper-script behavior:

Direct MTA custom application: the MTA must create/update the appropriate /process_audit/billing data for the BOC job.

Wrapper shell script: the script must either pass the BOC job/schema values to the MTAs it invokes, or create the appropriate process audit data itself if it performs non-MTA work.

Add a note that when multiple MTAs are invoked under one BOC custom job, BOC displays the results associated with the common BOC job rather than independent rows for each subordinate MTA. Add troubleshooting guidance for BOC showing zero records despite MTA processing: Check whether revenue assurance audit generation is enabled with pin_mta enable_ara 1. Check logs for “Not calling Revenue Assurance opcode as feature was disabled.” Verify that the MTA calls PCM_OP_PROCESS_AUDIT_CREATE. Verify that each subordinate MTA receives the BOC job ID and schema arguments. Review the current argument naming in the topic. The 15.2 page currently describes -job_id idNumber and -schema schemaNumber, while the bug logs and developer comments consistently show BOC invoking the custom script with -job <job_id> -schema <schema_number>. The doc should either align the option name with actual BOC behavior or explicitly document supported aliases.

Passing the job ID enables the utilities to create /process_audit/billing data for the same Business Operations Center job run.

You can set up Business Operations Center to run your custom application. To do so,

If you are running one or more MTA applications, ensure that each MTA application's pin.conf configuration file has the enable_ara entry set to 1:
```
- pin_mta enable_ara 1
```
For more information, see " Enabling Billing Utilities to Generate Revenue Assurance Data " in BRM Collecting Revenue Assurance Data.

If your custom application is a wrapper shell script that calls one or more MTA utilities such as pin_cycle_fees, pin_rollover, or pin_bill_accts, customize your wrapper script to read the arguments that Business Operations Center passed to it and pass them on to each MTA utility it invokes.

For example, the wrapper script should do something similar to this:

#!/bin/bash

JOB_ID=
SCHEMA=

while [ $# -gt 0 ]
do
   case "$1" in
      -job|-job_id)
         shift
         JOB_ID="$1"
         shift
         ;;
      -schema)
         shift
         SCHEMA="$1"
         shift
         ;;
      *)
         shift
         ;;
   esac
done

pin_cycle_fees -regular_cycle_fees -job "jobIdNumber" -schema "schemaNumber"
pin_bill_accts -active -pay_type 10001 -job "jobIdNumber" -schema "schemaNumber"
pin_bill_accts -inactive -pay_type 10001 -job "jobIdNumber" -schema "schemaNumber"
pin_bill_accts -close -pay_type 10001 -job "jobIdNumber" -schema "schemaNumber"

Customizing Your Custom Application to Run on Multischema Systems

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

Accept the -job_id jobIdNumber and -schema schemaNumber command-line arguments, where jobIdNumber 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 jobIdNumber -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 jobIdNumber
```
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 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);
}
```
- 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 jobIdNumber and -schema schemaNumer arguments and then:
- Run it against the specified database schema
- Create a /process_audit/billing object on the specified database schema

Configuring Roles for Custom Jobs

To run business operations jobs, you must be assigned the appropriate role. In Business Operations Center, you can create custom roles to match your specific operational needs. Each custom role is associated with a set of jobs that determine the actions a user with that role can perform.

You can use the Business Operations Center Jobs feature to define a new custom category. Within the Categories column, you can select the desired custom job to launch the job creation wizard, where you can specify the job name, execution frequency, and other relevant settings.
You can provide information, including the name and location of your custom script, the category for your script, and the resource name in the Define Category page. You use resources to provide different access permissions to different custom scripts, so all scripts using the same resource will have the same access permissions. Assign a unique resource name to each category, adhering to specific naming conventions and character limitations.

The system's access control for custom job categories has a dynamically generated resource name. When you enter a resource name in the BOC interface, it is converted dynamically into a resource with the name category_yourResourceName_resource. After the resource name is set, it cannot be changed.
You must add these custom resources to the system-jazn-data.xml policy file in a specific format. Business Operations Center will then check for access permissions on these custom resources.

65 Configuring Business Operations Center to Run Custom Applications

About Running Custom Business Applications

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

Customizing Your Application to Run MTA Applications

Customizing Your Custom Application to Run on Multischema Systems

Configuring Roles for Custom Jobs