1. Collecting General Ledger Data
  2. Configuring General Ledger Report XML Output Files

7 Configuring General Ledger Report XML Output Files

Learn how to configure your general ledger (G/L) XML output files in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

Configuring Preview and Monthly Report XML Output Files

To configure the file name and location of the XML output files for your preview and monthly G/L reports:

  1. Open the BRM_home/sys/data/config/pin_config_export_gl.xml file in an XML editor or a text editor.

  2. Edit the following tags:

    • OutputDirectory: Specify the directory in which to save your XML output files.

    • SourceSystemID: Specify a unique ID for the BRM system containing the G/L data. Use this tag if you export reports from multiple BRM systems and the external system needs to identify the source of the data.

    • FileNamePrefix: Optionally, specify a prefix to append to the XML output file name. You can use a prefix to identify the type of report.

      If the tag is empty or missing from the file, no prefix is added to the XML file name.

    • ReportInitialStartDate: Specify the start date for the first time a preview or monthly export report is generated.

      Note:

      The other XML tags in this file are ignored when you generate a preview or monthly export report.

  3. Save and close the file.

  4. Use this command to load the G/L configuration information into the /config/export_gl object in the BRM database: 

    load_pin_config_export_gl pin_config_export_gl.xml

    For more information, see "load_pin_config_export_gl".

  5. Validate that your G/L configuration file was loaded into the database correctly. See "Validating and Troubleshooting Exported G/L Reports".

About Preview and Monthly Export Report XML Output Files

When you generate a monthly export or preview report, their XML files are saved according to the configuration in the pin_config_export_gl.xml file.

Monthly export report files are saved to outputDirectory and use the following file naming convention: 

prefix_export_aggr_endDate_startDate_reportID.xml

Preview report files are saved to outputDirectory/PREVIEW and use the following file naming convention: 

prefix_preview_aggr_endDate_startDate_reportID.xml

where:

  • outputDirectory is the directory specified in the OutputDirectory tag of the pin_config_export_gl.xml file.

  • Prefix is an optional prefix that is added to your report XML files. You specify the prefix by using the FileNamePrefix tag in the pin_config_export_gl.xml file.

  • endDate is the last day (exclusive) covered by the report in YYYYMMDD format.

  • startDate is the first day covered in the report in YYYYMMDD format.

  • reportID is the unique ID of the G/L report in the BRM system. It comprises the following information, separated by dashes: database number, POID of the /process_audit/export_gl object, and report number. For example, 0.0.0.1-123456-10.

For example, a file named export_aggr_20200601_20200501_0.0.0.1-73061-4.xml is a monthly export report that contains data from May 1, 2020 through May 31, 2020.

Sample Configuration File for Preview and Monthly Export Reports

The following shows sample pin_config_export_gl.xml file entries for configuring preview and monthly export reports: 

<GLReportConfiguration>
    <SourceSystemID>India</SourceSystemID>
    <OutputDirectory>
        $PIN_HOME/GL_Output
    </OutputDirectory>
    <FileNamePrefix>
        ASC_GL_Report_
    </FileNamePrefix>
    <ReportInitialStartDate>
        08/30/2020
    </ReportInitialStartDate>
</GLReportConfiguration>

In this case, the monthly export report file would be saved to the $PIN_HOME/GL_Output directory and have a file name of ASC_GL_Report_export_aggr_20200918_20200830_0.0.0.1-73061-4.xml.

The preview report file would be saved to the $PIN_HOME/GL_Output/PREVIEW directory and have a file name of ASC_GL_Report_preview_aggr_20200918_20200830_0.0.0.1-73061-4.xml.

Configuring Individual Report XML Output Files

