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.

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.