1. Billing Care SDK Guide
  2. Basic Billing Care SDK Components
  3. Customizing Billing Care

4 Customizing Billing Care

Learn customization concepts for Oracle Communications Billing Care.

Topics in this document:

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.

You configure module definitions 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. The web browser renders a view as a module's user interface (UI). 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 your page's controls (buttons, menus, fields), which are defined by your HTML view.

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 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 the server and UI updates are reflected in each other.

About the customModule.properties File

Configure Billing Care to override the default module logic with your customizations by creating a customModule.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 customModule.properties:

  • account

  • adjustment

  • allocation

  • billing

  • billunit

  • collection

  • dispute

  • item

  • notes

  • oauthtoken

  • payment

  • paymentmethod

  • requestinfo

  • search

  • service

  • status

  • subscription

  • template

  • writeoff

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

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

where:

  • 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 customModule.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 customModule.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 including hard-coded paths for dependencies in the Billing Care files. The registry file provides a default configuration, which the SDK can override.

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 overridden in the customRegistry.js file.

Note:

The key names in the registry.js file are subject to change. Refer to the latest packaged registry.js file to view the registry key changes and then update your custom code.

Managing Billing Care Modules Using the Registry File

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

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

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

You create a customRegistry.js file when:

  • Replacing the view, view model, or validation logic for a 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 a 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 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 model references retrieved through the registry are loaded using RequireJS, they must conform to the asynchronous module definition (AMD) format.

Note:

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

Common functionality 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 your module behaves like 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 critical to most modules in Billing Care and will be equally crucial to any custom modules developed with the SDK. A view model representing the open account can be accessed using the following JavaScript code:

globalAppContext.currentAccountViewModel

About AJAX Calls

To improve security, the Billing Care SDK requires all AJAX requests to include cross-site request forgery (CSRF) tokens.

You must add CSRF tokens to all your custom AJAX requests sent to the Billing Care SDK. The Billing Care SDK will not authorize your custom AJAX requests without the token.

The following shows sample code for adding a CSRF token to an AJAX request:

$.ajax({
   type: "GET",
   dataType: "json",
   url: urlToFetch,
   beforeSend: function (xhr) {
      util.setRequestHeader(xhr)
   },
   contentType: "application/json; charset=utf-8"

}).done(function (data) {

}).fail(function (errorThrown) {

}).always(function () {

});

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 4-1 displays a POID and its equivalent reference ID.

Table 4-1 Example POID and Reference ID

POID Reference ID

0.0.0.1 /service/email12345

0.0.0.1+-service-email+12345

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 and from its own REST format. Sample syntax for 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 an 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.

    Note:

    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 results from 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 the error code and error message as mandatory arguments and optional parameters like the response status, a Boolean value to indicate validation error, an flist containing error parameters, and a list of error parameters in the order mentioned.

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

About Custom Resource Authorization

Your customizations may require authorization configuration in Oracle Platform Security Services (OPSS). See "Billing Care Security" 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 OPSS 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):

    <keyvals>
   <key>authorizationResourceTypes</key>
   <value>MyCustomRESTResourceType, MyCustomViewResourceType</value>
   <desc>Add comma separated OPSS Resource Types(values) for authorization. Define these resource types in OPSS. Please note that the key should not be changed here.</desc>
</keyvals>

  3. Use the Billing Care JavaScript utility functions listed in Table 4-2 when performing authorization on UI resources.

    Table 4-2 Billing Care JavaScript Utility Functions

    Resource Description

    util.getAllResourceGrants()

    Gets all resource grants for UI authorization.

    util.getGrantedActionsByResource(resourceName)

    Gets granted actions for the given resourceName.

    For example:

    util.getGrantedActionsByResource('PaymentResource);

    util.isGrantedResourceAction(action, resourceName)

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

    For example:

    util.isGrantedResourceAction('Make';'PaymentResource')

Performing Authorization on the REST Framework

To perform authorization on the REST framework:

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

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

    UIRequestValue parameters are optional and used for handling obligations.

Note:

EnforcementUitl.checkAccess() returns an ‘ErrorInfo' object with status 401 Unauthorized when no grant exists 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,
ERROR_MIN_AMOUNT_LIMIT);
//If entered amount(UI value) is greater than OPSS 'max currency adjustment limit' then throw error
UIRequestValue maxCurrencyLimit = new UIRequestValue("Maximum Currency Adjustment Amount",
adjustment.getAmount(), ConstraintOperator.GREATER_THAN,
ERROR_MAX_AMOUNT_LIMIT);