10 Extending Notifications

This chapter provides information about extending notifications in Oracle Communications Unified Inventory Management (UIM).

About Notifications

Notifications in UIM are messages that can optionally be sent to a user or a user group when a qualifying event occurs. By default, qualifying events relate to workflows and their activities, but notifications can be extended to other events. Notification messages inform the recipient that an event requires attention.

By default, UIM sends notifications when the following events occur:

An activity in a workflow is changed to the Ready state, which indicates a user or group can work on the activity.
An activity in a workflow is assigned to a user or a user group.

These events cause a notification to be sent to the user assigned to the activity. (For more information about activities and workflows, see UIM Concepts.)

Notifications are email messages by default. You can extend notifications to include other types of messages, such as Short Message Service (SMS) text messages. You can also customize message content. Additionally, you can extend notifications for other UIM events by creating custom events and handling these events using rulesets.

Note:

Notifications are sent only if the system administrator has configured UIM to send notifications.

About Extending Notification Functionality

You can customize the UIM notification functionality in the following ways:

By customizing the content and format of notification messages. You can specify the message text or template that is sent to users. You can format messages by using HTML markup, or you can use simple text format. You can use variables in message template strings. The variables are replaced in notification messages by values that are retrieved at the time the messages are sent. See "Understanding Notification Message Content" for more information about the structure and syntax of templates and variables.
By changing the type of notification message sent or sending multiple types of messages. You customize the type of message sent by using different Java handler classes. UIM includes a handler for email messages by default. To send other types of messages, such as SMS text messages, you create a custom handler. See "Changing the Type of Notification Messages Sent" for more information.
By setting up notifications for additional types of events. For example, you might want to send an email when a service moves to a pending disconnect status. See "Adding Notifications for Additional Events" for more information.

When you customize UIM notification functionality, you supply the following information in the system-config.properties file:

The names of the handler classes used for different message types
The message template string
The name of the resolver class used to resolve variables in the message template string

See "System Configuration Properties for Notifications" for a list of the notification properties you set in the system-config.properties file.

Understanding Notification Message Content

The content of a notification message consists of a message template and variables within that template. When a qualifying event occurs, the notification framework resolves the variables and sends the message.

The following sections describe the structure of variables and templates.

Understanding Message Variables

A notification message variable is a value that can be different in each notification. When generating an event, the Java notification resolver classes substitute values retrieved from the event for the variables in the template.

For example, you might use a variable to represent the sender of the message. When the notification message is generated, the sender's name or address is retrieved and is inserted into the message content.

Variables have the following syntax:

${variableName}

where variableName is the name of the variable.

