K2 [blackpoint] & Web service

Problem
Determine manager of AD group dynamically in K2 [blackpoint]

Scenario
User A starts a K2 workflow (this makes the user “originator” of the workflow). This user belongs to an Active Directory group “ABC”. Manager property is not set, but group “ABC” has “Managed By” value set. Question is how to get the manager of the group and use it as a destination in K2 [blackpoint]?

Resolution Scenario
Possible resolution to this problem is using web service, consumed in K2 process. This service can:
1. Get workflow originator name as an income parameter
2. Determine the AD group, this user belongs to
3. Search for the manager of this group
4. Return the manager as a result (XML)
Once these steps are complete (and the service is published), it could be consumed from K2 [blackpoint] and the result used as a destination in an activity.


Web service
Creating a web service is simple – open Visual Studio, select to create a new project and choose select “ASP .NET Web Service Application” as a project template.


When the project is ready, include as a reference System.DirectoryServices namespace. This namespace provides access to Active Directory Domain Services.
There are 2 options (at least) to get AD group to which the user belongs to.

Option 1: Get the “Canonical name” and parse the result to extract group names:



Option 2: Get the list with groups where the user is a member:


Note that there is one method used above when creating search filter - “ExtractUserName”. This method does nothing more, but removing domain prefix from the name of the user to make it in a proper format for filter. In other words, if the input name looks like this: “domain\UserA”, this method will return only “UserA”.
Assuming that we already have the list with groups where “User A” belongs to, and group “ABC” is located, the next task is to get the manager of this group. This time we are interested in “Managed By” value, which can be extracted with “managedBy” property:


When the manager is determined, it is time to prepare the service response. Since this service will be consumed by K2, the response can only contain simple data types – string, double, Boolean etc. In order to return more complex results, the data can be presented as a XML string. Below is shown how to use both simple sting and XML as a response.

Case 1: Simple string
In this case the response returned is just the result – manager.

Case 2: XML string
This more complex scenario includes 2 steps:
1. Build the response:



2. Prepare XML definition file (XSD) to define the structure of the K2 filed that will keep the response:



K2 [blackpoint]

Add data fields for the response
Since we defined 2 cases (simple string and XML string):

Case 1: Simple string
To add a string field, expand Object Browser in K2 Studio, locate “Process/Activity Data” tab, select “Data Fields”, right click on the process name and select add. When “Add Data Field” window opens, type the name (“SimpleServiceResponse” in our case), make sure that “String” is selected as “Data Type” and click OK.



Case 2: XML string
Follow the steps from Case 1, but now, instead of “Data Fields”, select “XML Fields”. Type the name of the new field (“XMLServiceResponce”). Then open “XML Schema” tab, and browse for the schema file created above.


Once the schema is loaded, click on Initial Value tab and select Generate Sample XML file. Make sure that the file looks fine and click “OK”.



Get service response
First have to add a reference to the service. To do this, click on References button in K2 studio toolbar.


When Manage Project References window opens, select “Add” and click on “Web” tab. Type the address of the service and click on “Discover” button.


When “Web service discovered successfully” message appears, click on “Select” to add it as a reference. Close Manage Project References window.
From event wizards panel select Reference event and drag it on designer canvas. Click “Next” till “Event Method Editor” page opens and select “Add”. Expand the reference node till “Constructor()” is shown, select it and click Next.


No changes are needed in the next step for our case, so click “Finish”. Event Method Editor window should look like this:


Select the line defining the constructor and click on Add once again. This time “Select a Method” window opens. Locate the method needed and click on Next.


On “Configure Method Call” page assign the income parameters (Originator Name in our case) and the outcome parameter (either “SimpleServiceResponce” or “XMLServiceResponce”).


Click Next, and then Finish.

Usage

Case 1: Simple string
In this case the field contains the name of the manager that has to be used as an activity destination. To add it as a destination in iTechnology Forms Accelerator event (or other client event), expand Event Wizards panel, locate iTechnology Forms Accelerator event and drag it on the canvas. Follow the wizard till “Destination Users” page. There click on Add to add new destination rule, click on select object button and open “Process/Activity Data” tab. There expand Data Fields node and locate the field used above to keep simple data response (“SimpleServiceResponce”). Click on “Add”.


Note that “User” has to be selected as a destination type.

Case 2: XML string
The only difference from Case 1 is that this time you have to expand “XML Fields” node and locate the XML field used to store the compose service response (“XMLServiceResponce”). Expand this field to locate the proper node before assigning it as a destination rule.


The result should look like this:



Notes
1. Information in the field, populated by calling a web service method is static. This means that if you need to update/check it at some other point of time, you need to update it by adding additional reference events before using it again.