7 Customizing Billing Care

This chapter provides an overview of Oracle Communications Billing Care customization concepts.

About Billing Care Customization Concepts

You customize Billing Care by modifying or creating configuration files, Java classes, JavaScript, html, and CSS. Customizations are performed in NetBeans IDE, packaged into a customizations shared library using the Java jar utility, and deployed to the Billing Care domain as a referenced shared library.

To customize Billing Care, you perform the following tasks:

About Billing Care Modules

Billing Care is composed of unique functional modules. Each module includes an html view and a JavaScript view model. Some modules may also contain a validation definition specifying a module's field validation rules.

Module definitions are configured in the registry file where a module's view, view model, and validation rules are defined. When you customize a Billing Care module, you create a custom registry file (customRegistry.js) defining your module configuration. See "About the Registry File" for more information.

About Views

A view is the visible, interactive manifestation of the view model, written in html. A view is rendered by the web browser as the user interface (UI) for a module. It displays information from the view model, triggers operations on the view model, and updates itself when the data in the view model is changed.

About View Models

A view model is a JavaScript representation of the data and operations for your module. A view model is independent of the controls (buttons, menus, fields) on your page defined by your view html.

You can reuse a view model with multiple views because of this independence. For example, UI interfaces for your customer service representatives (CSRs) and self-care subscribers that expose similar functionality can use the same view model while using unique views to provide different functions to each user depending on your business requirements.

When you create a custom view model, you create the view model's JavaScript file to support any custom functionality you add to Billing Care. The JavaScript file is referenced in your customRegistry.js and packaged and deployed in your Billing Care domain as part of the customizations shared library.

About Data Binding between Views and View Models

Data is synchronized between views and view models within a module through use of the Knockout open source library. Data attributes in the view model are exposed as Knockout Observables. The various html elements in the view bind themselves to these Observables so that updates in both the server and UI are reflected in the other.

About the customModules.properties File

Configure Billing Care to override the default module logic with your customizations by creating a customModules.properties file in the myproject/web/WEB-INF/classes/custom folder, where myproject is your NetBeans IDE project folder containing your Billing Care customizations.

You can override the default Billing Care logic in the following modules by specifying a customized alternative for each of the following module keys in customModules.properties:

  • account

  • billing

  • subscription

  • search

  • payment

  • allocation

  • paymentmethod

  • adjustment

  • status

  • writeoff

  • billunit

  • service

  • item

  • notes

  • dispute

  • collection

  • template

Each override you configure must contain an entry of the following format:

billingcare.rest.modulekey.module = com.company.module.custom


  • modulekey is the module for which you are overriding default logic.

  • company is the name of the folder in your NetBeans IDE project myproject/src directory structure where you place the source code for your overriding Java classes.

  • custom is the subdirectory folder name in your NetBeans IDE project myproject/src directory.

For example, if a company named samplecompany is overriding the default account module with a custom account module named CustomAccountModule, use the following entry in customModules.properties:

billingcare.rest.account.module = com.samplecompany.module.CustomAccountModule

This example assumes your custom module Java code is stored in the myproject/src/com/samplecompany/modules directory.

See "Customizing Billing Care Templates" and "Extending and Creating Billing Care REST Resources" for examples of when using a customModules.properties file are required.

About the Configuration.xml File

The Configurations.xml file contains flags controlling the display of specific account attributes, timeout values, and BRM-related ENUM mappings. See "Editing the Billing Care Configuration File" for more information.

About the Registry File

The registry file (Registry.js) dynamically loads dependencies, which avoids the inclusion of hard coded paths for dependencies in the Billing Care files. The registry file provides a default configuration, which can be overwritten through the SDK.

To override the key and values of the Registry.js, create a customRegistry.js file with the same given keys, but new values. Include only the entries that need to be over ridden in the customRegistry.js file.

Managing Billing Care Modules Using the Registry File

The registry file is strictly a repository for describing a module. There is no logic within the registry itself for invoking (displaying) the modules.

The following view model example shows the accountBanner module definition in the default registry.js:

accountBanner: {
    view: 'text!templates/home/accountBannerView.html',
    viewmodel: 'viewmodels/home/accountBanner/AccountBannerViewModel'

Create a customRegistry.js file when:

  • Replacing the view, view model, or validation logic used for a particular Billing Care module. For example, your business requires a different adjustment REST operation from the default Billing Care operation, which also changes the fields defined in the UI. You can create your own view model (and optional validation rules) and then create a customRegistry.js to reference your files.

    All elements within Billing Care that provide access to the edited module now automatically use your custom module.

  • Adding custom modules to Billing Care. For example, you develop a new module for a business requirement and add the module to Billing Care.

Because view models references retrieved through the registry are loaded using RequireJS, they must conform to asynchronous module definition (AMD) format.


The Billing Care view models are core elements of the modules that form the body of the application (Home tab, Bills tab, assets, News Feed) and Billing Care overlays (dialog boxes).

Common functionality/behavior across the overlays in Billing Care, including validation, data saving, and navigation between the pages within the overlay has been captured in a reusable overlay view model that you should use when you create a custom overlay. This helps ensure that your module behaves similar to the rest of Billing Care.

About Billing Care View Model JavaScript Framework

This section provides an overview of the Billing Care JavaScript framework used in view models and how to use an account record key across modules.

Access to the Open Account

The current account record is key to most modules in Billing Care, and will be equally important to any custom modules developed with the SDK. A view model representing the open account can be accessed using the following JavaScript code:


Object IDs

Objects in the BRM database contain a unique identifier called a POID. The Billing Care REST framework refers to these identifiers as references or refs. Table 7-1 displays a POID and its equivalent reference ID.

Table 7-1 Example POID and Reference ID

POID Reference ID /service/email12345

There are reference IDs throughout the Billing Care data model. POIDs are used when interacting with BRM opcode input and output parameter lists (FLists), but reference IDs are used in the JavaScript layer.

The POID format is not suitable for a web application, so the REST framework provides two static utility methods (restIdFromPoid and poidFromRestId) for converting a POID to/from its own REST format. Sample syntax on calling the methods is provided below:

String BRMUtility.restIdFromPoid(String poid);
Poid BRMUtility.poidFromRestId(String restId);

About Error Handling in REST Operations

Error handling is a crucial aspect of Billing Care REST customization, and it has multiple benefits, for example:

  • Indicating the exact error to the application user

  • Helping the application developer to debug the issues.

The default Billing Care REST operations return an ErrorInfo object with error code and error message in case of any exception. The error object contains the following components:

  • errorCode - A key used to retrieve a localized error message from the Billing Care resource bundle.


    A custom error code must start from the 70000 series. For example, 70001, 70002, and so on.
  • errorMessage - The raw error message from the Billing Care REST layer.

  • isValidationError - A true value indicates the error is the result of a BRM validation issue (for example, an invalid country is specified).

Invoking Error Handing in Customizations

Invoke method buildErrorInfo() in ExceptionHelper.java to build the ErrorInfo object and return the error object to the caller of the REST services when extending the Billing Care REST framework with custom classes.

The method buildErrorInfo() in ExceptionHelper.java takes error code, error message as mandatory arguments and optional parameters like response status, boolean value to indicate validation error, flist containing error parameters and list of error parameters in the order mentioned.

By default, buildErrorInfo() builds and returns error info object with a boolean value of false for isValidationError attribute and http response status of BAD REQUEST (400).

About Custom Resource Authorization

Your customizations may require authorization configuration in Oracle Entitlements Server (OES). See "Securing WebLogic Resources" in Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server for more information about configuring resource authorizations in OES and Oracle Communications Billing Care Security Guide for information on securing your Billing Care installation.

The following sections provide general guidelines on how to perform authorization for protected resources.

Performing Authorization in the Actions Menu

ActionsMenu.xml contains the tags <permission-key> and <action-key> to authorize menus.

For more information, see "Customizing the Billing Care Actions Menu".

Performing Authorization on the UI

To perform authorization on custom UI resources:

  1. Define new ResourceTypes, Resources, and corresponding actions in the OES Server.

  2. Add the new ResourceType to CustomConfigurations.xml.

    For example, use the following definition when creating two new ResourceTypes that control both your custom REST API (MyCustomRESTResourceType) and your custom views (MyCustomViewResourceType):

    <value>MyCustomRESTResourceType, MyCustomViewResourceType</value>
            <desc>Add comma separated OES Resource Types(values) for authorization.
       Define these resource types in OES.
                 Please note that the key should not be changed here.
  3. Use the Billing Care JavaScript utility functions listed in Table 7-2 when performing authorization on UI resources:

    Table 7-2 Billing Care JavaScript Utility Functions

    Resource Description


    Gets all resource grants for UI authorization.


    Gets granted actions for the given resourceName.

    For example:


    util.isGrantedResourceAction(action, resourceName)

    Checks whether the given action is granted for the given resource.

    For example:


Performing Authorization on the REST Framework

To perform authorization on the REST framework:

  1. Define ResourceTypes,Resources and corresponding actions in OES Server

  2. In the REST resource operation that requires authorization, call EnforcementUitl.checkAccess() by passing required subject,Application Name,Action,Resource Type,Resource,Error and optional UIRequestValue objects as parameters.

    UIRequestValue parameters are optional and used for handling obligations.


EnforcementUitl.checkAccess() returns a &rsquor;ErrorInfo' object with status 401 Unauthorized when there is no grant on the requested resource for the specified action.

Using REST Authorization without Obligations

To use REST authorization without obligations:

Subject subject = Security.getCurrentSubject();
  // create new error object
  EnforcementError error = new EnforcementError(20020,"You are not authorized to save credit profile");
  EnforcementUtil.checkAccess(subject, EnforcementConstants.APPLICATION,"make","CreditProfileResourceType","CreditProfileResource",error);

Using REST Authorization with Obligations

To use REST authorization with obligations:

Subject subject = Security.getCurrentSubject();
  // create new error objects
EnforcementError ERROR_MIN_AMOUNT_LIMIT = new EnforcementError(20014, "The amount fall short of your authorized limit.");
EnforcementError ERROR_MAX_AMOUNT_LIMIT = new EnforcementError(20015, "The amount exceeds your authorized limit.");
UIRequestValue minCurrencyLimit = new UIRequestValue("Minimum Currency Adjustment Amount",
adjustment.getAmount(), ConstraintOperator.LESS_THAN,
//If entered amount(UI value) is greater than OES 'max currency adjustment limit' then throw error
UIRequestValue maxCurrencyLimit = new UIRequestValue("Maximum Currency Adjustment Amount",
adjustment.getAmount(), ConstraintOperator.GREATER_THAN,