16 Job Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) job opcode workflows.

Topics in this document:

• Opcodes Described in This Chapter

• Running BRM Applications

• Running Business Operation Jobs

• Managing Business Operations Job Templates

• Managing Business Operations Jobs

Opcodes Described in This Chapter

Table 16-1 lists the opcodes described in this chapter.

Caution:

• Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.

• Do not use SQL commands to change data in the database. Always use the API.

Table 16-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_JOB_EXECUTE	Running BRM Applications Running Business Operation Jobs
PCM_OP_JOB_PROCESS_TEMPLATE	Managing Business Operations Job Templates
PCM_OP_JOB_PROCESS_DEFINITION	Creating Custom Jobs Modifying Custom Jobs Deleting Custom Jobs
PCM_OP_JOB_POL_VALIDATE_DEFINITION	Validating Job Definitions
PCM_OP_JOB_POL_POST_PROCESS_DEFINITION	Post-Processing Job Definitions

Running BRM Applications

Note:

Before calling this opcode, ensure that:

• The pin_job_executor process is listening for calls from PCM_OP_JOB_EXECUTE. See "Configuring pin_job_executor to Listen for Opcode Calls" in BRM System Administrator's Guide.

• The opcode is configured to run BRM applications. See "Configuring PCM_OP_JOB_EXECUTE to Run BRM Applications" in BRM System Administrator's Guide.

• The pin_job_executor process is running in the background. To start the process, run this command from the $PIN_HOME/bin directory:

  ./start_pje

To run pin_virtual_time or another BRM utility, use the PCM_OP_JOB_EXECUTE opcode and pass in the following data:

• The POID of the account calling the opcode.

• PIN_FLD_FLAG set to 0, which indicates to run the application in a non-job context.

• The utility command to run, such as my_custom_utility -f filename -v.

• The working directory, relative to $PIN_HOME, in which to run the utility command. For example, for a working directory of $PIN_HOME/sys/cm, you would enter sys/cm.

  Note:

  Enter an absolute path to the working directory. Do not include /../ or ./ in the path.

PCM_OP_JOB_EXECUTE then performs these operations:

1. Opens a non-job context.

2. Creates an /event/activity/job_request object for auditing purposes.

3. Validates that the specified utility is located under the $PIN_HOME directory.

4. Validates that the specified path to the working directory is an absolute path.

5. Validates that the working directory specified in the PIN_FLD_DIRECTORY input flist field matches one of the allowed directories in the pin_job_executor utility's Infranet.properties file.

6. Runs the utility commands passed in the opcode's input flist.

7. Returns the result of the utility's execution in the opcode's output flist.

The following shows a sample PCM_OP_JOB_EXECUTE input flist for running a BRM application in a non-job context:

0 PIN_FLD_POID            POID [0] 0.0.0.1 /account 1 0
0 PIN_FLD_FLAGS            INT [0] 0
0 PIN_FLD_INSTRUCTION      STR [0] "pin_virtual_time -m 2 01010000"
0 PIN_FLD_DIRECTORY        STR [0] "apps/pin_billd"    

In this example, PCM_OP_JOB_EXECUTE would run the following command from the $PIN_HOME/apps/pin_billd directory:

pin_virtual_time -m 2 01010000

Running Business Operation Jobs

Note:

Before calling this opcode, ensure that:

• The pin_job_executor process is listening for calls from PCM_OP_JOB_EXECUTE. See "Configuring pin_job_executor to Listen for Opcode Calls" in BRM System Administrator's Guide.

• The pin_job_executor process is running in the background. To start the process, run this command from the BRM_home/bin directory:

  ./start_pje

To run business operations jobs, such as billing, invoicing, and payment collections, use the PCM_OP_JOB_EXECUTE opcode and pass in the following data:

• The POID of the account calling the opcode.

• PIN_FLD_FLAG set to 1, which indicates to run applications within a job context.

• The parameters and values to run, provided as a set of key-value pairs in the PIN_FLD_ARGS array. Table 16-2 lists the supported parameters.

  Table 16-2 PCM_OP_JOB_EXECUTE Parameters for Business Operations Jobs

  Parameter	Description	Mandatory
  job_template	Specifies the ID of the job template to run. The job template contains information about the utility that is run as well as the database schema numbers.	Yes
  request_id	Specifies the job request ID to use.	Yes
  start	Specifies the start time of the job. The default is immediately.	No
  end	Specifies the end time of the job.	Yes
  job_id	Re-runs the job with the specified job ID.	No

This opcode is called by Business Operations Center.

PCM_OP_JOB_EXECUTE then performs these operations:

1. Opens a job context.

