BizTalk

Digg This!

One of the lesser known or least understood features of BizTalk Server 2004 is Human Workflow Services (HWS). This Web services-enabled platform provides most of the tools you need to build robust workflow solutions. One of the missing tools is a user interface that understands and can work with this great feature. With the release of Service Pack 1 for InfoPath 2003, Microsoft introduced new features that provide developers with the tools they need to use InfoPath as the user interface for workflows, thus taking full advantage of InfoPath's natural XML editing capabilities. The source code for this article is available at http://sys-con.com/dotnet/.

BizTalk Human Workflow Services
Human Workflow Services is a component of BizTalk Server 2004 that allows for the creation of both a priori and ad hoc workflow models. This provides support for both well- known constraint-driven models of processing, as well as the ability to compose steps into a workflow on the fly.

HWS is made up of a few key components that are important to understand before trying to build a workflow solution. Each of these components is defined below with a brief explanation of the role each plays in the process.

• Action: Represents a single step in a workflow such as "assign," "delegate," or "approve." An action can have one or more tasks.
• Task: Represents a single, assignable piece of work in an action. For example, in the Assign action, a task might be a message that gets sent out to a user who does some work and responds to the task, signaling that he or she has completed it. All of this work takes place in the scope of an action. Several people might get tasks based on a single action, and it could be the case that one, several, or all people need to respond for the action to be completed.
• Activity Flow: Represents a collection of actions that have been or are being composed into a workflow. An activity flow actually represents an in-process workflow. In order to start a workflow, a new activity flow ID must be retrieved from HWS, which is used to tie all of the actions together in that flow; it provides the correlation between actions.
• Constraint: Represents a condition that is applied to determine whether a particular action can be taken. Typical constraints indicate that users in a given security group can use an action in their workflow, be targets for an action in a workflow, or have actions sent to them. Constraints can be used in this ad hoc fashion, or they may be used with activity models to structure the flow of the predefined workflow.
• Activity Model: A defined workflow stored in the system which, unlike an ad hoc workflow, provides distinct paths of execution and defines the actions available at a given step in the workflow. In this model actions are also referred to as steps.

This article will focus on interacting with workflows rather than creating them. The steps to do so are as follows:

• Obtain a new activity flow ID.
• Figure out the available actions based on the current user constraints and active actions.
• Add actions to the activity flow; as tasks get sent out from actions, they get responded to.
• Add more actions and respond to tasks until all tasks and actions are complete.

InfoPath as a Client of HWS
Before the release of Service Pack 1 for Office 2003, the steps defined above had to be handled in a developer's code by calling to the HWS Web service for each of these steps, and any UI for interacting with these steps had to be created from scratch. While InfoPath provided the capability to call Web services and send InfoPath documents to those services, much of this work was done in the Microsoft Script Editor when using HWS. The new features in SP1 handle the calls to the service, creating a workflow pane that provides buttons for initiating actions, responding to tasks, and checking the status of an activity flow.

The one thing that InfoPath SP1 does not provide is a nice user interface for configuring these features. The point of this article is to provide the information you need to correctly configure an InfoPath solution to interact with your HWS actions.The following sections will walk through creating an InfoPath solution using predefined HWS actions, highlighting the details that you really need to understand.

Steps to Get InfoPath to Interact with HWS
The steps to get your InfoPath solution working with HWS are as follows.
1.  Add HWS Receive Data Connections. The workflow support needs connections to the HWS service in order to perform queries to populate the workflow pane and check status on the workflow.

Four receive data connections (shown below) need to be added to the InfoPath solution. Using the Tools/Data Connections menu item, add each of these connections as receiving data from the HWS Web service on your BizTalk server. In each case you should accept the default values for the name and parameters, and you should uncheck the box that indicates if the data should be retrieved at startup. It is very important that the names of the data connections match the names of the method calls.

• GetActivityList
• GetActivityFlowInfo (set the detail level parameter to "ActivityInstanceLevel")
• GetTaskInfo
• GetActionInstance

2.  Add required fields to enable activation of HWS workflow. To initiate a workflow in HWS, an activation message must be sent. In order to enable this, fields may need to be added to the InfoPath data fields so they can be included in the activation message. Examples include the target or person who should receive tasks, and a task description. If you already have fields that provide the data, you'll be able to map those to the appropriate fields in the HWS messages. In step 4, you actually provide mappings, in the form of XPath statements, between your InfoPath document and the HWS Activation message.

3.  Add Activation Message Templates to Resources. When sending an activation message to start an activity flow, a "template" or default instance is used to create the initial message before adding your activation content. You must add these files to your InfoPath solution as resource files. Use the BizTalk developer tools in Visual Studio.Net to create an instance of the activation message for the action(s) you are enabling. In each instance, edit the instance document so that there is only one payload element, then validate this instance against the schema to make sure you have a valid starting point. This is a very important step because the BizTalk tools do not always generate an instance that is valid.

4.  Enable hwsWorkflow and hwsAdapters within Manifest.xsf. In order to get your InfoPath solution working with HWS, you need to extract the form files and edit the manifest to include information about the available actions and tasks, and to configure the adapters to submit the appropriate messages to HWS.

This takes the form of two sections within the manifest: hwsWorkflow and dataAdapters. Listing 1 shows the hwsWorkflow section. In this section you define whether the workflow task pane is going to be visible, the URL of the HWS service, and the allowable actions and tasks for this InfoPath solution. Notice that for each action an actionTypeID is required. This value can be looked up in the HWS_Actions table of the HWS database. Notice also that you can indicate which actions are available to initiate the workflow and which actions must come as later steps by using the canInitiateWorkflow attribute of the action.

The next section is the data adapters section, which provides an adapter for each submission you need to trigger. The sample in Listing 2 shows one adapter used to initiate the workflow. Notice that the hwsOperation element has a type attribute that maps to the name of a method on the HWS service, and a typeID attribute which is the ID of one of the allowed actions for this solution, in this case the Assign action. In this sample we are adding an action to the activity flow, which is the first step after getting a new activity flow ID (which InfoPath handles for us). Also notice that we have identified the activation.xml instance that we created earlier for our HWS activation message, and that we then use the partFragment element to provide the mappings from our InfoPath document into that activation message.

5.  Enable script actions for the workflow pane. The workflow task pane contains buttons that initiate the configured actions. In order for these buttons to operate correctly, you must write script that handles the click events and submits the appropriate adapters. For example, the adapter in the previous listing was named Assign. We need a script handler for the Assign button, which will be created in the workflow task pane for us, that will trigger this adapter to submit. The listing below shows this simple script.

function Assign::OnClick(eventObj)
{
    XDocument.DataAdapters.Item("Assign").Submit();
}

You need a script block such as this for each dataAdapter element you include in the manifest.

How It All Works, and What You Have to Tweak
After you have made the modifications to the InfoPath solution as described above, you should be able to open a new instance of the form to fill out and get your workflow task pane. However what really happens when you click that button to, for example, Assign this InfoPath form? First, InfoPath will try to map the fields that you specified into the activation message you provided, along with some other important tracking and information data such as a new activity flow ID. Next, the InfoPath form data in XML format is base64-encoded and added as a payload item in that activation message with the ID of "Microsoft Office InfoPath 2003." This whole message is submitted as an activation message to HWS.

It is important to understand that when you are working with InfoPath in this way, the HWS messages are really acting as carriers of your form. You'll need to populate some of the necessary fields for the task messages and activation messages to indicate the status of your workflow, but you are really focused on doing so to move your InfoPath form around. With that said, it is important for the Payload element of messages to be mapped properly from activation messages to task messages; otherwise, your InfoPath form gets lost. Likewise, when a task message gets sent, what you really want sent is the InfoPath form, and not the task message XML. To accomplish this, you need a send pipeline with a component in it that can appropriately pull out your InfoPath form from the Payload and send that as the outbound message (there is sample of this in the source code for the article).

Finally, the last key component that makes this all work is the processing instructions. These are the statements at the top of an InfoPath XML document that provide information on how to process the document. InfoPath uses these instructions to identity that a particular XML document is an InfoPath form, as opposed to just an XML document. In addition, for workflow there is a special processing instruction that provides valuable identifiers for the workflow and current step. An example of this processing instruction is shown below.

<?mso-infoPathHWSWorkflow
activityFlowID='bdf3a304-8736-49d5-920a-49818a969638'
actionInstanceID='9b69bd25-bfa0-4ca0-92da-29606a2e4486'
taskID='84cc2a95-3b90-4762-8e82-e64747320332'?>

In the sample code, this processing instruction is created in the pipeline component before the form is sent out. It is necessary to provide this information so the InfoPath code can properly respond to HWS when new actions are taken.

Conclusion
Hopefully this article has helped you understand the steps necessary to getting your InfoPath solution integrated as a client for HWS. The accompanying source code sample uses the sample Absence Request InfoPath form and the Assign and Delegate sample HWS actions to provide a simple working solution with very little work. InfoPath's XML editing capabilities make it a natural interface for XML Web services and Human Workflow scenarios.