Modeling Jeopardy and Notifications

13 Modeling Jeopardy and Notifications

This chapter describes how to model jeopardy and notifications in an Oracle Communications Order and Service Management (OSM) solution.

Best Practices for Using Notifications for Status Updates

Status values for an order item and for the whole order often need to be sent to the upstream system that submitted the original request. There are a number of ways to achieve this.

Status Update Strategies

Some common strategies for updating order status are:

Use an event notification triggered by a change to order data, or when an order reaches an order milestone; for example, completed. The notification runs an automation plug-in that sends a status message to the upstream system. The automation plug-in should have all of the values for status data defined in its view, in order to calculate an aggregated status value.

Be aware that there can be race conditions if multiple status updates are executed in parallel. Since each update is taking a snapshot at a particular moment, it is possible that none of the status updates will have a snapshot that includes all of the final values. This strategy is better used when there are no multiple concurrent status updates.

You also can use this strategy in conjunction with fulfillment state or processing states. However, for these two options, the calculation of the aggregated status value is handled by OSM before the event notification is triggered. The event notification can be configured against the order level fulfillment state or order item processing state. In this case there is no race condition as the event is only triggered on the top most data element when it is changed.
Configure an automation plug-in to generate a status message whenever the order changes state. Because order state changes are generally less frequent than data changes, this may provide better performance.
It is possible to configure status update functions as order components and make them first-class members of the orchestration plan. However, it is not desirable to do this in most circumstances, because this can quickly lead to a large increase in the number of tasks in the cartridge. If used, this option will work only if status updates are sent at a specific point in the orchestration plan, for example as the last function after provisioning and billing.

Strategies for Using Notifications

Some common uses for notifications are:

In general, jeopardy notifications are used for alerting order management personnel about something that should have happened but did not happen. By contrast, event notifications are based on events that have happened, and they are used more for communicating status information and for directing the order fulfillment process to the next step.
Communication with external systems is usually handled by automation plug-ins run by event notifications. For example, the progress of an order is typically monitored in external systems by tracking which parts of the order have been completed. To communicate that, you typically configure event notifications based on a change to order data or a change to task status.
Notifications intended for an internal audience (OSM users) are typically created using a notification type that, by default, sends a notification to the Task web client. The only notification types that do not are event notifications based on order data change and task state change notifications that run an automation plug-in. See "About Using Task States and Rules to Trigger Event Notifications" for more information.

Modeling Notifications

The following sections provides information about modeling notifications.

Using Task States and Statuses to Trigger Event Notifications

You can use task states and task statuses to trigger event notifications. For example, changing to the Failure status can trigger a notification to a fallout specialist. See "About Event Notifications" for more information.

About Notification Priority

You can specify a priority for most types of notifications. For example:

Notifications can be prioritized to control how they are sorted in the Task web client. You should prioritize jeopardy notifications higher than information messages.
Prioritizing notifications sent to external systems helps those systems process the more important notifications first.

OSM evaluates notifications with the highest priority first (1 is the highest priority). For notifications that are sent to external systems, the notification priority represents the JMS queue priority.

About Sending Notifications in Email

You can deliver notifications in email. The email message consists of the same information that is displayed in the Notifications window in the Task web client. You cannot customize the message or add information to it. The message template is:

You have a notification for Order ID ID number and notification ID
 notification ID. Use the following URL to connect to the notification details:
url

For most types of notifications, you specify to send email by selecting a check box in the notification configuration. For event notifications that are used only for running an automation plug-in, you configure the automation plug-in to send the email. See OSM Developer's Guide for information about automation.

To specify who to send the email to, you do the following:

When configuring the notification in Oracle Communications Design Studio, or in your automation plug-in, specify the roles that receive the notification.
Configure the email recipients for the roles by using the OSM Order Management web client. (Roles are called workgroups in OSM Administrator.)

About Configuring Entities to Support Notifications

Before you configure notifications, you need to configure the following entities:

You must create the roles to assign notifications to.
To trigger notifications based on a change to order data, you must first model the data. See "About Using Order Data Changes to Trigger Notifications" for information.

You can model automation plug-ins as you define notifications, but modeling automation plug-ins before you configure notifications is more efficient.

About Jeopardy Notifications

A jeopardy notification is a message that is sent to OSM users or users on other systems (for example, to return status to a CRM system). Jeopardy notifications are not event-driven; they use polling at specified intervals to identify processes or tasks in jeopardy.

OSM uses three methods to deliver jeopardy notifications:

By displaying a notification in the Task web client.
By sending email to users.
By using an automation plug-in to notify an external system. Each order jeopardy notification can map to one automation plug-in.

Jeopardy notifications can be defined for an order using the Order Jeopardy editor or the Order editor, or for a task using the Task editor. Many of the jeopardy properties are the same for orders and tasks; for example, you can specify the roles to notify and the rule to trigger the notification. However, defining a jeopardy notification for an order or a task allows you to use the order or task properties. For example:

You can trigger a notification based on the state of the order.
You can trigger a notification if a task has exceeded its expected duration.

You can use two methods to trigger a jeopardy notification:

Conditions; for example, if the order processing time has exceeded the expected duration.
Order rules; for example, you can define an order jeopardy notification based on a rule that evaluates a data condition where an order milestone is not equal to the Complete state and has a due date that is greater than the value specified in the condition. For example:

orderMilestone <>completion and dueDate>SpecifiedDate.

This checks to see if there are any orders that are not completed but that are supposed to be completed by today.

About Modeling Jeopardy Notifications

You can model jeopardy notifications for tasks and for orders. The following list describes where in Design Studio you can model jeopardy notifications:

Task editor: The Task editor Jeopardy tab is the only place to model task jeopardy notifications. For more information, see the topic on working with tasks in the Design Studio Modeling OSM Processes Help.
Order Jeopardy editor alone: The Order Jeopardy editor enables you to define detailed jeopardy conditions based on order states, including multiple states to be used as start and end states for the order jeopardy notification timer. The Order Jeopard editor also enables you to define order states during which the timer will pause. Although these order jeopardy notifications are not defined in the Order editor, they are still defined for a specific order. For more information, see the topic on working with jeopardy and event notifications in the Design Studio Modeling OSM Processes Help.
Order Jeopardy editor and operational jeopardy file: When you define an order jeopardy notification in the Order Jeopardy editor, you can choose to make that order jeopardy notification an operational order jeopardy notification. This means that you can define the order jeopardy in Design Studio, but the details of the order jeopardy notification can be changed at run-time without having to redeploy any cartridges. You can change the details of operational order jeopardy notifications by editing text files on the OSM system. You specify the names of the text files in the oms-config.xml file. For more information about the Order Jeopardy editor, see the topic on working with jeopardy and event notifications in the Design Studio Modeling OSM Processes Help. For more information about using the text file to define operational order jeopardy notifications, see the information about configuring OSM with the oms-config.xml file in OSM System Administrator's Guide.
Order editor: The Order editor Jeopardy tab provides simple order jeopardy modeling capabilities and works in basically the same way as the task jeopardy notification configuration. For more information, see the topic on working with orders in the Design Studio Modeling OSM Processes Help.

About Jeopardy Notification Triggering

OSM triggers jeopardy notifications in one of two ways, depending on where you modeled the order jeopardy notification.

If the order jeopardy notification has been modeled using the Order Jeopardy editor, either with the configuration defined in Design Studio or with an operational jeopardy defined in a text file, OSM triggers the notification using the following process:

When the timer starts for an order, OSM adds the notification to an internal list, sorted by the due date of the notification. The system frequently polls this list and retrieves the items that have come due.

Because this is a server-wide, internal, automatically generated list, you do not have to configure polling intervals for order jeopardy notifications defined in the Order Jeopardy editor.
OSM checks whether there are any rules that might restrict the notification from being triggered. For example, you might configure two jeopardy notifications, one that is triggered for orders from only business accounts and one that is triggered for orders from only residential accounts. Each notification might have a different email recipient, so the notification is only triggered for the correct recipient. The rule is checked after the conditions have been met to ensure that the latest version of the order data is used in the evaluation.
If a rule evaluates to true, the notification is triggered.