For example, the variable ${activityName} in a message template represents the name of an activity. When a notification message is generated, the activity name (for example, “Print Reports") replaces the variable in the notification message.

If you want to use custom variables, you can create a custom Java resolver class that looks up and resolves each variable. For example, the resolver class can look up the following:

A value from the activity event object
A value from an API call
A value from a customized property file

See "Customizing Message Content and Format" for additional examples of variable references in message templates.

Understanding Message Templates

Message templates provide the text that is included in every notification for a particular event. UIM includes a default message template for email notification messages. You can define your own template to modify the message content for email messages or to define content for other types of messages. The message string is the value of a configuration property in the system-config.properties file.

You define message templates in the inventory.EventClassName.message.template property in the system-config.properties configuration file. EventClassName represents the name of your Java event class. You enter the full text and formatting marks of the message template in the inventory.EventClassName.message.template property.

See Table 10-1 "Table 10-1" for additional information on this and other notification properties.

Notification message templates can have these formats:

Rich text format using HTML tags. You use HTML tags to apply formatting to the text, such as bold, color, fonts, and so on.
Simple text format that includes line feed characters (\n).

Both rich text and simple text templates can include variables.

Message Templates in HTML Format

You can use HTML tags to apply formatting to the message templates. Example 10-1 shows an email message template in HTML format that includes several different variables. Some variables are enclosed with quotation characters (\") when the quotes are desired in the output text. This example template is also the UIM default template.

Note:

This example includes extra white space for readability. You do not include extra white space in the template property value.

Example 10-1 Example Email Message Template in HTML Format

<html>
    <body>
        <pre>
            <span style=\"font-family: tahoma, arial, helvetica,
                    sans-serif; font-size: small;\">${notificationReceiver},
                <br />
                <br /> An activity named 
                <strong> \"${activityName}\"</strong> from Work Order 
                <strong>\"${workOrderName}\"</strong> which is assigned to you, is
                    ready for action. 
                <br />
                <br /> Please note that this activity should start on 
                <span style=\"color: #008000;\">
                    <strong>${activityStartDate}</strong>
                </span> and finish no later than 
                <strong>
                    <span style=\"color: #ff0000;\">${activityEndDate}</span>
                </strong>. 
            </span>
            <br />
            <br />
            <span style=\"font-family: tahoma, arial, helvetica, sans-serif;
                font-size: small;\"> Login to 
                <a href=\"${uimURL}\">Unified Inventory Management Application</a>
                to check the details. 
            </span>
            <br />
            <br />
            <br />
            <span style=\"font-family: tahoma, arial, helvetica, sans-serif;
                font-size: small;\"> Thanks,</span>
        </pre>
        <pre>
            <span style=\"font-family: tahoma, arial, helvetica, sans-serif;
                font-size: small;\"> ${notificationOriginator}</span>
        </pre>
    </body>
</html>

Figure 10-1 shows the email text that is the result of the template in HTML format in Example 10-1.

Figure 10-1 Email Message from an HTML Template

Description of "Figure 10-1 Email Message from an HTML Template"

Example 10-2 shows how the example email template in HTML format is set as the value of the inventory.ActivityAssignmentEvent.message.template property.

Example 10-2 Example Email Message Template (HTML) as a Property Value

inventory.ActivityAssignmentEvent.message.template = <html><body><pre><span style=\"font-family: tahoma, arial, helvetica, sans-serif; font-size: small;\">${notificationReceiver},<br /><br /> An activity named<strong> \"${activityName}\"</strong> activity from Work Order <strong>\"${workOrderName}\"</strong> has been assigned to you. <br /> <br /> Please note that this activity should start on <span style=\"color: #008000;\"><strong>${activityStartDate}</strong></span> and finish no later than <strong><span style=\"color: #ff0000;\">${activityEndDate}</span></strong>. </span><br /> <br /><span style=\"font-family: tahoma, arial, helvetica, sans-serif; font-size: small;\"> Login to <a href=\"${uimURL}\">Unified Inventory Management Application</a> to check the details. </span><br /><br /><br /><span style=\"font-family: tahoma, arial, helvetica, sans-serif; font-size: small;\"> Thanks,</span></pre><pre><span style=\"font-family: tahoma, arial, helvetica, sans-serif; font-size: small;\"> ${notificationOriginator}</span></pre></body></html>

Message Templates in Simple Text Format

You can use minimal text formatting in message templates. Example 10-3 shows an email message template in simple text format.

Note:

This example includes extra white space for readability. You do not include extra white space in the template property value.

Example 10-3 Example Email Message Template in Simple Text Format

${notificationReceiver}, \n\n  

An activity named \"${activityName}\" from Work Order \"${workOrderName}\" has been assigned to you. \n\n  

Please note that this activity should start on ${activityStartDate} and finish no later than ${activityEndDate}. \n\n  

Login to ${uimURL} to check the details. \n\n 

Thanks,\n\n 
${notificationOriginator}

Example 10-4 shows how the example email template in simple text format is set as the value of the inventory.ActivityAssignmentEvent.message.template property.

Example 10-4 Example Email Message Template (Simple Text) as a Property Value

inventory.ActivityAssignmentEvent.message.template = ${notificationReceiver}, \n \n  An activity named \"${activityName}\" from Work Order \"${workOrderName}\" has been assigned to you. \n \n  Please note that this activity should start on ${activityStartDate} and finish no later than ${activityEndDate}. \n \n  Login to ${uimURL} to check the details. \n\n Thanks,\n\n ${notificationOriginator}

Extending Notifications

This section explains how to extend the notification functionality. You can extend the functionality to alter message content, notification type, or behavior. You can:

Alter the message content of the message using property settings without making additional changes. For this extension, you only need to add the new template definition in the system configuration property file.
Alter the content and the variables of the message. For this extension, you add the template text and provide a resolver class. The resolver class is specified with a configuration property.
Alter the type of notification messages that UIM sends or alter the behavior of the default email message. For this extension, you specify one or more handler classes in the configuration properties. For example, the handler classes can change the functionality by:
- Retrieving the recipients of the message from a third-party system.
- Determining the type of notification to send, such as email, SMS or another type.
- Sending multiple types of notification messages for one event.
- Tailoring the subject of the message depending on some other criteria.
Alter the notifications for additional custom events. For this extension, you specify one or more handler classes in the configuration properties.

Customizing Message Content and Format

You can customize the content and format of notification messages by defining a message template. The message content in your template can include variables.

To customize notification message content and format, you perform the following tasks:

In the UIM_Home/config/system-config.properties file, where UIM_Home represents the directory into which UIM was installed, define the message template. You define the message template as the value of the inventory.EventClassName.message.template property, where EventClassName represents the name of your Java event class. Add a property entry for each event type to which the template applies, or to the InventoryEvent event class if the generic class applies.

See "Understanding Notification Message Content" for information about the syntax of the template value.
If your message template includes variables, do the following:
- Create a custom resolver class to resolve the variables and replace them with values in the notification messages. The resolver class must extend the StrLookup class in the Apache Commons project.
  
  For information about the StrLookup class, refer to the Apache Commons project website:
  
  https://commons.apache.org/
- In the system-config.properties file, specify your custom resolver class as the value of the inventory.EventClassName.variable.resolver property, where EventClassName represents the name of your Java event class. Add a property entry for each event type to which the template applies.

For more information about the notification properties in the system-config.properties file, see "System Configuration Properties for Notifications".

Changing the Type of Notification Messages Sent

You can change the type of notification messages that UIM sends. You can also send additional types of messages, such as SMS text messages.

To change the type of notification message sent, you perform the following tasks:

Create a custom Java handler class that handles the new message type. For simplicity, create a handler class for each type of message that you want to send. Your custom handler classes must extend the NotificationHandler class.
In the UIM_Home/config/system-config.properties file, specify your custom handler class in the value of the inventory.event.EventClassName.handler.list property. To specify multiple handler classes, separate the class names with a comma. UIM invokes the handlers in the order you list them.
(Optional) If you want to define a new notification message template or modify an existing template for the new message type, perform the tasks described in "Customizing Message Content and Format".

See "System Configuration Properties for Notifications" for more information about the notification properties in the system-config.properties file.

Adding Notifications for Additional Events

You can extend UIM notifications to include additional events. To add a notification for a new event class, you perform the following tasks:

Create a custom Java event class that extends InventoryEvent class.
Create a custom Java handler class that handles the new event class. Your custom handler classes must extend the NotificationHandler class.
In the UIM_Home/config/system-config.properties file, specify your custom handler class in the value of the inventory.event.EventClassName.handler.list property. To specify multiple handler classes, separate the class names with a comma. UIM invokes the handlers in the order you list them.
Define a new notification message template for this new event class. Refer to the tasks described in "Customizing Message Content and Format" for more information on this topic.
Create ruleset logic to inject code for any API manager method with an extension point. You include the handling of the new custom event in the rule logic.

Refer to "Extending UIM Through Rulesets" for more information on rulesets and extension points.

Your new custom event class includes the following:

A constructor where you set the message information for this event, such as the subject and handler classes.
A populateValueMap() method that returns a HashMap of the variable values.
(Optional) A getUIMUrl() method if you need direction navigation from the email template to a specific UIM web page.

Example 10-5 gives an example of a constructor for a custom event class.

Example 10-5 Code Example for a Custom Event Class Constructor

public CustomEvent() {

String propertyName = "inventory." + this.getClass().getSimpleName() +
   ".message.template";
// get the template from the property file
setNotificationMessage(SystemConfig.getInstance().getProperty(propertyName,
    DEFAULT_MESSAGE_TEMPLATE));
List<NotificationHandler> notificationHandlerList = 
    new ArrayList<NotificationHandler>();
// get the list of handlers from the property file
notificationHandlerList.add(NotificationHandlerFactory.getNotificationHandler(
    NotificationType.Email));
setNotificationHandlers(notificationHandlerList);
String subject = MessageResource.getMessage("custom.event",null);
setNotificationSubject(subject);
}

Example 10-6 gives an example of a populateValueMap() method for a custom event class.

Example 10-6 Code Example of a populateValueMap() method for a Custom Event

protected Map<String, String> populateValueMap() {
        HashMap<String, String> valuesMap = new HashMap<String, String>();
        valuesMap.put("notificationReceiver",  this.getUserDisplayName(this.getNotificationReceiver().get(0)));
        valuesMap.put("activityName", this.getActivityName());
        valuesMap.put("workOrderName", this.getWorkOrderName());
        valuesMap.put("activityStartDate", this.getActivityStartDate());
        valuesMap.put("activityEndDate", this.getActivityDueDate());
        valuesMap.put("uimURL", this.getUIMUrl());
        valuesMap.put("notificationOriginator", this.getUserDisplayName(this.getNotificationOriginator()));
        return valuesMap;
    }

Example 10-7 gives an example of a getUIMUrl() method for a custom event class.

Example 10-7 Code Example of a getUIMUrl() method for a Custom Event

private static final String ACTIVITY_URL =
"http://${SERVER}:${PORT}/Inventory/faces/adf.task-flow?adf.tfId=MasterFlow&adf.tfDoc=/WEB-INF/MasterFlow.xml&objectId=${ActivityOid}&entity=Activity&workOrder=${WorkOrderOid}";
.
.
.
public String getUIMUrl() {        
    String serverDetails = super.getUIMUrl();
    String[] serverDetailsArray = serverDetails.split(":");
    String serverName = serverDetailsArray[0];
    String serverPort = serverDetailsArray[1];
    HashMap<String, String> valuesMap = new HashMap<String, String>();
    valuesMap.put("SERVER", serverName);
    valuesMap.put("PORT", serverPort);
    valuesMap.put("ActivityOid", this.getActivityOid());
    valuesMap.put("WorkOrderOid", this.getWorkOrderOid());
    StrSubstitutor substitutor = new StrSubstitutor(valuesMap);
    String url = substitutor.replace(ACTIVITY_URL);
    return url;
}

Overview of Notification Java Classes

This section provides an overview of the Java classes that support UIM notification functionality. The Java classes are grouped into the following categories:

Container or data classes that are the event classes
Behavioral classes that are the handler and utility classes
Internal UIM classes

Notification Functionality Class Diagram

The primary Java notification classes and their relationships are represented in Figure 10-2. The factory classes (EventFactory and NotificationHandlerFactory) create the specific instances of event or handler classes. ActivityAssignmentEvent and ActivityReadyEvent extend the abstract InventoryEvent class. EmailHandler, the UIM handler class, extends the abstract NotificationHandler class. MailMessenger is called by EmailHandler. The InventoryEvent class calls the custom resolver class, when it is provided, in an extension.

Figure 10-2 Notification Functionality Class Diagram

Description of "Figure 10-2 Notification Functionality Class Diagram"

About Event Java Classes

This section describes the classes used to manage the event data. These classes include getter and setter methods for the event data. The constructor sets many of the member values.

InventoryEvent Java Class

The InventoryEvent Java class is an abstract base class for ActivityAssignmentEvent and ActivityReadyEvent. You can create your own custom events by extending InventoryEvent. This base class maintains the generic notification data. The InventoryEvent class has getter and setter methods for the following attributes:

The notificationOriginator string indicates the originating email of this event, such as the user or user group source of the email.
The notificationMessage string is the content of the notification message.
The notificationSubject string is the subject of the notification.
The notificationReceiver is a Java list of strings indicating who is being notified.
The notificationHandler is a Java list of NotificationHandler objects that represents the Java handler classes. The handler classes determine the notification behavior of event instances that extend InventoryEvent. See "Handler Classes" for definitions of the Java handler classes used for notifications.
The copyNotificationTo is a Java list of strings indicating who is being copied on the notification. The strings specify the recipients' email addresses. This attribute is used only in extensions of the notification functionality.

Example 10-8 illustrates the package location and the declaration of the InventoryEvent class.

Example 10-8 InventoryEvent Class Declaration

package oracle.communications.inventory.api.framework.event;
public abstract class InventoryEvent

Activity Event Java Classes

The ActivityAssignmentEvent and ActivityReadyEvent classes manage activity event notification data. ActivityAssignmentEvent encapsulates the data required to notify users when they are assigned activities. ActivityReadyEvent encapsulates the data required to send a notification when an activity is in the Ready state. These classes have getter and setter methods for attributes, such as activity start date, activity due date, and activity name. The activity event classes extend the InventoryEvent class.

Example 10-9 illustrates the package location and the declaration of the ActivityReadyEvent class.

Example 10-9 ActivityReadyEvent Class Declaration

package oracle.communications.inventory.api.framework.event;
public class ActivityReadyEvent extends InventoryEvent

Example 10-10 illustrates the package location and the declaration of the ActivityAssignmentEvent class.

Example 10-10 ActivityAssignmentEvent Class Declaration

package oracle.communications.inventory.api.framework.event;
public class ActivityAssignmentEvent extends InventoryEvent

About Notification Behavior Java Classes

This section describes the classes used to manage the notification behavior and message variables. The handler and resolver classes do not have getter and setter methods.

Handler Classes

When an event occurs, the Java notification handler classes determine the behavior of the notification for the following:

The recipients for the message
The mechanisms to look up the message addresses
The subject of the message
The originator of the message
The type of notification message to send, such as sending an email or a text

UIM includes the default EmailHandler notification handler class. A handler class must implement the interface NotificationHandler.

Resolver Classes

The Java resolver classes resolve the variables in the message templates for an event class. You can use the same resolver class for multiple types of notification messages. The resolver class looks up a variable string key and provides a string value result. You must define this class to extend the class StrLookup in the Apache Commons project. See "Understanding Message Variables" for more information on variables.

Note:

For information about the StrLookup class, refer to the Apache Commons website:

https://commons.apache.org/

Overview of Internal Notification Java Classes

This section describes the Java classes that are part of the notification functionality but are internal to UIM. They are included in the documentation to provide clarity on the usage of all classes. The internal classes do not have getter and setter methods.

Factory Classes

The Java notification factory classes provide instances of the notification classes. The EventFactory class creates the event classes, and the NotificationHandlerFactory class creates a list of NotificationHandler classes.

NotificationType Class

The NotificationType class is an enumeration class that identifies the type of notification message to send. Example 10-11 show the class declaration, which enumerates the Email and SMS message types.

Example 10-11 NotificationType Enum Class

public enum NotificationType {
    Email,
    SMS
}

MailMessenger Class

The Java MailMessenger class is a utility class that sends email messages. The MailMessenger class does not have getter and setter methods. This class holds a private constant that identifies the mail session name.

Note:

The system administrator must configure the server to set up the mail session as a postinstallation step after UIM is installed. For more information about this topic, see UIM Installation Guide. For more information about managing the email addresses for users and user groups, see UIM System Administrator's Guide.

System Configuration Properties for Notifications

This section describes the system configuration properties that you set when you customize UIM notification functionality. You add the properties to the system-config.properties file in the UIM_Home/config directory, where UIM_Home represents the directory into which UIM was installed. By default, these properties are not in the properties file; you add them only to extend the notification functionality.

When specifying the property name that includes an event name, you include the name of the event Java class for which to send notifications. For instance:

inventory.event.EventClassName.list

The property applies to that event class and to all its subclasses. The general syntax of the property entries is a name and value pair:

property_name=value

For properties that can have multiple values, such as the handler list properties, values must be separated by a comma. For example:

inventory.event.InventoryEvent.handler.list=CustomEmailHandler,CustomSMSHandler

The syntax of the message template property values depends on how you want to format the notification message. See "Understanding Notification Message Content" for information about how to specify the template value.

Table 10-1 describes the notification properties you set in the system-config.properties file.

Table 10-1 System Configuration Properties for Notifications

Property	Description
inventory.event.ActivityAssignmentEvent.handler.list	A comma-delimited list of Java handler classes that handle notifications when an activity event is assigned to a user. This handler list takes precedence over the generic event handlers defined in the inventory.event.InventoryEvent.handler.list property.
inventory.event.ActivityReadyEvent.handler.list	A comma-delimited list of Java handler classes that handle notifications when an activity event is moved to the Ready state. This handler list takes precedence over the generic event handlers defined in the inventory.event.InventoryEvent.handler.list property.
inventory.event.InventoryEvent.handler.list	A comma-delimited list of Java handler classes that handle notifications for all events. This handler list takes lower precedence than the specific event handlers defined in the ActivityAssignmentEvent and ActivityReadyEvent properties.
inventory.event.EventClassName.handler.list	A comma-delimited list of Java handler classes that handle notifications for a custom event where EventClassName is the name of the custom event class.
inventory.ActivityAssignmentEvent.message.template	Defines the notification message template. The template provides the static text of the notification message for the ActivityAssignmentEvent and can include variables that are resolved by the Java resolver class.
inventory.ActivityReadyEvent.message.template	Defines the notification message template. The template provides the static text of the notification message for the ActivityReadyEvent and can include variables that are resolved by the Java resolver class.
inventory.EventClassName.message.template	Defines the notification message template. The template provides the static text of the notification message for a custom event where EventClassName is the name of the custom event class.
inventory.ActivityAssignmentEvent.variable.resolver	Specifies the Java resolver class name. This class determines the variable values in the message template for the ActivityAssignmentEvent event class. This resolver class looks up a variable string key and provides a string value result.
inventory.ActivityReadyEvent.variable.resolver	Specifies the Java resolver class name. This class determines the variable values in the message template for the ActivityReadyEvent event class. This resolver class looks up a variable string key and provides a string value result.
inventory.EventClassName.variable.resolver	Specifies the Java resolver class name. This class determines the variable values in the message template for a custom event where EventClassName is the name of the custom event class. This class looks up a variable string key and provides a string value result.
uim.host.name	Specifies the server host name. This is the Oracle WebLogic Server host name where UIM runs. This property is used in building the URL in the default email template text.
uim.host.port	Specifies the server port. This is the Oracle WebLogic Server port where UIM runs. This property is used in building the URL in the default email template text.