You use automation plug-ins to implement specific business logic automatically. You can create automation plug-ins to update order data, complete order tasks with appropriate statuses, set process exceptions, react to system notifications and events, send requests to external systems, and process responses from external systems.
When working with automation plug-ins, see the following topics:
When learning about automation plug-ins, see the following topics:
There are two basic types of delivered automation plug-ins: Sender and Automator. Each type can be implemented using XSLT or XQuery, and each type can be defined as an internal event receiver (the JMS message that triggers the call to the plug-in is generated by OSM) or as an external event receiver (the JMS message that triggers the call to the plug-in is generated by an external system).
Automator plug-ins receive information from OSM or from an external system, then perform some work. Depending on how you configure the plug-in, it can also update the order data. See "Predefined Automation Plug-ins" for sample XQuery and XSLT automators.
Sender plug-ins receive information from OSM or from an external system. They perform some business logic, and they may or may not update an order, depending on your configuration. Additionally, they can produce outgoing JMS or XML messages to an external system. When generating JMS messages, you can define JMS messages to connect to a topic or queue. See "Predefined Automation Plug-ins" for sample XQuery and XSLT senders.
Note:
XQuery automation types cannot be implemented when using releases prior to OSM 7.0.When you add an automated task to a process, you must associate at least one automation plug-in for the task. To associate an automation plug-in for a task, you open the automated task entity in the Automated Task editor, and add the plug-in to the task in the Automation tab. When you deploy your cartridge to the run-time environment, the OSM server detects a task that has an automation plug-in associated with it and the server triggers the plug-in to perform its processing.
An automated task might have only a single automation plug-in associated with it. For example, you might associate a built-in Automator plug-in with the task to interrogate the task data, perform some calculation, update the order data, and transition the task. In this example, as soon as the Automator plug-in has finished processing, it updates the task with an exit status, and the OSM server moves to the next task.
An automated task can have multiple associated automation plug-ins. For example, you might want to associate multiple plug-ins with a task to represent conversations with external systems. You can associate a built-in Sender plug-in to receive the task data and send it to an external system for processing. That external system might send an acknowledgment back to a queue, where a second Automator plug-in (one that is defined as an external event receiver: it receives data from external system queues) consumes the reply and updates the order data with the response. A third Sender plug-in might send the external system a message to begin processing, and a fourth Automator plug-in can receive the "processing complete" message from the external system, update the order, and transition the task.
Automation plug-ins defined as external event receivers are designed to process JMS messages from external systems. JMS messages are asynchronous, therefore external event receivers provide a method of correlating responses to requests previously delivered to enable you to map OSM orders to external system orders.
To correlate responses, the plug-in sets a property on the outbound JMS message, with the name of the value set for the correlation property in the automationmap.xml file and a value decided by your business logic.
For example, business logic might dictate that you correlate on a reference number. The external system copies the properties that you defined for the correlation on the request and includes that data in the response.
You can use the Message Property Selector field to filter messages placed on the queue and determine which automation to run. You define the Message Property Selector value as a Boolean expression that is a string with a syntax similar to the where clause of an SQL select statement. For example, the syntax may be:
"salary>64000 and dept in ('eng','qa')"
When the condition evaluates to true, the message is picked up and processed by the automation that defined that condition.
In a second example, consider that an external system defines five order types and OSM defines a different automation to process each order type. Each automation defines a different value in the Message Property Selector field, such as orderType=1, orderType=2, and so forth. When a message is sent to the queue by the external system, and the message includes the order type upon which the condition is based, the automation framework evaluates each condition until one evaluates to true. If more than one automation defines the same condition, the first one that evaluates to true is picked up and processed.
Note:
When you define only one automation plug-in external event receiver for each automated task, and you use the Optimized build-and-deploy mode to build and deploy automation plug-ins, you are not required to enter a selector in the Message Property Selector field. (For OSM 7.3 servers and later, Optimized is the only build-and-deploy mode available.) In this case, automated tasks can share the same JMS queue without a message property selector being set. You must set a message property selector when you do any of the following:Define multiple automation plug-in external event receivers for the same automated task.
Set up other applications (besides OSM) to share the same queue that an external event receiver is listening on.
Use the Legacy build-and-deploy mode to build and deploy cartridges with automation plug-ins.
Use the Both (Allow server preference to decide) build-and-deploy mode to build and deploy cartridges with automation plug-ins and configure the OSM server dispatch mode for the Internal mode.
For information on build-and-deploy modes, see "Defining Build-and-Deploy Modes for Automation Plug-ins".
Automation plug-ins enable you to extend OSM behavior by running specific business logic when events occur, sending and receiving data to and from external systems, and updating orders.
Design Studio supports two types of built-in automation plug-ins: Sender and Automator. Additionally, you can create your custom automation plug-ins using the custom automation plug-in template. You can, for example, write your own custom code to make CORBA or web services calls to external systems and register the custom plug-in against an automated task.
To create a custom automation plug-in:
From the Studio menu, select New, then select Order and Service Management, and then select Custom Automation Plug-in.
The Custom Automation Plug-in wizard is displayed.
In the Project field, select the project in which to save the new custom plug-in.
In the Name field, enter a name for the plug-in.
The name must be unique among the automation entity types within the same namespace.
Click Finish.
The Custom Automation Plug-in editor is displayed.
Click Select.
The Select Java Class dialog box is displayed. Select from the src folder the Java class that implements the automation interface. See OSM Developer's Guide for more information about Java classes and custom plug-ins.
Click OK.
In the XML template field, enter the XML required for the plug-in's implementation.
In the Documentation field, enter information about the plug-in.
After you add a plug-in to the Design Studio entity, you define the plug-in properties.
Note:
The type of automation (for example, an XSLT Sender) and the automation function (for example, a task event) determine which tabs appear in the Properties view.To configure automation plug-ins:
From the Studio menu, select Show Design Perspective.
In an OSM entity editor Automation subtab, select an automation plug-in. You can configure automation plug-ins in the following editors:
The Order editor Jeopardy tab Automation subtab.
The Order editor Notifications tab Automation subtab.
The Order editor Events tab Automation area.
The Manual and Automated Task editor Jeopardy tabs Automation subtabs.
The Manual and Automated Task editor Events tabs Automation subtabs.
The Process editor, flow lines with status transition defined in the Properties subtab Events subtab Automation subtab.
The Process editor exception path flow lines in the Properties subtab Events subtab Automation subtab.
The Process editor Automated and Manual Tasks in the Properties subtab Events subtab Automation subtab.
Click Properties.
The Properties view is displayed showing the automation plug-in properties tabs. If you selected properties from the process editor properties sub-tab, then the Properties view displays in a Additional Properties dialog box.
Click the Details tab.
In the Details tab, you can name the plug-in and identify the user whose credentials will be used to run the automation plug-in. See "Properties View Details Tab" for more information.
Click the Compensation tab.
Note:
This tab is called the Execution Mode tab in the Manual and Automated Task editor Events tabs Automation subtabs.In the Compensation tab, specify the execution modes in which the plug-in will run when called.
See "Properties View Compensation Tab" for more information.
(For external event receivers only) Click the External Event Receiver tab.
Define the name of the external system from which the plug-in receives messages. Additionally, you can define whether the plug-in filters for specific properties on the incoming message header or body. Finally, you can provide specific connection information if the messages are retrieved from an external system. See "Properties View External Event Receiver Tab" for more information.
(For external event receivers only) Click the Correlation tab.
Map messages from external systems to specific OSM tasks. You can use the JMSCorrelationID or enter an XPath expression to filter for a specific element in the XML body of the message. See "Properties View Correlation Tab" for more information.
(For XSLT types only) Click the XSLT tab.
Define where the XSLT style sheet is located, caching properties for the style sheet, and the exit status that the plug-in should use if it throws an exception.
See "Properties View XSLT Tab" for more information.
(For XQuery types only) Click the XQuery tab.
Define where the XQuery file is located, caching properties for the file, and the exit status that the plug-in should use if it throws an exception.
See "Properties View XQuery Tab" for more information.
Note:
XQuery automation types cannot be implemented when using releases prior to OSM 7.0.(For Sender types only) Click the Routing tab.
Define where the automation plug-in should send messages, and where the external systems should send responses. See "Properties View Routing Tab" for more information.
Click the Notes tab.
Document the intended use of the automation plug-in.
Click Save.
This example demonstrates how to configure an Automator plug-in that receives data from an internal OSM JMS queue and updates order data using an XSLT style sheet. In the example, assume that the XSLT style sheet includes conditional logic to apply a level 1 priority to the order if the order is from a specific customer.
This example demonstrates how to:
Create an automated task and add the relevant task data.
Add an automation plug-in to the automated task.
Configure the automation plug-in properties.
Note:
An automated plug-in exists within the context of a Design Studio cartridge project, order, process, and automated task. For purposes of demonstration, this example assumes the existence of multiple Design Studio entities. For example, it assumes the existence of a cartridge project called DSLCartridge, an order called DSLOrder, a process called DSLProcess, and an XSLT style sheet called check_customer.xslt that populates default values in the order data. It assumes that the Data Dictionary includes the two data nodes, customer_name and order_priority. It also assumes that the new automated task will be added to the DSLProcess entity. The naming conventions used in this example are for illustrative purposes only.Step 1: Creating the automated task
From the Studio menu, select New, then select Order and Service Management, and then select Automated Task.
The Automated Task wizard is displayed.
In the Automated Task wizard, enter or select the following values:
In the Project field, enter DSLCartridge.
In the Order list, select DSLOrder.
In the Name field, enter Check_Customer.
See "Creating New Tasks" for more information.
Click Finish.
The new automated task is displayed in the Automated Task editor.
Click the Task Data tab.
In this example, you will update the order_priority field with a default value of 1 if the order is from a specific customer.
Note:
Normally, the task data includes all of the data that the task requires to complete. To simplify the example, this task includes only the two pertinent fields: customer_name and order_priority. See "Defining Task Data" for more information.Right-click in the Task Data area and select Select from Data Schema.
The Select Data Elements dialog box is displayed.
Select the data nodes customer_name and order_priority.
Click OK.
The two data nodes are displayed in the Task Data area.
Click the Permissions tab.
On the Permissions tab, you can ensure that only the automation role has permissions for automated tasks. See the note in "Assigning Task Permissions" for more information.
You are now ready to add a plug-in to the automated task.
Step 2: Adding the automation plug-in to the automated task
In the Automated Task editor, click the Automation tab.
Click Add.
The Add Automation dialog box is displayed.
In the Name field, enter Check_Customer.
In the Automation Type field, select XSLT Automator.
Click OK.
The Check_Customer plug-in is displayed in the Automation list.
From the Automation list, select the Check_Customer plug-in.
Click Properties.
The Properties view is displayed showing the automation plug-in properties tabs.
You are now ready to define the automation plug-in properties.
Step 3: Defining automation plug-in properties
In the Automated Task editor Properties view Details tab, accept the default value in the EJB Name field.
Ensure that the model variable that defaults to the Run As field points to a user name set up in the WebLogic Server Administration console. When you deploy the cartridge, the user in the Run As field is added automatically to the OSM_automation group.
For more information about users and groups, see the discussion of setting up security in OSM System Administrator's Guide. For more information about model variables, see "Project Editor Model Variables Tab."
Click the XSLT tab.
On the XSLT tab, you define where the XSLT style sheet is located and the status to set if the automation fails. In this example, you define a location on your local machine where the XSLT file is stored.
Select Absolute Path.
In the XSLT field, enter the location of the XSLT file.
For this example, enter C:\oracle\user_projects\domains\osmdomain\xslt\DSLCartridge\1.0.0\check_customer.xslt.
In the Exception field, select Failure.
This field represents the exit status that the plug-in should use if it throws an exception. The options available in this field include any status values you assigned to the task.
Select Update Order.
This option ensures that the default values obtained from the XSLT style sheet are saved to the order data.
Click Save.
You have completed the basic configuration for an Automator plug-in defined as an internal event receiver.
Note:
Successful automation requires a complete automation build file in the cartridge. If no automation build file exists, Quick Fix generates one.