7Unified Messaging
Unified Messaging
This chapter describes the Unified Messaging framework used by Siebel Business Applications. It includes the following topics:
About Unified Messaging
The Unified Messaging framework is the mechanism used by Siebel Business Applications to display messages to users. The foundation of the Unified Messaging framework is the Unified Messaging Service (UMS) business service. For Siebel order management uses, UMS messages recommend products and promotions, explain eligibility, provide price waterfalls, and display results of checks on promotion commitments and integrity. For example, a message prompts a customer service representative (CSR) to cross-sell batteries and a camera case when a customer is purchasing a camera. Messages come to the user in the form of a pop-up applet or rows in a list applet in a view.
The Unified Messaging framework supports the display of dynamic, actionable messages. The framework is an entity independent of the source and type of messages displayed. The Unified Messaging framework natively supports advanced features such as translation of message text, substitution of textual values into the message template, logging of message responses, and suppression of duplicate messages when appropriate (such as advice to a CSR against trying the same upsell if the customer has already rejected it).
In Siebel order management, a message is guidance, a recommendation, or an explanation presented to an end user in response to a button click or an action the end user takes. For example, the Order Catalog view might display the following message when an end user orders an item that is temporarily unavailable:
The product you have selected is on back order until [date].
A message’s text is constructed from a fixed message template as well as substitutable text fragments, such as the name of a product.
Messages displayed are sorted by score. The message-generation algorithm sets the score. For the simple preconfigured rules-based messages, the user enters the score in an administration view. Make sure that your messages use a consistent scoring scheme so that the most important messages of any type appear at the start of the list. The default message-generation algorithms can be extended to call out to a propensity-based scoring algorithm to dynamically score the messages that are displayed based on self-learned rules.
Concepts of Unified Messaging
A message type stores the definition of a message, including its text, its bitmap (such as a graphic of an exclamation point), and its display mode (active or passive). A message type with an active display mode means that a dialog box is displayed to the user and the user must provide a response; a passive message type means that the message is displayed to the user without requiring a response. A message type group is a list of values used to group message types, making them available in picklists.
Payload is the contents of the message delivered to the end user. The message type payload is a list of all payload fields that must be provided with every message of a certain type.
A message type response is an allowed response to a message. The allowed responses and their associated actions are soft-coded in an administration view. For example, a preconfigured upsell message has “Accept” and “Reject” responses. You can configure an additional “Send E-Mail” response that automatically emails the upsell product details to the customer.
A message response is a logged response to a message.
Message Types Administration
You implement Unified Messaging for Siebel order management using the Administration - Order Management screen, then the Message Types views, as follows:
All Message Types view. Create new message types. Work with existing message types. Enter text for messages. Attach titles and bitmaps to messages. Specify whether messages are active or passive. Specify the group to which the message type belongs.
Payload view. Create and work with payload variables, which substitute values into message text and which are used for automated response processing.
Responses view. Create the possible responses for a message type. Control response logging. Control message suppression. Enable automated processing of responses.
Translations view. Enter translations for message text.
Components of Unified Messaging
The following figure shows the interaction between the components of Unified Messaging.
Registered Message Display Services
The UMS business service relies on pluggable message display services that are responsible for displaying messages and accepting user responses. These message display services are the following:
List Applet Message Display service
Pop-up Applet Message Display service
The following figure shows the interaction between UMS and registered message display services.
Message display services subscribe to updates to the message cache in the UMS. A message display service subscribes when it is included in the user interface. A message display service unsubscribes when it is not included in the user interface. More than one message display service can be subscribed at the same time.
Update Messages Method
The UMS calls the Update Messages method on the message display service every time the message cache is updated.
Process Response Method
The message display service invokes the Process Response method on the UMS when the user selects a response in the UI.
For more information about UMS business service methods, see Unified Messaging Service Business Service Methods.
Custom Message Display Services
If necessary, you can develop your own message display service for use with the UMS as long as it adheres to the protocol of method invocations described in Registered Message Display Services. Using a custom message display service, you may choose to provide a different UI layout or a filter to display only a subset of messages.
Payload Variables
A payload variable is a name-value pair associated with a message instance. It can be substituted into the final message text, saved to the database when a response is logged, used as the scope for duplicate message suppression, or used to process a response. For example:
[Product Id] = "12-E2345", [Product] = "Canon F150", [Account] = "Marriott HQ"
The payload property set is passed with the message to message display services and automated response services. The payload structure is a set of name-value pairs.
Any payload variable can be substituted into the text by enclosing its name in []. Any payload variable can be logged to the response table as long as a Response Field mapping is specified.
Payload variables are also used for message suppression. See About Suppressing Duplicate Messages.
You create payload variables using the Administration - Order Management screen, Message Types, and then the Payload view.
Message Property Set
Characteristics of a message’s structure are described in the following table.
| Attribute | Type | Description |
|---|---|---|
Message Id |
String |
A unique identifier for the message. This is used to make sure the same message does not display twice. Every time a message is displayed, it must be assigned the same message ID to enable suppression of repeated messages. This is also used to identify the message when an action is selected. |
Message Type |
String |
The message type of the message. Refers to a row in the Message Types table. |
Score |
Number |
An integer between 1 and 100 indicating the priority of the message. This is used to determine the order in which passive messages are displayed. |
Display Mode |
String |
(Optional) Indicates how to display the message. Seed data values are “Active” and “Passive”. You (the integrator) can extend this list.
Note: This input is optional. If not specified for a particular message, then the Display Mode defaults from the message type.
|
[Payload] |
Property Set |
A list of name-value pairs that are used to specialize the display and processing of the message. Examples: Line Item Id = “12-ABC123" Upsell Product = “Canon 128 MB Memory Card" The payload attributes are defined in the Message Type administration view. They are stored as sibling properties of Message Id, Score, and so on. |
Message List Property Set
The example that follows shows the structure of a sample message list called “Message List.”
This sample message list consists of a set of messages. Each message has a child property set providing the payload properties.
CCFPropertySet@0013B0AC p#1 c#1 type="" vt=0 value=""
{
p["Source"] = "Product Recommendation";
c[0] CCFPropertySet@0BC04D00 p#0 c#2 type="Message List" vt=0 value=""
{
c[0] CCFPropertySet@0BDE0408 p#61 c#2 type="Message" vt=0 value=""
{
p["Message Type"] = "Cross-Sell Recommendation";
p["Score"] = "66";
p["Message Id"] = "42-4Z1RL";
p["Display Mode"] = "Passive";
c[0] CCFPropertySet@0BF0E578 p#14 c#0 type="Payload" vt=0 value=""
{
p["Doc Id"] = "42-528T1";
p["Account Id"] = "";
p["Related Product Id"] = "99-28GJ1";
p["Contact Id"] = "";
p["Line Item Id"] = "42-528VT";
p["Related Product"] = "10GB Hard Drive";
p["Reason"] = "Test XSell";
p["Campaign Id"] = "";
p["Net Price"] = "";
p["Prod Id"] = "98-4NVN0";
p["Currency Symbol"] = "$";
p["Document Type"] = "Quote";
p["Product"] = "1006667";
p["Party Id"] = "";
}
}
c[1] CCFPropertySet@0BD18070 p#61 c#2 type="Message" vt=0 value=""
{
p["Message Type"] = "Upsell Recommendation";
p["Message Type Id"] = "04-E8VXZ";
p["Score"] = "77";
p["Message Id"] = "42-4Z1RN";
c[0] CCFPropertySet@0BE4B178 p#14 c#0 type="Payload" vt=0 value=""
{
p["Doc Id"] = "42-528T1";
p["Account Id"] = "";
p["Related Product Id"] = "99-28GSH";
p["Contact Id"] = "";
p["Line Item Id"] = "42-528VT";
p["Related Product"] = "10MB USB Home Networking Adapter";
p["Reason"] = "Test UpSell";
p["Campaign Id"] = "";
p["Net Price"] = "";
p["Prod Id"] = "98-4NVN0";
p["Currency Symbol"] = "$";
p["Document Type"] = "Quote";
p["Product"] = "1006667";
p["Party Id"] = "";
}
}
}
}
Message Responses
A message type with an active display mode means that a dialog box is displayed to the user, and the user must provide a response. A message type response is an allowed response to a message. Defining message type responses is part of the process of creating a message type.
You create message type responses using the Administration - Order Management screen, Message Types, and then the Responses view. For information about creating message type responses, see Creating Message Types.
Message Translations
The Unified Messaging framework allows for translations of message text and message response text. If you are implementing message translations, you enter the translations as part of the process of creating a message type. You create message type translations using the Administration - Order Management screen, Message Types, and then the Translations view. For information about creating message translations, see Creating Message Types.
Unified Messaging Service Business Service Methods
The Unified Messaging Service (UMS) business service exposes the APIs described in the following table for updating the messages in the UMS cache, formatting messages, and attaching a new message display service. These APIs can be called from any run-time event, signal, workflow, or custom script.
| Method | Arguments | Description |
|---|---|---|
Add Messages |
[in] Source: String [in] Message List: Hierarchy |
Add a new list of messages to the message cache. Associate each message with the specified source. |
Update Messages |
[in] Source: String [in] Message List: Hierarchy |
Replace the current set of cached messages for the specified source with the new list of messages. Associate each message with the specified source. |
Delete Messages |
[in] Source: String [in] Message List: Hierarchy |
Delete all cached messages associated with the source or, if specified, the list of messages provided.
Note: For deletion, only the message IDs need to be identified in the message list.
|
Get Messages |
[out] Message List: Hierarchy |
Output all unsuppressed, cached messages (regardless of source) including information derived from the message type (such as allowed responses). |
Process Response |
[in] Source: String Message Id: String [in] Response: String |
Process the end-user response to the specified message as defined by the message type. |
Reset |
Not applicable |
Delete all cached messages. |
Subscribe |
[in] Business Service: String [in] Method Name: String |
Add a Message Display business service to the list of services that are informed when a change occurs to the set of messages in the cache. |
Unsubscribe |
[in] Business Service: String |
Remove the specified business service from the list of services that are informed when a change occurs to the set of messages in the cache. |
Format Message |
[in/out] Message: Hierarchy |
Substitute and translate the text for the input message. The message is not displayed. |
Creating Message Types
A message type stores the definition of a message, including its text, its bitmap, and its display mode. The process of creating a message type involves adding a new message type record, adding message translations, defining message type responses, and creating translations for message type responses.
To implement a new message type
Navigate to the Administration - Order Management screen, then the Message Types view.
In the All Message Types list applet, create a new message type record.
Complete the fields for the new message type record. Message Type fields are described in the table that follows.
Field Comments Title
Enter the title that will be displayed on the popup applet for an active message. For example:
Recommendation
Display Mode
Select the display mode. Options are:
Passive. The message is displayed on the screen, but it does not demand a response from the user.
Active. The message is displayed in a dialog box, and the user must select a response (such as “Accept” or “Reject”) to close the message and continue.
Group
Use this field to group related messages together. This field constrains pick applets in administration views, such as in the Administration - Product screen, then the Product Recommendations view.
Bitmap
Select the graphic that will be displayed on this message. For example, you might display an exclamation point graphic for an alert.
Note: The Bitmap field applies only to messages with active display mode.Short Text
Enter a short message to be displayed, using text and field names. For example:
We recommend [Related Product].
Note: Short Text is generally not used, except by a custom message display service.Full Text
Enter a message to be displayed, using text and field names. For example:
We recommend [Related Product] for [Net Price]. [Reason]
(Optional) If this text must be translated, click the Translations tab.
Add records to the Translations list, and enter the translation for the content of the Full Text field. You must add one record for each language being translated. Translations fields are described in the table that follows.
Field Comments Language
Enter the code for the language of this translation. For example, enter FRA for French.
Title
Enter the title that will be displayed on the popup applet for an active message. For example:
Un Recommendation
Short Text
Enter a short message to be displayed, using text and field names. For example:
Nous recommendons [Related Product].
Note: Short Text is generally not used, except by a custom message display service.Full Text
Enter a message to be displayed, using text and field names. For example:
Nous recommendons [Related Product] pour [Net Price]. [Reason]
Click the Payload tab, and specify the payload variables to be substituted into the Full Text field. Payload fields are described in the table that follows.
Field Comments Payload
Enter the name of the payload variable to be substituted with text. For example:
Campaign Id
Response
Choose from a picklist of values built from the fields of the UMS Response business component (which is based on the S_COMMUNICATION table). For example:
Campaign Offer Id
The response field is the field used to record the user response to messages.
Create a response for the message type.
Write a custom business service to process the new response.
For information about how to write a response-handler business service, see Attaching a Business Service to a Message Response.
For example, the custom business service creates an activity to mail product literature to the customer.
Compile a new SRF.
In the Administration - Order Management screen, then the Message Types view, select the message type for which you are creating a response.
Click the Responses tab.
Add the new response to the message type:
Complete the required fields: Name, Business Service, Method.
Set the Log flag to indicate whether to log this response.
Set the Suppress Repetition flag and its corresponding field, if this response causes suppression of the message.
Resequence the existing responses so that buttons appear in the correct sequence on the user interface.
Create translations for the message type response.
Translations for the message type response make sure that the text displayed on the actionable buttons is in the correct language.
Note: Translation records are not required if your implementation is mono-lingual. For single-language implementations, the default text in the message type and in the message type response is used.Test the application by creating a situation where the message is displayed, and then clicking New Response.
Configuring the Display of Messages
When configuring the display of messages, you can choose between two preconfigured mechanisms stored in the UMS, as follows:
Add a list applet to a view. If you want the messages to be displayed at all times, then include the UMF Messages list applet in a view.
Expose an icon on an applet. If you do not want to give up the screen space that an applet requires, then expose the UMF “You've got messages” icon on an applet.
Adding a Message Applet to a View
Use the following procedure to add a message applet to a view.
To add a message applet to a view
Add the UMF Message List Applet - SI to the view.
Add the UMF Passive Virtual Business Component to the Business Object of the view.
Adding a Message Icon to a View
Use the following procedure to a message icon to a view.
To add a “You’ve got messages” icon to a view
Create a new button with the following settings:
HTML Bitmap = ICON_TOOLBAR_MSGS
HTML Disabled Bitmap= ICON_TOOLBAR_MSGS_OFF
HTML Type = MiniButton
Method Invoked = MessagePopup
Add a user property with the following settings:
Name = “Named Method 1: Message Popup”
Value = 'INVOKESVC','UMF UI Service','PopupListApplet'
Add a user property with the following settings:
Name = 'Named Method Check Can Invoke’
Submethods = MessagePopup
Value = Y
Implementing Multilingual Substituted Text
The UMS automatically translates the Title, Short Text, and Full Text for a message. Payload fields must be either language-independent (such as Price or Product ID), or they must be translated by the message-generation engine. In this case, you must create translatable payload text for the message.
To implement multilingual substituted text
Add a custom child business component and associated administration view to the payload entity to store the language overrides for each language code.
Add a calculated field to the payload business component to store the system language.
Add an outer join from the payload business component to the translation business component with a search specification that matches the parent Id and the system language code.
Add a joined field for the translated field to the payload business component.
Add a calculated field that selects the translated text if it is not null or if it otherwise defaults to the default language text in the payload business component (example:
IfNull([Language Text], [Text])).
The message-generation engine uses the calculated field value (example: [Language Text]) to get translated text where available.
Implementing a Custom Message-Generation Engine
Any workflow or custom script can add, update, or delete messages stored and displayed by the Unified Messaging framework. The PSP engine provides a framework for implementing a custom message-generation engine. For example, you might implement a PSP procedure to generate disclosures that must be read before a product can be sold (such as “Are you 21”) and then display those messages via Unified Messaging. This topic provides the general approach to implementing a custom message-generation engine.
To implement a custom message-generation engine
Create new message types with associated responses and automated execution business services.
Create a PSP procedure that generates a Message List property set and passes that list to the UMS using the Update Messages method.
Use a new source name to distinguish these messages from others that are similar.
Make sure all payload variables are populated.
Make sure each message ID is unique and invariant.
Set up run-time events or signals to execute the new message-generation engine at the desired points in the UI process flow.
Note: Make sure to set up events that clear messages when they no longer apply.Add the Message Display list applet or enable the Pop-Up Message list applet for the views where the new messages are relevant.
About Working with Message Responses
For each message type, you can specify multiple possible responses. Each response is displayed as a button labeled with the Name text (or a language-specific translation of the Name text). Buttons are displayed from left to right, sorted by Sequence #.
Further information about message responses is organized as follows:
Logging Message Responses
You set logging of message responses using the Administration - Order Management screen, Message Types, and then the Responses view.
In the Responses list applet, use the Log flag to indicate whether responses are to be logged for a message type. You can use this for suppression of duplicate messages and to analyze the effectiveness of messaging.
Responses are logged to the S_COMMUNICATION table. This table stores marketing campaign responses. and you can view message responses in the existing campaign analysis views.
With response logging enabled, the following message fields are logged:
Message Type Id
Message Id
Response
Display Mode
Score
Language Code
Position In Message List
All payload fields with an associated Response Field mapping
Attaching a Business Service to a Message Response
When the user selects a message type response (for example, by clicking the Accept button for an upsell message), the active message display service informs the UMS by calling its Process Response method. The UMS then calls the business service method associated with that response.
You define which business service method will handle a response using the Administration - Order Management screen, Message Types, and then the Responses view.
The Siebel application provides prebuilt methods for handling upsell and cross-sell in the Product UpSell CrossSell Service business service. You can implement your own automated response-handling logic (such as for sending an email with product details) by scripting your own business service method. This method must process the Payload argument, as described in the following table.
| Argument | Type | Description |
|---|---|---|
Payload |
Hierarchy |
A property set containing all payload variables provided with the message when it was added to the UMS. The message-generation engine must provide values required to process the message in the payload variables. |
About Suppressing Duplicate Messages
Opportunities to communicate a message (such as an upsell) to a customer are limited. It is important to deliver the message that provides the highest likelihood of a new sale. Repeating a previously rejected message to the customer is unlikely to generate a new sale; instead, you are more likely to make a sale by presenting a new message, even if it has a lower score.
The Unified Messaging framework provides a flexible mechanism for suppressing duplicate messages. You can implement message suppression for particular responses (such as, implement suppression for “Reject” but not “Accept”) and for any scope (such as, for an instruction to never show this message again to the customer, or to not show the message again for this order).
Checking for duplicate messages occurs in two instances:
When new messages are provided to the UMS, (for example, with the Add Messages or Update Messages methods).
After a new response has been processed (using the Process Response method).
Suppress Repetition Flag
The UMS attempts to suppress duplicate messages if the Suppress Repetition flag is set for one or more of the responses for a message type.
Suppression Scope
The Field column indicates the scope of the message suppression (for example: Party Id, Document Id, or Line Item Id).
All responses for a particular message suppression scope (such as Party ID) are loaded with a single query and cached until the scope changes, for example, with a new caller.
For further information, see Suppressing Duplicate Messages.
Suppressing Duplicate Messages
You set suppression of duplicate messages using the Administration - Order Management screen, Message Types, and then the Responses view.
A message is suppressed if a response has been logged for that message ID, response, and scope value; for example:
[Party Id] = '12-W123')
For this reason, the message ID must be unique and invariant.
To enable suppression of duplicate messages
Navigate to the Administration - Order Management screen, then the Message Types view.
In the All Messages Types list applet, select the message type for which you want to suppress duplicates.
Click the Responses tab to see the Responses list applet.
In the Responses list applet, check the Suppress Repetition flag to set suppression for the message type response.
In the Field field, specify the scope of the suppression, for example, the suppression may be limited to the Party ID field.
Migrating Message Types Between Environments
Message types can be exported and imported using the applet menu on the All Message Types list applet.
Tuning Performance of Unified Messaging
Note the following considerations when tuning performance of the UMS:
Message type definitions are stored in an object manager-level cache. Messages are cached in memory and never written to the database. The Message Display list applet is based on a virtual business component that pulls data directly from the in-memory cache.
Avoid using duplicate message suppression for business-to-business accounts. Duplicate suppression processing has to load all previous responses for the account at the beginning of the call. Loading more than 100 responses will result in a perceptible delay. If you must use duplicate message suppression in business-to-business situations, configure the message suppression to suppress duplicates by quote or by order instead of by account.
Limit the number of messages displayed. It is generally accepted that the user will not view more than three or four recommendations at a time.
Carefully consider the events that trigger the message-generation mechanism. In general, the message-generation mechanism will have a larger overhead than the UMS.
Using Unified Messaging with the PSP Engine
PSP applications such as Pricer and Eligibility use the UMS to format translated, substituted text for waterfall output or for eligibility reasons. The PSP action syntax provides an API, LookUpMessage, that in turn invokes the Format Message method on the UMS. This method simply returns the formatted text. It does not add the message to the UMS cache. Messages formatted in this way do not support automated responses, duplicate suppression, or logging.
To use the new message type with a PSP procedure
After completing Step 5 in Creating Message Types, add an action to the PSP procedure that invokes the LookUpMessage function for the new message type, passing the payload fields. See Example of a LookUpMessage Call.
The LookUpMessage function allows the UMS to process translations of the message text.
Test the revised PSP procedure.
Example of a LookUpMessage Call
You can use the example that follows as a model for an invocation of the LookUpMessage function.
{Row.Eligibility Reason} = LookUpMessage('Eligibility - Not In Contract Error',
[Account] = {Row.Account Id})
The PSP engine calls the method Format Message. Arguments for this method are described in the following table.
| Method | Arguments | Description |
|---|---|---|
Format Message |
[in/out] Message: Hierarchy |
Substitute and translate the text for the input message. The message is not displayed. |