2. Calls the pin_job_executor utility with the parameters passed in the PIN_FLD_ARGS array.

3. The pin_job_executor utility does the following:

   1. Extracts the database schema numbers from the specified /job_template object.

   2. Creates a /job/boc object for each database schema.

   3. For each /job/boc object, a separate thread runs the business operations utility specified in the /job_template object:

      • For billing jobs, it runs the pin_bill_accts utility.

      • For payment collections jobs, it runs the pin_collect utility.

      • For invoicing jobs, it runs the pin_inv_accts utility.

      • For general ledger report jobs, it runs the pin_ledger_report utility.

      • For synchronizing pricing data, it runs the pin_export_price utility.

      • For refund jobs, it runs the pin_refund utility.

      • For custom jobs, it runs the utility that you configure.

   4. For each /job/boc object, generates an /event/notification/job_complete event.

4. Returns the result of the job and the POID of the /job/boc object in the opcode's output flist.

The following shows a sample PCM_OP_JOB_EXECUTE input flist:

0 PIN_FLD_POID              POID [0] 0.0.0.1 /account 1 0
0 PIN_FLD_FLAGS              INT [0] 1
0 PIN_FLD_ARGS             ARRAY [0] allocated 2, used 2
1     PIN_FLD_NAME           STR [0] "job_template"
1     PIN_FLD_VALUE          STR [0] "119188"
0 PIN_FLD_ARGS             ARRAY [1] allocated 2, used 2
1     PIN_FLD_NAME           STR [0] "request_id"
1     PIN_FLD_VALUE          STR [0] "pje_js_1"
0 PIN_FLD_ARGS             ARRAY [2] allocated 2, used 2
1     PIN_FLD_NAME           STR [0] "end"
1     PIN_FLD_VALUE          STR [0] "10/08/2021"

Managing Business Operations Job Templates

To create, modify, or delete a business operations job template, use the PCM_OP_JOB_PROCESS_TEMPLATE opcode and pass in the following data:

• The POID of the /job_template object.

• The POID of the /account object that is calling the opcode.

• The database schema on which to run the business operations job: 0 specifies all schemas, 1 specifies the primary schema, 2 specifies the second schema, and so on.

• The name of the program that is calling the opcode.

• The type of business operations job to run such as billing, collections, or invoicing.

• The action to perform on the job template: create, modify, or delete.

• The name of the Business Operations Center user.

• Other optional configuration information.

When called, PCM_OP_JOB_PROCESS_TEMPLATE does the following:

• Validates the database schema number passed in the input flist and then creates, modifies, or deletes the specified /job_template object. By default, this opcode is called by Business Operations Center.

• Throws an error on the Create action if the /job_definition is marked with the status Closed.

• Indicates whether the /job_template object was deleted or marked as closed.

Managing Business Operations Jobs

You can manage your custom Business Operations jobs by creating, modifying, or deleting job definition objects. Additionally, you can validate and carry on the post-processing of the job definitions.

• Creating Custom Jobs
• Modifying Custom Jobs
• Deleting Custom Jobs
• Validating Job Definitions
• Post-Processing Job Definitions

Creating Custom Jobs

You create jobs using the PCM_OP_JOB_PROCESS_DEFINITION opcode, which creates /job_definition objects. This opcode is called by Business Operations Center.

To create custom business operations jobs, use the PCM_OP_JOB_PROCESS_DEFINITION opcode and pass in the following data:

• The POID of the job definition to be created

• The user and account information that is calling the job

• The definition of the job, including the category and the resource name

• The action to be performed: in this case Create

PCM_OP_JOB_PROCESS_DEFINITION then performs these operations for the Create action:

• Validates that all mandatory fields for creating a job definition are provided in the input flist and that the resource name does not match any existing resource name (for example, the predefined names such as Billing or Invoicing).

• Calls PCM_OP_JOB_POL_VALIDATE_DEFINITION to perform further validation of the job definition.

• If all the validation checks are successful, calls PCM_OP_CREATE_OBJ to create the job definition object.

• Calls the policy opcode PCM_OP_JOB_POL_POST_PROCESS_DEFINITION with the return flist, for additional post-processing.

• Returns the PIN_FLD_POID of the created job definition or sets an error if the PCM_OP_CREATE_OBJ opcode fails.

Modifying Custom Jobs

You modify jobs using the PCM_OP_JOB_PROCESS_DEFINITION opcode, which modifies /job_definition objects. This opcode is called by Business Operations Center.

To modify custom business operations jobs, use the PCM_OP_JOB_PROCESS_DEFINITION opcode and pass in the following data:

• The POID of the job definition to be modified

• The user and account information that is calling the job

