Customizing Billing Care Templates

About Billing Care Templates

Templates define which columns Billing Care displays in account search, event, and Newsfeed results tables and enable you to add and remove displayed data depending on your business requirements. Event templates are specific to the Oracle Billing and Revenue Management (BRM) /event storable class. You may use one or more event templates depending on the supported events in BRM. A single template determines the displayed columns in the Newsfeed, and displays data from the /newsfeed storable class. The account search template is defined in the accountSearch.xml file.

See "Understanding Flists and Storable Classes" and "Creating Custom Fields and Storable Classes" in BRM Developer's Guide for more information about BRM storable classes.

Templates can specify both BRM data in storable classes, and data from external sources. If the data you want to display is not provided by default storable classes available in Billing Care, extend the REST framework to retrieve the required data.

A template file contains four types of elements. Each <columnHeader> defined in the template file contains a corresponding storable class <column> data definition of the type of data contained in the column. The <filter> elements define search fields available to the user to filter displayed data. The <sortbyFields> elements specifies field sorting behavior.

Table 5-1 lists the <columnHeader> properties in a template file.

Table 5-1 <columnHeader> Properties in Template Files

Property	Description
alignment	String specifying how to align column text with a cell
icon	Boolean specifying if an image icon is used in the header
label	String used as column header label
resizable	Boolean specifying if the column width is resizable by user
sortable	Boolean specifying if the results table is sortable by the column
tooltip	String used for hover over tool tip for the column
visible	Boolean specifying if the column is visible
width	Width of column specified as percentage

Table 5-2 lists the <column> properties in a template file. See the genericTemplate.xml file included in the SDK_home/references/eventtemplates, where SDK_home is the Billing Care SDK installation directory, for an example of how column properties are specified.

Table 5-2 <column> Properties in Template Files

Property	Description
column name	Specifies the ID used to map between the column header and column definitions.
fields	Specifies the BRM fields that will be displayed in the column.
format	Specifies the format of the text to be displayed. Used exclusively when type is text.
formula	Optional. If specified, the formula is applied on the specified <field> entries. Can be useful to perform math with multiple fields and display the calculated result.
styles	Specifies the CSS style for the data in a given column.
type	Specifies the data type of the column. Billing Care performs formatting appropriate to the data type. Supported data types include: id date time currency text image multi Boolean enum duration phoneNumber
types	Used when type is multi, this enables you to specify the data types of the specified fields

Table 5-3 lists the <filter> properties in a template file. Each filter contains one or more <criteria> definitions using the properties listed.

Note:

The filter definition applies only to events templates.

Table 5-3 <filter> Properties in Template Files

Property	Description
fieldGroups	Groups listed `<criteria>` together into a single filter.
groupLabel	Specifies the name of the grouped `<criteria>`.
groupOperator	Supports AND and OR values for setting the exclusivity of the grouped `<criteria>` when filtering results.
inputType	Specifies the type of data used in `<criteria>`.
visible	Boolean specifying if a `<criteria>` is visible in Billing Care.

Table 5-4 lists the <sortbyFields> properties in a template file.

Table 5-4 <sortbyFields> Properties in Template Files

Property	Description
defaultSort	Specifies the default sorting behavior.
sortingOrder	Specifies either ascending or descending sort order.
sortingPriority	Lists the fields and priority (by order listed) used to sort displayed results

Customizing Templates

You customize the columns displayed for events and in the Newsfeed by creating custom template files and including these templates, and any required Java code extensions, in your deployed customizations shared library.

The Billing Care SDK includes the default templates used by Billing Care in the SDK_home/references/eventtemplates and SDK_home/references/newsfeedtemplates directories, where SDK_home is the directory in which you installed the SDK. The account search template is defined in the SDK_home/references/accountSearch.xml file.

The SDK_home/samples/SDKTemplatesCustomization directory includes sample templates for customized events and the Newsfeed, and sample Java code for extending the REST framework to retrieve additional data. Use these samples as guidelines when creating custom templates and REST extensions. A README.txt file is provided with additional detail on creating custom templates.

