Integrating BizTalk Human Workflow Services with InfoPath 2003

  • Article

Summary: You can take advantage of features in Microsoft Office InfoPath 2003 Service Pack 1 to integrate Human Workflow Services functionality (part of Microsoft BizTalk Server 2004) with your InfoPath forms and create workflow solutions. Learn some tips for developing a BizTalk orchestration when InfoPath is the target client application, and read about best practices for designing and developing an InfoPath solution around HWS. (8 printed pages)

David Gerhardt, 3Sharp

October 2004

Applies to: Microsoft Office InfoPath 2003, Microsoft BizTalk Server 2004

Contents

  • Overview of Human Workflow Services

  • Setting Up the BizTalk Orchestration

  • Designing the InfoPath Form

  • Modifying the Form Manifest

  • Conclusion

  • Additional Resources

Overview of Human Workflow Services

Human Workflow Services (HWS) is a standard feature of Microsoft BizTalk Server 2004. HWS provides a workflow infrastructure built on the BizTalk Server 2004 engine. Figure 1 shows an example of the kind of workflow you can enable.

Figure 1. A sample workflow

A sample workflow

Because HWS actions are accessible through Web services, the actors in this example could be using any client application, such as Microsoft Office Word 2003 or Microsoft Office InfoPath 2003. Actors can initiate actions within the client simply by clicking a submit button, for example.

While you can incorporate HWS functionality into any client, the main benefit of choosing InfoPath over other applications is its ability to generate structured content. InfoPath is an XML-based forms client that uses submit adapters to pass data to a particular destination, such as a Web service. A BizTalk orchestration can be published as a Web service and can handle the XML submission without requiring any transformations, thus making it a natural and easy complement to InfoPath.

By learning about the general process of creating workflow solutions that use HWS with InfoPath, you can set up your InfoPath forms to take advantage of this BizTalk feature. You can gather tips for developing a BizTalk orchestration when InfoPath is the target client application, and learn about best practices for designing and developing an InfoPath solution around HWS. By doing so, you can more effectively manage tasks and data flow.

For more information about HWS, see Microsoft BizTalk Server 2004 Human Workflow Services (HWS). For a lab on creating an InfoPath solution that uses HWS, see Lab 12: Workflow Support in InfoPath 2003.

Setting Up the BizTalk Orchestration

In general, you should develop the BizTalk orchestration and HWS actions before you integrate them with InfoPath, because the InfoPath form requires information from the orchestration. In this section, examine some BizTalk items that you must consider to make HWS work effectively with InfoPath as a client application.

Synchronizing HWS with the Form

Within a BizTalk solution, pipelines allow messages to take varied paths. Along these paths, the pipeline component interacts with the message payload, which transports the InfoPath form data. The InfoPath form is stored as a base64Binary data type within the corresponding payload node of the HWS message. While HWS processes the message to generate the appropriate task IDs, the InfoPath form's workflow IDs must also be updated to keep the form synchronized with HWS.

A custom pipeline component handles the interaction that synchronizes the form with HWS. The pipeline unpacks the base64Binary nodes, updates the processing instructions, and then repacks the nodes. These actions take place after the message is sent from the source and before it arrives at its destination.

For instructions on how to configure an HWS pipeline to handle InfoPath forms, see Exercise 3 in Lab 12: Workflow Support in InfoPath 2003, referenced previously.

Promoting Data Fields

BizTalk can execute actions in a workflow based on values of elements in the InfoPath form. You can configure the orchestration to unpack the base64Binary nodes, and you can create your business logic based on the unpacked XML. An even simpler approach to evaluating elements in your workflow is to promote them as properties. After you promote the elements, you can use simple expressions in the orchestration to reference the properties.

To promote an element as a property

  1. Start Microsoft Visual Studio .NET 2003 and open the BizTalk project.

  2. In the Solution Explorer window, double-click the schema file that contains the elements to promote.

  3. In the schema tree view, located next to the schema definitions, right-click the root node, and on the Promote menu, click Show Promotions.

  4. To display elements that were already promoted as properties, in the Promote Properties dialog box, click Property Fields.

  5. In the tree view next to the dialog box, select the element you want to promote, and click Add. Repeat this step for as many elements as you wish to promote.

  6. After you finish adding promoted fields, click OK.

Setting Constraints on Actions

The HWS Server Administration console on BizTalk Server allows you to set constraints on actions. You can use constraints to restrict actions available to users, depending on that user's role in the organization. For example, suppose any employee in a company can submit an expense report, but only a manager has the authority to approve it. In this situation, you can set a constraint on the Approval action within HWS Server Administration to restrict non-managers from approving expense reports.

To set constraints on an action

  1. Start HWS Server Administration on BizTalk Server.

  2. In the navigational frame, right-click Constraints, and click Add Constraint.

  3. In the Constraint Properties dialog box, select an Action from the list, and add Initiator, EnactedOn, or Target clauses as needed.

  4. After you finish adding properties, click OK.

Using XML Namespaces

Within the BizTalk orchestration, all task messages use XML namespaces for their associated actions. HWS allows you to use the same XML namespaces for task messages on different actions. InfoPath, however, uses the namespace of the HWS task message to uniquely identify that task. Because of this, you should use unique namespaces for the HWS task messages in the BizTalk orchestration.

Designing the InfoPath Form

Once you set up the orchestration and HWS actions, you can develop the InfoPath form and integrate it with the BizTalk solution. Examine some of the best practices for designing and developing your forms for use with HWS so you can get the most benefit from this feature.

Designing an InfoPath form around HWS requires that you understand the actions that take place within the BizTalk orchestration. By understanding these actions, you can design your forms to work with those actions.

HWS Task Pane

Users can execute the actions you define in your BizTalk orchestration from the HWS task pane of the InfoPath form. These actions are bound to button controls. Because InfoPath allows for an extremely open design of HWS functionality, you can provide any names for these buttons and any text for the associated captions that you want. However, because the HWS task pane obtains data from BizTalk Server and follows the workflow logic you define in the BizTalk orchestration, the best practice is for you to keep the button names and captions synchronized with the actions and associated captions from the orchestration. Changing the names might lead to confusion for the form user.

User Roles

When you set up your BizTalk orchestration, you must specify a target user name for every HWS action. You can accomplish this by storing the target user name in the form data. With the user name data included, you can include user role functionality in the form. You can then match the user name to a specific role, which means you can make the form's UI and behavior change based on which user accesses the form.

To add a user role

  1. In the design mode of InfoPath, on the Tools menu, click User Roles.

  2. In the Manage User Roles dialog box, click Add.

  3. In the Add User Role dialog box, in the Role name field, type a unique name.

  4. In the Assign users or groups to this role section, add user names or group names as needed. If you are specifying an initiator role, select the Set as initiator check box.

  5. After you finish setting the user role, click OK twice.

Modifying the Form Manifest

After you design the form, you can incorporate the HWS functionality into the form. To do this, you modify the form manifest.

Adding the hwsWorkflow Section

The hwsWorkflow section within the manifest enables the HWS task pane in the form. You add the hwsWorkflow section to the manifest and customize it to enable the actions exposed by the BizTalk orchestration and the tasks to which users can respond.

To add the hwsWorkflow section with an action and task to the manifest

  1. Ensure that the form is not already open in design mode, and then open the file, manifest.xsf, with any text editor.

  2. Add the xsf:hwsWorkflow element to the xsf:xDocumentClass root element.

  3. Add an xsf:location element as a child of xsf:hwsWorkflow, and specify a value for that element's url attribute.

  4. Add an xsf:allowedActions element as a child of xsf:hwsWorkflow.

  5. Add an xsf:action element to xsf:allowedActions. Specify values for that element's name, canInitiateWorkflow, caption, and actionTypeID attributes. The actionTypeID attribute value is set when the associated action is registered with BizTalk Server and can be retrieved using the Microsoft SQL Server Query Analyzer.

  6. Add an xsf:allowedTasks element as a child of xsf:hwsWorkflow.

  7. Add an xsf:task element to xsf:allowedTasks. Specify values for that element's name, caption, and taskTypeID attributes. The taskTypeID attribute value is equal to the target namespace of the associated task's schema file in the BizTalk solution.

  8. Save all changes and exit the text editor

The following example is a sample fragment from a form manifest and shows an hwsWorkflow section with an action and a task.

<xsf:hwsWorkflow taskpaneVisible="yes">
    <xsf:location url="abc"></xsf:location>
    <xsf:allowedActions>
        <xsf:action name="Approval" actionTypeID
            ="B105B441-496C-FF92-DBF5-0B69376CBB05" 
            canInitiateWorkflow="yes" 
            caption="Start Approval"></xsf:action>
    </xsf:allowedActions>
    <xsf:allowedTasks>
        <xsf:task name="RespondToApproval" 
            taskTypeID="http://tempuri.org/Hws_Task_Approval" 
            caption="Respond To Approval"></xsf:task>
    </xsf:allowedTasks>
</xsf:hwsWorkflow>

Defining the dataAdapters Section

The dataAdapters section within the manifest enables the custom HWS adapters for the form. These custom adapters are based on the Web service adapters of InfoPath and directly call the HWS Web service used by the form. For each action you allow in the HWS task pane of the form, you can define the following operations:

  • addActionToNewActivityFlow

  • addActionToActivityFlow

  • sendTaskResponse

To add the addActionToNewActivityFlow adapter type to the manifest

  1. Ensure that the form is not already open in design mode, and then open the file, manifest.xsf, with any text editor.

  2. If this is the first HWS adapter type to define, add the xsf:dataAdapters element to the xsf:xDocumentClass root element.

  3. Add an xsf:hwsAdapter element as a child of xsf:dataAdapters, and specify values for that element's name, submitAllowed, queryAllowed, and wsdlUrl attributes. The wsdlUrl attribute represents the HWS Web service URL used by the form.

  4. Add an xsf:hwsOperation element as a child of xsf:hwsAdapter, and specify addActionToNewActivityFlow as the value for that element's type attribute.

    In addition, specify values for the typeID and serviceUrl attributes. The typeID value is the same as the actionTypeID value set in the previous section. The serviceUrl attribute represents the URL of the HWS Web service operation to execute.

  5. Add an xsf:input element as a child of xsf:hwsOperation, and specify a value for the source attribute. The source value represents the XML file that is generated by the BizTalk solution in connection with the HWS action.

  6. Add an xsf:partFragment element to xsf:input for each of the required fields in the HWS action. For each xsf:partFragment, specify values for the match and replaceWith attributes. The match value is the XPath statement for the required field in the XML file generated by BizTalk. The replaceWith value is the XPath statement for that field in the InfoPath form.

  7. Save all changes, and exit the text editor.

The following example is a fragment from a form manifest, showing the dataAdapters section with the addActionToNewActivityFlow, addActionToActivityFlow, and sendTaskResponse adapter types defined.

<xsf:dataAdapters>
    <xsf:hwsAdapter name="Approval" 
        wsdlUrl="http://fabrikam1/hwsservice/hwsservice.asmx?WSDL" 
        submitAllowed="yes" queryAllowed="no">
        <xsf:hwsOperation type="addActionToNewActivityFlow" 
            typeID="B105B441-496C-FF92-DBF5-0B69376CBB05" 
            serviceUrl="http://fabrikam1/hwsservice/
            hwsservice.asmx?op=GetActivityList">
            <xsf:input source="Activation.xml">
                <xsf:partFragment match="ActionSection/Target" 
                    replaceWith="/my:myFields/my:Target">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/Description" 
                    replaceWith="/my:myFields/my:Description">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/Status" 
                    replaceWith="/my:myFields/my:Status">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/EndAction" 
                    replaceWith="/my:myFields/my:EndAction">
                    </xsf:partFragment>
            </xsf:input>
        </xsf:hwsOperation>
    </xsf:hwsAdapter>
    <xsf:hwsAdapter name="ExtendApproval" 
        wsdlUrl="http://fabrikam1/hwsservice/
        hwsservice.asmx?WSDL" submitAllowed="yes" 
        queryAllowed="no">
        <xsf:hwsOperation type="addActionToActivityFlow" 
            typeID="B105B441-496C-FF92-DBF5-0B69376CBB05" 
            serviceUrl="http://fabrikam1/hwsservice/
            hwsservice.asmx">
            <xsf:input source="Activation.xml">
                <xsf:partFragment match="ActionSection/Target" 
                    replaceWith="/my:myFields/my:Target">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/Description" 
                    replaceWith="/my:myFields/my:Description">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/Status" 
                    replaceWith="/my:myFields/my:Status">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/EndAction" 
                    replaceWith="/my:myFields/my:EndAction">
                    </xsf:partFragment>
            </xsf:input>
        </xsf:hwsOperation>
    </xsf:hwsAdapter>
    <xsf:hwsAdapter name="RespondToApproval" 
        wsdlUrl="http://fabrikam1/hwsservice/
        hwsservice.asmx?WSDL" submitAllowed="yes" 
        queryAllowed="no">
        <xsf:hwsOperation type="sendTaskResponse" 
            typeID="http://tempuri.org/Hws_Task_Approval" 
            serviceUrl="http://fabrikam1/hwsservice/hwsservice.asmx">
            <xsf:input source="">
                <xsf:partFragment match="HwsSection/TaskStatus" 
                    replaceWith="/my:myFields/my:Status">
                    </xsf:partFragment>
                <xsf:partFragment match="ActionSection/EndAction" 
                    replaceWith="/my:myFields/my:EndAction">
                    </xsf:partFragment>
            </xsf:input>
        </xsf:hwsOperation>
    </xsf:hwsAdapter>
</xsf:dataAdapters>

Conclusion

To create a solution that uses HWS with InfoPath, you must set up the BizTalk orchestration and HWS actions before you design and develop the InfoPath form. The BizTalk solution generates task IDs, which you must include in the form to synchronize HWS and InfoPath. In addition, you must promote as properties any form field values used in the BizTalk orchestration logic so that they are evaluated.

Within the InfoPath form, you add most HWS-related functionality by updating custom sections in the manifest file. The task IDs generated by the BizTalk solution must be referenced in the manifest file.

By integrating HWS functionality with your InfoPath forms, you can more easily direct workflow related to form data.

Additional Resources

For more information, see the following: