D The PSR End User Billing API

The PSR End User Billing (PSREUB) API provides a mechanism for exporting data from the Oracle Communications MetaSolv Solution database to support end-user billing from product service requests (PSRs). This API defines a standard end-user billing interface which enables you to develop applications that act as a mediation layer to third-party billing systems. MetaSolv Solution facilitates integration with third-party billing applications by notifying the billing application when:

Gateway events associated with end user billing are initiated
An existing customer account is modified

Implementing an third-party billing server requires a detailed understanding of the PSREUB API as well the data communication and translation protocols involved in communicating with the billing system. The scope of this documentation is confined to a discussion of how to implement the interfaces required to integrate with the PSREUB API.

Note:

Before the PSREUB API can export any account or order information, a considerable amount of information must be set up correctly in the MetaSolv Solution database.

Essential Terminology

Table D-1 defines the terms that identify the concepts and information that are required to understand the PSREUB API.

Table D-1 MetaSolv Solution Concept Terms and Information

Term	Definition
Billing interface code	A status code housed in the MetaSolv Solution database but maintained by the third-party billing server. This code indicates whether the customer account information has been communicated to the billing system. Actual values used can vary depending on the billing system used.
System-defined gateway event	These are gateway events used by the PSREUB API. These events are pre-defined in MetaSolv Solution. Users can view these events on the MetaSolv Solution Gateway Maintenance window, but cannot modify event attributes.
third-party billing server	An application developed by you or a third party that allows MetaSolv Solution to communicate end user billing data to a third-party billing system.

PSREUBSession Interface

The PSREUBSession interface is defined in the WDIManager interface located in the WDIPSREUB.IDL file.

Figure D-1 shows the PSREUB API interfaces.

Figure D-1 PSREUB API Interfaces

Description of ''Figure D-1 PSREUB API Interfaces''

WDIRoot Interface

Table D-2 lists the operations available in the WDIRoot interface of the WDIPSRBIL.IDL file.

Table D-2 PSREUB API WDIRoot Interface Operations

Operations	Description
connect	Returns a reference object to the WDIManager interface.
disconnect	Terminates the connection.

WDIManager Interface

Table D-3 lists the operations available in the WDIManager interface of the WDIPSRBIL.IDL file.

Table D-3 WDIManager Interface Operations

Operations	Description
startPSREUBSession destroyPSREUBSession	Start/destroy the PSREUBSession.
startSignal destroySignal	Start/destroy the WDISignal interface.
startInSignal destroyInSignal	Start/destroy the WDIInSignal interface.

Operations

Description

startPSREUBSession

destroyPSREUBSession

Start/destroy the PSREUBSession.

startSignal

destroySignal

Start/destroy the WDISignal interface.

startInSignal

destroyInSignal

Start/destroy the WDIInSignal interface.

PSREUBSession Interface Operations

Table D-4 lists the operations and the accompanying notifications available in the PSREUBSession interface of the WDIPSREUB.IDL file.

Table D-4 PSREUBSession Interface Operations

Operation	WDINotiication
exportCustomer	exportCustomerSucceeded operationFailed
exportCustomer_v2	exportCustomerSucceeded_v2 operationFailed
exportOrder	exportOrderSucceeded operationFailed
exportOrder_v2	exportOrderSucceeded_v2 operationFailed
exportCustomerChange	exportCustomerChangeSucceeded operationFailed
exportCustomerChange_v2	exportCustomerChangeSucceeded_v2 operationFailed
setBillingInterfaceCode_v2	setBillingInterfaceCodeSucceeded_v2 operationFailed

Process Flows

This section describes business process flows associated with the PSREUB API. A third-party billing server should be designed to handle these process flows.

Process Flow for Send Bill Cust Gateway Event

The EventServer is running and polling the MetaSolv Solution database for gateway events in Sending status.
A new customer is created.
A new order is placed on that account and the SBC gateway event is initiated. This sets the gateway event status to Sending.
The EventServer picks up the gateway event and processes it. This process includes binding to the WDIRoot interface, connecting to WDIManager interface, and starting a session on the third-party billing server based on the Work Management gateway definition for PSRBilling.
The EventServer calls the eventOccurred operation on the third-party billing server passing in the parameter structure WDIEvent. The WDIEvent structure includes among other fields the document number and the gateway event name. The eventOccured operation must be written as part of the third-party server development.
The signal handler module on the third-party billing server activates the request handler module and updates the gateway event status to In Progress.
The third-party billing server gets the root, connects to the manager, and starts the session for the PSREUB server.
The third-party billing server gets the root, connects to the manager, and starts the session for the PSR server.
The third-party billing server calls the exportCustomer_v2 operation on the PSREUB server, which returns the cust_acct_id based on the documentNumber.
The third-party billing server calls the exportCustomerAccount_v2 operation on the PSR server, which returns all the customer account data as defined in PSRCustomerAccount structure in the WDIPSRTypes_v3.IDL file.
The third-party billing server imports the data into the billing system's database using the facilities provided by or supported by the billing system, such as an API, SQL, or an ODBC interface. To determine what facilities are provided by or supported by your billing system, and for information on how to use those features, see your billing system's documentation.
Depending on the success or failure of step 11, the signal handler module on the third-party billing server activates the request handler module and updates the gateway event status to Completed or Error.
Depending on the success or failure of step 12, the third-party billing server calls the setBillingInterfaceCode_v2 operation on the PSREUB server. The successful call results in the update of the customer account billing interface code from N, meaning New, to A, meaning Accepted. This code should be left as is in the case of a failure.
The third-party billing server destroys the session and disconnects from the manager for both servers with which it is interfaced.

Process Flow for Send Bill Ord Gateway Event

The EventServer is up and running polling the MetaSolv Solution database for a gateway event status of Sending.
A new order is placed and the SBO gateway event is initiated. This sets the gateway event status to Sending.
The EventServer picks up the gateway event and processes it. This process includes getting the root, connecting to the manager and starting the session of the third-party billing server based on the Work Management gateway definition for PSRBilling.
The EventServer calls the eventOccurred operation on the third-party billing server passing in the WDIEvent parameter structure. This structure includes among other fields the document number and gateway event name. The eventOccured operation must be written as part of the third-party server development.
The signal handler module on the third-party billing server activates the request handler module and updates the gateway event status to In Progress.
The third-party billing server gets the root, connects to the manager and starts the session for the PSREUB server.
Based on the gateway event name of Send Bill Ord, the third-party billing server calls the exportOrder_v2 operation on the PSREUB server. This call returns all the information in the Order structure as defined in the PSREUBTYPES_V2.IDL file.
The third-party billing server sends the billing information to billing system's database.
Depending on the success or failure of step 8, the signal handler module on the third-party billing server activates the request handler module and updates the gateway event status to Completed or Error.
The third-party billing server destroys the session and disconnects from the manager for the PSREUB server.

Process Flow for Customer Change Application Event

The process flow is for an application event, not a gateway event. The application event is initiated by clicking the OK button on the Customer Maintenance window for a customer who was previously sent to billing. The billing interface code for the customer must be A, meaning Accepted, or E for Error. If it is A, PSR will set the code to C, meaning Change, which is what invokes this interface point. If the billing interface code is E, then it has been sent to billing but something was wrong, and the user must change the information setting it back to C, so it will get resent to billing.

If the billing interface code for the customer is N, meaning New, the PSR module does not set the code to C because this would result in an attempt to update a customer that has not yet been sent to the billing system. Therefore, the PSR module only sets the billing interface code from A to C, not from N to C. Any changes made to a customer with a billing interface code of N are sent to the billing system through the Send Bill Cust gateway event.

The Event2Server is up and running polling the MetaSolv Solution database for a billing interface code C, meaning Change.
An existing account is updated on the Customer Maintenance window in MetaSolv Solution. The Customer Change Application Event is initiated only if the customer was previously added to the billing system's database. In other words only if the billing interface code is A, meaning Accepted or E, meaning Error.
When the OK button is clicked on the Customer Maintenance window in MetaSolv Solution, the client updates the billing interface code from A or E to C.
The Event2Server picks up the application event and processes it. This processing includes getting the root, connecting to the manager, and starting the session of the third-party billing server. Since this is not a gateway event, determination of the server is not based on the Work Management gateway definition for PSRBilling, it assumes the PSRBilling gateway definition.
The Event2Server calls the eventOccurred operation on the third-party billing server, passing in the WDIEvent parameter structure. The eventOccured operation must be written as part of the third-party billing server development.
The third-party billing server gets the root, connects to the manager, and starts the session for the PSREUB server.
The third-party billing server gets the root, connects to the manager, and starts the session for the PSR server.
The third-party billing server calls the exportCustomerChange_v2 operation on the PSREUB server. This call returns the customer account ID based on the given document number.
The third-party billing server calls the exportCustomerAccount_v2 operation on the PSR server, which returns the PSRCustomerAccount structure's information as defined in the WDIPSRTYPES_V3.IDL file.
The third-party billing server sends the information to the billing system's database.
Based on the success or failure of step 10, the third-party billing server calls the setBillingInterfaceCd operation on the PSREUB server, which updates the customer account billing interface code from C to A if successful. In the case of a failure the billing interface code should not be changed.
If there is anything wrong then the billing interface code should be updated to E for error.
The third-party billing server destroys the session and disconnects from the manager for both servers with which it is connected.

Viewing PSREUB API Event Errors in MetaSolv Solution

You can view errors for SBC and SBO gateway event on the MetaSolv Solution Work Queue Manager Window - Gateway Events Tab.

Errors for Customer Change Application Events can be viewed on the MetaSolv Solution Billing Discrepancies window. To open this window, select Infrastructure> List> Interfaces> Billing Discrepancies from the MetaSolv Solution main menu. The Billing Discrepancies window displays the error reported by the third-party billing server for that Customer Change Application Event.

See the online Help for more information.

Note:

The PSREUB API does not provide a persistence layer that the third-party billing server can use to update errors reported for Customer Change Application Events.

Solicited Messages

A solicited message is a message initiated by MetaSolv Solution. MetaSolv Solution plays the role of the client, and the third-party application plays the role of the server. The third-party application must use the IDL files provided with the PSR Order Entry API to implement the interfaces and operations shown in the following table:

Additional Process Flow Information

Figure D-2 PSREUB API Processing Flow Diagram

Description of ''Figure D-2 PSREUB API Processing Flow Diagram''

As shown in Figure D-2, account information and order details are entered and tasks for that order are generated in MetaSolv Solution. The PSREUB API passes this information to the third-party billing server at the SBC (Send Bill Cust) event, SBO (Send Bill Ord) event, and when account information is updated, which is also referred to as a Customer Change Application Event.

Interface Point 1: SBC Event

The PSREUB API enables account information to cross the interface at the SBC event to accomplish the following:

To avoid having an account established in a billing system that did not request service, and therefore would never bill.
To allow for pre-payments or deposits to be established on an account in a billing system before the order has been due-date completed in MetaSolv Solution.

Information Passed to the Server

The PSREUB API passes customer information. PSR account-level information that is passed to the server depends on the type of account. The product service request defines three types of accounts: customer accounts, billing accounts, and internal accounts.

Customer account information includes name, address, and contact information. Billing account information includes the same information plus bill cycle, tax exemptions, credit rating, auto payment information, and special handling codes. Internal account information is a name and a number, as internal accounts are used for departmental billing. Account information can be inserted, updated, and disconnected by MetaSolv Solution.

Interface Point 2: SBO Event

The PSREUB API sends order information to the third-party billing server at the completion of the SBO event. Users must select a provisioning plan that includes a task with the SBO event when the PSREUB API software option is enabled.

Information Passed to the Server

Order information passed to the third-party server from the PSREUB server includes products, services, features, and options, as well as the associated pricing, and customized attributes associated with the PSREUB API process points. Users must define products, services, features, and options as item types on the Product Specifications window. Item types are then grouped together as product offerings on the Product Catalog window. Product offerings, comprised of item types, are selected for an order. For each instance of an item type on an order, the product service request generates a unique service item ID. Every order can process New, Changed, Disconnect, Transfer Add, and Transfer Delete service items.

Implementation Concepts

MetaSolv Solution utilizes system-defined gateway events as well as an application event to notify the third-party billing server at specified points in the PSR workflow as shown in Figure D-2.

The gateway events used by the PSREUB API are:

Send Bill Customer (SBC)
Send Bill Order (SBO)

The SBC gateway event communicates information about a new customer account to the third-party billing server. This allows the third-party billing server to add the customer account to the billing system (see Interface Point 1 in Figure D-2, "PSREUB API Processing Flow Diagram"). The SBO gateway event communicates order information to the third-party billing server. This allows order information to be added to the billing system.

Within the Work Management subsystem, the SBC event should always precede the SBO event.

WARNING:

Both the SBC and SBO events must be completed before completion of the Due Date (DD) task. If you invoke SBC or SBO events after the service request is due date completed, and the third-party billing server reports an error; for example, "Invalid data" MetaSolv Solution does not allow you to supp the original service request to send the SBO or SBC again. This results in the data in the two systems being out of sync, and someone must manually change the data in one system to synchronize the data.

The MetaSolv Solution client uses the Customer Change Application Event to notify the third-party billing server, through the Event2Server, when a customer account is modified after it was successfully sent to the billing server.

In order to interact successfully with the PSREUB API, your application must implement three major functions:

A signal handler
A request handler
A response handler

The design you use when implementing these functions is entirely up to you. However, this documentation refers to the code that handles these functions as modules.

Signal Handler Module Design

The signal handler module implements the interfaces required to handle the SBC and SBO gateway events as well as the Customer Change Application Event. This module is also responsible for updating gateway event status to In Progress, Completed, or Error.

A WDIEvent data parameter structure is passed in.

Table D-5 lists the values of several fields for the SBC and SBO gateway events, and Customer Change Application Events.

Table D-5 SBC, SBO, and Customer Change Events

Event	eventName on WDIEvent	documentNumber on WDIEvent
SBC	"Send Bill Cust"	non-zero
SBO	"Send Bill Ord"	non-zero
Customer Change Application Event	"CCAE"	0 (zero)

Upon receiving a signal from the client, the signalhandler module activates the request handler module. For all types of events, the signal handler module is expected to return a WDIStatus data structure. In order to avoid locking up MetaSolv Solution, it is recommended that the signal handler return a status immediately upon activating the request handler module.

Request Handler Module Design

The request handler module addresses the functionality that the third-party billing server should implement to handle the information communicated by the client. Upon receiving event information from the signal handler, the request handler should perform the following steps:

Extract customer information (as applicable) by calling the exportCustomerAccount operation on the PSRSERVER.
Retrieve and examine the billing interface code before sending information to the billing system.

Note:
This step is essential because events may be initiated from MetaSolv Solution regardless of the value of the billing interface code. For example, new customer information needs to be sent to the billing system only if it has not already been sent. If the billing interface code indicates that it was successfully sent to the billing system, (status = A, meaning Accepted), then no information needs to be sent to the billing system and event status may be set to C, meaning Completed, or B, meaning Bypassed.
After data extraction and necessary conversions, the account information is passed to the billing system for processing. The UserPreference data structure received from the server contains user preference information that may be used by the third-party billing server. For example, user login information may be used to connect to the billing system.

Response Handler Module Design

The response handler module handles responses received from the billing system. The design of this module depends on factors such as the online/batch and synchronous/asynchronous nature of the interaction with the billing application.

Upon receiving a response from the billing system, the response handler module performs the necessary reverse translation/formatting using the formatting/translation module and then determines the operation's status. Based on the success or failure determination, this module should then:

Use the setBillingInterfaceCode operation in the PSREUBSession interface to update the billing interface code as applicable for the billing system used.
Record billing errors as applicable for the billing system used.
Update event status to Completed or Error.

Transaction Handling

Units of work in the third-party billing server should be carefully designed using the ”all-or-nothing” principle. This is necessary so the billing system's database and the MetaSolv Solution database do not get out of sync.

PSR Service Item Vs. the Billing Service Instance

The PSREUB API does not process every service item in the same way. Instead, service items are interrogated to determine whether they are a service instance. Not every service item in a PSR is a service instance. Only service items that are service instances are determined to be equipment. This determination is based on the definition of the item type on the Product Specifications window.

Each service item that is determined to be a service instance is further interrogated to determine the Usage Guide Key for the service instance. The usage guide key for the service instance is also based on the definition of the item type on the Product Specifications window.

The PSREUB API processes a service instance usage guide key as one of the following:

Authorization code
Auxiliary line
Circuit ID
Domain/Userid
Tel Nbr/Auth Cd
Telephone number
Travel card number
Universal

Pricing

Pricing can be associated with all service items. Each price associated with an item is interrogated and processed accordingly. Prices are based on type (recurring, non-recurring, usage) and level (account-level, service instance level). These price characteristics are defined on the Product Catalog window. The PSREUB API processes a service item price in PSR in one of five ways:

Account level recurring charge
Service instance level recurring charge
Account level non-recurring charge
Service instance level non-recurring charge
Service instance level usage charge

Transfer of Products Between Customer Accounts

The PSR module and the PSR API allow transfer of designated service items between customer accounts. When a transfer order is entered in PSR the order is associated with the recipient customer account. These enhancements required corresponding updates to the PSREUB API.

For transfer PSRs, the donor customer account is the customer account from which the service items are being transferred, and the recipient customer account is the customer account to which the service items are being transferred.

A transfer PSR for a new customer (no previous service requests) has an order-level activity code of N, meaning New. A transfer PSR for an existing customer (any previous service requests) has an order-level activity code of C, meaning Changed. When service items are transferred, each transferred service item must be deleted from the donor customer account and added to the recipient customer account.

From a provisioning point of view, these services are not actually disconnected and added, because the service itself continues to be available; it just belongs to a different customer account. However, from a billing point of view the pricing associated with these services is disconnected for the donor customer account and added for the recipient customer account. In other words the service itself remains uninterrupted or unchanged, only the account that pays for the service changes.

Using the ELEMENT, CONNECTOR, SYSTEM and PRDBUNDLE Item Types

If a service item of type ELEMENT, CONNECTOR, SYSTEM, or PRDBUNDLE has custom attributes, the PSREUB API passes the custom attributes. The structure that houses custom attribute information is defined in PSREUBTYPES_V2.IDL. The CustomAttribute structure itself is defined in WDIUTILS.IDL.

Items of type ELEMENT, SYSTEM, and PRDBUNDLE are never defined as billing service instances and therefore never have guide-to information. Items of type CONNECTOR are always defined as a billing service instance and therefore always have guide-to information. The usage guiding key for the CONNECTOR item type is always Universal.

Items of type ELEMENT, SYSTEM, or PRDBUNDLE never have PRILOC or SECLOC information. Items of type CONNECTOR always have either a PRILOC, a SECLOC, or both.