Extending and Creating Billing Care REST Resources

45 Extending and Creating Billing Care REST Resources

Learn how to extend the Oracle Communications Billing Care REST framework and create new REST resources for use with Billing Care.

Topics in this document:

About Extending and Creating Billing Care REST Resources

Billing Care supports extending the REST framework and creating new REST resources as required by your business needs. The following customizations are supported:

Manipulating Workflow

For example, customizing Billing Care to invoke different Oracle Communications Billing and Revenue Management (BRM) opcodes, either for data retrieval or persistence. A typical scenario is a customer who has created a custom opcode similar to one provided by Oracle but with alternate business logic that cannot not otherwise be provided through the associated policy opcode. An alternate scenario might involve invocation of an API from an application other than BRM.
Payload Manipulation

For example, manipulating or inspecting the payload before invocation of an opcode. An example scenario involves a web service that returns an error condition after validating the payload, before invoking the opcode. Another scenario might involve custom logic applied to the data before submission of a payload to BRM.
Filtering Custom HTTP Headers

For example, adding a filter that intercepts HTTP requests and makes decisions based on the custom HTTP header value. An example scenario involves a filter that checks whether an order ID passed in the HTTP header is a duplicate and, if so, rejects the request.
Creating New REST Resources

For example, a new REST resource used by a customized module to retrieve additional data for display.

About Billing Care Sample SDK REST Customizations

The Billing Care SDK contains the following example REST customizations located in the SDK_home/samples/REST_Scenarios/src/java/com/rest/sdk, where SDK_home is the directory where you installed the SDK:

To call a new opcode in a customized module, refer to CustomNewOpCodeBillUnitModule.java and CustomBillUnitWorker.java.
To modify data sent to BRM, refer to CustomPaymentModule.java.
To alter the application logic or support subclassing ready to use module classes, refer to CustomExtendAdjustmentModule.java.

For more information on invoking BRM opcodes through the Java API, see "About the PCM API" in BRM Developer's Guide and Billing Care Java API Reference.

Extending REST Services to Filter Custom Headers

You can extend the Billing Care REST framework to process custom headers sent in HTTP requests and responses and then perform additional functionality such as order tracking. You do this by adding filters to the Billing Care SDK that do the following:

Intercept HTTP requests before they are sent to the resource, and then make decisions based on the header value. For example, a filter could check whether the request is a duplicate and, if so, reject the request.
Intercept HTTP responses before they are sent to the client, and then make decisions based on the header value. For example, a filter could construct tracking objects and persist them in the BRM database.

To customize the Billing Care REST framework to support custom headers, perform these tasks:

Note:

The samples that are referenced in this document use predefined Order ID patterns to simulate duplicate request identification and depend on BRM base opcodes for simple order management.

Creating a Custom Storable Class in the BRM Data Dictionary

If you want to persist the custom header data in the BRM database, create a custom storable class.

To create a custom storable class:

In the Oracle DM configuration file (BRM_home/sys/dm_oracle/pin.conf), do this:
- Set the dd_write_enable_objects entry to 1. This allows you to create, edit, and delete custom storable classes in the data dictionary.
- Set the sm_oracle_ddl entry to 1. This configures the Oracle DM to run Data Definition Languages (DDLs) when updating object types in data dictionary tables.
```
- dm dd_write_enable_objects 1
- dm sm_oracle_ddl 1
```
Create a PODL storable class definition file for your custom storable class. For example, create a file named order_tracker.podl.

You can refer to the sample PODL file (SDK_home/samples/FiltersAndCustomHeaders/order_tracker.podl) when creating your storable class definition. In the sample PODL file, ensure that you replace all instances of __TABLESPACE__ with the name of the tablespace in which to store the header data.
Run pin_deploy in verify mode to see the changes that will be caused by importing new storable class definitions and to verify that there are no conflicts.
```
pin_deploy verify fileName
```
where fileName is the file name of the storable class definition, such as order_tracker.podl.
Import the definition for your custom storable class into the BRM data dictionary:
```
pin_deploy create fileName
```

See "pin_deploy" and "Creating Custom Fields and Storable Classes" in BRM Developer's Guide for more information about using the utility.

Processing Billing Care REST API Requests and Responses

Create a filter and wrapper object for retrieving and processing your custom headers.

Create a custom filter object that reads the request headers, resource paths, and attributes as well as the response status codes. Add functionality for making decisions based on the header value.

You can refer to the sample filter object (SDK_home/samples/FiltersAndCustomHeaders/src/java/com/oracle/communications/brm/cc/util/CustomHeaderSampleFilter.java) when creating your filter object.
Create a wrapper object that intercepts Billing Care REST API responses before they are submitted to the client.

You can refer to the sample wrapper Java class (SDK_home/samples/FiltersAndCustomHeaders/src/java/com/oracle/communications/brm/cc/util/MultiReadResponseWrapper.java) when creating your wrapper Java class.

Configuring WebLogic Server to Use an Exploded Archive

To configure WebLogic server to use an exploded archive:

Create a manifest file by following the instructions in "Creating a Manifest for your Shared Library".

You can use the SDK_home/samples/FiltersAndCustomHeaders/src/conf/MANIFEST.MF file as a sample.

Create a deployment plan by following the instructions in "Creating a New Deployment Plan for Billing Care with your Shared Library".

The following shows a sample deployment plan:

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd"
                 global-variables="false">
    <application-name>BillingCareREST.war</application-name>
    <variable-definition>
        <variable>
            <name>SDKLibraryName</name>
            <value>BillingCareCustomizations</value>
        </variable>
        <variable>
            <name>CUSTOM_HEADER_FILTER_NAME</name>
            <value>CustomHeaderSampleFilter</value>
        </variable>
        <variable>
            <name>CUSTOM_HEADER_FILTER_CLASS_NAME</name>
            <value>com.oracle.communications.brm.cc.util.CustomHeaderSampleFilter</value>
        </variable>
        <variable>
            <name>CUSTOM_HEADER_FILTER_URL_PATTERN</name>
            <value>/webresources/v1.0/*</value>
        </variable>
    </variable-definition>
    <module-override>
        <module-name>BillingCareREST.war</module-name>
        <module-type>war</module-type>
        <module-descriptor external="true">
            <root-element>weblogic-web-app</root-element>
            <uri>WEB-INF/weblogic.xml</uri>
            <variable-assignment>
                <name>SDKLibraryName</name>
                <xpath>/weblogic-web-app/library-ref/library-name</xpath>
                <operation>add</operation>
            </variable-assignment>
        </module-descriptor>
        <module-descriptor external="true">
            <root-element>web-app</root-element>
            <uri>WEB-INF/web.xml</uri>
            <variable-assignment>
                <name>CUSTOM_HEADER_FILTER_NAME</name>
                <xpath>/web-app/filter/filter-name</xpath>
                <operation>add</operation>
            </variable-assignment>
            <variable-assignment>
                <name>CUSTOM_HEADER_FILTER_CLASS_NAME</name>
                <xpath>/web-app/filter/[filter-name="CustomHeaderSampleFilter"]/filter-class</xpath>
                <operation>add</operation>
            </variable-assignment>
            <variable-assignment>
                <name>CUSTOM_HEADER_FILTER_NAME</name>
                <xpath>/web-app/filter-mapping/filter-name</xpath>
                <operation>add</operation>
            </variable-assignment>
            <variable-assignment>
                <name>CUSTOM_HEADER_FILTER_URL_PATTERN</name>
                <xpath>/web-app/filter-mapping/[filter-name="CustomHeaderSampleFilter"]/url-pattern</xpath>
                <operation>add</operation>
            </variable-assignment>
        </module-descriptor>
    </module-override>
</deployment-plan>

Deploy the exploded archive shared library to your Billing Care domain by following the instructions in "Deploying your Shared Library on your Billing Care Domain".
Redeploy Billing Care using the deployment plan you created in step 2. To do so, follow the instructions in "Redeploying Billing Care to Use Your Shared Library".

Sending a Test HTTP Request with the Custom Header

Verify that your filter processes the custom header correctly by sending a test HTTP request to the Billing Care REST API. For more information, see REST API Reference for Billing Care.

For example, you could submit this POST request to the /accounts resource using cURL:

curl -X POST \  
'https://hostname:port/bcws/webresources/v1.0/accounts' \  
-H 'content-type: application/json' \ 
-H 'Accept: application/json' \ 
-H 'customHeader: value' \  
-d '{"locale":"en_US","customerTypeCode":"","organizationHierarchyTypeCode":"-1","securityCode1":"","securityCode2":"","contacts":[{"firstName":"a","lastName":"a","middleName":"a","salutation":"","address":"a","city":"a","company":"a","emailAddress":"","state":"a","zip":"a","deleted":false,"newlyCreated":true,"elem":1,"contactType":"Primary","country":"IN","phonenumbers":[]}],"billUnits":[{"name":"Bill
      Unit(1)","billingFrequencyInMonths":1,"accountingType":2,"accountingCycleDom":1,"currency":"840","balanceGroups":[],"paymentType":"10001","walletPaymentInstrumentIndex":0}],"paymentMethod":[{"invoice":{"details":{"invoiceId":"inv-a-4","deliveryPrefer":"1","emailAddr":"","name":"a
      a","address":"a","city":"a","state":"a","zip":"a","country":"IN"}},"paymentType":"10001"}]}'

where:

hostname:port is the host and port number on which the Billing Care REST API instance is deployed and running.
customHeader is the name of your custom header.
value is a sample value to send with the custom header.

Extending REST Services

To extend REST services:

Create the Java classes and necessary resources (views, view models, CSS, validations) in the appropriate myproject/src/package directory for your implementation (for example, myproject/src/com/company/billingcare where company is the name of your company).

You can implement new functionality, override existing functionality, or add functionality by extending the Billing Care classes (from the JAR files added to CLASSPATH).

Note:

Any REST resources you create for Billing Care must be placed within the com.oracle.communications.brm.cc.ws package (myproject/src/com/oracle/communications/brm/cc/ws). This ensures that your REST resource can be deployed within the customizations shared library.
Compile the new Java classes.
Create a customModule.properties file in your myproject/web/WEB-INF/classes/custom/ directory, where myproject is your NetBeans IDE project containing your Billing Care customizations. This file will contain a reference to the location of the custom Java classes you create. See "About the customModule.properties File" for more information about specifying module overrides with customModule.properties.
Copy the default registry.js file from SDK_home/BillingCare_SDK/references to a custom registry file named customRegistry.js in your myproject/web/custom directory, where myproject is your NetBeans IDE project containing your Billing Care customizations. This file contains the module definitions for your custom view models (JavaScript). See "About the Registry File" for more information on using a custom registry file.
Add your customization files to your NetBeans IDE project (myproject):
- Add any JavaScript to support your custom view models in the myproject/web/js directory.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your customizations to your Billing Care domain.

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