bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Platform > WebLogic Integration > BPM Topics > Using the Studio > Configuring Workflow Resources |
Using the Studio |
Configuring Workflow Resources
This section describes how to configure system and application components, and includes:
Overview of Resource Configuration Tasks
All of the tasks described in this section can be performed before or during workflow design, but the resources described can be configured without accessing workflow templates. In some cases, workflow design activities are actually dependent on these resources having been set up already, such as business operations, which must be defined before a workflow can call them. Once the resources are defined, they are available globally for access by all workflows, users, and organizations in the system. These tasks do not need to be performed in any particular order.
Note: You may also want to familiarize yourself with the workflow expression language and the Studio's Expression Builder and XPath Wizard tools if you will be configuring event keys. Complete information on workflow expressions is available in Using Workflow Expressions.
Configuring Plug-Ins
A plug-in is a group of Java classes implemented as EJBs that extend the functionality provided in selected workflow components. Plug-ins provide a way to customize existing WebLogic Integration features so they are more appropriate for your environment, and to add functionality that is specific to your environment.
A plug-in can extend the functionality of the following workflow components:
If a plug-in is developed for any of these workflow components, the Studio dialog box for these components is also modified to include a way for you to access the plug-in's functionality. For example, the Studio provides several default methods in the Properties dialog box of a Start node to trigger the start of a workflow: timed, manual, called, and event. To extend the default methods, a developer can create a plug-in that specifies a custom event to trigger a workflow, such as receiving an e-mail message, which might be the preferred method for starting workflows in your environment. This plug-in method will appear as an option in the Start Properties dialog box.
Once a plug-in is developed and is deployed on WebLogic Server, it is available for use by WebLogic Integration. When WebLogic Integration starts, it checks WebLogic Server to see if any plug-ins are available on the server.
Before you can use an available plug-in, you must load it using the Studio to activate it. You might also need to specify some configuration settings for the plug-in before you can use it.
Note: To load or configure a plug-in, you must have Configure Components permission. For details about permission levels, see Assigning Permissions to Users and Roles.
Viewing Plug-ins
To view a plug-in, choose Configuration
Figure 4-1 Plugin Configurations Dialog Box
The information displayed for each plug-in is explained in the following table.
You can also obtain information about a plug-in by selecting the plug-in from the list and clicking About. Loading Plug-Ins If a plug-in's start mode is manual, you can load it each time a WebLogic Integration server session is started. If a plug-in's start mode is disabled, you must first change it to manual or automatic before you can load it. To load an initialized plug-in:
To load a disabled plug-in:
The status of the plug-in changes to Loaded in the list.
Note: Changes to the plug-in's start mode do not take effect until the WebLogic Integration server is restarted.
Updating a Plug-In Configuration
To configure a plug-in:
Deleting a Plug-In Configuration
You can delete a configuration for a plug-in if you no longer need the configuration. When you delete a configuration, you do not delete the plug-in itself. You just delete its registered configuration.
Note: You cannot delete the configuration of a plug-in unless the status of that plug-in is Missing.
To delete a configuration:
The following table describes the actions that occur when you restart the WebLogic Integration server after a plug-in configuration has been deleted.
Configuring Business Operations
To enable workflows to invoke software components that perform business logic, such as Java classes and Enterprise JavaBeans (EJBs), you define business operations. A business operation represents a method call on a Java class or EJB, including any variables that are passed to it as parameters, and result values that are returned to the workflow. You can use the business operations facility to create customized functions that invoke existing applications or applications that are built specifically for the workflow. The business operations facility displays all Java classes and EJBs registered in WebLogic Server, as well as their methods and parameters.
Note: For information about deploying Java classes and EJBs so that they are visible in the Studio, see "Deploying EJBs and Java Classes for Business Operations" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.
Once the business operation is defined, it is then globally available for all workflows in the system to invoke. You can also export and import business operations as part of Java archive package files, with or without the workflows that reference them (for more information, see Importing and Exporting Workflow Packages.)
Within an individual workflow, you use the Perform Business Operation action to invoke the business operation and, optionally, assign the results of the method call to a workflow variable. For more information, see Calling a Business Operation.
Note that before a workflow can call a method on an EJB or a non-static method on a Java class, the workflow must call its constructor method to create an instance of the EJB or Java class on the server. Therefore, you must be sure to create a business operation for the create() method of EJBs and a constructor method of Java classes, and a variable to store a reference to the instance. More information is provided in the following sections, which describe how to add and define business operations for each Java component type, and in Calling a Business Operation, which describes the steps for calling the necessary methods and assigning variables. An example of defining business operations is also provided in "Creating and Performing a Business Operation: Defining the Check Inventory Task" in Learning to Use BPM with WebLogic Integration.
Note: To add, define, or delete a business operation, you must have Configure Components permission. For details about permission levels, see Assigning Permissions to Users and Roles.
Viewing Business Operations
To view a business operation, choose Configuration
Figure 4-2 Business Operations Dialog Box
The information displayed for each business operation is explained in the following table.
Adding a Business Operation To create and define a business operation:
Figure 4-3 Define Business Operation Dialog Box
Adding a Business Operation for a Java Class
If you are creating business operations for non-static methods in a Java class, you must also create a business operation for a constructor method for the class. (Details are given in Calling the Business Operation to Create an EJB or Java Class Instance.) Be sure to give this business operation a meaningful name that identifies its function, as it will need to be called from the workflow before any non-static methods in the class may be called. You will also need to create a variable of type Java Object to hold a reference to the Java class instance when the instance is created at run time. For information on variables, see Working with Variables.
Finally, when you name your business operation, it is a good idea to indicate whether the business operation calls a static or non-static method, so the workflow designer will know whether or not a constructor method needs to be called first.
To define a business operation for a Java class, proceed as follows:
Figure 4-4 Java Class Name Dialog Box
Figure 4-5 Define Business Operation Dialog Box: Java Class Option
Figure 4-6 Parameter Dialog Box
Adding a Business Operation for a Session EJB
In addition to creating business operations that call methods that provide business logic for your workflow, you must create a business operation for the create() method of the Session EJB whose methods you are calling via a business operation. (Details are given in Calling the Business Operation to Create an EJB or Java Class Instance.) Be sure to give this business operation a meaningful name that identifies its function, as it will need to be called from the workflow in each transaction that calls other methods. You will also need to create a variable of type Session EJB to hold a reference to the EJB instance when the instance is created at run time. For information on variables, see Working with Variables.
All Session EJBs deployed on WebLogic Server are displayed in a list in the Define Business Operations dialog box according to their Java Naming and Directory Interface (JNDI) name.
Figure 4-7 Define Business Operation: Session EJB Option
To define a business operation for a Session EJB:
Adding a Business Operation for an Entity EJB
In addition to creating business operations that call methods that provide business logic for your workflow, you must create a business operation for the create() method of the Entity EJB whose methods you are calling via a business operation. (Details are given in Calling the Business Operation to Create an EJB or Java Class Instance.) Be sure to give this business operation a meaningful name that identifies its function, as it will need to be called from the workflow before other methods in the EJB may be called. You will also need to create a variable of type Entity EJB to hold a reference to the EJB instance when the instance is created at run time. For information on variables, see Working with Variables.
All Entity EJBs deployed on WebLogic Server are displayed in a list in the Define Business Operations dialog box according to their JNDI name.
Figure 4-8 Define Business Operation: Entity EJB Option
To define a business operation for an Entity EJB:
Updating a Business Operation
When updating a business operation, you should be sure to update any Perform Business Operation actions that reference the business operation from workflows. For more information on this action, Calling a Business Operation.
To update a business operation:
Deleting a Business Operation
Warning: Before deleting a business operation, make sure that the business operation is not referenced by any workflows using the Perform Business Operation action, or you will not be able to activate the workflow. When making a deletion, you will not be warned if any references exist, so be sure to update the Perform Business Operation action accordingly (for information, see Calling a Business Operation).
To delete a business operation:
Configuring Event Keys
A workflow can be started, or nodes within a workflow triggered, by an event. An event is an asynchronous notification from another workflow or from an external source, such as another application. Start nodes can be defined as event-triggered, and Event nodes are always asynchronous nodes that can only be triggered by an external event.
An event notification most typically takes the form of an XML document contained in a Java Message Service (JMS) message and received on a JMS queue, although it may also be plug-in defined, which means that the event notification can be a custom trigger rather than an XML document. (For more information, see Programming BPM Plug-Ins for WebLogic Integration).
In an XML event type, the actual trigger is either the document type declaration (DOCTYPE) specified in the prolog of the XML message, or it is the root element of the XML message. You specify the DOCTYPE or root element with which you want to trigger the event or start the workflow in a Start or Event node's properties dialog box. The event is not triggered unless the DOCTYPE or root element specified in the node's properties dialog box matches that in the incoming XML message.
In addition to using the DOCTYPE or root element, you can further qualify an event with an event key. An event key allows you to specify the contents of incoming XML messages or of JMS header or property fields that will trigger a Start or Event node. That is, rather than allowing all incoming XML documents with a particular DOCTYPE or root element to trigger the node, you can filter the instances of incoming XML messages according to specific values contained in the document or header, so that only a message, or messages, containing those values can trigger the node in the running workflow.
An event key consists of two parts:
You specify the key value expression in the Properties dialog box for Start or Event nodes. The key value expression is a workflow expression that is evaluated at run time to specify the exact data that the incoming message must contain for the node to be triggered. In a Start node, the expression typically contains a constant that refers to particular, recurring data contained in the incoming XML document, or it could be the value of a JMS header. In an Event node, the expression typically contains variables or functions to obtain a unique value at run time. Examples of key value expressions are given in Understanding Event Keys and steps for defining key value expressions are given in Defining Event-Triggered Start Properties and Defining Event Properties.
This is an expression that returns the key value from the header or body of the incoming message at run time and converts it to the data type required by the corresponding key value expression in a Start or Event node. You specify the event key expression in an event key expression dialog box that you access from the Configuration menu. The expression typically contains an XPath language expression to parse the XML document, or an EventAttribute() function expression to extract a value from a JMS message header.
In the event key configuration, you specify an event descriptor, which corresponds to the DOCTYPE or root element specified in a Start or Event node properties dialog box. You then specify an event key expression, which corresponds to a key value expression defined in the Start or Event properties dialog box, so that the process engine can compare the two values at run time and determine if there is a match. The relationship between event descriptors and DOCTYPE/Root elements, and between event key expressions and key value expressions is discussed more fully, with examples, in Understanding Event Keys.
However, since you can configure event keys independently of workflows, the procedures for doing so are given below. Once you have configured an event key expression, it is available for all workflows in all organizations. If you know the contents of your incoming messages, you can configure your event key expressions in advance to make them available to the workflow designer who will set up corresponding key value expressions in Start or Event nodes. You can also export and import event keys to and from a Java archive package file, with or without the workflows that reference them; for more information, see Importing and Exporting Workflow Packages.
Viewing Event Key Configurations
To view an event key configuration, choose Configuration
Figure 4-9 Event Key Expressions Dialog Box
The information displayed for each event key is explained in the following table.
Adding an Event Key Configuration To add an event key configuration:
Figure 4-10 Define Event Key Expression Dialog Box
For more information on the syntax for event key expressions, see Extracting Run-Time Event Data. Note also that an XPath() or EventAttribute() function must be wrapped in a typecasting function to return a data type that matches the type returned by the key value expression defined in the corresponding Event or Start node. For information on typecasting functions, see Converting Data Types.
Note also that the event key expression that you enter here should return a value that matches a value specified by a key value expression in a Start or Event node. For more information, see for defining key value expressions in Start or Event nodes, see Defining Event And Event-Triggered Start Properties.
Updating an Event Key Configuration
When updating an event key configuration, you can only update the expression, but not the event descriptor.
To update an event key:
Deleting an Event Key Configuration
When deleting an event key, take care that the key value is not referenced by key value expressions used in Start or Event nodes in workflows, or these events will not be triggered.
To delete an event key:
Managing Entities in the Repository
The WebLogic Integration repository contains a database table that is used to store XML entities, such as XML documents, DTD files, and XSL template documents. You can use the Studio to view, organize, and populate the repository, to make existing XML entities available globally for use and reuse by all workflows in the system. If you have previously-stored XML documents that you would like to reference in the workflows you create, you can set up your repository so that these documents are available to any client logged on to the system.
For example, if you will be using the Send XML to Client action to interact with a Worklist user (for information, see Sending an XML Message to the Worklist Application), you can populate the repository with the document type definition (DTD) files that are used to send messages to the Worklist, so that any Studio client user can easily access them in a central place. Or if you will be using the XSL Transform action to translate XML documents at run time (for information, see Transforming XML Documents), you may want to store your XSL stylesheet transform documents in the repository for easy access when defining that action.
In this section, we discuss how to set up the repository initially. However, the repository and all of the functions described in this section can be also be accessed from within workflow dialog boxes, as described in Working with XML Entities. You can also export entities contained in the repository to a file on disk (this option is discussed in Exporting an Entity to the File System) and to a Java archive package file for re-import into another system (for more information on import/export, see Importing and Exporting Workflow Packages.)
Viewing the XML Entities in the Repository
To view the XML entities in the repository:
Figure 4-11 XML Entities in the Repository
The following table describes information displayed in the Repository window.
To view the contents of a folder:
Figure 4-12 XML Entities in the Selected Folder
Figure 4-13 Preview Document Window
For more information about entities, see Working with XML Entities.
The left panel shows you a tree view of the repository with folders and sub-folders arranged hierarchically. The top-most panel on the right shows you the contents of the selected folder. The Description field contains a description of the selected folder, and the Notes field contains any notes about the selected folder.
Working with Folders
You can perform several different actions on a folder, including adding, updating, and deleting. To perform actions on a folder:
Adding a Folder
To add a folder:
Figure 4-14 Add Folder Dialog Box
Updating Folder Information
To update a folder:
Figure 4-15 Update Folder Info Dialog Box
Deleting a Folder
A folder may only be deleted when it has no sub-folders.
To delete a folder:
Working with XML Entities
The repository stores different types of XML entities, each one represented by a symbol, as shown in the following table.
You can perform several different actions on XML entities in folders in the repository, including adding, updating, moving, and deleting entities. Importing an XML Entity into the Repository To add an XML entity:
Figure 4-16 Add Entity Dialog Box
Figure 4-17 Open Dialog Box
Updating an Entity
You can use the Update Entity feature to change the content of an entity you have defined. You cannot, however, change the entity type. To change the type of an entity, you must create a new entity with the desired content type. For details, see Importing an XML Entity into the Repository.
To update an entity:
Figure 4-18 Update Entity Definition Dialog Box
Moving an Entity
You can move an entity from one folder to another by cutting it from the source folder and pasting it to the target folder.
To move an entity:
Exporting an Entity to the File System
You can save an XML entity from the repository database table to the local file system or a network drive mapped to the local machine.
To export an entity to a file:
Figure 4-19 Save Dialog Box
Deleting an Entity
If you delete an entity that is referenced by the XSL Transform action in a workflow, be sure to update this action in order to avoid WebLogic Integration server exceptions at run time (for more information on this action, see Transforming XML Documents).
To delete an entity: