15 Publishing Measure Change Events

Event-driven planning requires the ability to identify events when they arise. This includes events that result from changes in plans and those that arise because of advancement in the planning activity, for example, approval of a plan or creation of new items. The ability to get notification of the event when it occurs is therefore essential. In the context of RPAS applications, many measure changes result from business activities and therefore fall into the category of notification-worthy events.

RPAS Publishing Measure Changes (PMC) provides a mechanism to monitor measure changes and receive notification messages through a standard JMS messaging service. A measure change event is defined as the measure data being written by any means. The following is the list of the sources for PMC events:

MACE: all left-hand side measures in the expression or expressions of the rule group specified in the command line.
Workbook Commit: all left-hand side measures in the commit rule group.
loadMeasure: all successfully loaded measures.
loadHier: measures whose base intersection contains at least one affected dimension. "Affected" means adding and deleting one or more logical positions.
Dynamic Position Management (DPM): measures whose base intersection contains a dimension affected by DPM. Adding or removing positions to a dimension or its lower level children constitutes a change in the measure.

Figure 15-1 demonstrates a JMS system in the context of RPAS. The JMS system consists of four basic components:

JMS Provider: The central daemon that accepts connections from clients and routes and queues messages. It is sometimes called JMS Broker.
Java Naming and Directory Interface (JNDI) Service: A service that provides mapping between names and objects. It adds abstraction to the more complex structure of underlying objects.
JMS Client (Publisher): A standalone daemon process running with the other RPAS server side processes such as DomainDaemon and RpasDbServer.
JMS Client (Subscriber): Any applications interested in getting notifications of measure changes.

Figure 15-1 JMS System in RPAS

Configuring Subjects and Measures for Monitoring

A subject is defined as a logical grouping of measures. A subject is mapped to one or more measures in one domain, while a measure can belong to one or more subjects. For example, a subject named PlanningMeasures can include all measures associated with planning.

The configuration file of measure-change monitoring serves two purposes:

Defines the mappings between subjects and measures.
Defines the inclusion filters for monitored measures.

By default, no measures are monitored unless they are specifically included in the configuration.

For each domain, there is one measure-change monitor configuration file. It is named MeasureChangeMonitor.properties and must be located under {domainPath}/config/.

Note:

There is only one property file for a global domain. It is placed under the config directory of the master domain.

This configuration file is in standard Java properties file format. Each line defines the relationship between one subject and one measure:

Subject.MeasureName=true

true means inclusion in monitoring.
false is used to exclude a subject or measure from monitoring. Use of false is not recommended since, by default, a measure is not monitored and such a line can be deleted or commented out from the file. Comments are any contents on a line from "#" to the end of the line.

Example:

TestMeasures.R_EX_DEMOA=true
TestMeasures.R_EX_DEMOB=true
LanguageMeasures.R_MsgLabel=true

The following are defined in the above example:

Two subjects: "TestMeasures" and "LanguageMeasures".
The subject "TestMeasures" represents two measures: "R_EX_DEMOA" and "R_EX_DEMOB".
The subject "LanguageMeasures" represents one measure: "R_MsgLabel".

A subject name must be a valid hierarchical variable name, that is, consisting of only alphanumeric characters, underscores, and periods. RPAS does not enforce any naming convention for a subject. It is up to the retailer to define an individual naming convention.

After the configuration file is modified, RPAS processes can detect that the file has changed and automatically reload it. There is no need to restart any RPAS processes.

Configuring the RPAS JMS Publisher

JMS Publisher for measure change events is implemented in Java and runs as a standalone process. It is decoupled from any other RPAS server side processes in terms of inter-process communications and domain data file locking.

Each JMS Publisher process is tied to a domain and a JMS topic. When the publisher detects an event for its domain, it generates a JMS message and sends the message to a JMS provider. The format of the JMS message is defined by a template file, which can contain any of the macros listed in Table 15-1. The macros are replaced by actual values at run time.

Table 15-1 Configuration Macros

Macro Name	Format	Notes
__EventDateTime__	YYYY-MM-DDThh:mm:ss	Local time of the server.
__SourceURI__	RPAS/JMS/{hostname}	{hostname} is the name of the server where the publisher is running.
__SUBJECT__	String	Subject of the event as defined in MeasureChangeMonitor.properties.
__TYPE__	"MeasureChange"	Type is a constant string.
__DOMAIN__	String	Path to the domain.
__MEASURE__	String	RPAS internal measure name.
__ORIGINUSER__	String	RPAS User ID, only available for workbook commit or DPM. Use "-" if not available.