To configure the file name, location, and content of the XML output files for your individual G/L reports:

  1. Open the BRM_home/sys/data/config/pin_config_export_gl.xml file in an XML editor or a text editor.

  2. Edit the following tags for specifying the name and location of your XML output files:

    • OutputDirectory: Specify the directory in which to store your XML output files.

    • SourceSystemID: Specify a unique ID for the BRM system containing the G/L data. Use this tag if you export reports from multiple BRM systems and the external system needs to identify the source of the data.

    • FileNamePrefix: Optionally, specify a prefix to append to the XML file name. You can use a prefix to identify the type of report.

  3. Specify the content to include in your reports by editing the tags in Table 7-1:

    Note:

    If you are using Business Operations Center to generate individual reports, the values you enter in Business Operations Center override the values you enter here.

    Table 7-1 Configuration Tags for G/L Reports

    Use This Tag: To Do This:

    ReportInitialStartDate

    This value is only used as the report start date the first time a G/L report is exported for the corresponding segment. All subsequent reports for that segment use the end date of the previous G/L report as the report's start date value.

    Specify the initial start date for each G/L segment for which data is exported. The format is YYYYMMDD.

    The initial start date must be specified for the root G/L segment (Segment name="."). All G/L segments to be reported use this date. To set a different start date for a specific G/L segment, use the Segment tag and specify a different initial start date for that G/L segment. This date overrides the root segment start date.

    Segment

    Use the name attribute to specify a G/L segment to report on.

    If you specify a nested segment, be sure to include the root segment prefix. For example:

    <Segment name=.westcoast>

    Important: If you specify multiple instances of the same segment, each one must report on a different set of revenue types.

    Frequency

    Specify how often G/L reports are generated for the segment:

    • Daily

    • Weekly

    • Monthly

    • Yearly

    • Specific Dates

    Important: The frequency for your BRM G/L reports must match the frequency of the reporting schedule in your external G/L system. For example, if the BRM G/L calendar is Monthly, the export frequency should not be Weekly. This creates inaccurate G/L data.

    See "Setting Up Schedules for Individual G/L Reports".

    Date

    If Frequency is Yearly, set the DayofMonth and Month sub-tags under Date tag to specify the date to generate G/L reports.

    For Month, specify 01 through 12; for DayofMonth specify 01 through 31. If the month has fewer days than specified, the last day of the month is used. For example: 

    <Frequency>Yearly</Frequency>
<Date>
   <DayofMonth>-29</DayofMonth>
   <Month>-02-</Month>
</Date>

    DayOfMonth

    If Frequency is Monthly, specify the day of the month to generate G/L reports: 01 through 31. If the month has fewer days than specified, the last day of the month is used.

    Day

    If Frequency is Weekly, specify the day of week to generate G/L reports: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.

    Date

    If Frequency is Specific Dates, add one Month/DayofMonth pair for each date on which to generate a G/L report.

    For Month specify 01 through 12; for DayofMonth specify 01 through 31. If the month has fewer days than specified, the last day of the month is used. For example: 

    <Frequency>Specific Dates</Frequency>
<Date>
   <DayofMonth>-29</DayofMonth>
   <Month>-02-</Month>
</Date>
<Date>
   <DayofMonth>-31</DayofMonth>
   <Month>-05-</Month>
</Date>

    RevenueType

    Specify the revenue type for the G/L report:

    • Billed

    • Billed earned

    • Prior billed earned (Prior billed earned revenue is also known as Previously billed earned revenue.)

    • Unbilled

    • Unbilled unearned

    • Unbilled earned

    • Billed unearned

    Important: If you specify multiple instances of the same G/L segment, each one must report on a different set of revenue types.

    ReportLevel

    Specify the type of G/L report to generate: Summary or Detailed.

    Specify Detailed only when the report is customized using PCM_OP_GL_EXPORT_GL. See "Customizing G/L Reports for Export" in BRM Opcode Guide.

    ResourceType

    Specify the balance element type to include in the G/L report:

    • Monetary

    • Non-monetary

    • All

    IncludeNonMonetary

    If ResourceType is Non-monetary or All, specify the balance element ID of the nonmonetary balance element to include. Use a separate ResourceID tag for each balance element. All other nonmonetary balance elements are excluded from the report.

    Note: The IncludeNonMonetary and ExcludeNonMonetary tags are mutually exclusive. You can use only one.

    ExcludeNonMonetary

    If ResourceType is Non-monetary or All, specify the ID of the nonmonetary balance element to exclude. Use a separate ResourceID tag for each nonmonetary balance element. All other nonmonetary balance elements are included in the report.

    Note: The IncludeNonMonetary and ExcludeNonMonetary tags are mutually exclusive. You can use only one.

  4. Save and close the file.

  5. Use this command to load the G/L configuration information into the /config/export_gl object in the BRM database: 

    load_pin_config_export_gl pin_config_export_gl.xml

  6. Validate that your G/L configuration file was loaded into the database correctly. See "Validating and Troubleshooting Exported G/L Reports".

Setting Up Schedules for Individual G/L Reports

