General Ledger Opcode Workflows

12 General Ledger Opcode Workflows

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

Topics in this document:

Opcodes Described in This Chapter

Table 12-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 12-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_POL_SPEC_GLID	Assigning G/L IDs to Prerated Events
PCM_OP_GL_LEDGER_REPORT	How BRM Exports G/L Reports How BRM Stores General Ledger Reports
PCM_OP_GL_POL_EXPORT_GL	Customizing G/L Reports for Export Customizing G/L Export Report Contents How BRM Exports G/L Reports
PCM_OP_GL_POL_PRE_UPDATE_JOURNAL	Customizing G/L Data Stored in /journal Objects

How G/L IDs Affect Storage and Reporting of G/L Data

The G/L ID assigned to a balance impact determines whether the balance impact is stored in a /journal object and whether it is included in a G/L report as shown in Table 12-2:

Table 12-2 G/L IDs

G/L ID	Description	Stored in Journal Object?	Included in G/L Report?
0	Default G/L ID. If you forget to assign a G/L ID to a balance impact type, BRM automatically assigns G/L ID 0 to it. You should reassign such balance impact types to an appropriate G/L ID.	Yes	No
1 through 99	Assigned to balance impact types that are not included in G/L reports.	No	No
100 and above	Assigned to balance impact types that are included in G/L reports.	Yes	Yes

G/L ID

Description

Stored in Journal Object?

Included in G/L Report?

Default G/L ID.

If you forget to assign a G/L ID to a balance impact type, BRM automatically assigns G/L ID 0 to it. You should reassign such balance impact types to an appropriate G/L ID.

Yes

1 through 99

Assigned to balance impact types that are not included in G/L reports.

100 and above

Assigned to balance impact types that are included in G/L reports.

Yes

How BRM Records the Difference between Rounded and Unrounded Items

The difference between rounded and unrounded item totals is typically a very small amount referred to as the delta. This delta is recorded and included in G/L reports so that they can be accurately reconciled. The delta rounding difference is recorded in the following ways:

When billing is run and pending items are rounded, the delta rounding difference is recorded in the /item object.
A corresponding /journal entry object is created for each pending item. The delta rounding difference is stored as a credit or debit in the /journal object to balance the G/L:
- If the rounding difference is negative, the balance needs to be credited, so the amount is stored in the PIN_FLD_CR_AR_NET_AMT field.
- If the rounding difference is positive, the balance needs to be debited, so the amount is stored in the PIN_FLD_DB_AR_NET_AMT field.
When a G/L report is generated, the journal entry containing the delta rounding difference is included in the report.

The delta rounding difference is calculated as the difference between a rounded pending item total and the sum of the rounded journal entries associated with the pending item:

    round(unrounded pending items) 
 -  sum(round(journal entries)
-------------------------------------------
 =  rounding difference

For example, if a rounded pending item total is 11.72 and the sum of rounded journal entries is 11.73, the delta rounding difference is 11.72 - 11.73, or -.01.

Customizing G/L Data Stored in /journal Objects

During event processing, BRM retrieves balance impacts from each event and adds it to the revenue summary in the appropriate /journal object.

You can customize the data before it is written into /journal objects by using PCM_OP_GL_POL_PRE_UPDATE_JOURNAL.

PCM_OP_GL_POL_PRE_UPDATE_JOURNAL receives in the input flist the entries that are recorded in the /journal object. By default, the opcode does not perform any processing and returns only the entries passed in the input flist.

You can customize the opcode to add, modify, or remove one or more of the entries that will be recorded in the /journal object.

The opcode returns the following in the output flist:

PIN_FLD_POID field set to the /event object POID.
(Optional) PIN_FLD_JOURNAL_INFO array containing the entries that are recorded in the /journal object.

Note:

If the PIN_FLD_JOURNAL_INFO array is passed in the output flist, its PIN_FLD_POID field must be set either to -1 (when creating a new /journal object) or to a valid /journal POID (when updating an existing /journal object).

By default, BRM does not call PCM_OP_GL_POL_PRE_UPDATE_JOURNAL before writing data into /journal objects. You configure BRM to call the opcode by modifying the billing instance of the /config/business_params object with the pin_bus_params utility.

To enable this feature, run the pin_bus_params utility to change the CustomJournalUpdate business parameter. For information about this utility, see BRM Developer's Guide.

To enable custom updates to G/L data:

Go to BRM_home/sys/data/config.

Create an XML file from the /config/business_params object:

pin_bus_params -r BusParamsBilling bus_params_billing.xml

In the file, change disabled to enabled:

<CustomJournalUpdate>enabled</CustomJournalUpdate>

Save the file as bus_params_billing.xml.
Load the XML file into the BRM database:
```
pin_bus_params bus_params_billing.xml
```
Stop and restart the CM.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see BRM System Administrator's Guide.

Customizing G/L Reports for Export

You can customize the data in your exported G/L reports by configuring PCM_OP_GL_POL_EXPORT_GL. The pin_ledger_report utility calls this opcode in -export mode after it generates a G/L report but before it exports the G/L report data to an XML file.

For example, you can map the G/L revenue account name in the BRM system to a different account name based on your company's criteria. To do this, you customize PCM_OP_GL_POL_EXPORT_GL to do the mapping and return the modified PIN_FLD_GL_ACCTS array from the input flist.

When the pin_ledger_report utility runs in -export mode, it creates a new ledger report object with the custom data in the PIN_FLD_GL_ACCTS array. This customized G/L report is used for further processing and is exported to the G/L report XML files.

The PIN_FLD_RESULT value in the output flist determines whether to create a customized report from the original report used for export:

0: Use the original G/L data to generate the export report. This is the default.
1: Use the G/L data in the output flist to generate a custom export report.

Note:

The values returned by PCM_OP_GL_POL_EXPORT_GL must be in summary format even when the input flist data is in detailed format.

Customizing G/L Export Report Contents

Use PCM_OP_GL_POL_EXPORT_GL to customize the contents of your exported G/L reports. For example, the BRM G/L account names could be mapped to the third-party account names or the BRM balance element IDs could be mapped to the third-party balance element IDs.

Mapping BRM G/L Account Names to Third-Party Account Names

Use PCM_OP_GL_POL_EXPORT_GL to convert BRM G/L account names to the G/L account names in your external G/L system before XML reports are exported. This makes importing them into the external system easier. The following is an example of the code used to map BRM G/L account names to the third-party account names after PCM_OP_GL_POL_EXPORT_GL has been called.

#***********************************************************
#Section to customize report
#***********************************************************
PCM_OP(ctxp, PCM_OP_READ_OBJ, 0, in_flistp, &r_flistp, ebufp);
PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG,"Flistp after read obj in Custom report", r_flistp);
while ((tmp_flistp = PIN_FLIST_ELEM_TAKE_NEXT(r_flistp, PIN_FLD_GL_ACCTS,&rec_id, 1, &cookie, ebufp)) != (pin_flist_t *)NULL)
{
         char *segment = NULL;
         PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "GL accts from input flist", tmp_flistp);
         tmp1_flistp = PIN_FLIST_ELEM_ADD(out_flistp, PIN_FLD_GL_ACCTS, ctr, ebufp);
         PIN_FLIST_CONCAT(tmp1_flistp, tmp_flistp, ebufp);
         ctr++;
         vp = PIN_FLIST_FLD_GET(r_flistp, PIN_FLD_GL_SEGMENT, 0, ebufp);
         if (vp) 
        {
            segment = (char *)vp;
         }
         modify_acct_name(tmp1_flistp, PIN_FLD_AR_GROSS_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_OFF_GROSS_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_AR_NET_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_OFF_NET_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_AR_DISC_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_OFF_DISC_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_AR_TAX_GL_ACCT, segment, ebufp);
         modify_acct_name(tmp1_flistp, PIN_FLD_OFF_TAX_GL_ACCT, segment, ebufp);
         PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "GL accts from output flist ", tmp1_flistp);
         PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "Intermediate output flist ", out_flistp);
}
#************************************************************ 
#Set PIN_FLD_RESULT to indicate customization
#***********************************************************/
result = 1;
PIN_FLIST_FLD_SET(out_flistp, PIN_FLD_RESULT, (void *)&result, ebufp);

Mapping BRM Balance Element IDs to Third-Party Balance Element IDs

If the mapping capabilities provided with the BRM pin_glid mapping file are not sufficient, you can use PCM_OP_GL_POL_EXPORT_GL to convert BRM balance element IDs to the balance element IDs in your external G/L system before XML reports are exported. This makes importing them into the external system easier. The following is an example of the code used to map BRM balance element IDs to the third-party balance element IDs after PCM_OP_GL_POL_EXPORT_GL has been called.

#************************************************************ 
#Section to customize report
#****************************************************************
PCM_OP(ctxp, PCM_OP_READ_OBJ, 0, in_flistp, &r_flistp, ebufp);
PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "Flistp after read obj in Custom report", r_flistp);
while ((tmp_flistp =PIN_FLIST_ELEM_TAKE_NEXT(r_flistp, PIN_FLD_GL_ACCTS,&rec_id, 1, &cookie, ebufp)) != (pin_flist_t *)NULL)
{
       PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "GL accts from input flist ", tmp_flistp);
       tmp1_flistp = PIN_FLIST_ELEM_ADD(out_flistp, PIN_FLD_GL_ACCTS, ctr, ebufp);
       PIN_FLIST_CONCAT(tmp1_flistp, tmp_flistp, ebufp);
       ctr++;
       vp = PIN_FLIST_FLD_GET(r_flistp, PIN_FLD_RESOURCE_ID, 0, ebufp);
       if (vp) 
          {
          resource_id = (int32 *)vp;
          if (resource_id == 840)
              { 
              new_resource_id = 1840;
              } 
          }
PIN_FLIST_FLD_SET(out_flistp, PIN_FLD_RESOURCE_ID, (void *)&new_resource_id, ebufp);
PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "GL accts from output flist ", tmp1_flistp);
PIN_ERR_LOG_FLIST(PIN_ERR_LEVEL_DEBUG, "Intermediate output flist ", out_flistp);
}
#***********************************************************
#Set PIN_FLD_RESULT to indicate customization
#***********************************************************
result = 1;
PIN_FLIST_FLD_SET(out_flistp, PIN_FLD_RESULT, (void *)&result, ebufp);

Customizing the G/L Report XML File Names

To customize the XML file names for your G/L reports, use the FileNamePrefix tag in the pin_config_export_gl.xml configuration file. For example, if your company tracks G/L data separately for multiple divisions of the same company, you can prefix the G/L data for each division with a unique identifier.

Assigning G/L IDs to Prerated Events

Use PCM_OP_ACT_POL_SPEC_GLID to assign G/L IDs to prerated events or partially rated events. By default, this opcode retrieves an event's G/L ID from the /config/map_glid object. You can customize it to perform searches on other objects and look at other fields.

For example, you can categorize adjustments by customizing the opcode to assign G/L IDs based on the adjustment type.

All customization is done using pin_glid and COA files.

How BRM Exports G/L Reports

The pin_ledger_report utility performs the following tasks when it runs:

Retrieves G/L report configuration information from the /config/export_gl object to determine which reports to generate and which G/L segments to report.
Creates a new /process_audit/export_gl object for this run and sets the status of the /process_audit/export_gl object to IN_PROGRESS.
Reads the previous /process_audit/export_gl object and the ReportInitialStartDate value in the /config/export_gl object to determine if any G/L reports for previous periods have not been created. If so, creates them.
Calls PCM_OP_GL_LEDGER_REPORT to create the /ledger_report object for the current period.
Using the POID of the generated /ledger_report object, calls PCM_OP_GL_POL_EXPORT_GL and then does one of the following, based on the PIN_FLD_RESULT value:
- 0: No customization; generates and exports the original report.
- 1: Customization. If the G/L data was updated, creates a new /ledger_report object in database and exports the new report.
Note:

If the report contains cumulative revenue, generates an incremental report by using the G/L report for the previous period, if one exists, and updates the /ledger_report object.
If specified in the export configuration file, filters noncurrency balance elements from the generated /ledger_report object to be included in or excluded from the XML output file.
Generates the XML output file.
Updates the /process_audit/export_gl object with information about this run.
Posts reports in the database.
Sets the status of the /process_audit/export_gl object to RUN_COMPLETED.

Note:

If the pin_ledger_report utility encounters errors during processing, it exits without completing the report processing. (One or more prior reports and one or more G/L export reports may have been successfully generated.)

How BRM Stores General Ledger Reports

The pin_ledger_report utility uses PCM_OP_GL_LEDGER_REPORT to store general ledger reports in the BRM database. This opcode calls PCM_OP_CREATE_OBJ to create a /ledger_report object.

When the PCM_OPFLG_READ_RESULT flag is set, the opcode returns the entire contents of the /ledger_report object.