An extended member of the Microsoft Office Suite, InfoPath, as is a rich forms designer tool, designed to provide quick and easy creation of essentially paper-based forms for easy data capture and form filling.

Underneath the InfoPath designer (user interface) is an extensive XML schema and data model, into which K2 injects XML nodes and values for interacting with the workflow logic within the process.

Additionally, there is the ability to specify different views of the form, to show at certain logic points within the process, or for different security levels.

The workflow decision points known as actions are added to the InfoPath form by the K2 integration, with a combo box added to allow a user to select the relevant outcome when submitting the form.

Within the InfoPath world, there is the option to create rich-client forms, which requires users to have the InfoPath product installed on their local PCs or to display the form within a Web browser, using Office Forms Server (often referred to as InfoPath Forms Services) and SharePoint to allow for browser-based forms.

If the project or organization has a requirement to provide forms with rich user interfaces, or there is a need to integrate with additional back-end systems, then the choice of Web forms, Web pages, Web services and Web parts developed using ASP.NET is another option.

Using Visual Studio, you can create custom designed layouts and rich user interfaces including Silverlight, AJAX, and numerous custom controls, as well as create code that can reference namespaces and class libraries as part of the .NET framework and object model.

Using standard .NET languages such as C# and VB.NET, and the rich K2 API and object model, you can create Web pages that programmatically read values within the workflow process to display on screen in whichever text formatting, layout, or graphical design as required.

The Web pages are hosted within IIS, with the corresponding Web page address used within the workflow designer. The K2 process is configured to use the particular Web page URL, and the necessary input parameters (querystring) are provided automatically by the K2 integration. The Web page will then use the values to determine the user task, and the process associated with it.

The actions defined within the process can be shown to users, and then the relevant outcome determined, along with the saving of any workflow data variables users may have entered or updated.

There are a number of other forms technologies that can be included in the K2 process designer as Client Event forms. This chapter centers on the main choices of InfoPath and ASP.NET, and so only a high-level overview is provided.

C:Program FilesK2 blackpearlWorkspaceClientEventPages

There are many different decisions as to which forms technology to adopt, and there are perfectly valid reasons to use any one of these options, just as there are similar reasons why each should not be chosen. The choice will often depend on infrastructure, such as software available, and any budgetary or timing considerations, rather than any specific technical shortfalls of either approach.

The criteria list includes topics such as:

First, let's have a look at some of the pros and cons with regard to the two main contenders — InfoPath and ASP.NET.

InfoPath Pros

InfoPath is a great Microsoft Office-friendly product, primarily used to design the typical paper-based form. The interface to design forms is simple and intuitive, making it a great choice for business users, and power users alike, without the need to know any code.

The InfoPath designer includes a data source designer with an underlying XML schema file. There are numerous WYSIWYG forms layout tools that allow a user to quickly create professional-looking forms. The completed form contains both the form layout, and data elements and values, in a self-contained XML format.

InfoPath has a number of standard template forms allowing the organization to immediately start designing processes such as Expense Claims, Asset Tracking, or Travel Request.

It's easy to create views, which can be targeted using security, such as staff-, manager-, and CEO-level security views, for example. Alternatively, this may be based on logic related to certain business rules — such as "When stock is less than 10,000, display the LowStockDiscount view," with different data fields shown, for example.

Fields within a view can be hidden, read-only, and change colour/font dynamically according to the business rules to be implemented (within the K2 workflow).

Following the design of the various views within InfoPath, the client event inside the K2 Designer is configured with the specific view to show for the particular event. This can be seen in Figure 11-2.

Figure 11.2. Figure 11-2

The data validation capabilities of InfoPath are significant, with rules able to be configured by the user creating the form. Simply using drop-downs, the designer can select that certain field values must be greater than, less than, blank, not blank, match a pattern, and so on, as well as make comparisons between fields, dates, entered values, or using a formula.

These rules can then display a validation message to the user as a screen tip (or, if using rich-client forms, a message box dialog can be used). Users will not be able to submit the form until these validation errors have been corrected, although they can save the form (if the save option for the form has been set) and then update and submit at a later date. The same validation rules will be applied when the user resubmits the form.

The integration with K2 is deep, and provides the ability to modify and design InfoPath forms using the K2 Designer, with tools such as Visual Studio, Visio, or K2 Studio. With the InfoPath form being an XML file underneath, the K2 Designer can easily add nodes, update values, and include details for actions and outcomes.

When the K2 process is executed, the entire XML for the InfoPath form is loaded into a data variable within the process instance, meaning that server code within a K2 Server Event can read, add, and update nodes, and enact changes to the data that is then to be displayed to the user on the form.

A number of Web service data connections are added, to interact with the K2 Web services, upon loading, updating, and submission of the form, depending on the actions and outcomes defined for the process.

A big plus for K2 developers is that the InfoPath files will be included as items within the Visual Studio solution. This keeps all components within the same project, which in turn allows for the use of source control tools such as Team Foundation Server and Visual SourceSafe. InfoPath forms are also relatively easy to deploy, depending on the choice of destination.

InfoPath also allows users to interact with forms using a Web browser. Simply known as browser-based forms, the InfoPath Forms Services (as part of the SharePoint Enterprise installation) allow users to have InfoPath forms shown in a Web browser, rendered using HTML, JavaScript, and CSS. This means that end users (Form Fillers) won't need to have the Microsoft Office InfoPath tool installed.

When using SharePoint and InfoPath, an end user can open an InfoPath form from a document library and have SharePoint events intercepted, which can then initiate a K2 process. This means that the end user simply clicks "New," fills out the form, and once the form is submitted, the K2 workflow commences, using the form data. That seamless integration for initiating workflows is a great feature and one of the reasons that many organizations opt for InfoPath.

Alternatively, using the rich-client InfoPath form allows items saved within a SharePoint document library to be saved locally, meaning there is also an offline capability.

A rich-client InfoPath form can also act purely as an offline file, and has no requirement to coexist with SharePoint at all. These files can be treated as a Microsoft Word or Excel file, allowing a user to e-mail the form within an organization and use the data to interact with a business process on a central K2 server.

Last, the integration with K2 SmartObjects means that the display mechanism for this data can be InfoPath forms. Using a data connection, and mapping fields to the view, the InfoPath form will allow for saving data back to the same SmartObjects upon submission of the form.

Using the original criteria detailed earlier, and after an overview of the pros and cons of both front-runner forms technologies, there may still be some confusion relating to the best option to choose. The following table examines the capabilities from another perspective.

Creating a K2 process that uses an InfoPath form is a relatively simple task using the InfoPath Process Integration and InfoPath Client Event Wizards. Developing InfoPath forms is outside the scope of this book; however, this chapter will cover in detail how an InfoPath form is integrated with K2, design and integration considerations, and how to manage the InfoPath form with K2. This chapter will demonstrate how to create a simple InfoPath approval process. In Figure 11-3, it depicts a process where an InfoPath form is submitted and both a manager and director will need to approve the submission. If either of them were to reject the submission it will go back to the originator for resubmission. Once the process is completed or canceled the InfoPath form will be archived. The process will be built using the Opportunity SmartObjects that were created in Chapter 7

Figure 11.3. Figure 11-3

It is good practice to build the InfoPath form first and design the process flow with the business users before construction of the process were to begin. Visio is a great tool for process flow modeling as business users are familiar with its functionality. Forms can be created in InfoPath relatively quickly, and they do not need to be hooked into K2 blackpearl immediately. An analyst can create a form and provide a demonstration to the process owners while walking through the Visio diagrams. Much of the work done in the InfoPath form and Visio diagrams can be reused in the actual construction of the process.

Once the design of the process is completed, the InfoPath form can be integrated with K2; this is commonly referred to as K2-enabling the InfoPath form. When integrated, a copy of the form is added to the solution and used from that point forward. Then the designer can start adding InfoPath Client Events to the K2 process, which will require users to open the InfoPath form and complete actions. Figure 11-4 is a simple form that could be used for a business opportunity approval process. All of the fields are required in the decision-making process and are editable in this view.

Figure 11.4. Figure 11-4

In Figure 11-5, a second InfoPath view is created for approvals. InfoPath views provide a way for designers to create multiple views that use the same InfoPath data source. This is valuable because custom views can be created for different users based on the way in which they will work with the data. In the case of the approval view, all of the submission fields are disabled and a new field was added called Action. This field will be used by K2 blackpearl, and it will be dynamically populated with actions that users have permission rights to perform (Approve, Deny, Wait, Cancel, Redirect, etc.). It is important that this field be added to the InfoPath form prior to importing into a K2 blackpearl process because it will be used when configuring the first InfoPath Client Event.

Figure 11.5. Figure 11-5

Once the form has been created, it can now be integrated with the K2 process. No further actions need to take place with the InfoPath form prior to integrating it with K2. After creating a new K2 Workflow Project, the InfoPath Integration Wizard is used to integrate the InfoPath form with the K2 blackpearl process. To start the InfoPath Integration Wizard, drag-and-drop it from the Process Wizards group in the toolbox onto the design canvas (as shown in Figure 11-6).

Figure 11.6. Figure 11-6

The first step is to select an InfoPath form. In Figure 11-7, this is done in the Workflow Form Templates step of the wizard by clicking Add. K2 blackpearl allows for multiple InfoPath forms to be added to the process and additional InfoPath forms can always be added later, but right now, there is only one form to be added.

Figure 11.7. Figure 11-7

In Figure 11-8, clicking Add opens the Add an InfoPath Form Template window. In this window, the InfoPath template file (.xsn extension) must be located. The InfoPath template file can be selected from a local, network drive, already in Visual Studio, or it can be retrieved from the SharePoint site where the InfoPath form may have already been published.