The frequency for your individual G/L reports must match the frequency of the reporting schedule in your external G/L system. For example, if the external G/L calendar is Monthly, the export frequency for your BRM G/L reports should be Monthly. If the two frequencies do not match, inaccurate G/L data will be reported.

You configure the export schedule for your G/L segments by setting the Frequency value for the G/L segment in the pin_config_export_gl.xml file. Each G/L segment you report on can use a different export frequency as long as it matches the reporting frequency for that G/L segment in the external G/L system.

To set up multiple reporting schedules for the same G/L segment, you must specify different revenue types for each report. You cannot specify overlapping revenue types to report on.

For example, to report on billed revenue on a monthly basis and unbilled revenue on a weekly basis for the eastcoast G/L segment, list multiple instances of the eastcoast segment in the SegmentList tag and specify the revenue type for each schedule, like shown in the sample code below: 

   <SegmentList>
      <Segment name=".eastcoast">
          <Frequency>Monthly</Frequency>
          <DayOfMonth>01</DayOfMonth>
          <RevenueTypeList>
              <RevenueType>Billed</RevenueType>
          </RevenueTypeList>
          <ReportLevel>Summary</ReportLevel>
          <ResourceType>Monetary</ResourceType>
      </Segment>
      <Segment name=".eastcoast">
          <Frequency>Weekly</Frequency>
          <Day>Saturday</Day>
          <RevenueTypeList>
              <RevenueType>Unbilled earned</RevenueType>
          </RevenueTypeList>
          <ReportLevel>Summary</ReportLevel>
          <ResourceType>Monetary</ResourceType>
      </Segment>
   </SegmentList>

About Individual Report XML Output Files

When you generate individual G/L reports, BRM posts, runs, and exports multiple reports, each of them exported to a separate XML file. Exported XML files are saved with the following file naming convention:

RevenueType_ReportEndDate_ReportStartDate_ReportId.xml

where:

  • RevenueType is the abbreviation for the revenue type being reported, such as ue for Unbilled earned and be for Billed earned.

  • ReportEndDate is the end date of the current report in YYYYMMDD format.

  • ReportStartDate is the start date for the current report in YYYYMMDD format.

  • ReportId is the ID of the generated report. For details, see Table 7-2.

For example:

ue_20070731_20070630_0.0.0.1-123456-10.xml

One XML file is created for each combination of G/L segment and revenue type defined in the export configuration file.

If you configure your G/L reports for the root segment, G/L data for all segments is reported on, except those that do not roll up to their parent segments. As many XML files will be created as there are report types, and each one will contain data for the entire root segment.

Table 7-2 describes the XML tags in the G/L export files.

Table 7-2 XML Tags in G/L Reports

XML Element Description

SourceSystemID

The unique ID for the database containing the G/L data.

ReportId

The unique ID of the G/L report in the BRM system. It comprises the following information, separated by dashes: database number, POID of the /process_audit/export_gl object, and report number. For example, 0.0.0.1-123456-10.

RevenueType

Revenue type (billed, unbilled, and so on)

BRM_GL_Segment

The G/L segment being reported on.

ReportCreatedTime

Report run time.

PeriodStartTime

The start date and time of the revenue reporting period.

PeriodStartEnd

The end data and time of the revenue reporting period.

RevenueAmounts

The revenue reported for a specific G/L segment:

  • The balance element ID and its associated BRM G/L ID.

  • A list of revenue accounts and their credit and debit amounts. For example, ARGrossAccount name="monthly.debit".

Sample Configuration File for Individual G/L Reports

The following example shows the configuration of pin_config_export_gl.xml for the root ( . ) segment in an individual G/L report: 

 <GLReportConfiguration>
   <SourceSystemID>Germany</SourceSystemID>
   <OutputDirectory>
      /$PINHOME/GL_output
   </OutputDirectory>
  
   <FileNamePrefix>
      test
   </FileNamePrefix>
  
   <ReportInitialStartDate>
      <Segment name=".">
          <Year>2011</Year>
          <Month>--07--</Month>
          <Day>---01</Day>
      </Segment>
      <Segment name=".east">
          <Year>2011</Year>
          <Month>--07--</Month>
          <Day>---01</Day>
      </Segment>
   </ReportInitialStartDate>
  
   <SegmentList>
      <Segment name=".">
          <Frequency>Daily</Frequency>
          <RevenueTypeList>
              <RevenueType>Billed earned </RevenueType>
              <RevenueType>Unbilled earned</RevenueType>
              <RevenueType>Billed</RevenueType>
              <RevenueType>Unbilled</RevenueType>
              <RevenueType>Previously billed earned</RevenueType>
          </RevenueTypeList>
          <ReportLevel>Detailed</ReportLevel>
          <ResourceType>All</ResourceType>
           <!--ExcludeNonMonetary>
              <ResourceID>111111111</ResourceID>
           </ExcludeNonMonetary-->
      </Segment>
   </SegmentList>
  </GLReportConfiguration>

The following example shows a pin_config_export_gl.xml file that contains two segments that are exported at different frequencies:

  • eastcoast is exported monthly.

  • westcoast is exported on specific dates.

The eastcoast segment gets its initial start date from the root segment, but the westcoast segment was added at a later date. Therefore, it has a different ReportInitialStartDate value. 

<BusinessConfiguration>
 <GLReportConfiguration>

   <SourceSystemID>
       California
   </SourceSystemID>

   <OutputDirectory>
      /users/gluser/exported
   </OutputDirectory>

   <FileNamePrefix>
      USA_
   </FileNamePrefix>

   <ReportInitialStartDate>
      <Segment name=".">
          <Year>2006</Year>
          <Month>07</Month>
          <Day>15</Day>
      </Segment>
          <!-- Segment '.westcoast' was introduced on 1/1/2007 -->
      <Segment name=".westcoast">
          <Year>2007</Year>
          <Month>01</Month>
          <Day>01</Day>
      </Segment>
   </ReportInitialStartDate>

   <SegmentList>
      <Segment name=".eastcoast">
          <Frequency>Monthly</Frequency>
          <DayOfMonth>–––01</DayOfMonth>
          <RevenueTypeList>
              <RevenueType>Billed</RevenueType>
              <RevenueType>Billed earned</RevenueType>
          </RevenueTypeList>
          <ReportLevel>Summary</ReportLevel>
          <ResourceType>All</ResourceType>
           <ExcludeNonMonetary>
              <ResourceID>100000</ResourceID>
              <ResourceID>100001</ResourceID>
              <ResourceID>100002</ResourceID>
              <ResourceID>100003</ResourceID>
           </ExcludeNonMonetary>
      </Segment>

      <Segment name=".westcoast">
          <Frequency>Specific Dates</Frequency>
          <Date>
             <DayofMonth>–––29</DayofMonth>
             <Month>––02––</Month>
          </Date>
          <Date>
              <DayofMonth>–––31</DayofMonth>
              <Month>––05––</Month>
           </Date>
          <Date>
              <DayofMonth>–––31</DayofMonth>
              <Month>––08––</Month>
           </Date>
          <Date>
              <DayofMonth>–––30</DayofMonth>
              <Month>––11––</Month>
           </Date>
           <RevenueTypeList>
              <RevenueType>Billed</RevenueType>
              <RevenueType>Billed earned</RevenueType>
           </RevenueTypeList>
           <ReportLevel>Detailed</ReportLevel>
           <ResourceType>All</ResourceType>
           <ExcludeNonMonetary>
              <ResourceID>100000</ResourceID>
              <ResourceID>100001</ResourceID>
              <ResourceID>100002</ResourceID>
              <ResourceID>100003</ResourceID>
            </ExcludeNonMonetary>
      </Segment>
   </SegmentList>
  </GLReportConfiguration>
</BusinessConfiguration>

Validating and Troubleshooting Exported G/L Reports

Before exporting your G/L reports, validate that your G/L export configuration data was loaded into the database correctly. Do the following:

  1. To write loading errors to a log file, run the load_pin_config_export_gl utility with the -d parameter.

  2. Run the pin_ledger_report utility in post_only mode and verify that the /data/ledger_report object is updated in the database.

  3. Run the pin_ledger_report utility in run_report mode with the -report and -test parameters. This will display the G/L report without creating the /ledger_report object.

    Verify that the revenue types and G/L segments are correct.

  4. Run the pin_ledger_report utility in export mode and verify that the report name, report type, G/L segments, frequency, and revenue types are correct.

  5. Verify that the /process_audit/export_gl object was created in the database. View the data in this object and verify that the data is correct and that the status of the export run is COMPLETED. See "Retrieving Audit Data for Exported G/L Reports".