16 Using BRM Messaging Services

This chapter describes the Oracle Communications Billing and Revenue Management (BRM) Universal Message Store (UMS) framework and explains how to use its components to provide messages on invoices or other documents.

Before you read this chapter, you should have a good understanding of BRM opcodes and storable classes. See "Understanding the PCM API and the PIN Library" and "Understanding Flists and Storable Classes".

If you plan to develop custom applications that produce or consume BRM messages, you should also read "Adding New Client Applications" as well as the client applications chapter that covers the programming language you will use.

About the UMS Framework

The UMS framework enables you to include system-generated messages in customer documents such as invoices. You can use these messages to market new services or deliver reminders of overdue balances, for example.

UMS works by providing a middle layer between producers of messages, such as Collections Manager and third-party customer relationship management (CRM) applications, that generate invoice reminders, and consumers of message, such as the invoicing system. This middle layer includes storable classes to store messages and message templates as well as opcodes that process the messages.

Figure 16-1 illustrates the relationships among the components of UMS. These components are discussed in subsequent sections.

Figure 16-1 UMS Framework Components

Description of ''Figure 16-1 UMS Framework Components''

Setting Up Messaging by Using the UMS Framework

To set up messaging, perform these tasks:

Enabling Messaging
Loading the Message Style Sheet
Generating Messages in the Producer Application
Retrieving Message Objects in the Consumer Application

Enabling Messaging

To enable messaging, you must modify the PCM_OP_INV_POL_PREP_INVOICE policy opcode. See "Adding and Modifying Policy Facilities Modules" for general information about modifying policy opcodes.

To enable messaging:

Open fm_inv_pol_prep_invoice.c, the source file for PCM_OP_POL_PREP_INVOICE. This file is located in BRM_SDK_Home/source/sys/fm_inv_pol.
Delete or comment out the following line:
```
#ifdef UMS_MESSAGE_FEATURE
  
```
Delete or comment out the #endif line following the block of code after the #ifdef line.
Compile and link fm_inv_pol_prep_invoice.c to create a new shared library. See "Compiling and Linking a Policy FM".
Replace the existing shared library on your production system with the new one.
Add the following entry as a single line in your CM pin.conf to load the required messaging library:

- cm fm_module ${PIN_HOME}/lib/fm_ums/${LIBRARYEXTENSION} fm_ums_config - pin
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Loading the Message Style Sheet

If you are planning to use Universal Message Store (UMS) to deliver invoice reminders, you must load a new invoice style sheet that allows messages to be displayed.

The new style sheet is called message.xsl and is located in the BRM_Home/sys/data/config/stylesheets directory, where BRM_Home is the directory in which you installed BRM components. It is similar to the default invoice style sheet (sample1.xsl), except that it retrieves and displays messages.

You load the new style sheet by using the pin_load_invoice_template application. See "pin_load_invoice_template" in BRM Designing and Generating Invoices.

Creating and Loading Message Templates

Message templates are localizable /strings objects in the BRM database. They contain the basic text of a message along with placeholders for specific data such as names, balances, and dates.

You create message templates by writing a localized string file. Each file contains messages for one combination of locale (U.S. English, for example) and domain (invoice reminder messages, for example). The file also contains the text, optionally including placeholders, for one or more message strings. Each string requires a version and ID number.

The name of the template is entered in the HELPSTR field. This name can be displayed in client applications such as Collections Configuration.

The combination of locale, domain, ID, and version must uniquely define each string within the /strings class.

When you create a message string file, you can include placeholders that are filled with data when the complete /message object is created. The placeholder character is a percent sign (%) followed by a number that is incremented for each placeholder. In this example, there are two placeholders:

LOCALE = "en_US" ;
  
DOMAIN = "Messages - invoice reminder" ;
STR
     ID = 0 ;
     VERSION = 1 ;
     STRING = "Your account is now past due in the amount of %1                which was due on %2. Please send in your payment                promptly." ;
     HELPSTR = "First Reminder";
END

The placeholders are replaced with data supplied as elements in the PIN_FLD_ARGS array in the input flist of PCM_OP_UMS_SET_MESSAGE. Element numbers must correspond to placeholder numbers; element 1 replaces %1, element 2 replaces %2, and so on.

You can include HTML tags in the message string. This is useful when the string will be displayed in an HTML document such as an email or Web page.

You load message templates into the BRM database by running the load_localized_strings utility. To overwrite strings with the same version and ID, specify the -f option when you run the utility.

Generating Messages in the Producer Application

As their name implies, producer applications supply the messages to the UMS framework. In most cases, a complete message is assembled from a message template that is filled in with data supplied by the producer application.

Retrieving Message Templates

To create a complete /message object, the producer application requires the POID of the template on which the message will be based. The first step is gathering a list of available templates. From this list you can extract the POID of the template you want to use.

The producer application calls PCM_OP_UMS_GET_MESSAGE_TEMPLATES to return a list of the POIDs of all message templates for a domain and locale that you specify. For example, if you have stored a number of different marketing message templates for the same locale and domain, the opcode returns a list of the POIDs and template names.

If the producer application includes a graphic user interface (GUI), you can display the available template names for selection by the user. Otherwise, you can select the template Portal object ID (POID) programmatically.

You can also search for the /strings object that contains the message you want. This option is particularly useful if you aren't using a GUI and therefore do not need to display the list of available templates. See "Searching for Objects in the BRM Database" for information about searching.

If successful, PCM_OP_UMS_GET_MESSAGE_TEMPLATES returns an array containing the POID, brand, and name of each template in the current brand that matches the locale and domain specified in the input flist.

PCM_OP_UMS_GET_MESSAGE_TEMPLATES stops processing if no templates are available for the specified combination of brand, locale, and domain.

Retrieving Message Templates from /strings Objects

To display a full message template in an application, call PCM_OP_UMS_GET_MESSAGE_TEMPLATE. This opcode retrieves the full contents of the template.

If successful, PCM_OP_UMS_GET_MESSAGE_TEMPLATE returns the contents of the specified message template /strings object, including the POID, domain, locale, template name, and template string.

PCM_OP_UMS_GET_MESSAGE_TEMPLATE stops processing if the POID of the requested template is incorrect or missing.

You can skip this step if you do not need to display the template contents. The opcode that creates /message objects automatically calls PCM_OP_UMS_GET_MESSAGE_TEMPLATE to retrieve the template it needs.

Creating Message Objects

The producer application creates the /message object by calling PCM_OP_UMS_SET_MESSAGE_TEMPLATE. The input flist must include the POID of the message template that will be used for this message.

If the template contains placeholders, the input flist must also contain an array whose elements supply data for the placeholder. The data in element 1 replaces placeholder %1, the data in element 2 replaces %2, and so on.

You also set the scope of the message; whether it applies to a particular bill, an account, or to an entire brand when you create the /message object. You define the scope by supplying the POID of the brand, account, or bill to which the message applies.

If the message scope is the account or brand, you can also supply an effective date in the input flist.

PCM_OP_UMS_SET_MESSAGE stops processing under these circumstances:

The POID of the template is missing or incorrect.
No locale is specified.
No scoping information (brand, account, or bill) is specified.
No effective date is included for brand or account-scoped messages.

Retrieving Message Objects in the Consumer Application

The consumer application retrieves /message objects by calling PCM_OP_UMS_GET_MESSAGE.

The opcode retrieves /message objects based on scoping information that you provide. You specify the scope by including the brand, account, or bill object POID associated with the messages you want.

By default, PCM_OP_UMS_GET_MESSAGE retrieves all messages that apply at the scoping level you specify. For example, if you specify a /bill object, the opcode retrieves all messages that are scoped to that bill, the bill's account, and the brand with which it is associated. Similarly, if you specify an /account object, the opcode retrieves messages scoped to the account and its brand.

You can modify the default scoping behavior by including the PIN_FLD_SCOPE field in the input flist with a value of 1. With this option, PCM_OP_UMS_GET_MESSAGE finds only messages scoped narrowly to the bill, account, or brand you specify. For example, including a /bill object in the input flist returns only messages specifically scoped to that bill.

You can also include a locale and effective date in the input flist to further narrow the list of messages that is returned.

For each message that matches the scope, PCM_OP_UMS_GET_MESSAGE returns an array that contains the text of the message, the message template name, and the message domain. The consumer application can then select the individual message programmatically or via a GUI.

PCM_OP_UMS_GET_MESSAGE stops processing under these circumstances:

No scoping information is included in the input flist.
No /message objects exist that meet the scope defined in the input flist.