• The fields that should be modified for the job, including the category

• The action to be performed: in this case Modify

PCM_OP_JOB_PROCESS_DEFINITION then performs these operations for the Modify action:

• Validates that the resource name is not provided. If it is provided, it generates an error. The resource name cannot be modified.

• Calls PCM_OP_WRITE_FLDS to update the job definition object.

• Calls the policy opcode PCM_OP_JOB_POL_POST_PROCESS_DEFINITION with the return flist, for additional post-processing.

• Returns the PIN_FLD_POID of the modified job definition or sets an error if the PCM_OP_WRITE_FLDS opcode fails.

Deleting Custom Jobs

You delete jobs using the PCM_OP_JOB_PROCESS_DEFINITION opcode, which deletes /job_definition objects. This opcode is called by Business Operations Center.

To delete custom business operations jobs, use the PCM_OP_JOB_PROCESS_DEFINITION opcode and pass in the following data:

• The POID of the job definition to be deleted

• The user and account information that is calling the job

• The name of the program or application from which this opcode is called

• The action to be performed: in this case Delete

PCM_OP_JOB_PROCESS_DEFINITION then performs these operations for the delete action:

• Validates that the provided POID exists.

• Calls the PCM_OP_JOB_POL_VALIDATE_DEFINITION policy opcode for further validation and to ensure that the job definition can be deleted.

• Checks if the /job_definition object has any /job_template/custom instances associated with it to ensure that the job definition is not being used by any pending jobs.

• If the job definition is being used by any pending jobs, it is not deleted.

• Otherwise, the opcode deletes the /job_definition object using PCM_OP_DELETE_OBJ.

• Creates an event (/event/job_definition/delete) to log the deletion of the job definition.

• Searches for and deletes any associated /job_template/custom objects by calling PCM_OP_JOB_PROCESS_TEMPLATE with the Delete action on each result.

• Calls PCM_OP_JOB_POL_POST_PROCESS_DEFINITION with the return flist.

• Returns the result of PCM_OP_JOB_POL_POST_PROCESS_DEFINITION if the process is successful; otherwise, sets an error.

Validating Job Definitions

To validate the contents of a job definition, use the PCM_OP_JOB_POL_VALIDATE_DEFINITION opcode. This policy opcode is called by the PCM_OP_JOB_PROCESS_DEFINITION opcode during creation and modification.

To use the PCM_OP_JOB_POL_VALIDATE_DEFINITION opcode, pass in the following data:

• The POID of the job definition

• Name of the program from where this opcode is called

• Name of the BOC user making the call

• Action to be performed on the /job_definition object. It can be Create, Modify, or Delete

• Job Resource name: It should be unique

PCM_OP_JOB_POL_VALIDATE_DEFINITION then performs the following tasks:

• Validates the provided information for a job definition object, ensuring that all required and relevant fields are correctly populated.

• Checks if essential parameters like PIN_FLD_NAME, PIN_FLD_LOCATION, PIN_FLD_PROGRAM_NAME, PIN_FLD_USER_NAME, and PIN_FLD_RESOURCE_NAME are provided and within valid limits.

• Validates the action specified in PIN_FLD_ACTION is either Create, Modify, or Delete.

• If provided, it validates the job category in PIN_FLD_CATEGORY. The category should be unique, and it should not match any predefined category names, especially when creating a job definition.

• Validates the job definition's status in PIN_FLD_STATUS. It should be set to active or closed. If not provided, the default status is active.

• Ensures that the provided PIN_FLD_ACCOUNT_OBJ is associated with the job definition.

• The opcode returns the validated job definition POID for further processing.

Post-Processing Job Definitions

You can perform post-processing validation and actions on job definition objects and related templates with PCM_OP_JOB_POL_POST_PROCESS_DEFINITION opcode. It is typically used after specific operations, such as deletion or closure of job definitions, to ensure that any dependent templates are handled correctly and that the overall integrity of the job definition data is maintained.

To use the PCM_OP_JOB_POL_POST_PROCESS_DEFINITION opcode, pass in the following data:

• The POID of the job definition

PCM_OP_JOB_POL_POST_PROCESS_DEFINITION then performs the following tasks:

• Checks the PIN_FLD_DELETED_FLAG when the action is "Delete" to determine whether the job_definition was deleted or marked as closed.

• Processes the PIN_FLD_TEMPLATE_ARRAY, an array that may hold schema numbers and associated job templates.

• For each template in the array, checks the PIN_FLD_DELETED_FLAG to determine if the job_template was deleted or marked as closed.

• Updates the job definition's status or attributes based on the performed action.

• Returns the updated job definition's POID after post-processing.