If the order jeopardy notification has been modeled using the Order editor or using the Task editor, OSM triggers the notification using the following process:

OSM polls in-flight orders and tasks to determine if a condition has been met. For example, the condition might be that a task has been in progress for longer than one hour. If the condition is met, OSM begins to process the notification.

You can specify how often OSM should poll to reevaluate the jeopardy condition. You can specify a polling interval in hours, days, weeks, or months. You can specify the day of the week (for example, Monday), or the day of the month (for example, the first day of the month). You can specify a date and time for OSM to begin polling. The default is the current date.

Tip:

When configuring notifications in the Order editor or the Task editor, consider the performance impact from polling for jeopardy notifications. For example, a configuration that polls every minute on one million orders has a much greater performance impact than polling every hour on one thousand orders.
OSM checks whether there are any rules that might restrict the notification from being triggered. For example, you might configure two jeopardy notifications, one that is triggered for orders from only business accounts and one that is triggered for orders from only residential accounts. Each notification might have a different email recipient, so the notification is only triggered for the correct recipient. The rule is checked after the conditions have been met to ensure that the latest version of the order data is used in the evaluation.
If a rule evaluates to true, the notification is triggered.

About Jeopardy Notification Conditions

You can trigger jeopardy notifications based on an order or task condition. For example, you can specify to send a jeopardy notification if a task has exceeded its expected duration.

The conditions you can use depend on whether you define the jeopardy notification in the Order Jeopardy editor, the Order editor, or the Task editor.

Specifying Jeopardy Notification Conditions in the Order Jeopardy Editor

When you define a jeopardy notification for an order using the Order Jeopardy editor, you can specify to trigger the notification based on the following:

The amount of time that an order has spent in one or more states. You can specify lists of order states that can do the following:
- start the timer
- stop and reset the timer
- pause the timer
For example, you can trigger a notification because an order entered the In Progress state 30 days ago, without counting any time the order spent in the Suspended state, and has not yet entered the Completed or Aborted states.

You can set the expected duration in one of the following ways:
- Setting a specific duration value
- Using the expected duration for the order
- Using an XQuery expression to set the value
- Using the value of a field on the order
Whether the order has reached a certain date without having reached one of a list of specified end states.

You can set the expected date in one of the following ways:
- Using an XQuery expression to set the value
- Using the value of a field on the order

Specifying Jeopardy Notification Conditions in the Order Editor

When you define an order, you can specify to trigger a jeopardy notification based on the following:

The amount of time that an order has been in the In Progress state. For example, you can trigger a notification if the order has been in the In Progress state for longer than 30 days.
The amount of time that an order has been in the Completed state. For example, you can trigger a notification if the order has been in the Completed state for longer than 30 days.
If the process duration has exceeded the expected duration. The value is based on elapsed time, regardless of the order states that the order might transition in and out of.
If the process duration has exceeded a duration that you define; for example, five days. This duration value starts at the creation task.

To determine the duration that the order has been in any of these conditions, OSM polls the system at an interval that you define.

Specifying Jeopardy Notification Conditions for a Task

When you define a task, you can specify to trigger a jeopardy notification based on the following:

If the process that the task is associated with has exceeded the expected duration.
If the process that the task is associated with has exceeded a duration that you define. This duration is measured starting with the creation task.
If the task has exceeded the expected duration.
If the task has exceeded a duration that you define.
If the order has exceeded a specified amount of time past when it was received (when the order is created in OSM).

To determine the duration that the order has been in any of these conditions, OSM polls the system at an interval that you define.

When you define a jeopardy notification in a task, and the task can have multiple instances, you can specify if the notification should be triggered for every task instance.

About Event Notifications

Event notifications are triggered by events. You do not specify polling intervals for event notifications. You can configure them to occur in the following cases:

When a task transitions through a task status. For example, you might trigger an event notification when a task transitions to the Failed status.

Event notifications triggered by transitions can be sent to a workgroup. See "About Using Task Transitions to Trigger Event Notifications" for more information.
When a task reaches a specified state. You can use two methods:
- You can use the task state to trigger an automated event notification. In this case, only the task state is evaluated (no rules are applied to evaluate a condition), and the notification runs an automation plug-in that handles the notification actions. For example, when a task reaches the Assigned state, you can automate an external lookup before allowing the workflow to continue. You do not specify roles or email delivery for the notification. See "About Using Task States to Trigger Automated Event Notifications" for more information.
- You can use the task state in combination with rules to trigger the event notification. In this case, you can specify a rule to evaluate conditions, the priority, if the notification can be delivered by using email, and the workgroups that receive the notification. See "About Using Task States and Rules to Trigger Event Notifications" for more information.
When you use the task state to trigger an automated event notification, the notification is run from all processes that include the task. When you configure a notification based on a task state change in a process, the notification is applicable only to the task within the process in which it is defined.
You can trigger an event notification when an order passes an order milestone. You use this type of notification to trigger an automation plug-in that handles the notification actions. You do not specify roles or email delivery for the notification. See "About Using Order Milestones to Trigger Event Notifications" for more information.
You can trigger an event notification when a change is made to order data. You typically use these notifications to update external systems (such as a CRM) with information about the progress of the order when a specific data element in the order data is changed. See "About Using Order Data Changes to Trigger Notifications" for more information.
You can trigger an event notification based on order life-cycle changes. OSM posts the these notifications to a pre-defined JMS queue. See "About Enabling Order Life-Cycle Events" for more information.

About Using Task Transitions to Trigger Event Notifications

An event notification based on a task transition does not apply to all instances of the task. It applies to a task only as it is used in a specific process. Therefore, to configure an event notification based on a task transition, you edit the process that includes the transition and apply the event notification to the transition. Figure 13-1 shows the configuration for a success transition in Design Studio. In this figure, the success transition is selected, and the event notification properties are defined below the process window.

Figure 13-1 Event Notification Based on Task Transition

Description of "Figure 13-1 Event Notification Based on Task Transition"

The event notification for a status change works as follows:

When the task status changes to the status that you define for the notification, the notification runs a rule to evaluate if the conditions are true.
If the conditions are true, the event notification is triggered.

When you use a task transition to trigger an event notification, you can specify an automation plug-in that the notification runs; however, an automation plug-in is not required.

About Using Task States and Rules to Trigger Event Notifications

An event notification triggered by a task state change and rules works as follows:

When the task state changes to the state that you define for the notification, the notification runs a rule to evaluate if the conditions are true.
If the conditions are true, the event notification is triggered.

For example, you can specify that when the Completed task state is reached, a rule evaluates if the billing address is in California.

This type of notification does not apply to all instances of the task. It applies to a task only as it is used in a specific process. Therefore, you create this type of notification when you create processes in Design Studio. Figure 13-2 shows how to assign an event notification to a task in a process. In this figure, the EnterAccountInformation task is selected, and the rule and state are defined in the Properties window Events tab below.

Figure 13-2 Notification Based on Task State and Rule

Description of "Figure 13-2 Notification Based on Task State and Rule"

You can specify an automation plug-in that the notification runs; however, an automation plug-in is not required.

About Using Task States to Trigger Automated Event Notifications

You can use a task state to trigger an automated event notification. In this case, only the task state is evaluated (no rules are applied to evaluate a condition), and the notification triggers an automation plug-in which handles the notification actions. This type of notification runs for every instance of the task, independent of the process that it is in. Event notifications triggered by task states are not displayed in the Task web client.

For example, you can define an automated notification that sends a notification when the task reaches the Assigned state. The event notification works as follows:

When the task reaches the Assigned state, a notification is created.
When the notification is created, the automation plug-ins run.

Figure 13-3 shows an event notification configured in Design Studio. Any time this task runs, the event notification is triggered when the task reaches the Completed state.

Figure 13-3 Event Notification Based on Task Status

Description of "Figure 13-3 Event Notification Based on Task Status"

About Using Order Milestones to Trigger Event Notifications

You can use an order milestone to trigger an event notifications. Figure 13-4 shows an event notification based on an order milestone.

Figure 13-4 Event Notification Based on an Order Milestone

Description of "Figure 13-4 Event Notification Based on an Order Milestone"

Only the order milestone is evaluated (no rules are applied to evaluate a condition), and the notification triggers an automation plug-in that handles the notification actions. Each event notification maps to one or more automation plug-ins. For more information about automation plugins, see "About Automation Plug-ins".

For example, you can define an event notification that specifies the Completion milestone. The event notification works as follows:

After all tasks within a process successfully complete for an order, the order Completion milestone is reached and a notification is created.
When the notification is created, the automation plug-ins run.

Note:

You cannot define custom order milestones. Order milestones are based on order states; for example, the Completion milestone occurs when the order transitions to the Completed state.

When you create event notification that is triggered by an order milestone, you specify the order milestone that triggers the notification. You can use the following order milestones:

Creation: The order was created in the OSM system.
Completion: The final task in the order has completed, and the order transitioned to the Completed state.
Deletion: The order was removed from the OSM system by transitioning to the Deleted state.
Exception: A process exception or fallout was initiated.
State change: The order transitioned to a different state.

About Using Order Data Changes to Trigger Notifications

You define event notifications based on order data changes when you create orders in Design Studio. For example, you can define an event notification that sends a notification when a telephone number is entered. Event notifications triggered by data changes are shown in the Task web client.

When you create an event notification based on order data changes, you can specify the data field that triggers the notification when the data is changed. Any change to the field causes the notification to trigger. However, this value is not evaluated for content. To trigger the notification based on the value of the data, you must configure a rule to evaluate it.

For example, to trigger a rule when the billing address is changed to California, you specify the billing address field as the field that triggers the notification and run a rule that evaluates if the address was changed to California.

You can specify an automation plug-in that the notification runs; however, an automation plug-in is not required.

Figure 13-5 shows an event notification based on data change in an order. In this example, when a credit card number changes, the notification is triggered.

Figure 13-5 Event Notification Based on Data Change in an Order

Description of "Figure 13-5 Event Notification Based on Data Change in an Order"

About Enabling Order Life-Cycle Events

You can configure orders to publish events when any of the following occurs:

The order is created.
The order is removed.
The order state changes.
Amendment processing starts.
Amendment processing is queued.
Amendment processing completes.
Amendment processing is terminating.
Amendment processing is terminated.
Amendment processing is abandoned.

Order life-cycle events are published to the oms_order_events queue as Java Message Service (JMS) messages containing order identification and state information. You can configure which life-cycle events you want to be generated for an order type in Design Studio.

Summary of Notification Functionality

Table 13-1 shows a summary of notification functionality.

Table 13-1 Summary of Notification Functionality

Notification Type	Sends Email	Displays in Task Web Client	Can Be Evaluated By a Rule	Can Be Sent to Different Roles	Runs Automation Plug-in	Has a Priority
Jeopardy - Task editor	Yes	Yes	Yes	Yes	Optional	Yes
Jeopardy - Order Jeopardy editor	Yes	Yes	Yes	Yes	Optional	Yes
Jeopardy - Order editor	Yes	Yes	Yes	Yes	Optional	Yes
Event - Task status	Yes	No	Yes	Yes	Optional	No
Event - Task state, automation	Sent by automation plug-in only	No	No	Defined by automation plug-in only	Mandatory	Yes
Event - Task state, in a process	Yes	No	Yes	Yes	Optional	Yes
Event - Order milestone	Sent by automation plug-in only	No	No	Defined by automation plug-in only	Mandatory	No
Event - Order data change	Yes	Yes	No	Yes	Optional	Yes