Figure 11.8. Figure 11-8

In Figure 11-9, the next step in the Integration Wizard is to identify where the InfoPath form will be published to when the K2 blackpearl process is deployed. Publishing an InfoPath form basically means deploying the InfoPath template to a common location where it can be opened by a user. Publishing can be done by using the Publishing Wizard that is available inside of InfoPath. In the past with K2.net 2003, publishing the InfoPath form was a separate and manual step. However, with K2 blackpearl, the deployment of the InfoPath form has been automated so the designer does not have to manually go through the InfoPath Deployment Wizard. There are two options available, deploy it to a network share or to a SharePoint form library. Deploying it to a SharePoint form library is the most common scenario. It is highly recommended that environment variables be used and that you avoid hardcoding a URL and form library Name, as the URLs will be different for production and development environments.

Figure 11.9. Figure 11-9

Below the Form Library field are two radio buttons that determine if the InfoPath form will be deployed directly to a form library or as a SharePoint content type. A content type is a new feature of SharePoint 2007, used to classify content that is stored inside of SharePoint. For instance, a content type for a purchase request may be created in SharePoint and can then have a template assigned to it. This template can be one of many types of documents such as Word or Excel, but in this case the content type will use an InfoPath form. K2 blackpearl will create the content type and associate the InfoPath form to it whenever the K2 process is deployed. There are a few advantages of using a content type, for instance they can be reused in many form libraries and can be leveraged in MOSS Search.

The remaining fields of this step are the Form Client field, which determines how the InfoPath form will be delivered, either through InfoPath client or through a Web browser. With the release of InfoPath 2007, InfoPath now can be accessed through a browser; however, there are some InfoPath features that are not available and can only be used with the InfoPath client. Using the Design Checker task pane within InfoPath will provide assistance in checking if the form can be deployed to the Web. Browser-enabled InfoPath forms are only available when InfoPath Form Services has been enabled in a SharePoint farm. InfoPath Form Services is packaged as part of MOSS Enterprise but can be deployed separately if MOSS is not needed.

The next step of the wizard is to select SmartObject methods (as shown in Figure 11-10. This step in the wizard allows for any SmartObject method to be executed through InfoPath via a Web service data connection that K2 will add to the InfoPath form. This is commonly used to perform create, read, update, and delete operations on data within an InfoPath form. Right now no SmartObjects will be integrated; however, this is an extremely powerful feature to quickly expose a SmartObject to a business user.

Figure 11.10. Figure 11-10

Figure 11-11 shows the next step in the wizard, which is to optionally set up the HTML task pane for InfoPath. An InfoPath task pane is nothing more than an HTML file that is made visible on the right-hand side of the screen. A task pane is useful if there is functionality or reference information that should always be displayed to the user regardless of what view they are using. The InfoPath task pane is only available for client-based InfoPath forms. If the task pane is used, a button is placed into the task pane that will allow the user to submit the form to K2. In addition, there will be a link to open the View Process Flow report (note that this link could be added to the InfoPath form itself). For this process, the HTML task pane will not be used. Click Finish to complete the integration of the InfoPath form template.

Figure 11.11. Figure 11-11

Now that the form has been integrated, the rest of the Process Integration Wizard needs to be completed. When the Add InfoPath Form Template Wizard closes, the InfoPath Integration window is still open and needs to be completed. Clicking Next goes to the Process Start Details step of the wizard (as shown in Figure 11-12). This is the step where the designer must select which InfoPath form view will be used to initiate the InfoPath process. The Form Template field will have all of the InfoPath forms that have been added to the K2 process and the View field will show all of the views for the selected form. Once a form and view have been selected, the Folio field needs be specified.

The Folio field is displayed throughout the K2 Workspace, out-of- the-box reports, administrative screens, and K2 Worklist Web part. The Folio field is used to reference a specific process instance. A default value will always be displayed in the Folio, but it will not have any unique or contextual data associated to the process instance. It is a best practice to put some process-specific data into the Folio field. Commonly, users of K2 blackpearl would like to see a unique identifier number, a start date, or the originator's name, for example, which would help them make a decision as to whether to open the process instance or not. For this process, the company and opportunity names are concatenated together and will be displayed in the Folio name. The values are selected from the XML of the InfoPath form, using the Context browser. Both of these fields are required for initiating the process.

Figure 11.12. Figure 11-12

The Advanced Settings step of the InfoPath Process Wizard, shown in Figure 11-13, displays both the Workflow server and the Workflow Web services URL prepopulated with environment variables. The Workflow server variable is a connection string to the workflow server, while the Workflow Web services URL is the address where the K2 InfoPath Web service resides. The Web service provides all of the methods that are needed to integrate an InfoPath form with K2. It is not recommended that you hardcode these values. The values of the environment variable set here will be set into the InfoPath form.

Figure 11.13. Figure 11-13

On the Finish page of the InfoPath Integration Wizard (as shown in Figure 11-14), the designer is given the choice of starting an InfoPath Client Event by selecting the "Would you like to configure a client event now?" checkbox. This is referred to as wizard chaining where the finishing of one wizard will start another. In this case an InfoPath Client Event wizard will start if this checkbox is checked. This particular business process will require a manager's approval once the InfoPath form has been submitted. Knowing that, checking the checkbox will allow the designer to immediately create the manager approval activity.

Figure 11.14. Figure 11-14

Click Finish in the InfoPath Integration wizard to start the InfoPath Client Event. The first step of the InfoPath Client Event is shown in Figure 11-15. This is where the manager approval step will be configured.

Figure 11.15. Figure 11-15

Clicking Next will move to the General Event Settings step of the InfoPath Client Event Wizard (as shown in Figure 11-16). The Name field will be changed to InfoPath Manager Approval, which is the name displayed on the process view and shown in all of the reports. The Form Template field is used to select which InfoPath form will be displayed to the user. The Client Event View field shows all of the views for the selected form and allows the designer to select which view in the InfoPath form should be displayed. In this case, the Approve Opportunity view will be selected, which is a different view than the one that was used to initiate the process.

The Task Action field allows the designer to select which field in the InfoPath form will be populated with the list of user actions. Some examples of actions are approve, reject, cancel, and so on. To select a field, click the ellipse next to the Action Field. In the Context Browser, go to the Process/Activity Data tab. From there, open the XML Fields node and drill-down into the OpportunityApproval node to select the action field. Remember, the action field was added to the InfoPath form prior to the form's being integrated with K2. It is not possible from this step to add a new field to the InfoPath form. If there is no field, the wizard can be closed and restarted once there is a field.

The action field in the InfoPath form might not be a drop-down before being imported into the K2 process. If the action field is not a drop-down, it will be converted to a drop-down by this wizard. The action drop-down will be populated by Web service, which will retrieve a list of actions from the K2 server. This list of actions will be security trimmed based on the users currently logged in. Only one field per activity can be designated as the action field. Once populated, the user will use this field to make a decision on where the process should go next. In this case, a field called Action was added to the form prior to integration with K2. If the field is not present in the form, cancel this wizard, create the field in the InfoPath form, and start over again. Note, only one field in the InfoPath's form schema can be designated as the action field, regardless of how many views there are.

Finally, the "Who is allowed to finish the worklist item?" can be used to determine if all users who have access to the K2 process can complete the event, or if only a designated set of users can complete the event. In this case, "Only the destination user" radio button is selected because only the manager should be allowed to configure this operation.

Figure 11.16. Figure 11-16

When you click Next, the prompt shown in Figure 11-17 may appear if the task action field that was selected is not a drop-down. In this case, since the action field is not a drop-down, the wizard will convert the InfoPath field to a drop-down. It is highly recommended that this be done.

Figure 11.17. Figure 11-17

Figure 11-18 shows the Event Notification Settings step of the wizard, which can be used to send a notification e-mail to all the destination users that a task has been assigned to them for completion. The e-mail message is generic. Using this option does not allow for customization of the message through Visual Studio. The customization of the message can only be done after the process has been deployed in the K2 Workspace and the customizations are specific to the server where the change is made. This is a good, quick way to configure notifications to a process. If more customization is required, a simple Mail Event can be added prior to the InfoPath Client Event.

Figure 11.18. Figure 11-18

The next step of the wizard is the Configure Actions step, where a designer can add actions a user can perform. These actions will be populated into the action field drop-down in the InfoPath form that was created in a previous step. To add an action, click the Add button and the Add Action window will appear. In the Add Action window (as shown in Figure 11-19), there are Name and Description (optional) fields. The Name of the action can be action, deny, delegate, cancel, send to contracts, notify my manager, and the like. It should contain whatever decisions a user may need to make.

There is a checkbox called "Make the action available without opening the work item." Leaving this checkbox checked will ensure that this action is visible in both the SharePoint Worklist Web part and the K2 Workspace Worklist. The user will have the ability to action a worklist item without having to open the InfoPath form. As well, the user will have the ability to do batch actions if there are multiple tasks that have been assigned to them. The Worklist Web part allows users to select multiple items and then complete one-to-many of them without having to click or open each and every task. Unchecking this checkbox will require the user to open the InfoPath form to complete their task, which at times is a good thing. For instance, there may be important legal data in the InfoPath form the decision-maker must read before taking an action.

The last two radio buttons allow the designer to indicate if the action will finish the worklist item or keep it open until the user selects a different action that will complete the InfoPath Client Event. For instance, there may be actions like "approve" and "deny," which should complete the activity. However, an action like "wait" will not make the action complete.

Figure 11.19. Figure 11-19

For this process, both Approve and Deny actions will be added as shown in Figure 11-20. Once all of the actions have been added, the "Generate corresponding outcome(s) for listed action(s)" checkbox should be checked.

Figure 11.20. Figure 11-20

The next step in the wizard is to Configure Outcomes that are used in the Succeeding Rules for the activity. Succeeding Rules are used by the activity to determine whether the activity is complete or another action needs to be taken. When outcomes are added to an activity, a field called Outcome will be added as an activity-level field. The Outcome field will be populated with the action field value after the user submits the InfoPath form. Checking the "Generate corresponding line(s) for listed outcome(s)" checkbox will generate a line for each outcome. Each line that is generated will have a rule using the Outcome field that will determine which line the process should continue on. Figure 11-21 shows the default outcomes that are generated from the actions.

Figure 11.21. Figure 11-21

Although it is the default, there is no requirement for a one-to-one mapping between actions and outcomes, which provides a lot of flexibility to support more complex logic. For instance, there may be an Approve or Deny action. However, based on the dollar amount that was approved, the process will need to go down a different path. A simple business rule may be if the dollar amount that was approved is over $100,000, the request form will require a director's approval. Figure 11-22 shows that the new outcome has been added which will check to see if the ActionResult is Approved and if the estimated amount is over $100,000. The dollar amount is located in the XML of the InfoPath form.

Figure 11.22. Figure 11-22

Figure 11-23 shows the completed outcome modifications that were made. The original Approved outcome that was generated by the wizard was modified to check if the estimated amount is under $100,000.

Figure 11.23. Figure 11-23

Figure 11-24 shows the final step of the wizard is to add Destination Users who are the users assigned worklist items. For this activity, the Destination User will be the manager who was selected in the InfoPath form. To set the Destination Rule with data in the InfoPath from, select the Add button and then click the ellipse to open the context browser. From there, click the Process/Activity Data tab and drill-down into the XML Fields to get the Manager node.

Figure 11.24. Figure 11-24

Now the wizard is complete, both the InfoPath Integration Wizard and the first InfoPath Client Event will be complete. More InfoPath Client Events can be added to the process by dragging and dropping them on from the toolbox. A new icon will be displayed in the top-right corner of the design canvas. Clicking this will open the InfoPath Integration Wizard and will allow the designer to rerun any of the configurations that were made earlier. Figure 11-25 shows the completed InfoPath process.

Figure 11.25. Figure 11-25

InfoPath Form Integration Details

It is important to understand how the InfoPath form was integrated with the K2 process. First the InfoPath form has now been added to the Visual Studio solution. All changes to the InfoPath form moving forward should be done to the file that is part of the K2 Designer project and not to the file from where the template was originally located. The file in the K2 Designer project is the form that will be synchronized with the K2 process and will be the form that will be published by K2 when the process is deployed. Figure 11-26 shows the updated Solution Explorer in Visual Studio with the InfoPath Form that was integrated into the process.

Figure 11.26. Figure 11-26

To make a modification to the InfoPath form, select the InfoPath icon at the top-right corner of the design canvas. The InfoPath Integration menu will appear. Click the Design button to open InfoPath in design mode (as shown in Figure 11-27). The designer can make any needed changes to the InfoPath form. When the InfoPath designer is closed, the form will be resynchronized with the K2 process automatically.

Figure 11.27. Figure 11-27

It is possible to make changes to the InfoPath form outside of Visual Studio. Go directly to the .xsn file in the InfoPath Form Templates folder in the Visual Studio project files, open the InfoPath form in design mode, and make the necessary changes. It is extremely important to not go to the original location of where the InfoPath form was selected when it was integrated with the K2 process. Remember when the InfoPath form was integrated with the K2 process, a copy of the .xsn file was added to the K2 project itself. Once the changes to the InfoPath form have been completed, the changes to the form must be resynchronized with the K2 process. This is achieved by rerunning the InfoPath Integration Wizard, selecting the form that was modified, and then clicking the Refresh button. It is recommended that this be avoided when possible because the K2 InfoPath Integration Wizard provides the ability to launch the InfoPath form in design mode, and it will ensure that it is always kept in sync with the K2 process. The only time this may be needed is when information workers do not have a Visual Studio, and they require the ability to make changes to the InfoPath form directly.

InfoPath Form Versioning

InfoPath forms that are integrated with a K2 process are version controlled with that process. Whenever a form is added to a K2 process using the InfoPath Integration Wizard, the name of the InfoPath form template (.xsn file) will be made unique. Then that uniquely named file is mapped within the process definition. Within InfoPath, every time the form template is saved, an internal version number within the InfoPath definition is incremented. This version number can be found in the manifest.xsf file of the InfoPath form.

The manifest.xsf file is located with the InfoPath form template file. The InfoPath form template file is nothing more than a CAB file with an array of .xml, .xsd, and .xsl files. The manifest.xsf file contains the definition file for the InfoPath form itself. To access this file, open the InfoPath form in design mode and select Save As Source Files under the File menu.

When updating an InfoPath form through a K2 Designer, the updated form will be resynchronized in several places within the K2 process definition. If the InfoPath form is not resynchronized with the K2 process, definition issues can arise in production because the XML submitted from the InfoPath form will not conform to the XSD definition that is expected by the K2 process. To always avoid this issue, make sure that the InfoPath form is edited from within the K2 project by rerunning the InfoPath Integration Wizard and pressing the Design button.

Changes to InfoPath

There will also be many changes that are made to the InfoPath form as a result of being added to the K2 process. The first and most notable change to the InfoPath form is that a new group is added to the Main Data Source, called _K2, which has several fields reserved for K2. Figure 11-28 shows the main data source of the OpportunityApproval.xsn form template that was integrated with K2. It is not recommended that any field within this group be manually modified for any reason because these fields and the data within them are owned by K2. If fields are removed or data modified, errors can occur. These fields and the data within them will be managed by K2.

Figure 11.28. Figure 11-28

A second important change to the InfoPath form is that three new data connections have been added (as shown in Figure 11-29). These data connections are configured to work with K2's InfoPath Web service (located at <server>/RuntimeServices/InfoPathService.asmx). The first is called "Can I Submit Workflow Service," which is used to check if the current user has permission to connect to the workflow server. The second is called "Get Workflow Task Actions Service" and will retrieve all of the actions that the current user has permission to. This data connection is used to fill in the action drop-down that was specified in the InfoPath Client Event Wizard. The third is called "Submit Workflow Service" and is used to submit the XML from the InfoPath form to K2 server. The submit Web service method uses the data in the _K2 node to restart the process again with the updated XML in the form.

K2's InfoPath Web service also provides some other helpful methods that can be used in the InfoPath form. There is the "Can I Connect" method that determines if the user has permission to connect to the Web service. There is the Execute SmartObject method, which allows for any method of a SmartObject to be executed in an InfoPath form. Finally there is the Who Am I method, which will return the Active Directory name of the user connecting to the Web service.

Figure 11.29. Figure 11-29

Rules were also added to the InfoPath form by K2 that will be executed when the InfoPath form is opened. Figure 11-30 shows the Form Options window selected from the Tools main menu. The Open Behavior of the form can be configured by clicking on the Rules button in the Open and Save section. The InfoPath Integration Wizard will add rules for each view that is in the InfoPath form. These rules are used by the InfoPath Client Event to switch to the correct view the user should see. The InfoPath Client Event will set the DocumentView node (located within the _K2 group) with the view that should be displayed. When the form opens, it will switch the appropriate view. Another rule that will be added is Get Workflow Task Actions, which will call the Web method to get all actions for the current user and populate the Action drop-down with them.

Figure 11.30. Figure 11-30

The last changes made by the InfoPath Integration Wizard can be found under Submit Options. Figure 11-31 shows that the "Perform custom action using Rules" radio button is selected; clicking the "Rules" button will shows the rules that have been configured. The first rule sets the action field value to the _K2 group. The second rule submits the InfoPath form to K2's InfoPath Web service. This is a good place to add other operations that should be completed before the InfoPath form is sent to K2. The last set of changes to the Submit Options is in the advanced section. The "Show success and failure messages" has been selected and the form is configured to close after submission.

Figure 11.31. Figure 11-31

Adding rules after the Submit Workflow rule can lead to undesirable results. For instance if there is data that is saved to a SmartObject using a rule after the Submit Workflow rule, there will be no guarantee that the updated data will be available for Succeeding and Line Rules in the process. It is recommended that you complete all rules before the Submit Rule is executed.

Another important thing to know is users will have to be instructed to close their InfoPath form after submission because the K2 process will try to delete the XML file after a user clicks the Submit button. If the InfoPath form remains open, a potential locking error can occur between SharePoint and K2. This is particularly important when using client-based InfoPath forms. This error is not unique to K2, as this is introduced by SharePoint trying to manage two users accessing the same document at the same time. The same error will occur if two users were working with the same document while one has it open and the other tries to delete it.

Any modifications to changes that K2 made to the InfoPath form can be lost whenever the wizards within K2 are rerun. For instance, if the designer chooses to modify one of the submit or open rules, those changes will be lost when an InfoPath Integration wizard is rerun. However, the designer can add new Submit or Open Rules and those will always remain unaffected.

Changes to the K2 Process

Changes are not limited to the InfoPath form; there are changes that will be made to the K2 process as a result of running the InfoPath Integration Wizard. The most notable change is that a new process-level XML field has been added to the process. This XML field is created from the XSD schema from the InfoPath form and will contain all of the data from the InfoPath form after each InfoPath Client Event completes. This data can be used anywhere inside of the K2 process, for instance, in places such as Line, Destination, and Succeeding Rules. Figure 11-32 shows all of the XML fields that have been added to the K2 process as a result of the InfoPath form's being integrated.

Figure 11.32. Figure 11-32

It is important to know that the schema of the InfoPath form must be kept in sync with the XSD of the XML fields within K2. Errors could occur at run time if the designer were to add or a remove a field in the InfoPath form outside of Visual Studio and not resynchronize it using the Refresh button in the InfoPath Integration Wizard. A very common error could result from a field's being renamed or possibly removed, which would cause an XPath error. K2 will execute validation measures to ensure that these errors do not occur, but those validations will be based on the XSD schema in the XML field, not the XSD in the InfoPath form. This is why it is very important to keep the InfoPath form and the K2 process in sync with each other.

However, changes associated to the presentation of the form or conditional formatting are safe to make without having to resync it with the K2 process. In these cases, the InfoPath form can be changed and simply republished without having to redeploy the entire K2 process. As a best practice, if there are any changes that need to be made to the InfoPath form other than presentation, the InfoPath form should be resynchronized with the K2 process. Presentation changes do not require a redeployment of the K2 process. However, if the form must be resynchronized because the schema change, the K2 process must be deployed before the InfoPath form can be used.

One thing that may come up when working with an InfoPath process is that the data in the InfoPath form may need to be modified by the K2 process. For instance, in this process, there is one action field on the InfoPath form, and when the manager approves the opportunity, it is then routed to the director for approval. When the director opens the form, the action field will already be marked as approved. It would be better for the action field to be cleared out, forcing the director to make a decision to approve or deny. Clearing out the action XML field can be done by adding a server code event prior to the InfoPath Client Event, as shown in Figure 11-33. To open up the code event-handler, right-click the event, select View Code, and then Event Item. This is where code can be written to access the XML field and modify the XML string.

Figure 11.33. Figure 11-33

The following code shows that the XmlFields of the ProcessInstance is referenced. The InfoPath XML is subsequently set into a string variable, which is then loaded into an XmlDocument. Once the XmlDocument has been loaded, an XmlNamespaceManager is created, which allows for XPath queries to be executed on the XmlDocument. In this case, //my:Action, an XPath query, will get the value in the action field and set the action field to empty string. Once the XmlDocument has been modified, the XML string needs to be set back into the ProcessInstance.XmlFields. If this is not done, the changes that were made will not be committed and shown in the InfoPath form. This is a simple demonstration, but once the developer has access to the XML string, there is a potential to execute more sophisticated operations.

//Get the XML Field string
string xml = K2.ProcessInstance.XmlFields["OpportunityApproval"].Value.ToString();

//Load up the XML
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

//Create a name space manager for InfoPath
XmlNamespaceManager nsMgr = new XmlNamespaceManager(doc.NameTable);
nsMgr.AddNamespace("my", doc.DocumentElement.GetNamespaceOfPrefix("my"));

//Now set some values
doc.SelectSingleNode("//my:Action ", nsMgr).InnerText = "";

//Now set the value back into the XML Field
K2.ProcessInstance.XmlFields["OpportunityApproval"].Value = doc.OuterXml;

Understanding the mechanics of how the XML documents are created and managed by K2 is very important. To view how this is done, right-click any InfoPath Client Event and select view code, and the following Windows Workflow Foundation (WF) process will be displayed (as shown in Figure 11-34). This is the underlying code that is used for the InfoPath process. There are two major steps to the InfoPath client, which are: Create the XML document in SharePoint, and create worklist items for the destination user. To further understand how this works, right-click the WF process and select View Code.

Figure 11.34. Figure 11-34

Before diving deep into how the InfoPath XML is integrated with a K2 process, it is important to understand how the process and activity instances are related. First for every process instance there will be many activity instances. Then for every activity instance, there will be activity instance destinations. The creation of activity instance destinations is driven by the number of slots that will be created, which is based upon the Destination Rules.

What is relevant to this discussion is that for each process instance there is an XML field. As well, each activity with an InfoPath Client Event will also have an XML activity field. The WF process for the InfoPath Client Event, shown earlier, has logic that will take the XML from the process field and copy it in the activity field. Each activity instance destination also has an XML field, which will again be populated from the process XML field. This is done so that each destination user has a copy of the InfoPath document. When the activity completes, the XML from the activity instance destinations will be set back into the process instance XML, and the InfoPath form XML will subsequently be deleted from the form library in SharePoint. The code that deletes the InfoPath form resides in the Succeeding Rule of the activity. This can lead designers into a few traps if the process is not fully understood.

Now that the basic process has been built, a requirement can be captured to provide some delegation. This can be done simply by going back to the InfoPath Client Event and rerunning the wizard to add a new action. When the wizard appears, click Next to go to the Configure Actions step in the wizard. Add a new action called Delegate just as before (see Figure 11-35), but this time, the "Generate corresponding outcome(s) for list action (s)" checkbox will not be checked by default. Select it and continue to the Configure Outcomes step of the wizard. A new outcome called Delegate will be created. Select the "Generate corresponding line(s) for listed outcome(s)" checkbox. Finish the InfoPath Client Event Wizard, and the new Delegate line will be generated.

Figure 11.35. Figure 11-35

After adding the new action, take the new generated line and drag it to point back to the activity it started from. Figure 11-36 shows how the process was modified.

Figure 11.36. Figure 11-36

Even though delegation functionality is provided in the K2 Workspace, this example shows how flexible and adaptable K2 processes are. Actions and outcomes, new to K2 blackpearl platform, are the power behind this. In K2.net 2003 making this sort of change would have required more work because the line would have had to be manually added, rules would have had to be set, and the InfoPath form would have had to be modified to put the Delegate value into a drop-down.

A common requirement for an InfoPath process is that the InfoPath form should be archived when the process is completed. Using SharePoint, the XML can be saved to a form library that is designated as the archive. To save the XML to a form library, the SharePoint Documents Event can be added to the end of the process. Figure 11-37 shows the SharePoint Documents Event being added to the process. The Upload Documents From K2 Field option is selected in the wizard.

Figure 11.37. Figure 11-37

Figure 11-38 shows the Document Upload Source step of the wizard. This is where the designer selects the InfoPath XML.

Figure 11.38. Figure 11-38

Figure 11-39 illustrates the final step of the wizard. The Upload Document Destination is where both the SharePoint site and document library are specified. One key thing when configuring this final step is to set the File Name correctly. The file name should contain some sort of unique identifier so when the file is saved to the destination location, it will not overwrite an old one. Finally, add the extension .xml to the file name. Once this is done, the InfoPath XML will be saved and be accessible through SharePoint.

Figure 11.39. Figure 11-39

The archive SharePoint form library must be set up before the process is run. This archive form library will not be created by the K2 deployment package. To set it up, open InfoPath in design mode and publish the InfoPath Form template to the location specified in the wizard. Every time the InfoPath form changes, remember to update the archive form library with the latest version of the InfoPath form template.

If there is a requirement to allow a user to resubmit an archived InfoPath form, this can be achieved by modifying the data in the InfoPath form. To support this requirement, add a server-side code event before the SharePoint Document event that archives the InfoPath XML. In the Code Server Event, add the following code to it. This code will remove the serial number from the _K2 node in the InfoPath form. The serial number is an identifier that K2 generates to uniquely identify process, activity, or event instances. This Serial Number node is set into the form XML in every InfoPath Client Event and is used by the K2 InfoPath Web service. If the serial number is blank, the K2 InfoPath Web service will treat the form as a brand-new InfoPath form submission.

//Get the XML Field
stringstring xml = K2.ProcessInstance.XmlFields["OpportunityApproval"].Value.ToString();

//Load up the XML
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

//Create a name space manager for InfoPath
XmlNamespaceManager nsMgr = new XmlNamespaceManager(doc.NameTable);
nsMgr.AddNamespace("my", doc.DocumentElement.GetNamespaceOfPrefix("my"));

//Clear out serial number
doc.SelectSingleNode("//my:SN", nsMgr).InnerText = "";

//Now set the value back into the XML Field
K2.ProcessInstance.XmlFields["OpportunityApproval"].Value = doc.OuterXml;

One of the most exciting things with the introduction of SmartObjects to the K2 blackpearl platform is their integration with InfoPath. In the past, getting data in and out of InfoPath forms required several custom Web services to be written. Now, through SmartObjects, data can be brought in and out of an InfoPath form extremely easily by simply calling any SmartObject method. There two ways SmartObject methods can be added to an InfoPath form. The first is to use the InfoPath Integration Wizard, and the second is to modify the InfoPath form directly using the SmartObject Wizard. Figure 11-40 shows how to add a SmartObject method using the InfoPath Integration Wizard. Once the InfoPath Integration Wizard has been opened go to the Workflow Form Templates window, select the Template Form, and click the Edit button.

Figure 11.40. Figure 11-40

This will open the Edit the InfoPath Form Template window. The InfoPath Form Deployment Location step will be shown first. Click Next to get to the SmartObject Integration step. This is where SmartObject methods can be added to the InfoPath form. To add a SmartObject method, click the Add button and the Add a SmartObject Method window will appear (as shown in Figure 11-41). Next to the method field, click the ellipse to open the Context Browser. Find the SmartObject method, and click the Add method. In this case, the Opportunity.Create method is added. If the Add to Main DataSource checkbox is checked, the fields from the method will be added to the main data source of the form.

Figure 11.41. Figure 11-41

In Figure 11-42, the Opportunity.Create, Opportunity.GetList, and Company.GetList methods have been added. With these methods, a quick InfoPath form can be constructed that will get all of the opportunities for a company and provide the ability to create a new opportunity for a company.

Figure 11.42. Figure 11-42

The second way SmartObject methods can be added to an InfoPath form is by going to the InfoPath form template (.xsn file), right-clicking it, and selecting the Integrate with SmartObjects option (as shown in Figure 11-43). This will only be available on development machines where the K2 blackpearl design tools have been installed. Selecting this will open the same SmartObject Integration window that was previously shown, but now, SmartObject methods can be added to any InfoPath form regardless of whether or not it is integrated with a K2 process.

Figure 11.43. Figure 11-43

The SmartObject methods are called by an InfoPath form using a Web service. The following are the data connections that were added to the InfoPath form by K2. Each data connection is named for the SmartObject and method it is associated to, and all of the data connections call the K2 InfoPath Web service ExecuteSmartObjectMethod. Figure 11-44 shows three new data connections that have been added to the InfoPath form.

Figure 11.44. Figure 11-44

Since all of the data connections call the same generic Web service, it is good to know how the correct SmartObject method is called. This can be done by looking at the queryFields for the secondary data connection (as shown in Figure 11-45). There is a Locals node with the queryFields. This is where all the connection information to the SmartObject server is located. These values will be set every time the K2 process is deployed with the correct locations in the Environment Library.

Figure 11.45. Figure 11-45

Now that the SmartObject methods have been hooked into the InfoPath form using a Web service, the fact that SmartObjects are being used becomes transparent for an InfoPath developer. Figure 11-46 shows a completed InfoPath form that uses the Company.GetList method to populate the company drop-down. Once a company is selected, a list of its opportunities is displayed. Finally, there is a section that allows for new opportunities to be added for the selected company. This entire form was constructed in minutes dragging the secondary data source fields on the screen and then adding buttons to call the Web services.

Figure 11.46. Figure 11-46

One important thing to know is that InfoPath forms and SmartObjects should not be used to replace forms that are used to manage large quantities of data. InfoPath forms are great for "form" development, not data management. If there is a business process where data fields will be used to make business decisions, then InfoPath is a fantastic tool to use. However, if the InfoPath form is being used simply as way to access and update data outside of a business process, then it is not the right tool to use. Along that line of thought, there are some limitations when using SmartObjects in InfoPath. For instance, using an InfoPath repeating table to perform batch updates (as in an ASP.NET datagrid) is not supported out-of-the-box and would require some custom code to be added to the InfoPath form. Again, a good general rule is if complex custom code needs to be added to the InfoPath form, it is probably best to transition to ASP.NET.

That aside, the great thing is now InfoPath developers are empowered to integrate with data from multiple locations very rapidly. SmartObjects can be used to bring data from a number of different systems together such as data from SharePoint, ERP systems, mainframes, K2 historical data, and all of the data is shared using an XML document. The InfoPath form does not have to focus on where the data originates from or where it needs to go to. When using SmartObjects, developers no longer have to create custom Web services for a specific InfoPath form. The same SmartObject methods used by the K2 process are now exposed to all applications participating in the workflow, adding continuity to the entire solution.

There are several design considerations that should be thought about when developing an InfoPath form with K2; for instance, things such as database sizing considerations associated to the data captured in an InfoPath form, managing the data source of the InfoPath form, how to use required fields and InfoPath Views, and whether to use browser-enabled InfoPath forms.

Chapter 10 discussed all of the details associated with deploying a K2 process and SmartObjects; however, there are several things that must be accounted for when deploying a K2 process that is integrated with InfoPath. Many of the steps are associated to the deployment of the InfoPath form itself.

Deployment of Data Connections

Deploying a process with an InfoPath form has become much easier with K2 blackpearl. The InfoPath form is now published when the K2 process is deployed. The InfoPath form will be deployed using the same Environment Library variables as the K2 process. All of the data connections in the InfoPath form associated with the K2 InfoPath Web service will be updated during deployment. This is a major improvement from K2.net 2003 because designers are no longer required to make manual changes to the data connections in the InfoPath form when deploying from one environment to another. However, data connections that are not related to K2 will not be updated manually. For example, there could be an InfoPath form that has a direct connection to a SharePoint list. When the form is first developed, it will have a URL pointing to the development SharePoint site. When the form is deployed to production, it will still have the URL for the list that is on the development SharePoint site. The best way to resolve this issue is to publish these data connections to a data connection library on a SharePoint site.

When an InfoPath form is browser-enabled, a data connection library will be created by K2 on the SharePoint site. All of the K2 InfoPath Web service data connections will be stored in the data connection library. Again, this will only be done for data connections that are managed by K2, and all non-K2 ones will have to be manually converted using the process previously described. It is advantageous from deployment perspective to try to convert as many of your data connections to use SmartObjects. Figure 11-47 shows the data connection library created as part of the deployment of the K2 process InfoPath form.

Figure 11.47. Figure 11-47

In conclusion, this section demonstrates how easy it is for designers to take an InfoPath form and hook it into a K2 process and automate leveraging the entire K2 blackpearl platform. All the designer needs to do is initially create a form, use InfoPath Integration Wizard to add the form, use the InfoPath Client Event to create steps in the process, and then use actions to define what the destination user can do. K2 provides the ability to create data-driven InfoPath forms using SmartObjects, and K2 has streamlined the deployment of the process along with the InfoPath form. Now processes using K2 blackpearl and InfoPath can be authored and deployed in an extremely rapid fashion.

To initiate the workflow, a Web page will include program code to connect to the K2 server, set the starting parameter values, and initiate the process.

The next step is to include the code to create a new process instance and submit the workflow. The user will simply enter some values and click Submit.

Double-click the button to create an event-handler code segment:

protected void btnSubmit_Click(object sender, EventArgs e)
{
}

Add a reference to the K2 assembly, in order to use the namespaces and classes required.

The code to be added to the btnSubmit_Click method will do the following:

The following shows each step:

// Declare new K2 Connection & ProcessInstance objects
Connection conn = new Connection();

//Connect to Workflow Server
conn.Open("MyServer");

The connection Open method allows for a connection using either a server name or a connection string.

If the connection is opened using a server name, the security context used to connect to the K2 server will be the permissions of the current user. If this code were to be implemented within a Web service, there would be a user account assigned to the AppPool (IIS configuration). Or, the code could be wrapped within some Windows Impersonate code to change user context and kick-off the workflow.

Alternatively, and arguably easier, the connection parameters for the K2 server (such as server, port number, username, and password) can be specified using a connection string. This operates much the same as a SQL Server connection string.

This would usually be stored within a .config file but has been hardcoded to illustrate the example.

There are many attributes that can be specified; not all are required:

// Declare new K2 Connection & ProcessInstance objects
Connection conn = new Connection();

//create connection string
string connectionString = "Authenticate=true, Host=server,
Integrated=true, IsPrimaryLogin=true, Port=5252, UserID=Administrator,
WindowsDomain=domain, Password=password, SecurityLabelName=K2";

// Connect to Workflow Server
conn.Open(connectionString);

The key settings are the Host, UserID, Password, and WindowsDomain, as well as Port, depending on which K2 server is being connected to.

Now that a connection has been created, the next step is to create a process instance using the connection to the K2 server. This simply requires the name of the process folio and name of the process itself:

//Create process instance
string name = @"Information Request WorkflowInformation Request";
ProcessInstance pi = conn.CreateProcessInstance(name);

Again, the process folio and name would most likely be stored within a web.config file.

Note there is a further overload method for specifying the version of the process, allowing for an integer number corresponding to the version number:

string name = @"Information Request WorkflowInformation Request";
ProcessInstance pi = conn.CreateProcessInstance(name, [int]);

Now that a ProcessInstance has been determined, values can be assigned to the process variables using values entered within the fields on the form. This will use the DataFields collection within the process instance:

// Map the data to the K2 process data fields
pi.DataFields["Request ID"].Value = txtRequestID.Text.Trim();
pi.DataFields["Customer Name"].Value = txtCustomerName.Text.Trim();
pi.DataFields["Customer Email"].Value = txtCustomerEmail.Text.Trim();

Last, set the Folio value to something relevant or easily identifiable. This may be an attribute identifying the item in another system or database identity row, for example. Or, simply use the current date and time. In this example, this will be another field from the screen.

Then start the workflow using the StartProcessInstance method:

// Set the folio
pi.Folio = txtRequestID.Text.Trim();

// Start K2 process instance
conn.StartProcessInstance(pi);

There is an overload method for StartProcessInstance with an additional parameter to allow for a workflow process to be initiated asynchronously. This can be useful for a system workflow, and if you do not need to wait for the process to be started:

conn.StartProcessInstance(pi, [true|false]);

This method actually doesn't return a value, but the ID of the process that was initiated will be updated within the process instance object and can thus be shown in a screen label (as shown in Figure 11-49) :

// display message to user
lblStatus.Text = "Your new process is number : " + pi.ID;

The last thing needed is to close the connection to the K2 server, which will release any resources:

// Close Connection
conn.Close();

Figure 11.49. Figure 11-49

Here's the same code pieced together:

protected void btnSubmit_Click(object sender, EventArgs e)
{
    // Declare new K2 Connection & ProcessInstance objects
    Connection conn = new Connection();

    //Connect to Workflow Server
    conn.Open("MyServer");

    //Create process instance
    string name = @"Information Request WorkflowInformation Request";
    ProcessInstance pi = conn.CreateProcessInstance(name);

    // Map the data to the K2 process data fields
    pi.DataFields["Request ID"].Value = txtRequestID.Text.Trim();
    pi.DataFields["Customer Name"].Value = txtCustomerName.Text.Trim();
    pi.DataFields["Customer Email"].Value = txtCustomerEmail.Text.Trim();

    // Set the folio
    pi.Folio = txtRequestID.Text.Trim();

    // Start K2 process instance
     conn.StartProcessInstance(pi);

    // display message to user
    lblStatus.Text = "Your new process is number : " + pi.ID;

    // Close Connection
    conn.Close();
}

This is relatively easy to extend and customize, allowing for K2 workflow processes to be initiated using a class or Web service (for example).

Here are some ideas of how to extend the previous concepts:

As seen in Chapter 9 (refer to Figure 9-18), the forms generation capabilities within K2 allow forms to be created quickly and easily, without the need for any code or InfoPath. An example of this can be seen in Figure 11-50. Admittedly, the forms need a little polish, but they get the job done, and they can be ideal for a quick prototype or testing scenario.

Figure 11.50. Figure 11-50

There are a few things you can do to customize the form shown:

Within the Workspace Web site created for K2, the Web application contains all the pages and files needed for the K2 Workspace. There is an additional folder added that contains the Forms Generation pages (also known as Client Event Pages). These will have been code generated using the K2 Designer within Visual Studio, and the URL is captured within the K2 workflow.

The IIS Web site is configured to use the following folder for these pages:

C:Program FilesK2 blackpearlWorkSpaceClientEventPages

The Web site can be opened within Visual Studio, as with any other Web application. When the project is opened, the ASPX page, the class files, and the CSS styles to be applied can be viewed (as shown in Figure 11-51). There can be many customizations, to the layout, and look and feel, and any additional HTML or JavaScript can also be included.

Figure 11.51. Figure 11-51

Unfortunately, this is actually a compiled version of the Web site, so the code can't actually be viewed or edited.

Furthermore, the big downside is that the customizations will be overwritten when the Forms Generation Client Event happens on subsequent deployments. It follows that there must be some way to edit the template or, better yet, to create a new one.

Within the K2 Forms Generation Client Event, the Form Layout initially contains only one item in the combo: Blank Page, as shown in Figure 11-52. New entries can be added to that list of layouts, with different design, formatting and styles, and code behind.

Figure 11.52. Figure 11-52

The template Web page (ASPX) and code used by the Forms Generation Client Wizard can be found in the following folder:

C:Program FilesK2 blackpearlBinLayoutsclienteventCSharp1033

Within the 1033 folder, there is a folder entitled Blank Page. To create a new template, simply copy the folder, rename it (for example MyDepartment), and then update the files within. The name of the folder will then appear in the drop-down list of Form Layouts within the K2 Designer.

The styles for the page are contained in the default.css file, allowing for customization of fonts, colors, and so on.

The class.aspx.cs and layout.aspx files contain a number of symbols, which are replaced when the K2 Designer performs the forms generation (see Figure 11-53).

Tags like $SafeFieldName$, and $SafeControlName$ are replaced when the Forms Generation activity processes the Client Event Wizard, and the resulting page is copied to the ClientEventPages folder (as shown above).

Figure 11.53. Figure 11-53

Feel free to make some changes to the page layout, with your own text, layout, and images, as well as any JavaScript or HTML needed.

Within the K2 Designer, the Client Event Wizard allows the developer to specify which ASP.NET form to display for the particular user task.

The Workflow Designer will enter the URL of the corresponding Web site/Web page. The Client Event Wizard automatically appends a querystring value, which acts as an input parameter to a page. This value can be seen in the URL of the page (see Figure 11-54).

This identifier is named SN (serial number) and will uniquely identify the worklist item within the K2 server. The K2 API includes automatic security-trimming, meaning that only the allowed user can view the details for the particular task.

The form will be displayed when the user clicks to view the task from within a Workspace or worklist page, or by clicking on a URL provided in an e-mail notification. Program code included within the form will retrieve the worklist item details from the K2 server, using the SN value from the querystring.

Thus, any DataFields, Actions, and other process data can be displayed to the user and the action to be applied will be executed on the server.

Figure 11.54. Figure 11-54

As seen in the previous example, there are a few steps required to interact with the workflow:

Add another Web page, and rename it ConfirmReceipt.aspx.

This Web page will have three labels (not textboxes this time), a drop-down list, and a Submit button. There is also a comments field in which the user can enter any additional information.

Add some ASP.NET controls, including labels, so that the form resembles Figure 11-55.

Figure 11.55. Figure 11-55

Add the code to connect to the K2 server and retrieve details for the workflow instance. This will include the data fields and associated actions.

Switch to the code view to add some code to the Page_Load event-handler.

protected void Page_Load(object sender, EventArgs e)
{
}

First, a reference to the K2 namespace is needed. Scroll to the top of the class library and add the following using statement:

using SourceCode.Workflow.Client;

Begin the code for the Page_Load event with a connection to the K2 server:

// Declare new K2 Connection object
Connection conn = new Connection();

//Connect to Workflow Server
conn.Open("MyServer");

Open the specific K2 Worklist item using the SN value from the querystring of the page:

//get the serial number
string sn = Request.QueryString["SN"].ToString();

// Get the WorklistItem object
WorklistItem wi = conn.OpenWorklistItem(sn);

// get the process instance object
ProcessInstance pi = wi.ProcessInstance;

The WorkListItem object contains a number of properties and collections that allow for the retrieval of data in the process instance, user assignments, and the workflow actions.

The EventInstance and ProcessInstance objects allow you to determine the process folder, name, version, priority, and expected durations, as well as any DataFields, XMLFields, and Actions defined.

For now, some DataField values are retrieved from the ProcessInstance and displayed in the label fields:

// Map the data to the K2 process data fields
lblRequestIDValue.Text = pi.DataFields["Request ID"].Value.ToString();
lblCustomerNameValue.Text = pi.DataFields["Customer Name"].Value.ToString();
lblCustomerEmailValue.Text = pi.DataFields["Customer Email"].Value.ToString();

Next, the actions are displayed for the workflow step (from the WorkListItem), allowing the user to make a selection. The actions will be loaded into a drop-down list, using simple data binding. The Name field will be displayed, which will also be the key value used when executing the chosen action:

// set datasource for drop-down
ddlActions.DataSource = wi.Actions;
ddlActions.DataTextField = "Name";
ddlActions.DataBind();

As always, the last step is to close the connection to the K2 server.

// Close Connection
conn.Close();

Here's the same code pieced together:

protected void Page_Load(object sender, EventArgs e)
{
    // Declare new K2 Connection object
    Connection conn = new Connection();

    //Connect to Workflow Server
    conn.Open("MyServer");

    //get the serial number
    string sn = Request.QueryString["SN"].ToString();

// Get the WorklistItem object
    WorklistItem wi = conn.OpenWorklistItem(sn);

    // get the process instance object
    ProcessInstance pi = wi.ProcessInstance;

    // Map the data to the K2 process data fields
    lblRequestIDValue.Text = pi.DataFields["Request ID"].Value.ToString();
    lblCustomerNameValue.Text = pi.DataFields["Customer Name"].Value.ToString();
    lblCustomerEmailValue.Text = pi.DataFields["Customer Email"].Value.ToString();

    // set datasource for drop-down
    ddlActions.DataSource = wi.Actions;
    ddlActions.DataTextField = "Name";
    ddlActions.DataBind();

    // Close Connection
    conn.Close();
}

When the user actions the task, the form will appear as follows. Note that the URL has a querystring with the SN value 89_14 (seen in the address bar of the browser in Figure 11-56).

Figure 11.56. Figure 11-56

To complete the task, the user will enter any necessary details, and choose the action to take, by choosing a value within the drop-down list. The user will then click the Submit button, which runs the code covered next.

The functionality required for this step is:

The event-handler code for the button is included by double-clicking the Submit button within the Page designer:

protected void btnSubmit_Click(object sender, EventArgs e)
{

}

The first step is to create a connection to the K2 server:

// Declare new K2 Connection object
Connection conn = new Connection();

//Connect to Workflow Server
conn.Open("MyServer");

Then open the specific K2 WorklistItem, using the SN value as specified within the querystring of the page.

// Get the WorklistItem object
string sn = Request.QueryString["SN"].ToString();

// get the worklist item, and process instance (for data fields)
WorklistItem wi = conn.OpenWorklistItem(sn);
ProcessInstance pi = wi.ProcessInstance;

The user will have entered some text for the Comment field, which needs to be set as the corresponding data variable within the workflow instance. The reference to ProcessInstance was created in the previous step, so the DataField can be updated using the name of the variable:

// Set the Process Data Fields
pi.DataFields["Comment"].Value = txtComment.Text;

Of course, the code needs to complete the worklist task and set the Action corresponding to the drop-down list value selected. This just uses the name to determine the action and then execute it:

// determine the action object for the chosen item
Action action = wi.Actions[ddlActions.Text];

// execute the action
action.Execute();

Alternatively, this can be coded as a single statement, without the need to create an Action object reference:

// execute the action
wi.Actions["Confirm"].Execute();

Last, a message is to be displayed to the user and the Submit button on the page is disabled. This prevents the user from resubmitting the form and generating an exception (because the WorklistItem will have been closed):

// Display message
lblMessage.Text = "The activity has been completed";

// Disable the submit button and close connection
btnSubmit.Enabled = false;

The final step, as always, is to close the connection to the K2 server.

// Close Connection
conn.Close();

Figure 11-57 shows the completed form (after entering a comment and clicking Submit).

Figure 11.57. Figure 11-57

Here's the same code pieced together:

protected void btnSubmit_Click(object sender, EventArgs e)
{

    // Declare new K2 Connection object
    Connection conn = new Connection();

    //Connect to Workflow Server
    conn.Open("MyServer");

    // Get the WorklistItem object
    string sn = Request.QueryString["SN"].ToString();

    // get the worklist item, and process instance (for data fields)
    WorklistItem wi = conn.OpenWorklistItem(sn);
    ProcessInstance pi = wi.ProcessInstance;

    // Set the Process Data Fields
    pi.DataFields["Comment"].Value = txtComment.Text;

    // execute the action
    wi.Actions[ddlActions.Text].Execute();

    // Display message
    lblMessage.Text = "The activity has been completed";

    // Disable the submit button and close connection
    btnSubmit.Enabled = false;

    // Close Connection
    conn.Close();
}

As shown in the preceding examples, there are numerous namespaces and classes within the K2 API. In addition to the program code to interact with a specific process, such as displaying DataFields and to execute an action, there is also the ability to perform server management tasks.

The following example shows a number of these concepts:

The first step is to add another Web page to the existing Web site project.

The default Web page can then be renamed K2Manage.aspx.

This Web page has a drop-down list to display a list of processes and a gridview to show details upon selection. It will also include a few buttons to load different details for the process. After adding the necessary ASP.NET controls, the form should look similar to the layout shown in Figure 11-58.

Figure 11.58. Figure 11-58

Loading a Catalog of Process Definitions

The first step is to add the code to load the details for the page. Switch over to the code view, and add some code to the Page_Load event-handler.

This code is to be run once when the page initially loads, requiring code to check the IsPostBack flag:

protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {


    }
}

The code to be included requires the addition of two DLLs:

1. Within the Solution Explorer, click Add Reference and select the Browse tab.

2. Change the folder to C:Program FilesK2 blackpearlin.

3. Add a reference to SourceCode.Workflow.Management.dll.

4. Add a reference to SourceCode.HostClientAPI.dll.

This second DLL contains namespaces and classes required by the Management DLL.

Scroll to the top and add the following using statements:

using SourceCode.Workflow.Management;
using SourceCode.HostClientAPI.BaseAPI;

The first step is to create a connection to the K2 server, but with a twist. This time, the connection uses the K2 Host Server, which is running on port 5555 (by default).

Instead of creating a Connection object, use the WorkflowManagementServer class. This requires the server name and the port number as a constructor:

//open connection to K2 Host Server
WorkflowManagementServer wms = new WorkflowManagementServer("SERVER", 5555);
wms.Open();

The first action is to return a list of all ProcessSets within the K2 catalog. This is simply the list of all process definitions that have been deployed to the K2 server:

// load list of procsets
ProcessSets ps = wms.GetProcSets();

The resulting list of processes will be loaded into the drop-down list using data binding:

// assign drop-down to use process sets collection
dropDownListProcSets.DataSource = ps;
dropDownListProcSets.DataTextField = "FullName";
dropDownListProcSets.DataValueField = "ProcSetID";
dropDownListProcSets.DataBind();

When the page is loaded, the user will see a list of the processes within the K2 server (as shown in Figure 11-59).

Figure 11.59. Figure 11-59

Here's the full code snippet:

protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {
         //open connection to K2 Host Server
        WorkflowManagementServer wms = new WorkflowManagementServer
          ("SERVER", 5555);
        wms.Open();

        // load list of procsets
        ProcessSets ps = wms.GetProcSets();

        // assign drop-down to use process sets collection
        dropDownListProcSets.DataSource = ps;
        dropDownListProcSets.DataTextField = "FullName";
        dropDownListProcSets.DataValueField = "ProcSetID";
        dropDownListProcSets.DataBind();
    }
}

Displaying Versions of Process

When the user chooses a particular process definition from the drop-down list, the versions for that process will be loaded into the grid below. All process version information will be displayed, some of which will be used as keys to retrieve other details (as shown in the following example).

The user will click a button to display the details, so the following event-handler is required:

protected void btnShowVersions_Click(object sender, EventArgs e)
{

}

As previously shown, a connection to the K2 server is included:

//open connection to the K2 Host Server
WorkflowManagementServer wms = new WorkflowManagementServer("SERVER", 5555);
wms.Open();

The drop-down value determines the specific identifier for the process, as the field procSetID is set as the DataTextValue when the drop-down list is loaded.

//determine value selected
int procSetID = Convert.ToInt32(dropDownListProcSets.SelectedValue);

Then the collection of Processes is loaded and used to bind to the gridView:

//load processes collection
Processes p = wms.GetProcessVersions(procSetID);

//load grid with process versions
gridView.DataSource = p;
gridView.DataBind();

Figure 11-60 shows what the output may look like (depending on your processes and server).

Figure 11.60. Figure 11-60

Here's the same code pieced together:

protected void btnShowVersions_Click(object sender, EventArgs e)
{
        //open connection to the K2 Host Server
        WorkflowManagementServer wms = new WorkflowManagementServer
          ("SERVER", 5555);
        wms.Open();

        //determine value selected
        int procSetID = Convert.ToInt32(dropDownListProcSets.SelectedValue);

        //load processes collection
        Processes p = wms.GetProcessVersions(procSetID);

        //load grid with process versions
        gridView.DataSource = p;
        gridView.DataBind();
}

Furthering the previous example, the user can view the list of activities within the process definition for a particular version of the process.

First, create a method for the button event-handler:

protected void btnShowActivities_Click(object sender, EventArgs e)
{

}

And, of course, open a connection to the workflow server (Host Server):

WorkflowManagementServer wms = new WorkflowManagementServer("SERVER", 5555);
wms.Open();

Next, the process definition is loaded using the value selected within the drop-down list as the key. The procSetID value was set as the DataValueField when the drop-down list was loaded:

//determine value selected
int procSetID = Convert.ToInt32(dropDownListProcSets.SelectedValue);

The procSetID value is then used to load a version of the process definition. In this example, the first version of the process is loaded using the collection value of [0]. This may or may not be the default version, but it will be the most recent version.

//load the processes for the chosen procset definition
Processes pv = wms.GetProcessVersions(procSetID);

//determine the ID value of the first (most recent) item
int procId = pv[0].ProcID;

Now that the procId value has been determined, as opposed to procSetID, the list of activities can be loaded into the grid, using data binding:

//load activities using procID
Activities activities = wms.GetProcActivities(procId);

//add the results to the grid
gridView.DataSource = activities;
gridView.DataBind();

This will display as shown in Figure 11-61.

Figure 11.61. Figure 11-61

Here's the code in full:

protected void btnShowActivities_Click(object sender, EventArgs e)
{
        WorkflowManagementServer wms = new WorkflowManagementServer("SERVER", 5555);
        wms.Open();

        //determine value selected
        int procSetID = Convert.ToInt32(dropDownListProcSets.SelectedValue);

        //load the processes for the chosen procset definition
        Processes pv = wms.GetProcessVersions(procSetID);

        //determine the ID value of the first (most recent) item
        int procId = pv[0].ProcID;

        //load activities using procID
        Activities activities = wms.GetProcActivities(procId);

        //add the results to the grid
        gridView.DataSource = activities;
        gridView.DataBind();
}

Another code example (below) uses the same reference for the WorkflowManagementServer to determine the list of Events corresponding to an Activity (refer to Figure 11-61.

In this instance, the ID column in the grid provides the key for the ActivityEvents to be loaded using the GetActivityEvents method. To illustrate this, the ID is hardcoded to use the value from the sixth row in the grid — a value of 279 (Reporting Manager Approval).

This could then be loaded to a different gridview, for example:

//retrieve events for an activity
int ID = 279;
Events events = wms.GetActivityEvents(ID);

//add the results to the grid
gridView.DataSource = events;
gridView.DataBind();

Viewing Processes Currently Running

The previous code samples show how to use the K2 API to delve into process definitions, versions, and their activities and events. The real power of the management namespace and class libraries comes when looking into what's happening on the server at the moment, such as what processes are running and what user tasks are yet to be completed.

Imagine that the marketing department has asked for a Web part to be shown on the home page for its department portal site, with a list of the current processes underway showing the activity name, user assigned, and start date.

The quickest and easiest way to achieve this is to use a SharePoint Page Viewer Web part with the URL of an ASP.NET Web page containing the code to interact with the K2 server. This also negates the need to install the SharePoint SDK or Visual Studio project templates within the development environment. There are also more hoops to jump through when testing, debugging, and deploying a Web part. An ASP.NET page is a much simpler approach and the results are very similar.

The steps to achieve this are as follows:

1. Create a connection to the server.

2. Return a list of WorklistItems for a particular process ProcSet.

3. Show grid columns for the fields: EventName, ActivityName, Destination (User)

The Web page code will make use of a querystring value for ProcSet to determine the processes and WorklistItems to be displayed. The columns to be displayed in the grid will be specified; this is different from simple data binding, which displays all columns (as in the previous examples).

Within the Visual Studio project, add another Web page and rename it RunningProcesses.aspx.

For the page layout, simply add a gridview. Right-click the gridview and choose Auto Layout to change the colors and font sizes.

The form should then look similar to that shown in Figure 11-62.

Figure 11.62. Figure 11-62

Switch to the code view for the page. Scroll to the top and add the using statement:

using SourceCode.Workflow.Management;

The Page_Load event-handler first needs a check for IsPostback:

protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {
         //code goes here

    }
}

Once again, a connection to the K2 server is required:

// open the connection
WorkflowManagementServer wms = new WorkflowManagementServer("SERVER", 5555);
wms.Open();

The querystring value for ProcSet is used to retrieve a list of processes. The GetWorklistItems method operates as a search method with parameters passed as selection criteria (using wildcard values such as %).

The parameters are:

• From date

• To date

• Destination

• Process name

• Activity name

• Event name

• Folio

More information is available from the K2 blackpearl Developer Reference, available at www.k2underground.com.

For now, some default values for from and to dates are used, and wildcards will be used for the other parameters that are not required at this stage:

// load the querystring value
string procSet = Request.QueryString["ProcSet"].ToString();

// load collection of worklist items underway
WorklistItems wi = wms.GetWorklistItems(DateTime.MinValue,
DateTime.MaxValue, "%", procSet, "%", "%", "%");

The following example will use the parameter for Destination to retrieve the WorklistItems for the current user.

Next, add columns to the gridview and specify the fields to be shown:

//ensure columns have been cleared out of the grid
gridviewWorklistItems.Columns.Clear();

//set the data source to the worklist item collection
gridviewWorklistItems.DataSource = wi;

//don't create automatically, will specify
gridviewWorklistItems.AutoGenerateColumns = false;

The gridview will have four columns as BoundFields, which will be automatically populated when the DataBind occurs. The columns to include are Event Name, Activity Name, the User, and DateStarted:

//create a field, and set the data field name, and the column heading
//and add the column
BoundField fldEventName = new BoundField();
fldEventName.DataField = "EventName";
fldEventName.HeaderText = "Event Name";
gridviewWorklistItems.Columns.Add(fldEventName);

BoundField fldActivityName = new BoundField();
fldActivityName.DataField = "ActivityName";
fldActivityName.HeaderText = "Activity Name";
gridviewWorklistItems.Columns.Add(fldActivityName);

BoundField fldDestination = new BoundField();
fldDestination.DataField = "Destination";
fldDestination.HeaderText = "User";
gridviewWorklistItems.Columns.Add(fldDestination);

BoundField fldStartDate = new BoundField();
fldStartDate.DataField = "StartDate";
fldStartDate.HeaderText = "Date Started";
gridviewWorklistItems.Columns.Add(fldStartDate);

//display data on the gridview
gridviewWorklistItems.DataBind();

Figure 11-63 shows this page within a Web browser. The address bar shows the querystring value for ProcSet is specified as LeaveRequestWFProcessLeaveRequest, corresponding to the processes to be shown on the Marketing portal site.

Figure 11.63. Figure 11-63

The URL shown is then included within the settings for the Page Viewer Web part for SharePoint. Figure 11-64 shows the same page within the SharePoint home page.

Figure 11.64. Figure 11-64

Here's the code shown in a single listing:

protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {
        WorkflowManagementServer wms = new WorkflowManagementServer
          ("SERVER", 5555);
        wms.Open();

        // load the querystring value
        string procSet = Request.QueryString["ProcSet"];
        WorklistItems wi = wms.GetWorklistItems
          (DateTime.MinValue, DateTime.MaxValue, "%", procSet, "%", "%", "%");

        gridviewWorklistItems.Columns.Clear();
        gridviewWorklistItems.DataSource = wi;
        gridviewWorklistItems.AutoGenerateColumns = false;

        BoundField fldEventName = new BoundField();
        fldEventName.DataField = "EventName";
        fldEventName.HeaderText = "Event Name";
        gridviewWorklistItems.Columns.Add(fldEventName);

        BoundField fldActivityName = new BoundField();
        fldActivityName.DataField = "ActivityName";
        fldActivityName.HeaderText = "Activity Name";
        gridviewWorklistItems.Columns.Add(fldActivityName);

        BoundField fldDestination = new BoundField();
        fldDestination.DataField = "Destination";
        fldDestination.HeaderText = "User";
        gridviewWorklistItems.Columns.Add(fldDestination);

        BoundField fldStartDate = new BoundField();
        fldStartDate.DataField = "StartDate";
        fldStartDate.HeaderText = "Date Started";
        gridviewWorklistItems.Columns.Add(fldStartDate);
        gridviewWorklistItems.DataBind();
    }
}

Of course, the list of processes previously shown can be modified in many ways, including:

• Show the Folio or DataFields for the specific ProcessInstance.

• Include a link to the ViewFlow for the specific process.

• Update the layout of the grid, including fonts, colors, column sizing, and so on.

The specific details can be based on business rules or requirements within the organization.

//set the user name to be used as the Destination
string userName = "DENALLIX\Administrator";

//load the list of items
WorklistItems wi = wms.GetWorklistItems(DateTime.MinValue, DateTime.MaxValue,
userName, "%", "%", "%", "%");

using Windows.Security.Principal;

//set the user name to be used as the Destination
string userName = Windows.GetIdentity().Name;

//load the list of items
WorklistItems wi = wms.GetWorklistItems(DateTime.MinValue, DateTime.MaxValue,
userName, "%", "%", "%", "%");

The previous example is useful for a system administrator or console application — or when a manager needs to view other staff's list of work.

For users viewing their own worklist, there are a number of user interfaces as part of K2 blackpearl. The current tasks can be viewed using the K2 Workspace, SharePoint Web part, and even a Windows Vista sidebar gadget that is available on the K2 black market.

As an alternative, the same details can be retrieved from within custom code and displayed or actioned directly depending on business requirements. Similar code could be used with a Web service or WinForm or perhaps with an application for display on a mobile device.

To retrieve the WorklistItems using custom code, we need to jump back to look at the SourceCode.Workflow.Client namespace (added in previous examples).

This uses the automatic security trimming of the current user who has created the K2 server connection, rather than using program code to specify a username (as seen in the previous example).

Add another Web page to the solution entitled WorklistForCurrentUser.aspx.

Within the page designer, add a gridview control. The form should then look similar to that shown in Figure 11-65.

Figure 11.65. Figure 11-65

First, add the namespace to the class by adding the following using statement:

using SourceCode.Workflow.Client;

The first code segment to include is for the Page_Load event:

protected void Page_Load(object sender, EventArgs e)
{

}

Once again, create a connection to the K2 server, as seen in previous examples:

//Open Connection
Connection conn = new Connection();
conn.Open("SERVER");

The Worklist items can then be loaded using a statement that could not be simpler: OpenWorklist:

//Get Worklist for current Logged on User
Worklist wl = conn.OpenWorklist();

The K2 server will automatically determine the current user by using Windows Integrated Authentication from the browser or by using the AppPool identity (if it's running within a Web service).

The security trimming related to the particular user context is automatically applied to ensure that only those tasks assigned can be viewed.

The list of WorklistItems can then be shown in the grid:

gridviewWorklistItems.DataSource = wl;
gridviewWorklistItems.DataBind();

The list of columns displayed in the grid will initially be limited to SerialNumber and Data, which contains the URL of the page to be shown for a client event. Refer to Figure 11-66.

This simply illustrates the OpenWorklist method to retrieve the worklist items assigned to a specific user.

Figure 11.66. Figure 11-66

To add some detail for the user and show a more meaningful list, the code will need to cycle through each Worklist item and retrieve the details to display — ProcessName, EventName, ActivityName, StartDate, and Folio.

The first step is to create a DataTable with columns that can then be added to the grid using data binding.

//create a data table
DataTable dt = new DataTable();

//add some columns
dt.Columns.Add("SerialNumber");
dt.Columns.Add("ProcessName");
dt.Columns.Add("ActivityName");
dt.Columns.Add("EventName");
dt.Columns.Add("StartDate");
dt.Columns.Add("Folio");

The foreach statement is used to iterate through all worklist items, with the variable wli used for each worklist item in turn:

foreach (WorklistItem wli in wl)
{

}

Within the foreach block, there will be a DataRow added to the DataTable created previously, with the values from the WorklistItem and other values from the sub-objects ProcessInstance and EventInstance.

//create a new row, with columns defined
DataRow dr = dt.NewRow();

//add values from worklist + sub-objects
dr["SerialNumber"] = wli.SerialNumber;
dr["ProcessName"] = wli.ProcessInstance.FullName;
dr["ActivityName"] = wli.ActivityInstanceDestination.Name;
dr["EventName"] = wli.EventInstance.Name;
dr["StartDate"] = wli.EventInstance.StartDate.ToString();
dr["Folio"] = wli.ProcessInstance.Folio;

//add the data row to the data table
dt.Rows.Add(dr);

Once the list of WorklistItems has been added to the DataTable, this can be used as the DataSource for the gridview:

//bind data table to grid
gridViewWorklistItems.DataSource = dt;
gridViewWorklistItems.DataBind();

When the page is shown, the list is loaded, showing only the tasks for the current user. See Figure 11-67.

Figure 11.67. Figure 11-67

Here's the full code listing for this example:

protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {
        //Open Connection
        Connection conn = new Connection();
        conn.Open("SERVER");

        //Get Worklist for current Logged on User
        Worklist wl = conn.OpenWorklist();

//create a data table
        DataTable dt = new DataTable();

        //add some columns
        dt.Columns.Add("SerialNumber");
        dt.Columns.Add("ProcessName");
        dt.Columns.Add("ActivityName");
        dt.Columns.Add("EventName");
        dt.Columns.Add("StartDate");
        dt.Columns.Add("Folio");

        foreach (WorklistItem wli in wl)
        {
            //create a new row, with columns defined
             DataRow dr = dt.NewRow();

            //add values from worklist + sub-objects
            dr["SerialNumber"] = wli.SerialNumber;
            dr["ProcessName"] = wli.ProcessInstance.FullName;
            dr["ActivityName"] = wli.ActivityInstanceDestination.Name;
            dr["EventName"] = wli.EventInstance.Name;
            dr["StartDate"] = wli.EventInstance.StartDate.ToString();
            dr["Folio"] = wli.ProcessInstance.Folio;

            //add the data row to the data table
            dt.Rows.Add(dr);
        }

        //bind data table to grid
        gridViewWorklistItems.DataSource = dt;
        gridViewWorklistItems.DataBind();
    }
}

Enhancements to this example could involve the following:

In addition to the samples shown here, the K2 API allows for many more functions related to K2 workflows and the K2 server itself. The specific functionality to be implemented will depend on the requirements for the organization and the design and specifications of the solution at hand.

For example, the API allows for custom code to: