How to: Access Contact Data in Workflow Initiation and Modification Forms in SharePoint Server 2010 (ECM)

Applies to: SharePoint Server 2010

Microsoft SharePoint Foundation sends the data from Office InfoPath 2007 forms used in workflows to the workflow instance as XML. This includes the contact data specified by the user in the Contact Selector control. To use this data in the workflow, you must parse the form XML passed to access the contact data.

The location to which SharePoint Foundation passes the form XML data depends on the type of workflow form:

  • For workflow initiation forms, SharePoint Foundation passes the entire form data as an XML string to the WorkflowProperties.InitiationData property of the OnWorkflowActivated activity.

    For more information about this workflow activity, see the Microsoft Windows SharePoint Services 3.0 SDK.

  • For workflow modification forms, SharePoint Foundation passes the entire form data as an XML string to the ContextData property of the EnableWorkflowModification activity.

    For more information about this workflow activity, see the Microsoft Windows SharePoint Services 3.0 SDK.

Note

In the case of workflow task forms, the form data is passed as a hash table object, rather than as an XML string. For information about how to access contact data in task forms, see How to: Access Contact Data in Workflow Edit Task Forms.

For information about the schema of the contact data XML, see How to: Configure a Contact Selector Control on Your InfoPath Workflow Form (ECM).

You can use two approaches to parse the form XML to retrieve the contact data:

  • Use helper classes included with Office SharePoint Server 2007. The Microsoft.Office.Workflow.Utility namespace contains classes, such as the Form and Contact classes, that are designed to help you deserialize and access the contact data.

    The Form class includes a method to deserialize an InfoPath form field into a hash table object, with key-value pairs corresponding to the fields of the form.

    The Contact class includes methods to serialize and deserialize the Contact Selector data, and to access the relevant data for those contacts.

  • Use the XML deserialization functionality included in the Microsoft .NET Framework 2.0.

For more information about workflow association and initiation forms, see Workflow Association and Initialization Forms in SharePoint Server 2010 (ECM).

To access Contact Selector control data in workflow initiation or modification forms by using the Form and Contact classes

  • Include code in your workflow that does the following:

    1. Uses the XmlToHashtable method to create a hash table from the initiation data stored in the variable specified for the WorkflowProperties property of the OnWorkflowActivated activity.

    2. Uses the ToContacts method to create an array of Contact objects from the hash table.

      For example:

      Hashtable ht = 
      Form.XmltoHashtable(workflowProperties.InitiationData);
      Contacts[] contacts = 
      Contact.ToContacts(ht["myUsers"].ToString());
      
      Dim ht As Hashtable = Form.XmltoHashtable(workflowProperties.InitiationData)
      Dim contacts() As Contacts = Contact.ToContacts(ht("myUsers").ToString())
      

      In the example, the variable specified for the WorkflowProperties property of the OnWorkflowActivated activity is named workflowProperties. The first line of code uses the XmlToHashtable method to create a hash table from the InitiationData property of this variable. Next, the code creates an array of Contact objects by generating a string from the key-value pair representing the contact data in the hash table, and then calling the ToContacts method.

      Note

      The key-value pair representing the Contact Selector control data is accessed by using the name of the control on the form; in this case, the control is named myUsers.

To access Contact Selector control data in workflow initiation or modification forms by using the .NET Framework XmlSerializer class

  1. Extract the schema of your initiation or modification form.

    1. In Office InfoPath 2007, open your saved and published workflow form.

    2. On the File menu, click Save as Source File. Browse to the location to which you want to save the form source files, and then click OK.

    InfoPath saves a collection of form source files, including the schema file, to the specified location. The form schema file is always named myschema.xsd.

  2. Use the Microsoft Visual Studio 2005 command line tool xsd.exe to generate a new class file from the form schema. By default, Visual Studio 2005 installs the xsd.exe command line tool to the following path, where C: represents the drive on which you have installed Visual Studio: C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin.

    1. Open a Visual Studio command line prompt. Click Start, point to All Programs, point to Microsoft Visual Studio 2005, point to Visual Studio Tools, and then click Visual Studio 2005 Command Prompt.

    2. Navigate to the location of the form schema (.xsd) file, and then run the following command: xsd myschema.xsd /c /o:output_directory.

      This command generates a new class file based on the form schema, named the same as the schema file. The class in the file is named the same as the root element of the schema, which was named the same as the form fields collection.

      The class contains an array of type Person, with the same name as the Contact Selector control on the form.

  3. In Visual Studio, add the new class file to your workflow project.

  4. Include code in your workflow that deserializes the entire XML form string into an object whose type is that of the class you generated from the form .xsd file.

    In the following example, the form fields collection is named MyFields, so the class generated from the form .xsd file is also named MyFields.

    XmlSerializer serializer = new XMLSerializer(typeof(MyFields));
    xmlTextReader reader = new XMLTextReader(new 
    System.IO.StringReader(workflowProperties.InitiationData));
    MyFields fields = serializer.Deserialize(reader);
    
    Dim serializer As XmlSerializer = New XMLSerializer(GetType(MyFields))
    Dim reader As xmlTextReader = New XMLTextReader(New System.IO.StringReader(workflowProperties.InitiationData))
    Dim fields As MyFields = serializer.Deserialize(reader)
    
  5. To access the contact information, include code that accesses the form information by using the various class properties, which are named the same as the various controls on the form.

    In the following example, the Contact Selector control on the form is named Users. Therefore, to access the accountID data of a contact, the code accesses the Users[i].accountID property.

    string accountID = fields.Users[i].accountID;
    
    Dim accountID As String = fields.Users(i).accountID
    

Note

If you want to take advantage of the functionality offered in the Contact utility class, you can create a Contact object from the account ID returned by the previous code by using the FromName static method.

See Also

Tasks

How to: Add the Contact Selector to InfoPath (ECM)

How to: Configure a Contact Selector Control on Your InfoPath Workflow Form (ECM)

How to: Access Association and Initiation Form Data in a Workflow in SharePoint Server 2010 (ECM)

How to: Design a Workflow Form to Use Association and Initiation Data in SharePoint Server 2010 (ECM)

Concepts

InfoPath Forms for Workflows (ECM)

Using the Contact Selector Control in InfoPath Workflow Forms (ECM)

Other Resources

How to: Access Contact Data in Workflow Edit Task Forms