        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
Process Manager User's Guide
CHAPTER 6
This chapter discusses a wide variety of issues relevant to invocation and control of processes and activities, including the various actions that can be used inside components to implement "human intervention" scenarios involving work lists. To get the most out of this chapter, you should already be familiar with Composer project deployments and standard J2EE packaging and deployment constructs, such as EAR/WAR files, web.inf files, contexts, servlets, and so on; and you should be familiar with the basic Composer service trigger types. For more information on the latter subject, be sure to consult your Composer Server User's Guide for the app server environment (WebSphere, Weblogic, SilverStream) into which you will be deploying.
In order for a process to be invoked, it needs to be associated with a Process Execute action (see "The Process Execute Action" further below) in a calling component. The calling component can be any valid Composer component type (XML Map, JDBC, HTML, Telnet, or whatever). At some point, however, the component must itself be called by a service, and the service must be triggered by one of the standard Composer service trigger types. From the top down, then, the activation sequence is:
Servlet (service trigger) fires Composer service (web service)
Activities start and stop within the Process instance's lifetime
In its simplest form, the activation chain looks something like:
Here, a Composer service is shown calling/spawning a Process directly. But as mentioned earlier, any component type (XML Map, JDBC, etc.) can also call or spawn a Process. The way this is done is via a Process Execute action (discussed in further detail below).
The Process Manager adds six process-related actions to the component editor menus.
The actions can be thought of as supporting three basic types of functionality:
Process invocation via an action: This is accomplished by the Process Execute action. Within a given project, any Composer component or service (whether inside or outside of a Process) can launch any process in that project via this action.
Reentry into a Process: The Find Waiting Activity and Release Waiting Activity actions make it possible for a service that implements a Web Service Receive activity to get the attention of the process engine after it has finished running.
Human-accessible work queues: The Browse Waiting Activities, Lock/Unlock Waiting Activities, and Reassign Addressee actions provide support for scenarios involving delegation of tasks to individuals in an organization.
The Process Execute action allows you to launch a Process using runtime inputs and outputs that you specify. By using this action in a component's action model, you can invoke any Process in the current project.
The Process Execute action is similar to Composer's regular Component action (which fires components), except that it covers two possible methods of execution (namely, Call and Spawn) and optionally allows you to register the called/spawned process as a subprocess of a parent process.
If the process is started via a Call, then the action model containing the Process Execute action (the source component) will block any further action processing until the called process returns. This is the same behavior as for the regular Component action.
If the process is started via Spawn, then the process is executed in a "fire and forget" mode wherein the spawner does not wait for the spawnee to return. Instead, the spawned process returns (immediately) a "receipt" consisting of a unique identifier for the process and a timestamp. (See below.) This information can be used by other process actions such as the Browse Waiting Activities or Find Waiting Activity actions.
When you spawn a process, you are invoking the process asynchronously, in "fire and forget" manner. The spawned process will hand back a message containing certain information about the process instance that was spawned (which can be useful later). The "return receipt" information handed back by a spawned process looks like:
The information returned includes the ProcessID associated with the particular process instance that was just started, and the date of birth of the process instance, in Process/Info/CreationDate.
To create a Process Execute action:
Open the Composer component or service from which you wish to invoke a process. Click inside its action model at the point where you want to insert the action.
In the Action menu, choose New Action > Process > Process Execute, as shown above. (You can also reach this command from the context menu, available by right-clicking in the action pane.) A dialog appears.
Using the pulldown menu in the top left corner of the dialog, choose the Execute Method: Spawn (fire and forget) or Call (block until results come back).
From the pull down menu under Process Component, select the process that you want to invoke. The menu will be prepopulated with the names of all process xObjects in the current project.
Under Passed Part, select (from the dropdown list that appears when you click in this field) the name of the component DOM that will be the data source for the process.
Under Returned Part, select (from the dropdown list that appears) the name of the DOM that will receive information back from the process. For a spawn action, see discussion below.
If you are spawning this process as part of a fan-out (in anticipation of later using a Synchronize Subprocesses activity to sync back up), check the Spawn as Subprocess... checkbox and indicate (via XPath expression) where the parent process's ProcessID can be found.
NOTE: This is an advanced option that is useful primarily when you are working with the Synchronize Subprocesses activity type. Leave this checkbox unchecked unless the current component is an activity implementation for a process and you are using the Synchronize Subprocesses activity type somewhere else in the same process.
Passed Part represents the runtime name(s) of the source component parts that will be passed into the target process as its ProcessInput message. When you select a process to execute from the drop down list box, the parts it is expecting as defined by its input XML Template will appear. You then simply match up the current component parts to pass with their process counterparts. The Passed Parts do not have to match the template parts in name. However, to insure that the process receives all the data it needs, the number of parts passed should equal the number of parts expected.
The output from a Process Execute action is returned to a Part in the current component that you specify. If the process is executed via a Call, then the process output will be placed in the Returned Part. If the process is executed via Spawn, then a Process Info receipt is placed in the Returned Part.
The checkbox called "Spawn as a subprocess of Parent ID," underneath the Returned Part section of the Process Execute dialog, is visible only when Spawn is selected as the Execute method. The controls just below the checkbox appear, also, when Spawn mode has been chosen. These controls allow you to correlate a spawned process with a given parent process, so that the process engine can keep track of subprocess returns. This is important only in the context of a Synchronize Subprocesses activity implementation.
NOTE: If you are not implementing a "fan-out" type of scenario culminating in a fan-in via a Synchronize Subprocesses activity, you do not need to concern yourself with this discussion.
The parent Process ID that is attached to each process when it is spawned by the Process Execute action allows the engine to return each spawned process's results to the correct parent process. Since there may be many instances of the parent process running at one time, this mechanism prevents one instance of a parent process from receiving the results of a different instance.
For a more detailed discussion of a fan-in/fan-out scenario using the Synchronize Subprocess activity, see "Synchronize Subprocesses Activity" in the preceding chapter.
The unit of deployment in all Composer projects is the Web Service xObject. Thus, as with all other Composer components (e.g. JDBC, EDI, XML Map, 3270, etc.), any Process you wish to expose to a business partner must be executed from inside a Web Service component.
In the simplest case, you can deploy a Process by placing a single Process Execute action inside a Web Service, which you then deploy as you normally would. You merely need to make sure that the Web Service's input message (and its constituent parts) matches the input(s) for the Process. Then it is a simple matter to call the process via the Process Execute action and pass in the parts.
In a more complex deployment, the Process Execute action may be part of a larger action model that either prepares the initial process message or runs multiple other components and/or processes as well.
You will typically use the Find Waiting Activity action inside the implementation for a Web Service Receive activity. (It is usually followed by a Release Waiting Activity action. See discussion further below.) The Find Waiting Activity action allows you to retrieve runtime information from the process engine for a Web Service Receive activity that is waiting to be fired by (for example) a business partner. The retrieved information, along with the business partner's message, is then used to generate an output message for the activity.
A Release Waiting Activity action generally follows every Find Waiting Activity action. The Release Waiting Activity action causes output to be passed to the Web Service Receive activity and signals its "exit readiness" to the process engine, thus allowing the process flow to continue.
Recall that in the Process Manager, the Web Service Receive activity allows a process (or branch of a process) to halt the flow of control at that activity in order to wait for a Web Service to receive information that is necessary to continue the process flow.
The implementation for the Web Service Receive will typically be an exteNd Composer web service with a published WSDL endpoint for the business partner to contact. After being contacted, this Web Service needs a way to find its associated Web Service Receive activity in the correct process instance, pass it the business partner's message, and signal the process engine that the activity is complete (see Release Waiting Activity described later). The Find Waiting Activity action fills the need of locating the proper Web Service Receive activity.
NOTE: It's important to keep in mind throughout this discussion that activities and activity implementations are not the same thing. Activities are abstract entities that have certain attributes and states meaningful only to the process environment. An activity implementation is the business application that carries out some task in software. An activity has certain properties associated with it—these are shown in the property sheets which make up the tabs in the Object Properties panel. But in general, an activity doesn't know anything about the implementation, or underlying app, that carries out the actual work required to accomplish a given business task. Conversely, an implementation doesn't know that it is being used in a process.
Consider the following scenario: You have defined a process that places an order, sends a confirmation to a business partner asking for final approval to execute the order, and then waits to hear back from the partner. The partner sends a message referencing the order number back to you, at which point the order process continues. A Web Service Receive activity is used for the part of the process that waits to be contacted by the business partner (see No. 1 in the diagram below). This activity's implementation is usually a standard Web Service. That Web Service, in turn, uses a Correlation ID to keep everything instance-bound. The business partner will have been given this ID by an upstream activity in the process (the activity that queried the partner). The following diagram shows what happens when the partner finally answers back.
When the business partner sends a confirmation message to Web Service A (which implements the Web Service Receive activity in the above diagram),Web Service A needs to find and "wake up" its associated activity and process. Fortunately, Web Service A contains a Find Waiting Activity action that does precisely this (see 2, above). Using the Find Waiting Activity action, the web service finds the Web Service Receive activity that has been waiting for the business partner's response. That activity's input message and PendingActivity document can be utilized in creating an output message for the activity (see 3 above). Using the PendingActivity document, the Web Service executes a Release Waiting Activity action and passes output back to the Web Service Receive activity (see 4 above), which exits and allows the process to continue.
A waiting activity can be found using one of two methods. One method uses a combination of Process Name and Correlation ID; the other uses Activity Name and ProcessID.
The Correlation ID method is most common for business interactions with business partners on opposite sides of a firewall (i.e. two separate companies). The Correlation ID is simply any unique value—such as a timestamp, work order number, confirmation number, etc.—created earlier in the process and communicated to the business partner. The Find Waiting Activity action will extract the CorrelationID from a location in the Input document that you specify, then submit this ID to the process engine to find.
The second lookup method bases its inquiry on a unique key constructed by combining an Activity Name (i.e. the name of the Web Service Receive activity of which the component is a part) and the ProcessID of the process instance in question. The Find Waiting Activity dialog (below) allows you to enter this information.
The second lookup method is more common in cases where requesting and responding parties are both inside a common firewall.
With either lookup method, it is essential that the business partner provide the needed ID information in the input message to the Web Service. That ID information will consist either of a Correlation ID, or a combination of Process ID and Activity Name.
The Find Waiting Activity dialog consists of two tabs of controls. The Find tab is where you specify criteria used to find a waiting activity. The Message tab allows you to specify where to place the information returned from the process engine regarding the activity you find.
The Find tab will take on a different appearance depending on which of the two radio buttons is selected in the top part of the dialog. When "Process Name and Correlation ID" is selected, the dialog takes on the following appearance:
If you are finding an Activity by Process Name and Correlation ID, select a process name from the dropdown list. Then specify an XPath expression identifying where, in the message received from the business partner, Composer will find the CorrelationID. (Alternatively, click the Expression radio button and specify an ECMAScript expression that will evaluate to the needed ID.) The message part containing the business partner's message will normally be Input, but others are allowed. Note that the element containing the CorrelationID does not need to be named "CorrelationID."
A valid XPath expression might be: PurchaseOrder/Header/POID.
When finding an activity by Activity Name and Process ID (using the radio button labelled "Activity Name and Process ID"), specify an XPath expression identifying where, in the message received from the business partner, Composer can expect to find the Activity Name (i.e. the name of the Web Service Receive activity). The message part containing the business partner's message will ordinarily be Input, but others are allowed. Note that the element containing the Activity Name does not need to be named "Activity Name." A valid XPath expression might be: ServiceTicket/Header/InquiryType. Also, in similar fashion, specify the location of the ProcessID.
When an activity is found, the process engine will return two XML documents to the Web Service that issued the Find Waiting Activity action. The first document is the original input message (consisting of 1 or more parts) to the Web Service Receive activity before it began waiting for a contact from a business partner. This allows the activity's implementation to work on the activity message or use it as a reference with the message received from the business partner.
The second document returned by the process engine is runtime information about the waiting activity (see details below).
The first section of the Message tab allows you to map the activity's original input message into the Web Service so you can work on it. Two radio buttons control the options available to you:
The Parts radio button allows you to map each part of the activity's input message to a part in the Web Service. This will be the choice for most applications.
The Message radio button allows you to map the entire activity input message (including all its parts) to a single part in the Web Service. If no parts are available for use, you will need to add Temp documents to the Web Service.
The second section of the Messages tab allows you to specify what part in the Web Service will receive the waiting activity's process information from the process engine. Select a part from the dropdown list. If no part is available for use, you will need to add a Temp document to the Web Service.
The second document returned by the Find Waiting Activity action is used by a Release Waiting Activity action to signal the completion of the Web Service Receive activity and allow the process flow to continue to execute. The document returned by the process engine that describes a waiting activity contains a root element named PendingActivity.
The PendingActivity document contains the following child elements:
ProcessID—This is the unique number associated with the process instance in which the found Web Service Receive activity exists. This data is used by the Release Waiting Activity action to restart the waiting activity.
QueueDate—This is a date/time stamp indicating when the Web Service Receive activity starting waiting for contact from a business partner.
ActivityName—The name of the Web Service Receive activity that is waiting.
ProcessName—The name of the process to which the Web Service Receive activity belongs.
CorrelationID—The unique key used to identify and find the Web Service Receive activity. The value is specified as a property of the Web Service Receive activity and is set by the process when the activity executes and begins waiting.
Addressee—The name of a user who is supposed to contact this Web Service Receive activity. This data is usually used in assigning work to people in work queue applications that involve user intervention/interaction with a long-running process. The value is specified as a property of the Web Service Receive activity and is set by the process when the activity executes and begins waiting. This data is usually used in processes that run completely behind the firewall.
Priority—This data is used in assigning work to people in work queues and allows an application querying the process engine to sort waiting activities by relative importance. The value is specified as a property of the Web Service Receive activity and is set by the process when the activity executes and begins waiting. This data is usually used in processes that run completely behind the firewall.
LockedBy—This label is typically the name of a user in a work queue who has flagged this activity instance as being locked for exclusive use by one individual. No actual lock is created; rather, it is a semaphore or flag value for work-queue applications querying the process. The value is set by a Lock/Unlock Waiting Activity action.
LockedUntil—A date value indicating when the lock will be removed. The value is set by a Lock/Unlock Waiting Activity action.
The Release Waiting Activity action is used inside the implementation (usually a Web Service) for a Web Service Receive activity. The action is usually preceded, at some point in the implementation's action model, by a Find Waiting Activity action. The action passes data to the waiting Web Service Receive activity; and that data becomes the output message, signalling the activity's completion to the process engine. The passed data is usually information from a business partner that contacted the Web Service. Thus, the Release Waiting Activity action is the callback mechanism used by a Web Service to produce an output message for, and signal the completion of, a Web Service Receive activity inside a process.
Before an Activity can be released, you must produce a message part that contains a PendingActivity document indicating the Process and Web Service Receive activity you wish to release. This can be accomplished via a Find Waiting Activity action (see the previous section). In addition, you will need one or more parts that will be passed back to the waiting Web Service Receive activity as its output message. Once you have a PendingActivity document and one or more parts to serve as activity output, you can release an activity.
The Release Waiting Activity dialog has three sections to it.
The first section allows you to specify a part in the Web Service that contains a PendingActivity document describing the process and activity you wish to release. This part must have been populated previously by a Find Waiting Activity action.
The second section is where you map parts in the Web Service to output message parts in the waiting Web Service Receive activity.
The third section is optional and allows you to return output to the activity but flag it as a fault message causing the process flow out of the Web Service Receive activity to follow fault links.
Under "Part containing Waiting Activity's Process Information," just select a part name from the drop down list.
NOTE: In order for a part to show in the list, it must contain a PendingActivity document.
The second section of the dialog allows you to specify data from the Web Service that will become the waiting activity's output message. The Parts option allows you to map one or more parts in the Web Service to one or more parts in the Web Service Receive activity's output message. This will be the choice for most applications. The Target Part name you enter will be created in the activity's output message for you. The Message option allows you to map a single part in the Web Service as the entire activity output message (including all its parts).
The third section in the dialog allows you to specify (optionally) that the returned data is to be flagged as a fault inside the process. Use the expression builder to specify a fault message name corresponding to one that was defined for the Web Service Receive activity on its Messages tab.
Most processes require some kind of human interaction, if for no other purpose than the initial triggering of the process. In some scenarios, human involvement in all phases of a particular business task can be essential. Purchase orders may require personal approval; product inquiries may require personal e-mail responses or phone calls; large transactions may require escalation to a particular individual; and so on.
You can use Composer's Process Manager to implement a wide variety of sophisticated human-centric workflows. The Process Manager has features that make it easy to:
Mark work items as locked or unlocked for exclusive use by an individual
Integrate easy front-end access to work lists via JSP or HTML
To create human entry-points into a process, you will generally use Web Service Receive activities to expose outward-facing web-service applications (i.e., the implementations of the Web Service Receive activities). The user-facing services could be exposed via JSP or HTML pages; or they might be exposed by other means.
Your user-facing services can be designed to allow users to browse work queues, find and lock work items, unlock work items, reassign work, and/or push work back into the system. The actions that make these operations possible include the Find Waiting Activity and Release Waiting Activity actions already discussed above, as well as the Browse Waiting Activities, Lock/Unlock Waiting Activity, and Reassign Addressee activities discussed below.
Human participants in a process are known, in Process Manager, as Addressees. The runtime engine associates an Addressee with a particular document or work item via the Addressee property on the Object Properties panel for the Web Service Receive activity type.
NOTE: Addressee is a property of Web Service Receive activities only. You will not see this field in the Object Properties panel for other activity types.
The Addressee value is specified as an XPath expression. This affords a great deal of flexibility, since the Addressee can be in a passed-in message part, or it can be determined dynamically at runtime, or it can be hard-coded to a particular string value. Thus, you can accommodate any of the following common scenarios:
The sales person to whom the order should go is determined by a JSP scriplet or EJB at the time the order is submitted online. The ProcessInput message already contains the necessary Addressee name at process invocation.
An order arrives via the Web and kicks off a process. The Addressee is determined dynamically—"just in time"—by business logic in a preprocessing component, and it appears in the output message of an activity.
All orders must eventually be approved by John Smith. Therefore, a Web Service Receive activity is hard-wired to an Addressee value of "John Smith."
The Web Service Receive activity is the main touchpoint for human input into automated processes built with the Process Manager.
When a Web Service Receive activity "fires," three things happen:
Its Addressee property becomes associated with a string value (usually, although not necessarily, representing a real person's name)
The underlying implementation for that activity (namely, a user-facing Web Service that follows the WSDL One-Way or Request-Response pattern) becomes operational
The Process Engine puts the Web Service Receive activity (not its implementation!) into a waiting state
A person (i.e., a worker or an administrator; the Addressee) can then use a work-group application implemented in JSPs to execute Composer components or services to:
Browse all the waiting activities addressed to a particular person (using a Browse Waiting Activities action),
Lock waiting activities to prevent other users from approving an order (using a Lock/Unlock Waiting Activity action) while they are being reviewed by an Administrator,
Unlock an order, allowing it to be approved (using a Lock/Unlock Waiting Activity action),
Retrieve orders and mark them as approved (using a Find Waiting Activity action), and/or
Complete the approval and allow the process to proceed to the next activity (by finally calling a Release Waiting Activity action).
Notice that only the Release Waiting Activity action can actually complete a Web Service Receive activity (that is, cause it to exit). So by definition, the implementation to a Web Service Receive activity (i.e. a Web Service) must contain a Release Waiting Activity action. The other process actions (Browse Waiting Activities, Lock/Unlock Waiting Activity, Reassign Addressee, and even Find Waiting Activity) can be used in a variety of components not directly connected to a process. Such components might use these actions to add oversight and "see-into" functionality to external applications, giving users a means to view and manage waiting activities.
The Browse Waiting Activities action can be used in any service or component (even one outside the process), as long as the process and the service/component are deployed as part of the same Composer project. The sole purpose of the Browse Waiting Activities action is to allow an application to obtain a list (or lists) of pending activities, filtered by Addressee.
When you execute a Browse Waiting Activities action, you are merely supplying the Process Server with a name, or a list of names. The Process Server, in turn, examines all Web Service Receive activities in all instances of all processes, and hands back a list of activities waiting to be acted on by the individuals (or departments, etc.) in question.
The list that the Process Server returns in response to a browse is a PendingActivity document. This document contains such information as the ProcessID and Activity Name for the pending activity, as well as other information that can be used, if desired, to find and do work on behalf of a waiting activity. (See "The PendingActivity document" further above for additional discussion of the PendingActivity document structure.)
The Browse Waiting Activities action is usually utilized in scenarios where a long-running process requires the intervention of, or interaction with, a live person through another application such as a JSP. (See the eXtend Composer Silverstream Server Guide section titled "Creating a JSP that calls a Composer Service" for more detail.) For example, you may have a heavily trafficked process that processes orders one-at-a-time. The process contains an activity that accepts a single order and passes it to a Web Service Receive activity, where the process stops and waits for the order to be approved by a particular person. That person, in turn, will use a JSP (Java Server Page) to input his approval. In this kind of scenario, the Addressee (the person who approves the order) needs to be able to find out about (or discover) work waiting to be done, and also push work into the system as it gets done. The discovery part can be accomplished via a Browse Waiting Activities action in a service (not necessarily internal to the process) that can be triggered off a JSP. The "data push" part can be done via a service that implements the Web Service Receive activity type. This service would use a Find Waiting Activities action to look up individual work items, and a Release Waiting Activity action to execute the "push."
A waiting activity (no matter which process it is in) can be located by Addressee alone, using the Browse Waiting Activities action. But for this to work, the associated Web Service Receive activity must have a non-empty Addressee property. To specify a value for Addressee, just open the Process graph in Process Designer, click on the Web Service Receive activity in question, bring the Object Properties panel into view, and enter a legal XPath value next to Addressee. (See screen shot under "Addressees" above.) The XPath should point either to an input message part that contains an Addressee string, or a hard-coded string value.
A second Web Service Receive activity property named Priority can also be set in the Object Properties panel. Priority is an arbitrary number that allows the application to sort or filter retrieved work items before displaying them to the user. You can assign any value(s) you want here, or leave the value empty.
In most applications, a Browse Waiting Activities action will be followed by other process actions like Lock/Unlock Waiting Activities, Reassign Addressee, and/or Find (or Release) Waiting Activity. For instance, one possible scenario might be as follows. An administrator for a work group selects multiple waiting activities for a group of users (using the Browse Waiting Activities action). The administrator places a lock on all the selected activities to prevent users from working on the work items (using a Lock/Unlock Waiting Activities action) while they are under review. The administrator reassigns some work items among the users (using the Reassign Addressee action), finds and works on the high priority work items (using the Find Waiting Activities action) and completes them (using a Release Waiting Activity action), and then unlocks the activities not worked on (again using a Lock/Unlock Waiting Activities action).
The Browse Waiting Activities action differs from the Find Waiting Activities action in the following characteristics:
Browse can search for waiting activities by Addressee only, whereas Find can search only by Process Name/CorrelationID or Activity Name/ProcessID.
Browse can return information on multiple activities, whereas Find returns information on just a single waiting activity.
Browse maps its results to a message part or XPath location, whereas Find maps its results to a part only.
Browse does not return the input messages to the found activities, whereas Find does return the waiting activity's input message. So by using a Browse coupled with a Find, an administrator can look into the details of a waiting activity such as looking at the actual order.
NOTE: Both Browse and Find are nondestructive. No waiting activity is marked as finished until a Release Waiting Activity action has been called on it.
To create a Browse Waiting Activities action, go into a component and right-click in the action model; then select New Action > Process > Browse Waiting Activities from the context menu. A dialog will appear.
The Browse Waiting Activities dialog contains two basic control groups. The first control group offers a way to point to a list of Addressees in a message part in the component. The value(s) contianed in the nodelist will be used as the search key(s) for finding waiting activities. For example, in the dialog above, the Addressee XPath points to the list of Approvers shown below.
The second control group allows you to specify where to place the results of the browse. Specify a part name (such as Temp) and an XPath location within the part. The results of the browse will be placed as child elements of the XPath you specify.
A successful browse will return one or more PendingActivity documents (as shown above), each containing child elements describing the waiting activity. If the browse finds no waiting activities, then only the XPath you specify will be created and there will be no PendingActivity children elements beneath it.
NOTE: Unlike the Find Waiting Activity action, the Browse Waiting Activities action does not return the input message for the found activity. In order to retrieve the input message, you must loop through each PendingActivity element using a Repeat for Element action, and perform a Find Waiting Activity action on the activities of interest. (The PendingActivity branches contain all the information required by a Find Waiting Activity action to retrieve any given activity.)
The Lock/Unlock Waiting Activity action flags a waiting Web Service Receive activity as being in use or clears that flag, indicating the waiting activity is available to be worked on. The flag consists of the two elements /LockedBy and /LockedUntil in the PendingActivity document associated with a waiting Web Service Receive activity. A non-null value in the LockedBy element indicates the waiting activity is unavailable for use. When a lock is flagged, the LockedUntil element contains a date/time stamp indicating when the lock or flag will be cleared automatically by the process engine.
It is important to note that the Lock/Unlock Waiting Activity action does not physically lock the waiting activity. It simply marks the activity as being in use. Even when flagged as being in use, a Find Waiting Activity/Release Waiting Activity set of actions can work on and complete the activity. It is up to the designer of the work group application to honor the lock.
NOTE: Locked activities are not excluded from Browse results. The PendingActivity information returned by a Browse will show all applicable activities, including both locked and unlocked ones.
The Lock/Unlock Waiting Activity action is typically utilized in applications where a long-running process requires the intervention of, or interaction with, a live person through another application such as a JSP. (See the Composer Silverstream Server Guide section titled "Creating a JSP that calls a Composer Service" for more detail.) These work-group applications commonly use work queues filled with work items assigned to addressees.
Before you can lock or unlock a waiting activit,y you must have a ProcessID and Activity Name with which to locate the waiting activity. A Lock/Unlock WaitingActivity action will generally be preceded in an action model by a successful Browse Waiting Activities or Find Waiting Activity action. The result of either action is a PendingActivity document from which you can reference the necessary ProcessID and Activity Name.
If the activity you are trying to lock or unlock is no longer present in the process engine, Composer will throw an exception, so it is good practice to anticipate this (for example by placing Lock/Unlock Waiting Activity actions inside a Try/On Error action).
If the Lock/Unlock Waiting Activity action is successful (i.e., no exception is thrown), nothing is returned and the next action in the action model executes.
To create a Lock/Unlock Waiting Activities action, go into a component and right-click in the action model; then select New Action > Process > Lock/Unlock Waiting Activities from the context menu. A dialog will appear.
The Lock/Unlock Waiting Activity dialog has 5 sets of controls:
The first control group contains two radio buttons that determine whether the action is to set a lock or clear an existing one.
The second control specifies the ProcessID you wish to target. Specify an XPath within a PendingActivity document down to the ProcessID element.
The third control specifies the Activity Name you wish to target. Specify an XPath within a PendingActivity document down to the Activity Name element.
The fourth control is the LockedBy flag. Specify a meaningful value for the people or processes who might inspect it by executing a Browse or Find against the waiting activity while you have it flagged as locked.
The fifth control is the Lock Duration. Specify a time interval that will be used to calculate a date/time stamp to place in the LockedUntil element of the PendingActivity document associated with the waiting activity. The time interval default unit of measurement is seconds, so entering the text 60 will leave the lock flag in place for 60 seconds, after which the flag will be cleared automatically. Other units of measure include minutes (specified inside single quotes as: '60m'), hours (specified inside single quotes as: '60h'), and days (specified inside single quotes as: '60d').
NOTE: If you select the Lock Waiting Activity radio button, values for all controls are required. If you select the Unlock Waiting Activity radio button, values for the Process ID and Activity Name controls only are required.
The Lock dialog settings shown in the screen shot further above might give the following result when another user (say, Mary) browses waiting activities:
The Reassign Addressee action allows you to change the value of the Addressee attribute assigned to a waiting Web Service Receive activity. In most cases, the original value of the Addressee will be set by the Process Manager when a Web Service Receive activity enters its waiting state. Once in its wait state, the current Addressee can be changed to another value by the Reassign Addressee action. You also have the option of reassigning the the current Addressee for one Web Service Receive activity, or all of that person's Web Service Receive activities. (For example, you might want to reassign all of Mary's work to Joe while Mary is out sick.)
Remember that the Addressee is an optional attribute that can be assigned to a Web Service Receive activity. The presence or absence of a value does not inherently affect the processing of the Web Service Receive activity except as a flag or tag to an external work group application.
The Reassign Addressee action is typically used in applications where a long-running Composer process requires the intervention of, or interaction with, a live person through another application such as a JSP-driven application or form. Work group applications allowing human interaction commonly use work queues filled with work items assigned to addressees.
Before you reassign the addressee to a waiting activity, you must decide if the action will reassign all or just one of the activities associated with a particular Addressee. If you want the action to reassign all activities, then you need only define two parameters for the action: an XPath or ECMAScript expression identifying the current Addressee, and an XPath or ECMASCript expression identifying the new Addressee.
If you want to reassign a single specific activity of the current Addressee, then you will also need to supply a ProcessID and Activity Name. To do this, the Reassign Addressee action must be preceded in an action model by a successful Browse Waiting Activities or Find Waiting Activity action. The result of the Browse or Find will be a PendingActivity document from which you can reference the necessary ProcessID and Activity Name.
After the Reassign Addressee action executes, whether successful or unsuccessful, nothing is returned. To verify the success of the action, perform another Browse.
To create a Reassign Addressee action, go into a component and right-click in the action model; then select New Action > Process > Reassign Addressee from the context menu. A dialog will appear.
The Reassign Addressee dialog has several groups of controls. The first control identifies the current Addressee (the one whose work will be reassigned) while the second control identifies the new Addressee. For each one, enter an XPath location from a part in the current action model or an ECMAScript expression that will resolve to the correct Addressee name. (The value for each will typically be passed into the component in which the Reassign Addressee action is used.)
The All Activities and Specified Activity radio buttons in the middle of the dialog determine whether all activities for the current Addressee will be reassigned (as in the case where all of Mary's work needs to be reassigned to Joe), or just one specific activity. If Specified Activity is chosen, the control groups called Activity Name and Process ID become enabled and you must enter an XPath or ECMAScript expression identifying the specific Activity to reassign, along with the specific ProcessID containing that activity. In order to supply these values, you will generally have performed a Browse Waiting Activities or Find Waiting Activity action.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