Customize Event and Newsfeed templates by:

Example procedures for customizing templates are provided in the following reference sections at the end of this chapter:

Removing Columns from a Template

Remove unwanted events and Newsfeed columns from displaying in Billing Care by either deleting the column entries from the template file for or setting the visible property for the column to false.

To remove a column from an event or Newsfeed template and prevent the column from displaying in Billing Care:

Make a copy of a default event or Newsfeed template in your myproject/web/WEB-INF/classes/custom/eventtemplates or myproject/web/WEB-INF/classes/custom/newsfeedtemplates, where myproject is the directory for your NetBeans IDE customization project. Preface the template name with Custom. For example, to customize the template for the /event/delayed/session/telco/gsm/sms event, use CustomserviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml.
Open your template file in a text editor.
Do one of the following:
- Remove both the <columnHeader> and storable class <column> elements from your template for the column you want to remove.
- Set the <columnHeader> visible property to false for the column you want to hide.
Save and close the file.
Do one of the following:
- If you are using an exploded archive for your shared library, log out of and back into Billing Care to verify your updated template. See "About Using an Exploded Archive" for more information about using exploded archives.
- Package your customizations shared library and deploy it to your Billing Care domain. Redeploy Billing Care and login to verify your updated template. See "Packaging and Deploying Customizations" for more information on packaging and deploying your customizations.

Adding Columns to a Template

Add columns in an events or the Newsfeed template for display in Billing Care by adding elements for the new columns in a template file. The new columns can contain BRM fields in the /event or /newsfeed storable classes or custom classes. Custom /event classes require extension of the REST framework to retrieve required data for display.

To add additional columns in a template and display the column in Billing Care:

Make a copy of a default event or Newsfeed template (or create a template for a custom event) in your myproject/web/WEB-INF/classes/custom/eventtemplates or myproject/web/WEB-INF/classes/custom/newsfeedtemplates, where myproject is the directory for your NetBeans IDE customization project. Preface the template name with Custom. For example, to customize the template for the /event/delayed/session/telco/gsm/sms event, use CustomserviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml.
Open your template file in a text editor.
Add both the <columnHeader> and storable class <column> elements from your template for the new column you want to add.
Save and close the file.
If necessary, extend the REST framework to retrieve any data unavailable in the default storable classes. See "Extending the REST Framework to Support New Column Fields" for more information on extending the REST framework.
If necessary, create a customModule.properties entry specifying when Billing Care should override a module's default logic with your customizations. See "Creating a customModule.properties File" for more information.
Do one of the following:
- If you are using an exploded archive for your shared library, log out of and back into Billing Care to verify your updated template. See "About Using an Exploded Archive" for more information about using exploded archives.
- Package your customizations shared library and deploy it to your Billing Care domain. Redeploy Billing Care and login to verify your updated template. See "Packaging and Deploying Customizations" for more information on packaging and deploying your customizations.

Extending the REST Framework to Support New Column Fields

Create custom Java classes to retrieve and display new fields for columns you add. The following procedure provides an overview of the required classes. See the following examples for sample classes:

To add custom fields to an event template and customize the REST framework to support the new field:

Create a custom event template in your NetBeans IDE customization project. See "Adding Columns to a Template" for more information.
Create a custom event worker Java class in myproject/src/com/company/templates to retrieve the data for the new field, where company is a folder named for your company, that extends from com.oracle.communications.brm.cc.modules.pcm.workers.TemplateEventWorker.
Create a custom event template factory Java class in myproject/src/com/company/templates to return an instance of your custom worker from step 2.
Create a custom template module class in myproject/src/com/company/templates to return an instance of your custom event template factory from step 3.
Compile your custom Java classes using NetBeans IDE.
Add your customization files to your NetBeans IDE project (myproject):
- Add the customModule.properties in the myproject/web/WEB-INF/classes/custom folder.
- Add the custom template file in the myproject/web/WEB-INF/classes/custom/eventtemplates folder.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your custom templates to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Creating a customModule.properties File

Configure an entry in the customModule.properties file for each Billing Care module where you override default logic with your customizations. See "About the customModule.properties File" for more information on specifying custom module behavior in customModule.properties.

Example 1: Event Template Customization

This example includes changing the events template for SMS usage. In this example procedure:

The new field rum_name is added to show the value of the BRM PIN_FLD_RUM_NAME field. RUM refers to the ratable usage metric in BRM.
The existing field destination_network is removed.

To customize the events template with the stated changes:

Create a CustomserviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml template file in the myproject/web/custom/eventtemplates folder by copying the default serviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml available in the SDK_home/references/eventtemplates folder.

Add new <columnHeader> and <column> elements to CustomserviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml.

Add the <columnHeader> in the <column> in the appropriate location. For example, if you add the <columnHeader> as the fifth element, make sure you add the <column> as the fifth column element.

<columnHeader name="rum_name">
        <label>Rum Name</label>
        <width>10%</width>
        <visible>true</visible>
        <sortable>false</sortable>
        <tooltip>Rum Name of the event</tooltip>
        <resizable>true</resizable>
        <alignment>center</alignment>
    </columnHeader>
……..
<column  name="rum_name">
            <type>text</type>
            <fields>rumName</fields>
        </column>

Remove the existing destination_network column from the template by removing the <columnHeader> and <column> elements named destination_network as shown:

<columnHeader name="destination_network">
        <label>DESTINATION_NETWORK</label>
        <width>10%</width>
        <visible>true</visible>
        <sortable>true</sortable>
        <tooltip>DESTINATION_NETWORK_HINT</tooltip>
        <resizable>true</resizable>
        <alignment>left</alignment>
    </columnHeader>
……..
   <column  name="destination_network">
            <type>text</type>
            <styles>template-subtle-text</styles>
            <fields>telcoInfo.destinationNetwork</fields>
            <types>string</types>
        </column>

Save your template file.
Add your customization files to your NetBeans IDE project folder (myproject), by adding the custom template file in the myproject/web/WEB-INF/classes/custom/eventtemplates folder.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your custom templates to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Example 2: Event Template Customization with New Fields

This example shows how to customize the REST code to support a new field. In this example procedure:

A custom template is created with new <columnHeader> and <column> elements to display a new column called adjustments.
The destination_network column is removed from the template.
Required custom Java classes are coded to retrieve the new data for display in Billing Care

To add and delete fields in the event template and customize the REST code to support the new field:

Create a CustomserviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml template file in the myproject/web/custom/eventtemplates folder by copying the default serviceTelcoGsmSms_eventDelayedSessionTelcoGsm.xml available in the SDK_home/references/eventtemplates folder.

Add a new <columnHeader> and <column> for Event Adjustments to the XML file.

Make sure you add the <columnHeader> and <column> in the appropriate location. For example if you have added the <columnHeader> as the fifth element, make sure you add the <column> as the fifth column element.

<columnHeader name="adjustments">
        <label>Event Adjustments</label>
        <width>10%</width>
        <visible>true</visible>
        <sortable>false</sortable>
        <tooltip>Event Adjustments</tooltip>
        <resizable>true</resizable>
        <alignment>left</alignment>
    </columnHeader>
……..
 
<column  name="adjustments">
            <type>currency</type>
            <format>{0}</format>
             <fields>accountObj</fields>
            <fields>id</fields>
        </column>

Remove the existing destination_network column from the template by removing the <columnHeader> and <column> elements named destination_network as shown:

<columnHeader name="destination_network">
        <label>DESTINATION_NETWORK</label>
        <width>10%</width>
        <visible>true</visible>
        <sortable>true</sortable>
        <tooltip>DESTINATION_NETWORK_HINT</tooltip>
        <resizable>true</resizable>
        <alignment>left</alignment>
    </columnHeader>
……..
   <column  name="destination_network">
            <type>text</type>
            <styles>template-subtle-text</styles>
            <fields>telcoInfo.destinationNetwork</fields>
            <types>string</types>
        </column>

Save your template file.

To add custom logic to retrieve the data needed for the adjustments column, create a custom TemplateMyCustomEventWorker class.

In this example, a new BRM opcode AR_RESOURCE_AGGREGATION is called to retrieve the adjustment made for an event, which overrides the processFieldForColumnName() method of the default TemplateEventWorker class. If the column name is adjustments, then the opcode AR_RESOURCE_AGGREGATION is called:

public class TemplateMyCustomEventWorker extends TemplateEventWorker{
 
 @Override
protected void processFieldForColumnName(ColumnarRecord.Entries.Cells viCol, String storableClassType, FList flist, ColumnarRecord.Entries row, String field, Object value) throws Exception {
if ("adjustments".equalsIgnoreCase(viCol.getName())) {
             if (field.equals("id")) {
             Poid acctPoid =flist.get(FldAccountObj.getInst());
             Poid eventPoid =flist.get(FldPoid.getInst());
             FList inputFlist = new FList();
             inputFlist.set(FldPoid.getInst(),acctPoid);
             inputFlist.set(FldPoid.getInst(),acctPoid);
             FList eventInfo = new FList();
             eventInfo.set(FldPoid.getInst(),eventPoid);
             inputFlist.setElement(FldEvents.getInst(), 0, eventInfo);
             FList outFlist = opcode(PortalOp.AR_RESOURCE_AGGREGATION, inputFlist);
             BigDecimal adjustAmount = getAdjustmenAmount(outFlist);
                viCol.getArgs().add(adjustAmount.toString());
             }
         }else {
             super.processFieldForColumnName(viCol, storableClassType, flist, row, field, value);
         }
    }
        private BigDecimal getAdjustmenAmount(FList flist) throws EBufException {
        BigDecimal amountAdjustValue = new BigDecimal(0);
        if (flist.hasField(FldResults.getInst())) {
            SparseArray resultsArray = flist.get(FldResults.getInst());
            Enumeration results = resultsArray.elements();
            while (results.hasMoreElements()) {
                FList balFlist = (FList) results.nextElement();
                if (balFlist.hasField(FldAdjusted.getInst()) && balFlist.hasField(FldResourceId.getInst())) {
                    Integer resourceId = balFlist.get(FldResourceId.getInst());
                    if (BEIDManager.isCurrency(resourceId) ) {
                        amountAdjustValue = balFlist.get(FldAdjusted.getInst());
                        break;
                    }
                }
            }
        }
        return amountAdjustValue;
    }
}

Create a custom CustomTemplateFactory class and override its getTemplate() method to return the TemplateMyCustomEventWorker class (instead of the default TemplateEventWorker.java class):

public class CustomTemplateFactory extends TemplateFactory {
 
    @Override
    public TemplateBaseWorker getTemplateWorker(String templateType){
         if(BillingCareConstants.EVENT.equalsIgnoreCase(templateType)){
             return new TemplateMyCustomEventWorker();
         }else {
             return super.getTemplateWorker(templateType);
         }
    }
}

Create a custom template module class by extending the PCMTemplateModule class to override the getTemplate() method to return the new CustomTemplateFactory:

 public class CustomPCMTemplateModule extends PCMTemplateModule {
      @Override
    protected TemplateFactory getTemplateFactoryInstance(){
       return  new CustomTemplateFactory();
       }
}

In the NetBeans IDE, create a new Java project with all the mentioned Java files and XML files in the appropriate folders and include the jars required to compile and build the project.
Add your customization files to your NetBeans IDE project folder (myproject):
- Add an entry in the customModule.properties in the myproject/web/WEB-INF/classes/custom folder to override the default template module as follows:
  
  billingcare.rest.template.module=com.company.modules.CustomPCMTemplateModule
  
  where company is the company name used in your myproject/src directory.
- Add the custom template file in the myproject/web/WEB-INF/classes/custom/eventtemplates folder.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your custom templates to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Example 3: Newsfeed Template Customization

The following procedure shows how to customize the Newsfeed template by providing an example of adding a new column named billStatus. In this example procedure:

A custom template is created with new <columnHeader> and <column> elements to display a new column called billStatus.
Required custom Java classes are coded to retrieve the new data for display in Billing Care

To add a field in the Newsfeed template and customize the REST code to support the new field:

Create a Customnewsfeed.xml template file in the myproject/web/custom/newsfeedtemplates folder by copying the default newsfeed.xml available in the SDK_home/reference/newsfeedtemplates folder.

Add a new <columnHeader> and <column> in the XML file Customnewsfeed.xml.

In this example, the field object is added as a BRM field to retrieve the billStatus of a /bill object.

    <columnHeader name="billStatus">
        <label>Bill Status</label>
        <width>10%</width>
        <visible>true</visible>
        <sortable>false</sortable>
        <tooltip>Status of the Bill</tooltip>
        <resizable>true</resizable>
        <alignment>left</alignment>
    </columnHeader>
……..
<column  name="billStatus">
            <type>text</type>
            <fields>object</fields>
        </column>

Save your template file.

Create a custom TemplateMyCustomNewsfeedWorker class to add custom logic to retrieve the data needed for the billStatus column.

In this example, a new BRM opcode PCM_OP_READ_READS opcode is used to retrieve the status of a bill object, then overrides the processFieldForColumnName() method of the TemplateNewsfeedWorker class. This method checks if the column name is billStatus. If so, then the method gets the FLD_DUE amount by calling the opcode PCM_OP_READ_READS.

public class TemplateMyCustomNewsfeedWorker extends TemplateNewsFeedWorker {
    @Override
    protected void processFieldForColumnName(ColumnarRecord.Entries.Cells viCol, String storableClassType, FList flist, ColumnarRecord.Entries row, String field, Object value) throws Exception {
                    if ("billStatus".equalsIgnoreCase(viCol.getName())) {
                    if (flist.hasField(FldObject.getInst())) {
                      String billType = null;
                      billType = flist.get(FldObject.getInst()).getType();
                      if (billType != null && billType.equalsIgnoreCase("/bill")) {
                        FList billDueinputFList = new FList();
                        billDueinputFList.set(FldPoid.getInst(), flist.get(FldObject.getInst()));
                        billDueinputFList.set(FldDue.getInst());
                        FList billDueOutputFList = opcode(PortalOp.READ_FLDS, billDueinputFList);
                          BigDecimal billDue = billDueOutputFList.get(FldDue.getInst());
                        if (!billDue.equals( BigDecimal.ZERO)) {
                          viCol.getArgs().add("Pending");
                          return;
                        } else {
                          viCol.getArgs().add("Paid");
                          return;
                        }
                      }
                    }else {
                          viCol.getArgs().add("");
                      }
         }else {
             super.processFieldForColumnName(viCol, storableClassType, flist, row, field, value);
         }
    }
}

Create a custom CustomTemplateFactory Java class and override the getTemplate() method to return the TemplateMyCustomNewsfeedWorker Java class (instead of the default TemplateNewsfeedWorker Java class).

public class CustomTemplateFactory extends TemplateFactory {
 
    @Override
    public TemplateBaseWorker getTemplateWorker(String templateType){
         if(BillingCareConstants.NEWSFEED.equalsIgnoreCase(templateType)){
             return new TemplateMyCustomNewsfeedWorker();
         } else {
             return super.getTemplateWorker(templateType);
         }
   }
}

Create a custom template module class by extending the PCMTemplateModule Java class and overriding its getTemplate() method:

public class CustomPCMTemplateModule extends PCMTemplateModule {
     
    @Override
    protected TemplateFactory getTemplateFactoryInstance(){
       return new CustomTemplateFactory();
   }
}

In the NetBeans IDE, create a new Java project with all the mentioned Java files and XML files in the appropriate folders and include the jars required to compile and build the project.
Add your customization files to your NetBeans IDE project folder (myproject):
- Add the customModule.properties in the myproject/web/WEB-INF/classes/custom folder.
- Add the custom template file in the myproject/web/WEB-INF/classes/custom/eventtemplates folder.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your custom templates to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.