From The Bench

Stopping people from deploying to Production from K2/VS Studio and hiding the Production Environment from the Context Browser

2011-05-20T20:14:53Z

Recently I came across a scenario where someone wanted to enable the following:

- Allow people to work in K2D4SP in PROD

- Some of these people will also need to use K2 Studio in Dev, but not see PROD environment settings in the K2 Context Browser and/or Deployment dialog

The ability to restrict actual deployment to a PROD can be easily controlled via Workflow Server permissions in the Production K2 server (details below).

As the K2D4SP does not require each individual person to have export writes in order to deploy the process; the deployment is actually handled under the app pool identity running K2D4SP. However the “Production” environment will still appear in K2 Studio as these are two different things.

In order to to prevent the “Production” environment library from appearing for some people’s K2 Studio experience this can be done via Environment Library permissions:

1. Open up Workspace in your K2 Dev environment and go to the Workspace Management area

2. Browse to location below and add in users that ARE ALLOWED to see the prod environment settings

NOTE: by default this is empty, which means everyone can see the settings. However as soon as you add one identity here it restricts access to anyone not on the list.

3. Now if I open up K2 Studio with an identity other than Administrator I don’t have the option to select “Production” environment

…. And it does not appear at deployment time either …

Working with Arrays in K2

2011-01-08T13:36:00Z

I was asked recently how one can work with arrays in K2. The specific scenario presented to me was where one had a SharePoint delimited values such as “7#;Acme Bank” into the individual elements.

This can be very easily handled with K2 Inline Functions.

FYI, you can use Inline Functions in nearly any wizard; they are accessed via the context browser here:

Ok, so how would we use Inline Functions to emulate the scenario below? Attached is a simple self-contained example for your reference, but the highlights of it are:

I created 3 process datafields
- FullString – this simulates your SharePoint xml node, it contains a default value of: 7#;Acme Bank
- ID
- Value
Drag out a Data Event onto the Design Canvas
Select ‘Next’ on the welcome screen
Select ‘Transfer Data’ on the 2^nd dialog
Click ‘Assign’ button
In the ‘Destination’ field I drag “ID” from the Context Browser process datafields into it
I select the Inline Functions tab in the Context Browser and then expand “Lists”
I then select the “Index Item” method and drag and drop into the “Source” field
- This will then open up a new dialog to configure the extraction of an array
- I then set the following values:
  - Index: 1 (note: in K2 arrays are 1 based not 0 based)
  - Expected when empty: 0
In the ‘Values’ field I drag and drop the Inline Function Text > Split from the context browser
- This will open up a new dialog to configure a string to be split into an array
- I set the values of this Split dialog as follows:
  - Text: [Process Data Field].FullString (NOTE: you would use your xml field here)
  - Separator: #;
Click Ok
Now repeat steps 5 – 10 but substitute:
- In step 6:
  - Use ‘Value” process data field
- In Step 8:
  - User Index of 2
The final Data Event should look something like:

13. Save, deploy and run. We should see the string split into individual values:

In addition to this scenario there are other usages potential usages for arrays in K2. Such as:

- if a string held a delimited list of Domain\UserNames, one could use the Split Inline Function on that field within a Destination Rule in order to leverage generate a list of Destination Users.

- If a string held a delimited list of data for which sub workflows needed to be individually invoked in by an IPC event. The Split Inline Function could be used within the Plan Per Slot – No Destination option of the Advanced Destination Rules. For more information on Plan Per Slot – No Destination, which is essentially a For-Each loop within K2, please refer to this previous post:

http://k2underground.com/blogs/fromthebench/archive/2008/10/22/using-a-repeating-xml-node-to-start-child-ipcs.aspx

Introduction to K2 SmartObject Services

2010-12-29T18:21:00Z

K2 blackpearl 4.5 update 1230 introduces a potentially very useful feature called ‘K2 SmartObject Services’. This permits any K2 SmartObject to be exposed via WCF, ATOM, XML and/or JSON endpoints. This functionality is built into K2 and requires just a little server-side configuration. This opens up a world of possibilities for leveraging SmartObjects in distributed applications that previously required a significant development effort to create custom service(s).

The attached article focuses on a high level walk through of how to setup and use this service within a WCF scenario. It is assumed that a basic understanding of WCF is already present, as this article will not go into details around what is WCF. Additionally, this article does not replace the K2 product documentation. Full details around K2 SmartObject Services can be located in the K2 product documentation that ships with K2.

Where are comments stored within a SharePoint Integrated K2 Workflow?

2010-09-02T16:04:50Z

For those that have leveraged K2’s SharePoint Workflow Integration (SPWI) process type within K2 Studio or Visual Studio, there is the ability to leverage K2 generated task pages. Within these pages, there is the ability for the user to add comments at each task and view previous people’s task comments.

Sometimes there is a need to do something with these comments within the K2 process, perhaps include them in a workflow generated email. With K2 4.5, at first glance it looks like there is no way to do so. However there is a way.

The field in question is a Process level XML field called ‘SPComments’. You can actually see it in K2 reporting if you look.

So how do you see it at design time?

In the K2 context browser click the down arrow on the Proc/Act Data tab and select ‘Show hidden fields’ and becomes visible:

From there you treat it like any xml (parsing, transforms…).

How the K2 web designer deploys in a SharePoint farm

2009-11-19T13:48:00Z

If SharePoint is not setup in a particular way, processes deployed from the K2 Web Designer in SharePoint do not deploy as expected. Specifically, in a SharePoint farm, the Web Designer deployment will appear to be successful, but in reality it will only have been deployed to a single server in the SharePoint form.

Before explaining how to resolve this, it is useful to understand how the Web designer deployment works in a SharePoint farm:

Deployment first executes on the machine to which the session has been established
It then queries SharePoint for a list of Servers in the farm (e.g. http://IP:port/_vti_bin/K2SPsites.asmx)
It then takes the first WFE server and gets a list of sites on that server (e.g. http://IP:port/_vti_bin/K2SPsites.asmx)
After that it resolves the Server name to an IP address
It then hits each site on http://IP:port and not on http://machinename:port and try to deploy to the K2 Features web service (e.g. http://IP:port/_vti_bin/K2SPfeatures.asmx). Basically looping through all sites on each server and tries to deploy the solution

So how to resolve the scenario where the process only gets deployed to a single node in the SharePoint farm? This will mean that you need to have a site (web application) on each WFE server that can be accessed locally via http://IP:port. After doing this and redeploying the process is should make it to all nodes.

Special thanks goes to Barry from K2 for providing the details here.

Misc Windows 2008 Configuration Steps

2009-11-17T14:25:00Z

There are some subtle changes to configuring a Windows Server 2008 environment. I recently did a K2 installation within an environment where all servers were running Windows Server 2008 SP2. Below are some issues I encountered and how I got around them. In speaking with others that have done installs in Windows 2008 it sounds like these are not always encountered, but I thought it worthwhile sharing in case someone does come across one or more of them.

1. IIS & Windows Authentication

When initially installing K2 Workspace on the server running IIS7 in the, the K2 Configuration Manager would not permit it to be configured because IIS did not have Windows Authentication enabled. When I checked out this site in IIS I found that Windows Authentication was not even an option to be enabled. After following the instructions in the below blog and doing an IIS reset for good measure, I was able to enable Windows Authentication for the site and the Configuration Manager proceeded.

http://weblogs.asp.net/zroiy/archive/2008/08/17/missing-windows-authentication-provider-for-iis-7-on-windows-server-2008.aspx

2. DTC and Windows Firewall

The first time I tried to deploy a SmartObject I received a “root element is missing” error. After doing a little digging it seems that Windows Firewall will block DTC by default. Since DTC is required on all server machines running K2 components, simply I simply opened up Windows Firewall on each server in the mix and adding an exception for DTC. After doing this my SmartObjects deployed without issue. FYI, details on how to enabled firewall exceptions for MS DTC can be found here:

http://technet.microsoft.com/en-us/library/cc725913(WS.10).aspx

3. K2 Webpart failing to connect to K2 server

After deploying the K2 task list webpart, I tried to configure it. After wiring it up to the proper K2 server and ports, I received “failure to connect; no such host” messages. I confirmed my K2 service was up and running. In watching the service in console mode I did not see any activity hitting the K2 sever at all. I was able to ping the K2 server without issue from the SharePoint server. I then tried telnetting to the K2 server workflow (5252) and host (5555) ports. These both failed. NOTE: the telnet utility is considered a feature in Win 2008 and may not be enabled on the system you are working on. To enable it you can following the instructions here: http://www.elmajdal.net/Win2k8/How_To_Enable_Telnet_In_Windows_Server_2008.aspx.

Once confirmed that I couldn’t connect to the ports, it started to sound like another Windows Firewall issue. I then opened Windows Firewall again on the SharePoint server and added some custom exceptions to unblock the workflow port (5252) and host port (5555). After completing this, the webpart was able to connect to the K2 server with out issue.

4. Not able to connect to K2 workspace from a machine other than the server running K2 workspace

Workspace opened without issue when browsing to it on the local IIS server. However whenever I tried to connect to it from a different machine in the domain, I got prompted for my credentials three times then was rejected with a 401 error. Long story short, it turns out that while Windows Authentication was enabled for the Workspace, no authentication protocols had been configured. This was confirmed by opening the appplicationhost.config file (C:\Windows\System32\inetsrv\config\ applicationHost.config) and then locating the <security> node within Workspace entry. It looked something like:

</windowsAuthentication>

I changed it to read:

</providers>

</windowsAuthentication>

After doing this I was able to open Workspace for other machines without issue.

NOTE: this is essentially the same steps outlined in the K2 product documentation around enabling Kerberos:

http://help.k2.com/helppages/k2blackpearl/page=Activate_delegation_settings_for_IIS_7.0_web_application_.html

However, since I hadn’t gotten to the point of Kerberos configuration yet I had not set these. Also, it is probably worth mentioning as I could see potential for this issue to occur even if Kerberos is not being used.

How To: Create an InfoPath Integrated Process

2009-08-20T09:13:00Z

Platforms: K2 blackpoint, K2 blackpearl

Audience: K2 process designers

Requirements: This article assumes that the reader has a basic understanding of how to create a K2 process and is familiar with the concepts of processes and activities. Knowledge of MOSS and InfoPath would be very helpful along with a high level understanding of XML.

Introduction

Whether you are using K2 blackpearl or K2 blackpoint, both platforms have the ability to allow a process designer to use InfoPath as the user interface. The nice thing about InfoPath is that is can allow nontechnical staff to create forms without writing any code. If your organization is using the enterprise version of SharePoint with Forms Services, InfoPath forms can be easily rendered as web pages by simply enabling that feature in the form, but more on that in a moment.

For the purpose of this article, I am going to explain how to create an InfoPath Integrated process from creation through deployment. I am going to focus primarily on K2 concepts and how the technologies overlap. If you have not used InfoPath before, there are many great blogs on the Internet that can help you get started. A couple of basic InfoPath concepts that you need to be familiar with before starting your first process are views and data sources as these concepts will be introduced early in the process development cycle. Additionally, a high level understanding of form libraries in SharePoint would also be extremely beneficial.

The steps I provide in this article can be applied to both K2 blackpearl or blackpoint. K2 blackpoint does provide a more streamlined method for creating an InfoPath based process through the use of a Process Helper. I prefer to teach people how to setup this type of process manually the first time so the process designer has a clear understanding of how all the moving parts fit together. Later should you have an issue, the designer will have a better understanding of where they need to start troubleshooting.

So let’s begin….

Create an InfoPath Form

The first step is to create your form. You can take your design queues from an existing paper form or use your own imagination. In either case, you need to have a clear understanding of what information you will need to be collecting and presenting to users throughout the process lifecycle. An InfoPath form is more than what it appears. It is really an XML data structure wrapped in a package with a form stacked on top to display the data. The data is displayed using “views”. [ Important InfoPath Concept #1 ]

A view is just another way of displaying the same data. All the views in an InfoPath form reference the same XML data structure. The difference is that on each view of the form a designer can decide what data is visible to the form user. This is a key concept to keep in mind when designing forms for a K2 process. As the process moves from step to step such as a first level manager approval step to a second level approver each of those steps may have slightly different requirements for displaying the data. The first level approver may need to see fields that the second level approver does not. Another situation is that the original person submitting the form may need to see less options than either of the approvers. This is the most common scenario for a K2 process. When you design a form for K2, you are going to need at least two views: one for the submitter and one for the approver. Just to clarify, when you add views to an InfoPath form, you are not duplicating data, you are merely providing additional options for how that data is displayed.

Speaking of data, before the views can be designed a data structure has to be created. This is done by adding fields to the main data source of the InfoPath form. [ Important InfoPath Concept #2 ] I recommend starting with the data structure first. As your create your data fields, they can be easily dragged onto your form to create text boxes, drop down lists and so on. In my experience, I find when a user starts the design process by dragging controls (textboxes and what not) onto the form they end up with extra fields in their data structure that are unused. This happens because when the designer drags a control onto the form a data field is automatically created. If the designer changes their mind and deletes the control, the data field remains. This is why I recommend defining all your data fields first to avoid orphaned fields.

For this exercise, I am going to create a form with at least one data field. I am going to name this field, Approver_Action. The purpose of this field is that it will contain the result of a choice made by an approver in the process. When the form is created, this field will only be used on the approver views. Simply drag the field onto the form in a location that works with your design. Later, when this form is added to the K2 process, the field will be automatically changed into a drop down list that will display possible actions that are updated automatically from the process. More on this in a bit…

To review, a designer will need to create an InfoPath form with at least two views. One view will be a submitter view that users who are submitting the form (starting the K2 process) will use and an approver view that will be used by approvers in the process. The approver view will need at least one control that was created from an Approver_Action field defined in the main data source. To be clear, a real InfoPath form will always have many more fields in the data source and multiple controls on each view to display data. These are just minimum requirements for K2 to work with the form.

Finally, save the form in a location that can be easily located. I recommend in My Documents as this is the default location the K2 wizard looks first in order to save a few clicks, but the form can be saved wherever works best.

Create a K2 Process

When creating a K2 process, all the real work is done when creating the form. The steps taken to integrate the form with a K2 process is wizard driven and incredibly easy as long as you understand the basic concepts. It only becomes complicated when the process designer does not understand the InfoPath and SharePoint concepts needed to be successful or the requirements of the business process exceed the capabilities of the technologies used such as complex form validation requirements.

First, open the K2 process design application for your version of the platform. In order to follow along with this article, K2 blackpearl users will need to use Visual Studio and blackpoint users will be using K2 Studio. The concepts shared can be applied to the K2 blackpearl Visio design tool as the wizards involved are the same as the other design applications, the only difference is how the wizard is launched from within Visio.

In the process design application, create a new K2 process. Visual Studio users will choose File à New à Project ( or Crtl + Shift + N) and from the New Project dialogue box select the K2 project type and then select “K2 workflow project” from the templates section on the right. Do not forget to give the project a name and click OK.

K2 blackpoint users will click on the K2 button in the upper left hand corner of the application and select “New”. Select “K2 Project”, provide a project name at the bottom of the window and click “Create” in the lower right hand corner. Choose a save location and click “Save”. Next choose “Blank Process”, provide a name for the process at the bottom of the window and click “Create” in the lower right hand corner.

In both applications, there should be a blank process canvas with a single start activity.

Before the InfoPath can be used in this process, it must be “integrated” with the process. I emphasized the word integrated because that is the name of the first wizard, InfoPath Integration. This wizard can be located under “Process Wizards” in both the K2 Studio and Visual Studio applications.

For those designers that this may be their first process, a process wizard is used to set high level or global settings for the entire process. There will not be any visual indication that this wizard has been run on the canvas because these setting compass the process itself. In Visual Studio, an icon will appear on the tool bar in the upper right hand corner of the canvas. In K2 Studio, an icon will appear on the ribbon bar at the top of the application under the Process tab in a section entitled Integration.

The InfoPath Integration process wizard is ran to communicate a few important facts to the K2 process such as what form should be used with this process and where the form will live when the process is deployed. The most common location for an InfoPath form to live is inside a Form Library in SharePoint. This is a requirement if the plan is to use Forms Services to display the form as a web page.

The next step is to launch the InfoPath Integration process wizard by selecting it from the toolbox, left click holding the button down and dragging it onto the canvas. If successful, a wizard window will launch.

Click next on the wizard window to move to the “Workflow Form Templates” page. This is where a process designer tells K2 which form (or forms there can be multiple) are being added to the process. To add a form, start by clicking the “Add” button in the upper left corner of the window. This launches a second wizard entitled “Add an InfoPath Form Template”.

The first page of this new wizard wants to know where the form you are adding has been saved. If my directions have been followed closely, this would be “My Documents”. To locate the file, click the “browse” button to the right of the window. Other source location options are available via the drop down box at the top of the window, but those are outside the scope of this article.

Once you have selected the form, click next on the wizard window.

It may look like the wizard did not change, but it did. Pay attention to the wording at the top of the window. As illustrated in the graphic above, the previous page was entitled “InfoPath Form Source Location”, the new page is entitled “InfoPath Form Deployment Location”. With this page, the wizard is asking the process designer where the InfoPath form is going to live when the process is deployed. For my example, I am going to choose “SharePoint Form Library” from the drop down list at the top of the window. When I made this selection, the window updated with new options that are specific to this type of deployment location.

Under location details, there are now three additional questions that need to be answered. First, the wizard wants to know in which SharePoint site the Form Library is or will be located. In this example, the wizard is already populated with an Environment Library field.

What is the environment library? In brief, the environment library is a global resource that stores the locations of servers or URLs that make up your environment. The purpose is to provide a centralized location for managing configuration information to avoid hard coding the setting into a process. By storing the information outside a process and referencing it in this manner, it helps make the process more portable when moving between environments like development to production. Please see the K2 Documentation for more details on the environment library.

Next, the wizard need to know which form library to use. At this point in my example, I have not created a form library to hold the form. I could have created the form library before hand or I have the ability to create a new form library on the fly from inside this wizard. In either case, click the browse button. K2 will now communicate with the SharePoint server at the site URL you provided above and return a list of available form libraries.

As illustrated by the screen shot, I currently have only one form library in my SharePoint site. This will not meet my requirements. If I click “Create” in the upper left corner of the window, I am given another new window which asks for details about the new form library. If you have been keeping count, there are now four windows stacked on top of each other.

Here, provide a name for the new form library. I will call mine MyFormLibrary. There are also options for providing a description and indicating if the form library should appear on the Quick Launch. Once the choices have been made click “OK” to create the form library. After a brief delay while K2 talks to SharePoint, the window closes and the form library that was just created is shown in the “SharePoint Browser” window.

Select the new form library and click “OK”. The SharePoint browser window closes and the selected library is now displayed in the Form Library text box on the “Add an InfoPath Form Template” window.

There is still two more bits of information the wizard needs. A choice needs to be made if this form will be added to the library we just selected as a library template or as a content type. I recommend choosing to add as a content type. The reason is that if the form is made a content type, then it will be versioned with the process. For example, the first phase of a process is completed, the business is happy and it is placed into production. A few months later, the business comes back to the process design team with new requirements that change the form and the process. The team makes the changes including changes to the data structure of the form and they are ready to deploy.

The dilemma faced by the team is that there are still processes running that are the old version that have not completed. Will deploying the changed process break the current running processes if the updated form is deployed? The answer is no if the form was deployed as a content type. This allows both the old form and the new form to coexist. This scenario would break if the form had been deployed as a library template since the new form would have overwritten the old form, breaking the currently running processes.

The final question remaining is which form client to use. The options are:

· InfoPath – this choice configures the library to attempt to open the form in the InfoPath application when it is opened.

· InfoPath, Web browser if InfoPath is not available – this choice is fairly self explanatory. If the user opening the form does not have the InfoPath application, then SharePoint will attempt to use Forms Services to open the form.

· Web browser – this setting instructs SharePoint to always open the InfoPath form as a web page using Forms Services

For my example, I am going to choose “Web browser” and click “Next”.

The next page in the “Add an InfoPath Template” wizard is entitled Smart Object Integration. This page would allow a process designer to add smart object methods to an InfoPath form to allow the designer to save a retrieve data from alternate locations inside the InfoPath form. This can be a very handy feature and is worth a closer look. The K2 Documentation has additional details on this feature.

For the purpose of this article and keeping to the basics, I am not using Smart Objects in my InfoPath form, so I simply click “Next” on the wizard page to move to the next step.

Because I am using the web browser as my form client, the next page entitled “HTML Task Pane” does not apply to this example and is only available if InfoPath as been selected as the form client, so I click “Finish” to complete this wizard and close the window returning me to the “InfoPath Integration” wizard page. This window now shows a single entry called MyIPForm which was the name of my InfoPath form.

Everything looks good so far, so I click “Next” to move to the next page in the wizard entitled “Process Start Details.” Here, a process design tells K2 how an InfoPath integrated process is to be started. My business requirement is that when a user submits a new form, a process is started so I change the form template drop down from “Start without InfoPath form” to myIPForm indicating that when this form is submitted it starts a new K2 process.

Here is also where views first start to come into play. Along with what form to use, the wizard also needs to know which view in the form has been designated as the view used to start the form. When I designed my form, I created a view called “Submitter” for this exact purpose.

The last bit of information needed to complete this page is the Folio. This field serves as an open text box where the process designer can basically create a subject line for each instance of a process. This field is surfaced on the K2 work list, where it can help provide information that distinguishes one task from another. For example, an accounting user is responsible for reviewing expense requests. They may get 50 to 100 requests day. When the accounting user looks at the K2 work list, all these tasks could start to look the same and there would not be an easy way of knowing some details about each individual task. The process designer can help ease some of the pain by putting a few details in the folio such as the requestor name and expense amount. Now when the accounting user looks as the work list , they may see an entry in the folio field like “Becky Smith - $100” or “Jim Connor - $50”. This is just one illustration. The folio field can be populated with any process data, workflow context information (metadata about the process) or smart object data. Just keep in mind that space is limited so it is best to make the folio entry clear and to the point. Once the folio has been configured, click “Next”. Skip the advanced settings page by clicking “Next” again, very rarely is there ever a need to change the values on this page.

Welcome to the final page of the InfoPath Integration process wizard! This page contains a single option “Would you like to configure a client event now?” I am being asked if I want to K2 to go ahead and add a client event for me. This would close the current wizard and launch the “InfoPath Client Event” wizard. Since many processes consist of more than one approval step, I am going to leave the check box blank and click “Finish” closing the wizard and returning me to the canvas. Remember, at this point there will not be any visual indication on the design canvas that the process wizard was ran. Look to the tools bars described earlier to access the wizard again if changes need to be made.

Since this article has went much longer than I intended, I am going to move briskly through the next steps focusing on InfoPath specific concepts. General K2 concepts I am going to gloss over and details can be found in the K2 Documentation .

In my example process, I need an approval step to allow someone to review my process and make a decision such as approve or decline. This accomplished by using an InfoPath client event. I locate the Event Wizards section of my toolbox and find the InfoPath Client Event. Select the event, click and hold to drag the event onto the process design canvas. This action will launch the “InfoPath Client Event” wizard.

Click “Next” to move to the next page entitled “General Event Setting”. This page we tell the wizard what to name the event, which InfoPath Form should be used, which view will this user see and where the action taken will be saved.

The important points on this page are the form template which is the InfoPath form that was just added during the InfoPath Integration Event. The client event view which I explained earlier should be different for the review or approval step as there would be an additional control added to allow the work list task to be actioned (hint hint). The task action field tells K2 that this field is where the action the approver takes will be stored. This field is located by using the Object Brower to locate the Process/Activity Data tab which will provide access to the data fields defined in the form. I located the Approver_Action field and drug it into the text box. When “Next” is clicked, the wizard will prompt to be allowed to create a drop down list control to display the available actions, click “yes”, the prompt closes and the wizard advances.

The rest of this wizard covers K2 concepts that are universal to any K2 client event regardless of forms technology used. The process designer will be asked if email notifications should be sent, what actions should be made available, automatically generate outcomes and lines and pick what users will be responsible for working this task in the form of destination users. Once these questions have been answered, click “Finish” to close the wizard and a new activity will appear on the canvas.

At this point my process is incomplete. Additional steps that need to be taken are connecting the Start activity to my InfoPathClientEvent Activity, adding an activity for both the approve and decline branches of my process (I am going to use mail events to notify the originator of the decision) and, finally, saving and deploying the process. So the end result would look something like this….

The only step left to do is give users start rights to the process. To start the process, I open a web browser and navigate to the SharePoint site and locate the form library. Once in the library, I click new from the menu bar to open a new InfoPath form. I fill out the form and click submit which will start a new K2 process.

That is all there is to it. It really is simple to accomplish once a process designer knows what to do, and I hope this article can help provide that guidance.

Good Luck!

How To: Use a web service for destinations in K2 blackpoint

2009-08-19T04:45:37Z

Platforms: K2 blackpoint

Audience: K2 process designers, .NET Developers

Requirements: This article assumes that the reader has a basic understanding of how to create a K2 process and is familiar with the concepts of processes and activities. .NET development experience in the area of web services is also helpful.

Introduction

There are many times when users are not managed in Active Directory. Their roles and functional areas are managed in a third party application or even a SQL database. In K2 blackpoint, there is not an out of the box method of accessing these third party data sources unless you use a web service.

K2 blackpoint provides process designers with the ability to use web services through the Reference Event Wizard. This event allows the user to reference either a web service or a .NET DLL. In this article, I am going to explore how to use a web service, but this approach could also be applied to a DLL as well.

Also, as you read this article, keep in mind that the main point is how to retrieve data from a web service and save those values to an XML data field. For illustration purposes, I have chosen to discuss this in the context of setting a destination rule, but this approach could be used to meet other requirements such as populating an email with values from a data source. Once the information retrieved from the web service has been saved to an XML data field, those values can be used any where in the K2 process that accepts XML data.

Creating the web service

First, I am going to write a simple web service to return some XML that contains a list of users. For this example, I am going to manually create my XML with a few hard coded users. This code could be easily updated to use ADO.NET, Oracle’s API or some other vendor API to retrieve data. The key points to take away are the data type used to return the XML and the structure of the XML.

Code Snippet
  using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Web;
 using System.Web.Services;
 using System.Xml;
 
 namespace MyWebService
 {
     /// <summary>
     /// Summary description for Service1
     /// </summary>
     [WebService(Namespace = "http://tempuri.org/")]
     [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
     [System.ComponentModel.ToolboxItem(false)]
     
     public class Service1 : System.Web.Services.WebService
     {
 
         [WebMethod]
         public string ReturnUserList()
         {
             XmlDocument doc = new XmlDocument();
             XmlElement root = doc.CreateElement("UserList");
             doc.AppendChild(root);
 
             XmlElement SQLUser = doc.CreateElement("Users");
             SQLUser.InnerText = @"domain\user1";
             root.AppendChild(SQLUser);
 
             SQLUser = doc.CreateElement("Users");
             SQLUser.InnerText = @"domian\user2";
             root.AppendChild(SQLUser);
 
             SQLUser = doc.CreateElement("Users");
             SQLUser.InnerText = @"domain\user3";
             root.AppendChild(SQLUser);
 
             return doc.OuterXml.ToString();
         }
     }
 }
  

The first important item to note about this code example is that my method “ReturnUserList” has been declared as type string. This is because the Reference Event Wizard only handles simple data types. The last line of my method we return the XMLDocument’s OuterXml converted to a string. These are the two key points to make this method successful.

Build and publish your web service.

Creating an XSD

The first step to setup your blackpoint process to use the web service is creating an XML process data field to hold the returned values from your web service. XML data fields in K2 require a schema definition to define the data field’s structure.

For the purpose of my example, I took my XML file and used the XSD.EXE tool included with Visual Studio to generate an XSD for me. For more information on the XSD.exe utility, check out this article on MSDN. You can also write your own by hand using your favorite text editor. Here is an example of the XSD I used:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="UserList" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="UserList" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="Users" nillable="true">
        </xs:element>
      </xs:choice>
    </xs:complexType>
</xs:element>
</xs:schema>

I saved this file as mywebservice.xsd since this represented the XML structure of what my web service would be returning. Please note, it is important to make sure that the node in your XML that is going to contain the list of users (in my case the node is called Users) is defined as a complex type. For more information on XSD files and how to create them check out this article at W3Schools.com.

Once you have your xsd file created, you are ready to start K2 Studio and begin developing your process.

Setting up the blackpoint process XML data field

The first thing I like to do when creating a new process is to define my data fields. New data fields can be created at any time during the process development cycle, but I like to define data fields first, as I prefer a more structured approach to process design. Plus, it is always good practice to make sure you have done your homework.

To create a new XML process data field, you need to locate the K2 object browser on the left side of the K2 Studio window and look for the Process/Activity Data tab.

Locate the XML Fields node and lick on the + sign to extend the node. Next, you will right click on the node below Activities. In my example to the right, the node is called “MyTestProcess”. This is the process level XML data field node. Since it contains data field definitions that are global to the whole process, this node takes on the name of the process which in my case is called MyTestProcess.

Finally, it is now time to add a new process XML data field. Right click and choose “add”. Do you remember where you saved the XSD file you created above? It is now time for us to use that file to define the structure of the XML data field we are adding.

The Add XML Field dialogue box contains several tabs: General, Initial Value, Metadata and XML Schema. For this article, we are going to focus on XML Schema and Initial Value. On the General tab, we only need to provide a name for this data field. I am going to call mine “MyXMLData”. It is a required field as noted by the red vertical bar next to the text box. You will receive a validation error if you forget to provide a name.

Now that we have given the data field a name, click on the XML Schema tab in the Add XML Field window. In the lower left hand corner of the window you will see a “browse” button. Clicking this button will give you a file dialogue box where you will navigate to the save location of your XSD file, select it and choose open.

The final step in preparing the XML data field is to click on the Initial Value tab and then click the “Generate sample XML file” button at the bottom of the window. This generates sample XML that represents what the data structure of your field will look like. Once satisfied with the results, simply click OK to save.

Back in the Object Browser you should see a new XML data field. In my case, I see a new field called MyXMLData. When I click on the + sign next to the field, I sell all the nodes that make up my XML data structure.

Adding a reference to the web service to the process

A web service is a resource that is external to your K2 process. In order to use the service, you are going to have to tell the process where it is and that it is available by adding a Reference to your project.

You can find the button to access the reference settings for your project at the top of the K2 Studio window on the ribbon bar on the “Home” tab. There, you will see a button called “References.” You may also access the Project References feature by pressing Crtl + R.

The next steps are pretty simple. Click Add in the upper left hand corner of the window. This will present you with the “Add References” window. Here, you will see four tabs: .NET, COM, Web and Service. For this article, we are going to work with the Web tab.

At the top of the window, there is a text box with the label: WSDL Url. This is where we are going to enter the full URL to our web service. This location will depend entirely on where you decided to publish your web service in your environment.

Once you enter the URL, click the “Discover” button at the right of the window. This basically validates your URL web service and ensures that it can be reached.

Next, locate the Name textbox and make any changes to the name of your reference.

Finally, click “Select” on the right hand side of the window. This adds this new reference to the Selected Items section and once completed, you may click OK to close the “Add References “ window and return to the Project References wizard. In the reference list, you should now see the reference you just added. Click the “Finish” button in the lower right corner of the screen to close the wizard.

Calling the Web Service and populating the data field with results

To begin, from the Event Wizards tool box, click and drag the Reference Event onto the process design canvas. This will launch the Reference Event wizard. Click next and you will be given the opportunity to name the event. In my example, I am going to call my Reference Event “My Web Service Call”.

The next page of the wizard is titled “Event Method Editor”. Basically this is the page where you will setup the call to your web service and then be given an opportunity to decide what to do with the results. Setting up the web service call is a two step process, and may be a bit confusing the first time through for non-technical process designers. I am not going to go into why these steps must be followed, but simply explain what to do to achieve the results you desire. Now, click on the “Add” button in the upper left corner of the window.

A new window called “Select a Constructor” opens. The window should contain a list of references that are available.

STEP 1: You will locate the reference that was just added in the previous step. In my case, I named my reference, well, MyReference. As you can see in the image to the left, I clicked on “MyReference” and extended the nodes till I reached the “Constructor” node. I selected the constructor node and clicked the “Next” button.

The next window will provide you with the ability to set many different parameters for your web service. My web service is very basic, so I do not need to make any changes to his page, so I clicked the “Finish” button.

Back on the “Event Method Editor” window, you will now see an entry for the constructor you just added. Now, we need to actually add a method call which uses this constructor.

STEP 2: Click on the single line to that it is highlighted in grey and then click the “Add” button once more. This opens a new “Configure Method Call” window. Scroll through the list and locate the method you wish to use. Based on the web service I provided at the beginning of this article, my method is called “ReturnUserList”. Simply select the method name, and click “Next”.

This page in the wizard is the page that we have all be waiting for as this is where the magic finally happens. We now will configure the wizard to save the method results. Click on “Return Parameter” so the that line is highlighted in grey and then click the “Assign” button in the upper left hand corner of the window. You will be given a small window where you will want to click on the ellipse button at the right of the text box to bring up the Object Browser. Locate the Process/Activity Data tab, choose XML Fields and then the process data field node. You should see the data field we added a few steps ago called “MyXmlData”. Select your data field, click add and then click “OK” to close the window.

Now, simply click “Next” and then “Finish” in the Configure Method call window. The configure method call window will close returning you to the Event Method Editor. You should now see a second method entry in the window. Click “Finish” to close the wizard.

If everything was wired up correctly, when your process reaches this activity it will invoke the web service and save the results to the process XML field. Now, you will be able to use those results anywhere in the process. It is import to keep in mind that information in the XML data field is static. You may have to add additional reference events elsewhere in the process if the needs change.

For example, if you were retrieving a list of users selected based on department and the first time you used the web service you pulled a list of users for marketing, you would then have to repeat the steps in this section if you wanted to retrieve a list for HR or Sales at a different point in the process.

The reference event has to be called BEFORE you need to use the data to make sure the XML field is correctly populated with the right information.

Use the XML data field in a destination rule ( or anywhere else )

Now that you have a populated XML data field, you simply add it to any text box where you want to provide a value that is determined dynamically as the process executes.

In the case of a destination rule, you would add the “users” node since this is the part of the XML data structure that contains the AD account name for the user that is to be assigned a task.

As I stated at the beginning of this article, the ideas conveyed here are not limited only to destination rules. You can use XML data fields through out your K2 processes to meet many different requirements. The most common use of data fields (XML or other wise) in a K2 process is to make the process more dynamic while it is running. Allowing choices to be made by the users of a process instead of hard coding values while the process is being designed. This provides a great deal of flexibility.

How To: Create InfoPath Task URL

2009-08-10T19:21:00Z

Create an InfoPath URL to open work list item in Forms Services.

Platforms: K2 blackpearl, K2 blackpoint

Audience: K2 process designers

Requirements: This article assumes that the reader has a basic understanding of how to create a K2 process and is familiar with the concepts of processes, activities, events (client event, InfoPath client event and mail event). An understanding of Microsoft SharePoint Server and InfoPath would also be helpful.

Work List Item URLs - Some Background

As much functionality as K2 delivers out of the box, there is constant interest on how to do things a bit more custom. One of the most common is process designers like to use K2’s mail events to send task notifications to users instead of using the out of the box task notifications since they are easier to customize from inside the process.

Part of the information that is commonly included in the body of the email is a link to the task item. This is the same link a user is directed to upon clicking a work list item in either K2 workspace or the Work list web part in Microsoft SharePoint Server.

When creating a process that uses an ASP.NET page as the UI, creating the URL is fairly easy and straight forward. The URL is merely the complete website address for the webpage that is being used with a parameter on the end. For example, let’s pretend I have a website that is hosting my web pages called www.mysite.com. The web page I have decided to use as my UI for my process is called mypage.aspx. The complete URL to an ASP.NET based task list item would look something like http://www.mysite.com/mypage.aspx?SN=123_14. The parameter SN is added by K2 and stands for serial number. This is a unique number that identifies this particular work list item.

An important concept to remember as we move forward is how a serial number is created. In the example above, the serial number used in the URL, 123_14, is actually two unique numbers separated by an underscore. These two numbers are the Process ID and the Activity Instance Destination ID.

The what? The who?

The Process ID is a unique number that is assigned to a process each time an instance of that process is started. For example, if you have an expense report process, each time a user submits an expense report that instance of the process will be assigned a unique process id number.

The Activity Instance Destination ID is a unique number that is assigned to each activity in the process that is executed. To create a serial number, you simply use the format Process ID_Activity Instance Destination ID. The good news is that these numbers are easily accessible when you are designing your K2 processes from the K2 Object Browser under the “Workflow Context Browser” tab.

So now that you have a basic understanding of a work list item url and how to determine the always important serial number the next step is to show you how to apply these concepts in order to create an InfoPath work list item url.

The InfoPath URL is a bit more complicated than a standard ASPX page. This is because there are a few more moving parts involved. InfoPath work list item URLs do not point directly to the form itself, but start out pointing to a K2 ASP.NET web page that is passed several parameters. The web page will then redirect the user to the correct URL of the InfoPath form. It can sound a bit complicated, but once it is broken down you will see that is actually pretty simple once you know the correct answers for all the parameters.

For the purpose of this post, I will be focusing primarily on what is needed to create an InfoPath work list item URL for an InfoPath form that is going to be delivered via Forms Services. The concepts learned here can be applied to situations where the form is opened using the InfoPath application with some minor modifications.

The InfoPath Work List Item URL – Deconstructed

Here is an example of the InfoPath work list item URL:

http://<workspace_servername>/RuntimeServices/OpenInfoPathTask.aspx?K2Server=<k2 server>&SN=<serial number>&XmlFN=<InfoPath Form Name>&Lib=<MOSS Form Library>&OpenAsWebPage=True&SPURL=<SharePoint Site URL>&Single=True&target=_blank

In this example, I have inserted <variable place holders> to denote the spots that should contain information specific to your environment and K2 process. The list below discusses each of the variables and the values that are expected.

InfoPath URL Variables:

· Workspace_servername: This is the fully qualified server name (server.yourdomain.com) that hosts the K2 runtime services. If you are using K2 blackpearl this is typically the server upon which you installed K2 Workspace. If you are using K2 blackpoint this will be MOSS web front end where you installed blackpoint.

· K2 Server: This is the name of the K2 server. K2 blackpearl users will enter the name of the server where pearl was installed. K2 blackpoint users will enter the name of the MOSS web front end where point was installed.

· Serial Number: Now you can see why the discussion on the serial number was important. This is where that number is used for an InfoPath work list item. Just remember, Process ID_Activity Instance Destination ID.

· InfoPath Form Name: This is the name of the InfoPath form that was added to your K2 process when you ran the InfoPath process integration wizard. If you forget the name of the form, it is available from the Solution Explore under the InfoPath Templates folder. The name is the file name you assigned to the form WITHOUT the XSN file extension. For example, if I added a form to my process called MyForm.XSN the InfoPath Form Name that is used in the URL will be MyForm.

· MOSS Form Library: This is the form library that was chosen during the InfoPath integration wizard as the deployment location for the InfoPath form template such as MyFormLibrary.

· SharePoint Site URL: This is the SharePoint site where the form library lives. The variable expects a full URL such as http://mymosssite.yourdomian.com/.

Using the examples provided in the list above, a complete InfoPath work list URL would look like:

http://server.yourdomain.com/RuntimeServices/OpenInfoPathTask.aspx?K2Server=k2server.yourdomain.com&SN=123_14&XmlFN=MyForm&Lib=MyFormLibrary&OpenAsWebPage=True&SPURL=http://mymosssite.yourdomain.com/&Single=True&target=_blank

If you are not certain what the values are for your environment, you can find answers to many of these in the K2 Object Browser such as workspace_servername which is stored in the K2 Object Browser on the Environment Library tab under Web Service URL.

Right click on the node and choose “edit field”. This will open a dialogue box so that you can see the value.

IMPORTANT: DO NOT CHANGE THE VALUE OF THIS FIELD! When in doubt, simply click CANCEL when you are ready to close the dialogue box.

Building the InfoPath Work List Item URL in a K2 Process

Now that you know how to create a proper InfoPath work list item URL, we can now take a look at how you could go about building this URL inside a K2 process. For this example, we will be looking at how to place this URL inside a Mail Event to be emailed to a process user. You will add a Mail Event to your process and move through the wizard to the Message Body page. The first thing you will want to do is set the Message Format to HTML. This will allow us to enter a bit of HTML code to add a clickable link to the body of the message.

Next, we need to start writing our HTML code to add a link to the email message. To create a link, we will be using the <a> tag with the href attribute.

The href attribute expects a fully qualified URL as its value. This is where we will start to build the InfoPath work list item URL.

In this example, I typed in the URL with correct values with the exception of ProcessID and ActivityInstanceDestID which are displayed in green above. This is because I added these values from the K2 Object Browser by clicking n the ellipse to the right side of the body window, selecting the values and then clicking “add”.

Why hard code the whole URL and not the IDs?

As discussed above, the Process ID and the Activity Instance Destination ID are unique for each time the process is ran and for each time an activity is executed so these numbers are always changing and therefore cannot be hard coded. Environments can change. Ideally, a process designer would have set the URL outside of the process in some sort of variable that could be changed later on if the environment changed without having to edit the process. K2 provides this funcaitonality as part of the Environment Library using a field called a “miscellaneous field”.

After the URL is complete, simply finish out the rest of the <a> tag with the necessary information. In my example, I used CLICK ME as the text that would represent the URL in the body of my email.

Conclusion

At first glance, the InfoPath work list item URL can seem pretty intimidating. It took me a bit of head scratching to figure it out the first time I attempted to create one, but once you are successful they are easy. The key is to understand what information the URL requires.

This method can be used in other K2 event wizards in which you may want to provide the URL. Another common use is when a SharePoint list is used to display items in process. The list will need to be created with a column that is set to type of hyperlink. A K2 process designer can then use the SharePoint List Items event to make new entries into that list and using this article can set the value of the hyperlink column to the InfoPath URL.

It is important that as a K2 process designer, you will need to remember that your event will only have access to the correct Activity Destination Instance ID from inside the same activity as the InfoPath Client event. Work list items are created by InfoPath client events which derive part of the serial number from the activity destination instance ID.

This technique can be very useful and address many business scenarios, but it is not without its limitations. Whenever a work list URL is emailed or written out to a list, the URL starts to spoil like fresh fruit and will have a very limited shelf life. For example, if a task is always assigned to a single user, then chances are things will be fine. The situation can become more complicated when there are many users that could be assigned to a task.

The out of the box K2 work list is designed to filter out and remove work list items that expire or are no longer available. This is because it queries the K2 database for the latest snapshot of data everytime the worklist is opened. The link in an email, however, is static. In a scenario where there are multiple users, the first user that clicks on the link can action the item without issue, but this does not remove the email from other users InBox. Thus any of the other users that attempted to open the link from their respective emails would be presented with an error because the link would have become stale. SharePoint lists are preferable to email messages since the K2 process can be designed with steps to keep the list up to date. NOTE: there are scenarios within K2 where a task can be setup to be actioned by multiple users (called “slots”); for the purposes of simplicity in explanation; this example assumes only 1 slot; which is the default.

Personally, I recommend that process designers refrain from embedding specific work list time URLs in an email message. I find a better approach is to include a link to either the K2 workspace, a MOSS site that is home to the K2 work list web part or even a link to a SharePoint list. This way the link can remain static but will send the user to a location that is constantly being refreshed.

Code Sample: How to use Workflow.Management API to force a process instance to a specific activity

2009-08-10T18:30:00Z

I was asked today how to use the workflow managment (SourceCode.Workflow.Management.dll) API to programmatically force a process instance to a specific activity. This is done with the GotoActivity method. Below is the code sampe:

        private void WorkflowManagementGoto(int processinstanceid, string activityname)
        {
            // get connection to Workflow.Management for a K2 workflow SERVER admin
            SourceCode.Workflow.Management.WorkflowManagementServer mgmt = new SourceCode.Workflow.Management.WorkflowManagementServer();
            mgmt.CreateConnection();
            mgmt.Connection.Open(GetConnectionString(5555, "K2Demo", "bpservice", "k2pass"))

mgmt.GotoActivity(processinstanceid, activityname);

mgmt.Connection.Close();
}

private string _K2Server = "localhost";
private uint _WFPort = 5252;

        private string GetConnectionString(uint port, string domain, string username, string pwd)
        {
            SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder builder =
                    new SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder();

            builder.Integrated = true;
            builder.IsPrimaryLogin = true;
            builder.Authenticate = true;
            builder.EncryptedPassword = false;
            builder.Host = _K2Server;
            builder.Port = port;
            builder.SecurityLabelName = "K2";
            if (domain != "")
            {
                builder.WindowsDomain = domain;
            }
            if (username != "")
            {
                builder.UserID = username;
            }
            if (pwd != "")
            {
                builder.Password = pwd;
            }

            /*
            Integrated=True;IsPrimaryLogin=True;Authenticate=True;EncryptedPassword=False;Host=localhost;SecurityLabelName=K2;Port=5252
            */

return builder.ToString();
}

Code Sample: How to add a user to a Working Hour / Zone

2009-03-04T14:14:00Z

Recently I needed to expose the ability to add users to an existing Zone / Working Hour Set. This can of course be done manually via K2 Workspace but these requirements needed to do this from a custom application. This can be done pretty easily via the K2 API (SourceCode.Workflow.Management.dll)

First you'll need to add a reference in your project to the K2 file SourceCode.Workflow.Management.dll. The below example also uses the K2 connection string builder which is from the file SourceCode.HostClientAPI.dll.

Below is some sample code that can be used to expose this functionality:

Normal 0 false false false EN-US X-NONE X-NONE MicrosoftInternetExplorer4 /* Style Definitions */ table.MsoNormalTable {mso-style-name:"Table Normal"; mso-tstyle-rowband-size:0; mso-tstyle-colband-size:0; mso-style-noshow:yes; mso-style-priority:99; mso-style-qformat:yes; mso-style-parent:""; mso-padding-alt:0in 5.4pt 0in 5.4pt; mso-para-margin:0in; mso-para-margin-bottom:.0001pt; mso-pagination:widow-orphan; font-size:11.0pt; font-family:"Calibri","sans-serif"; mso-ascii-font-family:Calibri; mso-ascii-theme-font:minor-latin; mso-fareast-font-family:"Times New Roman"; mso-fareast-theme-font:minor-fareast; mso-hansi-font-family:Calibri; mso-hansi-theme-font:minor-latin; mso-bidi-font-family:"Times New Roman"; mso-bidi-theme-font:minor-bidi;}

private void Form1_Load(object sender, EventArgs e)

{

string zoneName = "Sales";

string userName = @"K2:K2Demo\CarolM";

AddUserToZone(zoneName, userName);

}

private void AddUserToZone(string zoneName, string userName)

{

SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder connectionString = new

SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder();

connectionString.Authenticate = true;

connectionString.Host = "localhost";

connectionString.Integrated = true;

connectionString.IsPrimaryLogin = true;

connectionString.Port = 5555;

connectionString.Integrated = true;

// this connection needs to be made as a Workflow admin

// in this example we're forcing it to a specific ID. It must be a workflow server admin because

//only those identities have the rights to set zone users in K2

connectionString.WindowsDomain = "K2Demo";

connectionString.UserID = "bpservice";

connectionString.Password = "k2pass";

WorkflowManagementServer workflowServer = new WorkflowManagementServer();

try

{

workflowServer.CreateConnection();

workflowServer.Connection.Open(connectionString.ToString());

if (workflowServer.ZoneExists(zoneName))

{

workflowServer.UserSetZone(userName, zoneName);

}

catch (Exception ex)

{

// do something with the exception

throw (ex);

}

finally

{

workflowServer.Connection.Close();

}

Leverage existing SmartObjects to access new Sharepoint sites created with Templates or Site Definitions

2008-11-21T17:01:00Z

Throughout the Sharepoint service interface you will find a curious little property called Sharepoint URL. This url refers to the "site" that you want to run the method against, for instance http://localhost/somesite

Attached is a Word Doc that walks you through a quick overview of getting an example of this running and understanding how you can leverage this in your processes.

InfoPath Tip: InfoPath Wizards Part 2 - Conditional Formatting Is Your Friend

2008-11-19T19:12:00Z

In my last post, I talked about how to create an online wizard using InfoPath and Forms Services. It was a pretty simple process, but I did mention there was a pitfall regarding data validation.

The pitfall is when using data validation on multiple views in a wizard scenario, the submit button is typically on the last view/page of the wizard. The submit button is responsible for causing data validation to fire. This can create an issue if one of the controls you used 3 pages back has a validation problem. The user is told validation failed, but what they aren’t told is which view contains the offending field.

One way to address this issue is by using conditional formatting.

Conditional formatting allows you to hide or disable controls based on conditions in the form, hence the name. Additionally, there are other formatting options such as read-only or text formatting options.

This approach works best when dealing with situations where the data validation pertains to required fields. You may be able to handle more complex situations, but it will take some creativity and a combination of rules and conditional formatting. For the purpose of this article, I am going to stick to required fields.

Conditional formatting doesn’t actually validate the data, but what it can do is prevent the user from advancing in the wizard if they haven’t filled in all the required fields. The trick is you don’t apply the formatting rules to the field; you apply the formatting to the navigation button.

In our wizard scenario, to advance from step to step (change from one IP view to the next) we had to provide the user with a NEXT button. What we are going to do is set the conditional formatting to disable the NEXT button if our field we are requiring has been left blank.

First, locate the navigation button on your view, right click and choose “conditional formatting.” You will be presented with a conditional formatting dialogue box. You have the option of adding multiple formatting rules.

Next, click the add button and you will be presented with the “Conditional Format” window. The first line in the window is where you will define the condition. For this example,I am going to assume I have a field called “name” that I am going to require.In the conditional format window, I would select the “name” field from the first drop down box. The middle drop down is your comparison argument. For this scenario, I am going to select “Is blank”. The third drop down box becomes unavailable since the comparison argument I chose doesn’t’ make a comparison against another field. At this point,you could also click the “And” button which would allow you to add another condition rule to check if you had more than one field required. For example, you could say if Name is blank OR address is blank. Once you click the “And” button, you are given a drop down list so that you may specify the logic that needs to be applied to the second condition.

The bottom half of the window is what sort of formatting isapplied based on the conditions we just defined above. Since I am checking to see if the field is blank because I am going to require that field (in this case the “name” field), I will check “Disable this control.” The NEXT button will remain on our page, but the user will be unable to click it unless they have provided a value for the name field.

These steps would need to be repeated on the navigation buttons on the rest of the views in our wizard. These steps could even be applied to the submit button on the last view, to prevent submission of the form if certain fields on that page are blank.

The goal of this approach is to prevent the user from advancing to the next page in the wizard if all the fields we need have not been filled out, so refrain from creating conditional formatting rules that reference fields on other views as we are only interested in checking to see if this step in our wizard have been fully completed before allowing the user to advance to the next step.

Granted there are situations where this approach will not work because the validation required is more complex, but works great for scenarios where the need is simply to check if the field has been completed or not.

InfoPath Tip: Creating a wizard using InfoPath and Form Services

2008-11-17T17:33:00Z

It would seem that InfoPath and I are crossing paths on a more frequent basis these days. I was assigned to assist a client with an interesting idea, they wanted to use InfoPath and Form Services to create a wizard (i.e. a series of web pages) interface for the start of a process,

I admit, I had to crack the InfoPath book for this one, but what I found out is that it is actually simple to accomplish!

First, you will need to create an InfoPath form with a view for each step (page) in the wizard. For example, let’s assume that you want to create a wizard that consists of 3 steps. You will have a view for Step 1, Step 2 and Step 3. Each view will contain fields for the information that needs to be collected during that step, PLUS one extra feature: the “next” button.

The nice thing about using Form Services with InfoPath in this scenario is that moving between the pages in our wizard doesn’t require anything special other than a button or two that surfaces the ability to move between the views. The reason is that MOSS manages the session for you and automatically saves the information you are collecting as part of the session as you move from page to page. Visit with the MOSS Administrator to make sure session state has been enabled in your configuration.

As I mentioned, each of the views will need to have a button on the page that moves the wizard from one view to the next. The configuration of the button is pretty simple. All that is required is one rule on the button that is set to change the view of the form. For example, the button on “Step 1” view would have a rule to change the view to “Step 2”. If you are not sure where to set the rules for your button, just right click on the control and choose Button Properties à Rules… à Add… à Add Action…

The one key thing to keep in mind when working with InfoPath is that IP is all about the rules. So be prepared for several dialogue boxes and lots of clicking “OK”.

The final view in the wizard (in this scenario “Step 3”), the button will be configured as a a submit button instead of using it to change views. If you wanted to add extra functionality, the submit button could be configured to change the view to confirmation page after submit.

Once the views have been created and the buttons added to control navigation and submission, the IP form is ready to be integrated into a K2 process. All the data that is collected in the various views of the form is saved as part of the session allowing it all to be submitted to K2 during the final step. K2 treats the form just as it would any other InfoPath form, so nothing special is needed within K2 outside of the normal InfoPath integration steps.

I was pleasantly surprised with how simple it was to setup a wizard, but it isn’t without a few pitfalls. The primary issue is using multiple views in this configuration is going to cause an interesting situation if the form designer decides to use field validation. IP’s default behavior is to fire validation upon submit. IP will validate all controls configured for validation on all the views, but it will not tell you which control is causing the validation error. There is a pretty quick solution to the situation, but I’ll save that for another post. In the mean time, you can find an example InfoPath form attached to this post.

Until next time....

InfoPath Tip: My form won't open in Form Services!

2008-11-13T17:13:00Z

When working at a client site, I ran into a situation where my InfoPath form became cross with me and refused to open in Forms Services. This was confusing because everything had been working great up until that point. Isn’t it that way with most relationships?

I had been working on my form making changes. One of the changes caused an error in the form which prevented it from opening using just the web browser. Below are a few things to check if you find yourself in a situation where your IP form refuses to open using Form Services.

1) Check the current patch level of the K2 software. I feel it is always a good rule of thumb to make sure you have the latest and greatest. To find out what level you are on, go into the Control Panel à Add Remove Programs à Check “Show Updates” and compare the version number of the K2 bits to the latest version number listed in the K2 customer portal at http://portal.k2workflow.com. The latest updates and releases can be found under Downloads à BlackPearl.

2) Check to make sure “Web Browser” is selected in the InfoPath Integration wizard. When you add an IP form to your K2 process, you are asked if you want to open the form in InfoPath, Web Browser with No InfoPath or Web Browser. To check this setting, click on the purple InfoPath Integration icon in the upper right hand corner of the design canvas in K2 Designer for Visual Studio. In the wizard window, choose your form and click the edit button on the menu bar above. In the next window, check the “Form Client” option to ensure “web browser” is selected.

3) Check the Form Library settings in MOSS. All is in vain if the MOSS form library itself isn’t configured to open the form template in a web browser. During deployment, the form library setting will be made based on your choices when you added your InfoPath form to the process. From time to time, a situation may arise where the form library doesn’t get configured. It could be due to an environmental issue or the form client option was incorrectly set.

In any case, it is a good idea to double check. Navigate to your form library in MOSS, choose Settings à Form Library Settings. Under General Settings, you will find an option for “Advanced Settings.” Here, there will be an option for “Browser-enabled documents” which will need to be set to “Display as web page.” Make the change if needed and click OK to save your changes.

4) Check the design of your form. This was the problem in my situation. I had made changes to the form that caused an error. Whenever you make changes to or when you originally design your form, always run the design checker.

Before you begin, you will need to open Tools à Form Options à Compatibility and ensure you have checked “Design a form template that can be opened in a browser or InfoPath.” Also on this page, there will be a text box where you will enter the URL of your MOSS website. InfoPath will use this URL to contact your MOSS server to check the design of the form template.

To check your design, choose Tools à Design Checker from inside InfoPath. If your form has any errors or warnings, they will be displayed on the right side of the window. My form had an error with an image I chose to use and was the source of my troubles. I corrected the issue and redeployed. Success!

Please note that these are not in any particular order and assumes you are working in an environment that has been properly configured. You will need to be using the enterpirse version of MOSS which includes Form Serivces, or installed the stand alone Form Services product. A good way to check to see if Form Services is working properly before you get started with K2 is simply create a form library and check the setting from step 3 above. Then, create a web enabled form in InfoPath and deploy directly to your MOSS/FS server from InfoPath. Try to open the form from the library to see if it opens in a web browser as expected. If it works, you are ready to start working with K2. If not, I see additional troubleshooting steps in your future and quality time with the MOSS administrator.

In my case, since the form had been working before I made changes I should have ran design checker first. It could be considered a best practice to always run design checker to make sure you aren't setting yourself up for an issue later. What is the saying, "An ounce of prevention is worth a pound of cure?"

Have fun!