Simple SharePoint Workflow with InfoPath Task Form

I’m going to write a series of short(er) articles that I can reference later in longer examples. The focus of this post is to describe how to create an InfoPath form and how to pubish it as a task form, so that it can be used in a custom SharePoint workflow. A task form is presented to a user as part of the CreateTask activity in a SharePoint sequential workflow. It is rendered as a web page and if the user is running Outlook 2007, it can even be displayed within Outlook.

I’ll be using the following tools here:

• InfoPath 2007
• Visual Studio 2008 (with VSeWSS 1.3 installed)

My aim is to describe the following theory:

1. Publishing the form in InfoPath
2. How to reference the form in your workflow
3. Sending data to the form
4. Receiving data from the form

You don’t need InfoPath to create tasks form in SharePoint workflows. You can also use .Net web forms. Reasons for using InfoPath include:

• InfoPath forms are much easier to work with.
• They are natively stored in a serialized format.
• The InfoPath architecture handles the page lifecycle and links the code-behind.

The disadvantages to consider when using InfoPath forms are:

• You need a Microsoft Office SharePoint Server 2007 Enterprise License to render InfoPath forms in the web browser. This includes task forms.
• You are limited to the controls made available to use by web-compatible InfoPath forms. This is a subset of the controls available when building native InfoPath forms and can sometimes require you to get creative to achieve your goals.

A typical task form will contain two text boxes and two buttons. We will build such a form. It will be a simple InfoPath 2007 form with the following controls:

1. Textbox 1 – Details: This will display the details of the workflow. It might be details of an order, or details of a leave application.
2. Textbox 2 – Comments: A place for the user to enter any comments they’d like recorded against the task.
3. Button 1 – Approve: When clicked, the form sends an Approve value back to the workflow.
4. Button 2 – Reject: When clicked, the form sends a Reject value back to the workflow.

Creating the Base Form

Creating the Fields

1. Open InfoPath 2007 and Design a new, Blank Form Template. Be sure to enable broweser compatible features and click OK.
   
2. Using the Data Source pane, rght-click on myFields and add two Text fields. Name Details and the second Comments.
   
3. Click on each of the fields and drag them to the form. Double click on each field to bring up their properties and change them to multi-line fields. Then move & resize them so that you end up with a form that looks like this:
   
4. In the Data Source pane, click on Design Tasks and change to the Controls pane. Add two buttons to the form, just below the text fields. Double-click on each button and change their labels to Approve and Reject. You’ll end up with a form that looks something like this:
   
5. Below the buttons add another text field (add it to the data sources, then drag it to the form) named Result and delete its caption. This field will report the approval result back to the workflow. We don’t want this field to be visible, so add some conditional formatting to hide it.
   1. Double-click on the Result field change to the Display tab.
   2. Click on Conditional Fomatting.
   3. Click the Add button.
   4. Add a condition stating that when Comments is black, hide this control. Click OK the commit the formatting. The configuration will look like this:
      
   5. Add a second instance of conditionl formatting. This time add a condition stating that when Comments is not blank, hide this control. This will ensure that the Result field is always hidden. Click OK to commit the formatting.
6. Still inside the Result field’s properties, change to the data tab and set its Default Value to 0 (zero). We will use this value to check if the form has been changed.

Adding the Publishing Data Connection

1. Now we’ll add a data connection to the form. This data connection will be activated later when the user clicks on a button.
2. From the Tools button, click on Data Connections.
3. Click the Add button and create a data connection to submit data. Click Next.
4. This data connection will submit our data to the hosting environment, such as an ASP.NET page or a hosting application.
5. We’ll leave the data connection named Submit, since that’s what it’s used for. Click next, then finish and return to the form.

Adding the Receive Data Connection

1. We will want to update our task form from the workflow. To send data to the form fields from the workflow, we need to create a receive data connection. For this, we will use a very simple text (XML) file.
2. In the same folder (for convenience) as your form create a new text document. Name it: ItemMetadata.xml. The name is case-sensitive and any other name will not work.
3. Inside this file place the following line of text: <z:row xmlns:z=”#RowsetSchema” ows_Details=”” />.
4. Save and exit the file. If, in future you want to pass other data back to a task form, just create a similar file and reference the fields in your form by adding ows_ before the field name. You can have multiple fields, separated by a space.
5. Back in InfoPath, select Data Connections from the Tools menu.
6. Click the Add button and create a new data connection to receive data.
7. Select XML document as our data source and click Next.
8. Browse to ItemMetadata.xml file you just created and select it. Click Next.
9. Leave the remaining settings at their default value and click Next until Finished.
10. Back in the form,double-click on the Details field.
11. We’re going to set the default value to that passed into the data connection via the workflow. Click the fx button next to the default value field.
12. Click the Insert field or group button.
13. From the Data Source drop-down, select ItemMetadata.
14. Select the ows_Details field and click OK until you return to the form.

Configuring the Buttons

1. Time to configure the buttons. A couple of rules will record the result of the button click and then submit the form using the data connection we created earlier.
2. Double-click on the Approve button and click on the Rules button.
3. Add a new rule and name it Set Result.
4. Click the Add Action button. Use the Set a fields value action to set the result field to 1. The Action box looks like this:
5. Click OK and use the Add Action button again to add a second action to this rule.
6. This time select the Submit using a data connection action. Ensure the Submit data connection is selected and click OK.
7. Again, click the Add Action button to add a third and final action to this rule.
8. Select the Close the form action and click Ok. The final ruleset should look like this:
9. Repeat step 8 for the Reject button. The only difference is to set the Result fields value to -1 in step 4.

Setting the Correct Security Level

There’s a couple of settings that we need to configure so that the form will open correctly in our workflow.

1. From the Tools menu, select Form Options.
2. In the Security and Trust category, turn off the Automatically determine security level setting and select Domain.
3. Click OK to commit the change

Publishing the Form

1. Before you publish the form, you must save it. Save it as TaskForm0. Again, that’s a zero at the end of the filename, not the letter o. This font is weird.
2. Now it’s time to publish the form. From the File menu, select Publish.
3. Publish the form to a network location. This is just a generic publish mode and is all we need. Click Next.
4. The form template path is the location that the published version of the form will be saved. I will save it to a Published subfolder of the folder where I saved the form earlier.
5. Use the same filename as you did for the form in step 1. The form template name will be filled in automatically. Click Next.
6. This screen asks you to create an alternate access path. I don’t know what this is. What I do know is that every guide I’ve ever read says to ensure that field is blank. I have never left anything in there, so I don’t know what will happen if you do. Just delete any text in that field and click Next. If you receive a warning, just select that you know what you’re doing and want to continue.
7. You’ll receive a summary. Click Next and then Finish.

That’s the form ready to go. We’re now finished with InfoPath and ready to wire it up to our workflow in Visual Studio. If you decide to make any changes to your form you will have to save and publish it again.

A Simple Workflow to Host the Task Form

I’m going to use Visual Studio 2008 to create a simple workflow to host the task form and prove the theory. Before starting, ensure that you’ve also installed the Visual Studio Extensions for Windows SharePoint Services (version 1.3). These extensions include project templates that make developing (and deploying) WSS solutions easy.

You’ll also need a SharePoint list to deploy the solution to. To make life easier, develop your solution on the same server running SharPoint. I run a virtual machine, from my development laptop, with Windows 2003 Server, SharePoint 2007, SQL Server 2005 & Visual Studio 2008. If you don’t have an MSDN license, check Microsoft’s web site for trial versions of these applications.

Creating the SharePoint List

The focus of this example is to illustrate how to interact with an InfoPath task form from within a SharePoint workflow. To illustrate this we need a SharePoint list to host the workflow and a SharePoint workflow to host the task form. First, let’s create the list:

1. Open your SharePoint site and create a new Custom List. Call it SimpleWorkflow.
2. From the List Settings, rename the Title field to Details.
3. Create a new Multiple lines of text column. Call it Comments and set it to plain text.
4. Create a new single line of text field and name it Result.

Creating the Workflow Project

1. Open Visual Studio and from the File menu, select New Project.
2. If you’ve got the VSeWSS installed, you’ll be able to select SharePoint 2007 Sequential Workflow from the Office Project Types.
3. Name your project. I’m calling mine SimpleWorkflow (same as the list. One less thing to remember). Take note of where you’re creating the project, because we’ll be copying files to that location later.
4. Click OK and VS will start the New Workflow Wizard (we didn’t have these when I was a kid).
5. Leave the workflow name, but change the local site to the address of the SharePoint site you created the list in earlier. Click Next.
6. Allow VS to automatically associate the workflow. This allows us to use the Publish feature in VS to easily push any changes out to the list we specify. It save a lot of time (and scripting).
7. Select the SimpleWorkflow list from the drop-down. Leave the history and task lists and click Next.
8. Set the workflow to only be started When an item is created. Turn off the Manually by users option.
9. Click Finish. Your project is created and you’ll be left staring at the workflow designer.

Adding the Published Task Form to the Project

1. Using Windows Explorer, browse to the project’s folder and create a new subfolder named Forms.
2. Copy the published task form and paste it into this new Forms folder.
   

Updating workflow.xml

1. The form is now available to the project, but the project doesn’t yet know that it exists or that it’s a task form. We have to update the workfow.xml file with information about the form. The workflow.xml file describes our workflow., but I’m not going to go into all the settings here.
2. In the Metadata element, you’ll see there’s a Task0_ForumURN tag that’s commented out. Uncomment this field and add the task form’s URN. To get the URN:
   1. Open Windows Explorer and browse to the published task form’s location.
   2. Right-click on the form and select Design. This will launch InfoPath and open the form in design mode.
   3. From the file menu, select Properties. Copy the ID field.
3. After you’ve pasted the task form’s URN, the MetaData element should look something like this:
   
4. There’s one more change to make to the workflow.xml file. We have to tell the workflow to host the task form within a web form This is achieved by providing the GUID of the InfoPath form content type. The code to achieve this is:
   TaskListContentTypeId=”0x01080100C9C9515DE4E24001905074F980F93160″
5. The code is inserted within the Workflow element. After you’ve added the code, the Workflow element will look like this:
   

Updating Feature.xml

1. The feature.xml describes all the resources of our workflow. This includes the location of the workflow.xml, any other files that need copying when the feature is installed and which forms to register with the forms server. Double-click on feature.xml in the VS Solution Explorer to open it.
2. First, we need to tell the feature.xml the location of our task form file. We do this by creating an ElementFile tag. This tag accepts a file path relative to the location of feature.xml and will ensure that our task form is copied up to the server when the feature is installed. Add the element file reference, so that the ElementManifests tag looks like this:
   
3. Second, we need to tell feature.xml which forms to register with SharePoint, as belonging to this workflow. We created a Forms folder earlier. Rather than specifying individual forms, I always create this folder and copy all my forms to it. As such, we can use a wildcard value to tell feature.xml to register any .xsn files it finds in the Forms folder. The Register Forms property sits within the Properties element. Modify the Register Forms property to look like this:
   

Designing the Workflow

To use the task form we will use a workflow that:

1. Creates a workflow task.
2. Waits for the task to change.
3. Completes the task when the task form is completed.

Using the VS workflow designer, complete the following:

1. From the VS toolbox add a CreateTask activity to the workflow and set the following properties:
   • Correlation Token: taskToken
   • OwnerActivityName: Workflow1
   • TaskId:  Use the ‘details’ button. Bind to a new Member. Select Create Field and leave its name as createTask1_TaskId1. Click OK
   • TaskProperties: Use the ‘details’ button. Bind to a new Member. Select Create Field and leave its name as createTask1_TaskProperties1. Click OK.
   • The designer and properties will look like this
       
2. From the VS toolbox add a While loop to the designer. The While loop will show an error. Ignore this for now. The designer will now look like this:
   
3. Add an OnTaskChanged activity inside the while loop. Set the following properties:
   • Correlation Token: taskToken
   • OwnerActivityName: Workflow1
   • AfterProperties: Use the ‘details’ button. Bind to a new Member. Select Create Field and leave its name as onTaskChanged1_AfterProperties1. Click OK.
   • BeforeProperties: Use the ‘details’ button. Bind to a new Member. Select Create Field and leave its name as onTaskChanged1_BeforeProperties1. Click OK.
   • TaskId: Use the ‘details’ button. Bind to an existing member. Select createTask1_TaskId1. Click OK.
   • The designer and properties will now look like this:
      
4. Add a CompleteTask activity. This is the last activity we’ll be adding to this workflow. Set the following properties:
   • Correlation Token: taskToken
   • OwnerActivityName: Workflow1
   • TaskId: Use the ‘details’ button. Bind to an existing member. Select createTask1_TaskId1. Click OK
   • Task Outcome: Successful
   • This is what the designer looks like with all our activities added.
     

Coding the createTask1 Activity

1. Double-click on the the createTask1 activity to bring up the code view.
2. Add the following code. An explanation will follow:
   
   • Lines 35 & 36: Just outside the CreateTask method, create to variables to store the description and comments field. This is not absolutely necessary in this example, but I’ve found that its good to retreive your variables once and use them locally. The advantage becomes apparent in larger workflows.
   • Line 39: Every task needs a new GUID.
   • Line 40: The AssignedTo field designates the person that will be assigned the workflow. It takes in a username. In this simple example, we will assign the workflow to the person that activated the worklow. Not very exciting, I know.
   • Line 41: The TaskType identifies the task form to be used. In this workflow, we’re only using one task form, but in more complex workflows there may be many task forms. Make sure this number matches the number in the TaskFormX_URN in the workflow.xml file.
   • Line 42: The task Title is shown in the workflow properties screen of the list item and is also used in the email advice that’s sent out to the AssignedTo person.
   • Line 43: The Description text makes up the body of the email advice.
   • Line 45: I’ve had bad experiences when grabbing field values from list items. I find that, sometimes, if the field’s empty SharePoint returns null. This can play havoc with code. These days, I always test if the field is null before attempting to return its value. Notice that I’m calling the field Title (and not Details). When you rename a field in SharePoint, you only rename its display name; the internal name does not change. If you ever need to find the field’s internal name, edit the field via the list’s settings. The field name is the last parameter of the URL in your browser.
   • Line 47: Grab the text in the Details field and store it in the class variable we created in line 35.
   • Line 48: The task properties’ ExtendedProperties is a hash table. This hash table allows easy access to the form’s data. If you pass data into the ExtendedProperties, the form will match it to a field and pass that data into the field.
3. That’s is to the createTask1 activity. There’s really not that much code to it. As always with SharePoint development, the trick is knowing how to wire it all up.

Coding the onTaskChanged1 Activity

1. The onTaskChanged1 activity executes once the task has been completed (i.e. the task form has been opened and submitted back to SharePoint). Jump back to the design view and double-click on the createTaskChanged1 ativity to bring up the code view.
2. Add the following code. Just like before, I’ll explain the code below:
   
   • Line 52: Just above the onTaskChanged method, create a variable to store the result of the task. Cast your mind back to the task form. We set the Result field to 0 by default. The Approve button changes the Result value to 1 and the Reject button to -1. So, by examining this variable, we’ll know how the approver voted.
   • Line 55: Again, we access the form’s fields via the ExtendedProperties hash table. We change the value to a string and pass it to a method variable.
   • Line 57: Set the comments (class variable) to the value of the Comments field
   • Line 58: Cast the method variable to an integer and update the result, class variable.
3. That’s it. Three lines of code and we’ve grabbed the task form’s fields and also determined the task’s result.

Configure the While Activity

1. The while activity plays a very important task in the workflow. It forces the onTaskChanged activity to wait until the task form is completed, before continuing the workflow. Without it, the onTaskChanged activity would complete instantly, instead of recording the result of the task. We’ll configure the while activity to continue looping (and waiting), until the task form’s Result field has been changed. While the Result is equal to zero, the workflow will not continue and the onTaskChanged activity won’t commit its values.
2. We’ll configure the While loop using a Declarative Rule Condition. In the workflow designer, click on the While actvity to bring up its properties.
3. From the Condition property drop-down, select Declarative Rule Condition.
4. On the Condition Name line, click the Details button to bring up the Select Condition dialog.
5. Click New and in the text editor, enter: result == 0. This is shown below:
   
6. Click OK a couple of times the return to the editor.

Coding the CompleteTask Activity

1. This is the final activity in this workflow. There’s two things we want to achieve here. Firstly, we’ll want to write the approver’s comments back to the list item. Secondly, we’ll write the approval result back to the list item.
2. Double-click on the CompleteTask activity to bring up the code view.
3. Here’s the code:
   
   • Lines 63 & 66: The using statements allow our code to run within the context of our SharePoint site. They’re nice ways to work within the context as they don’t require you to dispose the SPWeb object manually.
   • Lines 65, 68, 84 & 86: You must enable unsafe updates on your site collection and site if you’re updaing a site object via the object model. We need this to perfom the update command on line 83. Make sure to turn them off before exiting, to prevent unwanted code messing with your site.
   • Line 70: Get a reference to the list item this workflow orginated in. This is nicer than referencing the list by name as the code can be reused if you moved the workflow to another server or list.
   • Line 71: Update the Comments field with the approver’s comments we gathered in the onTaskChanged method.
   • Lines 72 – 82: For this code to have executed, the result field must’ve changed from its default value of 0. If it’s set to 1, then the approver must’ve selected Approve in the task form; if -1, it was Rejected.
   • Line 83: Update the list item. List items haven’t been commited until this point. Normally I’d wrap this code in a try\catch block as we’re interfacing externally.

Publishing the Workflow

1. We’ve finished. We’ve built our form, built our workflow we’re ready to test it out.
2. Thanks to the VSeWSS and VS2008 we can publish the workflow to our SharePoint site in a single click.
3. From the Build menu, select Deploy. VS will:
   1. Build your code
   2. Copy the files to the SharePoint site’s 12\TEMPLATE\Features\ProjectName folder.
   3. Activate the feature which will install the task form in SharePoint Forms Services
   4. Install the compiled DLL into the GAC.
   5. Activate the workflow to the site collection, so that it’s available to be added to lists.
   6. Associate the workflow with the list we chose in the Workflow Wizard.

If you want to change the site and list that you’d initially selected, right-click on the project name in the Solution Explorer and select SharePoint Debug Settings. This will bring up the wizard again. If you’re working in a small environment, you could use this as your formal deployment method. In a larger enterprise, you’ll probably need a more manual deployment procedure, consisting of copying the project files to the server, installing the DLL in the GAC and usng stsadm to install, then activate the workflow.

Testing the Workflow

1. Browse to the list you created at the beginning of this guide.
2. Create a new list item and enter some text in the Details text field. The other fields are also showing. In your own time, you can hide these fields by a number of methods; one is to modify the content type and hide the fields from appearing in forms.
3. If you have email enabled, you’ll soon receive a task email which will allow you to complete the task. If not, hover over the item’s Details and select Workflows from the drop-down. Under Running workflows, click on the workflow title (SimpleWorkflow for me).
4. Your task form will open in the web browser (Yay!!), with the Details from the list item already populated (Yay again!!).
5. Enter some text in the Comments field and approve the form.
6. Browse back to the list and you’ll see the Details, Comments and Results have been entered into the list item by our workflow (Yay!)

So.. I failed in writing a short post. I’ll try harder next time. I hope this helps clear up some of the confsion associated with this topic.

References

• http://msdn.microsoft.com/en-us/library/ms550782.aspx
• http://msdn.microsoft.com/en-us/library/ms550938.aspx
• http://blogs.officezealot.com/jkremer/archive/2006/06/16/10887.aspx
• http://www.sharepointkings.com/2008/08/how-to-get-currently-logged-in-user-in.html
• http://msdn.microsoft.com/en-us/library/ms460303.aspx

Download the full source code and all related file for this project from my Live SkyDrive: http://cid-ba333a1e7a3f182a.skydrive.live.com/browse.aspx/.Public/SharePoint%20Gear

About Fodi Dervidis

A software engineer by trade, with a Masters degree in eCommerce, I focus on delivering end-to-end business solutions. ...and SharePoint's my platform.

‹ Super Mega Quiz – SharePoint & InfoPath Working Together

Ready, Set, Workflow – Using SetState to Update Workflow Status ›

Tagged with: complete task, completetask, Create Task, data source, InfoPath, ontaskchanged, ows, SharePoint 2007, Task Form, Workflow, workflowproperties, xml
Posted in C#.Net, InfoPath 2007, SharePoint 2007, Visual Studio 2008, Workflow