30 Embedding Billing Care Screens in External Applications
Learn how to use the SDK to embed Oracle Communications Billing Care screens in external applications such as customer relationship management (CRM) applications or online account management interfaces.
Topics in this document:
About Embeddable Billing Care Screens
Billing Care supports embedding screens into CRM applications and online account management interfaces using inline frames (iframe) or pop-up windows. Embedding screens gives external applications direct access to Billing Care functionality without requiring complex integration.
Subscriber information stored in your Oracle Communications Billing and Revenue Management (BRM) system, and Billing Care account management screens, can be displayed in external applications without creating custom interfaces for retrieving such data or performing account management actions.
Use this functionality to expose Billing Care screens in your application's business workflow. For example, configure your CRM application to display the Billing Care payments interface when adding a new payment type for a subscriber.
The following Billing Care screens can be exposed and embedded in external applications:
-
Account Adjustment
-
Account Profile
-
Account Status
-
Account Transactions Graph
-
Account Transactions Table
-
Billing Information
-
Financial Setup (including Payment Methods)
-
Make a Payment
-
Payments Summary
-
Purchased Products
-
Write Off Account
-
Purchase Package/Purchase Deal
See the relevant chapter in Billing Care Online Help for more information on each screen and what account actions can be performed.
Embedding Billing Care Screens
Embedding Billing Care screens in external applications requires the following:
You can embed Billing Care screens in test installations not using Oracle Identity and Access Management (IAM) when developing your external application integration. User authentication and resource authorization are not required with test installations. Billing Care displays the requested screen without requiring credentials. See "About Test Installations" and "Configuring WebLogic Server for a Test Installation" in Billing Care Installation Guide for more information on test installations.
Production Billing Care installations require IAM. An external application and its users must be authenticated and authorized by Billing Care before embedded screens can be displayed. See "Configuring Security for External Application Access" for information on embedding Billing Care screens in external applications in production installations.
Understanding the index_embedded.html File
External applications call the index_embedded.html file when retrieving a Billing Care screen for display. By default, Billing Care exposes this file without additional configuration on the application server.
This file contains the information required by Billing Care to render the requested screen properly for the queried account. External applications send Billing Care an index_embedded.html URL request containing a unique query string for the required screen, and the account or bill numbers for the subscriber using the following format:
https://host:port/bc/index_embedded.html#query_string
where:
-
host is the Billing Care application host.
-
port is the port on which Billing Care is listening on.
-
query_string is the string containing the desired embeddable screen and account and bill details. You can use either account ID or account number, and bill ID or bill number in the request.
If you are using account ID and bill ID in the request, the query_string format is:
Screen?accountId=BRM_db#+-account+AccountID&billId=BRM_db+-bill+BillID
where:
-
Screen is the requested screen for the queried account.
-
BRM_db# is the BRM database number containing the queried account or bill.
-
AccountID is the unique BRM subscriber account ID to query.
-
BillID is the bill ID to query when requesting bill-related screens.
For example, to request the Billing Information overlay for the BRM bill number 0.0.0.1-1115086, owned by the BRM account number 0.0.0.1-1117902, use the following URL request:
https://example.com:7001/bc/index_embedded.html#overlay/billDetails?accountId=0.0.0.1+-account+1117902&billId=0.0.0.1+-bill+1115086
If you are using account number and bill number in the request, the query_string format is:
Screen?accountId=AccountNumber&billId=BillNumber
For example, to request the Billing Information overlay for the BRM bill number B1-8839, owned by the BRM account number 123456, use the following URL request:
https://example.com:7001/bc/index_embedded.html#overlay/billDetails?accountId=123456&billId=B1-8839
Note:
Embedded screens do not include the Billing Care application banner, search functionality, or Actions menu.
Table 30-1 lists the URL request strings used to call each embeddable Billing Care screen.
Table 30-1 Sample URL Request Query Strings for Embeddable Billing Care Screens
| Screen | Sample URL Query String Used by External Application |
|---|---|
|
Account Adjustment |
|
|
Account Profile |
|
|
Account Status |
|
|
Account Transactions Table |
|
|
Account Transactions Graph |
|
|
Billing Information |
If only the account ID is passed then the Bill in progress bill is shown. If any specific bill must shown, the bill id must be passed. |
|
Financial Setup |
|
|
Make a Payment |
|
|
Payments Summary |
|
|
Purchased Products |
|
|
Write Off Account |
|
|
Purchase Package/Purchase Deal |
|
Configuring Your External Application to Access Billing Care
Configure external applications to request an embeddable Billing Care screen by creating a link on the application's screen, from where users initiate the request. For example, create a clickable text, image, or button on your application's screen with an html href attribute containing the embeddable screen overlay listed in Table 30-1.
Example 30-1 contains sample html code for a text link which opens the Account Status screen in a new window.
Example 30-1 Sample Account Status Screen Link Code
<a href ="http://example.com:7001/bc/index_embedded.html#overlay/accountStatusChange?accountId=0.0.0.1+-account+1117902" onclick="openWindow(this.href);
return false;">Click to open Account status Dialog</a>Configuring Security for External Application Access
Production Billing Care installations use Oracle Identity and Access Management (IAM) to authenticate users using single sign-on (SSO) and authorize access to Billing Care screens and resources. You must configure the required authentication and authorization policies in IAM before embedding Billing Care screens in external applications in production environments. Doing so enables embedded screens to be displayed without requiring Billing Care user credentials and ensures that a failed permissions error message is not displayed on the embedded screen.
Note:
With configured IAM, Billing Care returns an error message if the user or external application does not have the correct permissions to access or view the requested embedded screen. For example, if the external user or application has not been configured with access to the Billing Care payments resource, the following error message error message is displayed:
You do not have permission to make payments
Billing Care enforces a single security configuration of user access and resource permissions for both the native Billing Care application and any embedded screens exposed within external applications.
See "Billing Care Preinstallation Tasks" in Billing Care Installation Guide for more information on installing the required IAM components for a secure Billing Care installation, and "Implementing Billing Care Security" in BRM Security Guide for more information on how to configure authentication and authorization for external users and applications.