KB000168

Introduction

Background Information

It is important to understand what occurs behind the scenes during the creation of an InfoPath process in order to understand the communication flow and interaction with the various components involved during execution of the process.

When an InfoPath process is created using K2.net Studio 2003, the InfoPath Process Wizard will prompt for the information needed to integrate the process with K2.net Server and optionally, SharePoint.

The Wizard performs two primary functions:

1. It modifies the InfoPath form template to include the K2.net functionality required to integrate with K2.net Server. For example, K2.net specific fields are added, Data Connections that submit to the K2.net InfoPathService Web Service are created, Rules that define the view to be used when the form is opened are created etc.
2. It creates Process XML Fields from the InfoPath Form Template needed to store the InfoPath form data as Process data during the execution of the process. Process Data Fields are also created for the SharePoint integration etc.

The Wizard creates two InfoPath Activities:

• InfoPath Initialize Activity with InfoPath Server Event
  
  The first Activity contains an InfoPath Server Event that defines where the completed InfoPath form data will be saved; either to a File System or a SharePoint Workspace. When integrating with SharePoint, this event can be configured to use an existing Workspace or create a new one.
• InfoPath Activity with InfoPath Client Event
  
  The second Activity contains an InfoPath Client Event that defines what occurs when the item is placed on a Destination User's Worklist. For example:

1. What View will be used when the InfoPath form is open?
2. Will the Worklist item be added to a SharePoint Task List?
3. Will an email notification be sent to the Destination User?

In addition, the Succeeding Rule for this Activity will handle clean-up operations such as deletion of temporary files. This specialized Succeeding Rule is discussed in more detail below.

 When the InfoPath Process Wizard completes, the process as seen in K2.net Studio will look similar to the following:

To illustrate what occurs during execution of the process, assume we are using the process shown above for a simple Travel Request scenario where the InfoPath form has two views; the default view named 'Request' and an 'Approval' view. The InfoPath Initialize Activity and Event defines the storage location of the InfoPath form data submitted by an employee for a Travel Request using the 'Request' view. In this example the process is integrated with SharePoint and thus the form will be stored in SharePoint when submitted by the user.

The second InfoPath Activity and Event will then handle the approval of the Travel Request. The Client Event will create a Worklist item for each approver (Destination User) that displays the form populated with the data submitted by the employee, using the view specified in the Client Event; in this case the 'Approval' view rather than the 'Request' view.

While this is simplified example for a Travel Request scenario, it can be used to demonstrate what happens behind the scenes during the execution of the process from submittal of the Travel Request form through completion of the process. The diagram below shows the communication flow that occurs during the execution of the process. Each step of the process execution is described in detail below.

1. 1. InfoPath 'Travel Request' Form Retrieved from SharePoint
      
      The client, User A, retrieves the InfoPath form from the SharePoint Form Library. The form is downloaded and opened in InfoPath on the client machine using the 'Request' view, the default view of the InfoPath form.
   2. InfoPath Form submitted to InfoPathService
      
      User A completes and submits the InfoPath form. The form data is submitted to the K2.net InfoPathService Web Service on the IIS server. The InfoPath form contains Data Connections that were added by the InfoPath Process Wizard that will submit the form to the K2.net InfoPathService Web Service. See the Background Information section above to understand how the InfoPath form is modified to include this information.
   3. K2.net InfoPath Process Started
      
      The K2.net InfoPathService Web Service uses K2ROM to connect to the K2.net Server and start the process using the credentials of the user that submitted the form. The connection string for the K2.net Server along with the process to be planned is also included in the form data. Again, see the Background Information section above for additional details. Note that in this example configuration, Kerberos authentication must be configured to pass the user's credentials from the IIS server to the K2.net Server.
      
      The K2.net Server will populate the K2InfoPathSchema Process XML field that was added during creation of the process with the form data submitted by the user.
      
      When the Process is integrated with SharePoint, the InfoPath Server Event will also populate the Process Data Fields, K2DWSPath and K2DWSName, with the SharePoint Workspace URL and name of where the temporary InfoPath xml file will be stored in SharePoint. Note that at this point the form data resides only in the Process XML field and does not exist in SharePoint. The Server Event simply defines the SharePoint Workspace that will be used to store the InfoPath form data as an xml file.
       
      1. New Workspace Created in SharePoint
         
         The InfoPath Server Event will also handle the creation of a new Workspace if the SharePoint integration was configured to create a new Workspace rather than use an existing one. The K2.net Server accomplishes this by creating an instance of K2SPSList which calls the "/_vti_bin/K2SpsList.asmx" web service on the SharePoint server to create the Workspace
   4. InfoPath Activity and Client Event Executed
      
      The Succeeding Rule for the InfoPath Initialize Activity evaluates to true when the Server Event completes and the InfoPath Activity is instantiated for each Destination User. It contains an Activity level instance of the K2InfoPathSchema XML field and additional Activity level data fields in support of the InfoPath Client Event.
      
      The InfoPath Client Event then executes and handles several tasks:
      
      Process XML Copied to Activity XML
      The Process level K2InfoPathSchema XML field is copied to the Activity level K2InfopathSchema XML field. Note that each Destination User will have their own copy of the InfoPath form data. This includes the travel request data submitted by the user as well as the K2.net specific data such as the Serial Number, ConnectionString, DocumentView etc.
      
      InfoPath Form Saved to Temporary XML file
      Since the Client Event is integrated with SharePoint, the InfoPath form data stored in K2.net will be uploaded as a temporary xml file to the SharePoint Workspace specified in the InfoPath Initialize Server Event (see step 3). A temporary file will be created for each Destination User if the client event was configured to use unique temporary filenames. If the client event is not integrated with SharePoint, a location on a file system must be specified for storing the temporary files.
      
      The K2.net Server creates an instance of K2SPSList (K2SPSList.dll) which calls the "/_vti_bin/K2SpsList.asmx" Web Service on the SharePoint server to upload the file.
       

      Note: When the "Integrate with SharePoint" option is chosen in the Client Event, it allows for selection of a specific Document Folder. This must be an existing folder that resides in the Workspace specified in the Server Event. If an existing Workspace was selected in the Server Event, then the Browse button will be enabled for selecting the Document Library and Folder within that Workspace at design time. If the Server Event was configured to create a new Workspace, use the default folder of 'Shared Documents', since the new Workspace will be created at runtime and 'Shared Documents' will be the only document library that exists.

      
      SharePoint Task List Item Created
      The Client Event can optionally be configured to add the item to a SharePoint Task List making the Worklist item available from within SharePoint. The Task List item creation is also handled by the same instance of K2SPSList that was used to upload the file. It too calls the "/_vti_bin/K2SpsList.asmx" Web Service to create the Task List item.
      
      K2.net Worklist Item Created
      A Worklist item is created for each Destination User. Note that the InfoPath form view is defined in the Client Event and gets included in the K2InfoPathSchema xml field. When a user opens the Worklist item (the InfoPath form), the InfoPath Rules added during creation of the process are executed to determine which view will be used.
      
      In this example, the Client Event was configured to use the 'Approval' view, so when the Worklist item is opened the InfoPath form will be displayed using the 'Approval' view.
      
      Other
      The Client Event can also be configured to perform other tasks such as sending an email notification that will include a link to the Worklist item
   5. InfoPath 'Approval' Form Retrieved from SharePoint
      
      User B, a Destination User for the InfoPath Activity, opens the InfoPath form now stored as a temporary file in SharePoint via one of the following mechanisms:
      1. The Task List Item in SharePoint if one was created by the Client Event
      2. The user's Worklist. For example using Workspace or a custom application
      3. A link to the Worklist item included in an email notification

The Worklist item is a link to the temporary InfoPath xml file that will be downloaded and opened in InfoPath using the 'Approval' view of the form.

In this example, assume User B is using the Task List item in SharePoint to launch the 'Approval' view of the InfoPath form that will display the data submitted by User A

Note: The form could also be opened using the direct link to the temporary xml file in the SharePoint site, however, when using unique filenames there is a temporary file for each Destination User. These files are added by the K2.net Service account and by default there is no means of determining which file corresponds to a particular user. It's possible that one user could complete another user's Worklist item. In addition, depending on how the Client Event was configured, the Submit button may be hidden if the wrong file is opened.

1. InfoPath 'Approval' Form Submitted to InfoPathService
   
   User B either approves or declines the travel request using the 'Approval' view of the form and submits it to the K2.net InfopathService web service. Again, the Data Connection configured in the InfoPath form contains the url for the InfoPathService web service.
2. InfoPath Process Instance Updated in K2.net
   
   The K2.net InfoPathService web service uses K2ROM to connect to the K2.net Server and complete the Worklist item as the user that submitted the Approval form. Again, Kerberos authentication must be configured to pass the user's credentials from the IIS server to the K2.net Server.
3. InfoPath Process Completed
   
   The Succeeding Rule will execute for User B and delete the temporary InfoPath xml file if the Client Event was configured to do so. The Task List item for User B, if one was created, will also be deleted. If the Succeeding Rule evaluates to true, the temporary files and Task List items will be deleted for all Destination Users and the process will complete. This is done using an instance of SourceCode.K2SPUtilities.SPSUtilities on the K2.net Server that calls the '/vti_bin/K2SPSList.asmx' web service on the SharePoint server as the K2.net Service account.
   
   The Succeeding Rule will then copy the K2InfoPathSchema Activity level field back to the K2InfoPathSchema Process field.
    

   Note: In a situation where there are multiple Destination Users that must approve the request before the Succeeding Rule evaluates to true, the Process xml will be overwritten by each successive approver and will ultimately contain the data from the last user to approve the form, just prior to the succeeding rule evaluating to true. It is important to be aware of this if the Process level data will be consumed later in the process or by another application.

   In this example the activity was limited to one slot and when User B submits the Approval form the process is complete.