Here are two examples of a JMS message template.

Example 1: Simple name/value pairs:

type=__TYPE__
domain=__DOMAIN__
measure=__MEASURE__
time=__EventDateTime__
user=__ORIGINUSER__

Example 2: XML-based Notification Event Architecture for Retail (NEAR) format:

<?xml version="1.0" encoding="UTF-8" ?>
<AlertEvent MajorVersion="1" MinorVersion="0" TypeCode="RPASEvent"
            Priority="0" Severity="Information" Mode="Test" FixVersion="0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://www.retail.oracle.com/workspace/alerts/AlertEventV1.0.0.xsd"
            xmlns="http://www.retail.oracle.com/workspace/alerts/">
      <SequenceNumber>0</SequenceNumber>
      <EventDateTime>__EventDateTime__</EventDateTime>
      <EventDescription>RPAS Measure Change Event</EventDescription>
      <SourceName>RPAS</SourceName>
      <SourceURI>__SourceURI__</SourceURI>
      <Instance>1</Instance>
      <RoutingInfo TypeCode="SubjectInfo">__SUBJECT__</RoutingInfo>
      <AlertData><![CDATA[<type>__TYPE__</type>
<domain>__DOMAIN__</domain>
<measure>__MEASURE__</measure>
<originUser>__ORIGINUSER__</originUser>]]></AlertData>
</AlertEvent>

Command Line

The following command line is used for JMS Publisher:

java -cp {classpath} oracle.rpas.pmc.MCPublisher -d {domainPath} [-c {configFileName}] [name1=value1 [name2=value2 [...]]]

Table 15-2 provides descriptions of the arguments used in the command line.

Table 15-2 Arguments Used in the Command Line

Argument	Description
classpath	Should include rpaspmc.jar and jms.jar under $RPAS_HOME/lib and any vendor-specific JMS implementation jar files.
-d domainPath	Path to the monitored domain. It must be a simple or master domain.
-c configFileName	Configuration file in Java properties file format. This argument is optional.
name1=value1 name2=value2 …	The name/value pairs. If the configuration file is not specified, the name/value pairs are used. If the configuration file is specified, the name/value pairs are added to the configuration and overwrite any value with the same name already present in the file. This argument is optional.

Configuration Settings

The configuration settings for the JMS Publisher can be categorized into general and vendor-specific settings.

General Settings

Table 15-3 lists all vendor-neutral configuration settings for the JMS Publisher:

Table 15-3 Vendor-Neutral Configuration Settings for the JMS Publisher

Setting Name	Description	Required	Value
topic	JMS topic lookup name.	Yes	A string with only alphanumeric characters, underscores, and periods. Maximum length is 100 bytes.
topicConnectionFactory	JMS topic connection factory lookup name.	Yes	A string with only alphanumeric characters, underscores, and periods. Maximum length is 100 bytes.
messageTemplate	Template file name for the JMS message. This file must be placed under the config directory of the domain.	Yes	Standard template file PMCMessageTemplate.xml is available under $RPAS_HOME/domain/config. This file must be copied to the config directory of the domain.
logLevel	Logging level. A log level is a cut-off level which means logs with a lower level are filtered out.	No	Specify one of the following values, in low to high order. "VERBOSE": All logs. "DEBUG": Debug logs. "INFO": Informational logs. "WARN": Warning logs. "ERROR": Error logs. "SUPPRESS": No logs. If not specified, the default is "INFO".
logFile	The path to the log file. Can be a relative or absolute path.	No	If not specified, output to the console.
restartAfterException	Flag to restart after encountering any JMS related exceptions.	No	If true, the publisher will try to restart after catching any JMS related exceptions. Interval between retries is 180 seconds. To stop the publisher from trying to restart, the process must be ended manually. Default is true.
message.deliveryMode	Delivery mode.	No	"NON_PERSISTENT" or "PERSISTENT". Default is "PERSISTENT"
message.priority	A priority number for the JMS message.	No	0 to 9. Default is 4.
message.timeToLive	Time to live in milliseconds.	No	0 or any positive integer. Default is 0 (unlimited).

Vendor-Specific Settings

Sun Open Message Queue is used as an example for these settings. For further details, consult the vendor documentation for your JMS implementation.

File-Based JNDI Object Store

File-based JNDI object store is used primarily for development and testing. It is very easy to set up, but has weak built-in security.

Table 15-4 File-Based JNDI Object Store

Property Name	Description	Required	Value
java.naming.factory.initial	Initial context for JNDI lookup.	Yes	For Open Message Queue, it must be: com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url	Directory path to the object store.	Yes	Example: file:///C:/myapp/mqobjs

Property Name

Description

Required

Value

java.naming.factory.initial

Initial context for JNDI lookup.

Yes

For Open Message Queue, it must be: com.sun.jndi.fscontext.RefFSContextFactory

java.naming.provider.url

Directory path to the object store.

Yes

Example:

file:///C:/myapp/mqobjs

LDAP-Based JNDI Object Store

An LDAP server is the recommended object store for production JMS messaging systems. LDAP servers are designed for use in distributed systems and provide security features that are required in production environments.

Table 15-5 LDAP-Based JNDI Object Store

Property Name	Description	Required	Value
java.naming.factory.initial	Initial context for JNDI lookup.	Yes	For Open Message Queue, it must be: com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url	Server URL and directory path to the object store.	Yes	Example: ldap://myD.com:389/ou=mq1,o=App where administered objects are stored in the directory /App/mq1
java.naming.security.principal	Identity of the principal for authenticating callers.	No	The format of this attribute depends on the authentication scheme. For example: uid=homerSimpson,ou=People,o=mq If this attribute is not specified, the behavior is determined by the LDAP service provider.
java.naming.security.credentials	Credentials of the authentication principal.	No	The value of this attribute depends on the authentication scheme. For example, it might be a hashed password, clear-text password, key, or certificate. If this property is not specified, the behavior is determined by the LDAP service provider.
java.naming.security.authentication	Security level for authentication.	No	Specify one of these options: "none": No security "simple": Simple security "strong": Strong security For example, if you specify "simple", you are prompted for any missing principal or credential values. This enables a more secure way of providing identifying information. If this property is not specified, the behavior is determined by the LDAP service provider.

Here is a sample configuration file for RPAS JMS Publisher:

java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///C:/Temp
topic=RPASEventTopic
topicConnectionFactory=RPASEventTopicConnectionFactory
messageTemplate=PMCMessageTemplate.xml

Configuring the RPAS JMS Subscriber

A sample JMS Subscriber is implemented to use for testing or troubleshooting. This subscriber is packaged and deployed along with the publisher. It simply writes the messages it receives to logging output, which can be console or a log file.

Command Line

Here is the command line for the sample JMS Subscriber:

java -cp {classpath} oracle.rpas.pmc.MCSubscriber [-c {configFileName}] [name1=value1 [name2=value2 [...]]]

The {classpath} should include rpaspmc.jar and jms.jar under $RPAS_HOME/lib and any vendor-specific JMS implementation jar files.
The {configFileName} is a configuration file in Java properties file format. It is optional.
The name/value pairs are used if the configuration file is not specified. Otherwise, the name/value pairs are added to the configuration file and any value with the same name already present in the file is overwritten.

Configuration Settings

Vendor-specific settings are the same as the JMS publisher. Refer to "Configuring the RPAS JMS Publisher" for details.

Table 15-6 lists all the general settings for the JMS Subscriber:

Table 15-6 General Settings for the JMS Subscriber

Property Name	Description	Required	Value
topic	JMS topic lookup name.	Yes	A string with only alphanumeric characters, underscores, and periods. Maximum length is 100 bytes.
topicConnectionFactory	JMS topic connection factory lookup name.	Yes	A string with only alphanumeric characters, underscores, and periods. Maximum length is 100 bytes.
logLevel	Logging level. A log level is a cut-off level which means logs with a lower level are filtered out.	No	Specify one of the following values, in low to high order. "VERBOSE": All logs. "DEBUG": Debug logs. "INFO": Informational logs. "WARN": Warning logs. "ERROR": Error logs. "SUPPRESS": No logs. If not specified, default is "INFO".
logFile	The path to the log file. Can be a relative or absolute path.	No	If not specified, output to the console.
clientID	JMS Client ID. Only required for a durable subscription. Not recommended for other use.	No	This must be a unique string for all JMS clients using the same connection factory.
durableSubscriptionName	A unique name for a durable subscription.	No	If a name is not provided, the subscription will be a transient subscription. This means messages are not queued up if the connection for the subscriber is lost or the subscriber is not running.

Here is a sample configuration file for RPAS JMS Subscriber:

java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///C:/Temp
topic=RPASEventTopic
topicConnectionFactory=RPASEventTopicConnectionFactory