Initiating K2 blackpearl Processes

In this first chapter of our series on integrating K2 blackpearl and Microsoft Dynamic CRM 4 we will be looking at ways in which you can initiate, or start, a K2 blackpearl process based upon a user interacting with a Dynamics CRM 4.

During the course of this series we will be developing a solution based upon the creation, review and approval of a new lead. The scenario will see:

• a inside sales staffer identifies and capture a new lead in CRM 4
• a K2 blackpearl is process initiated
• the process will provision a SharePoint site to manage all documents and collaboration concerning the lead
• it will assign a task to the Sales Team to review the lead in CRM and make a decision on it's potential
• based upon the Sales Team decision the process will conduct some further integration with CRM & SharePoint.

It is intentionally a simple scenario to begin with aimed at demonstrating the ability to drive a K2 blackpearl process through Dynamics CRM 4 and having such a process span multiple line of business systems and people within the organisation. Over the course of the series we may look to evolve the scenario further.

Where to Start

Dynamics CRM 4 provides two key mechanisms to add additional business logic and functionality to the platform, Plug-ins and Workflow. The description of these and when and where to use one versus the other is beyond the scope of this post. If you do need some information on the topic I recommend that you have a look at the following:

• Dynamics CRM 4 SDK
• Plug-in or Workflow
• Differences between Workflow and Plugins in CRM 4.0

For our example we will be using Workflows and in particular developing a custom workflow activity specifically for initiating our K2 blackpearl process. It is worth pointing out that you could use either approach, Plug-ins or Workflows, to start a K2 process. I have chosen to use Workflows in this example to allow users to have greater control as to when a process is started and to demonstrate how we can leverage and extend the existing workflow platform in CRM 4.

In this chapter the basics of building a custom workflow activity for CRM 4 is out of scope. If you'd like to learn how to build a custom workflow activity then have a look at the following tutorial - Developing Custom Workflow Activities for Microsoft Dynamics CRM 4.0. What we will be focusing is the key elements within that activity that enable it to start a K2 blackpearl process.

All source code for this post and all other posts in this series can be found in the Microsoft Dynamics CRM 4 - blackpearl Integration blackmarket project on K2 Underground.

Step 0 – The Necessary Pieces

From this point forward I am going to assume that you have set up the base requirements for a custom workflow activity;

• Created a new Workflow Activity Library project
• Added a reference to Microsoft.Crm.Sdk.dll and Microsoft.Crm.SdkTypeProxy.dll
• Renamed the generated class file (no spaces)
• Annotated the class with the .NET attribute CrmWorkflowActivity and overriden the Execute method

Again, if you need assistance in this area a create reference is Developing Custom Workflow Activities for Microsoft Dynamics CRM 4.0.

Step 1 – Inputs and Outputs

Now we need to define the input and output properties for the Activity. For our simple demonstration activity we will have four input properties that will allow the user to configure which K2 blackpearl process to start and which data fields to pass key entity information. Our input properties are:

• Process Folder – The folder or project name in which our K2 blackpearl process resides.
• Process Name – The name of the K2 blackpearl process we wish to start.
• Entity ID Datafield – The name of the data field in our process that will hold the ID of the CRM entity that started the process.
• Entity Name Datafield -  The name of the data field in our process that will hold the entity type name for the CRM entity that started the process.

The first two properties are obvious if you have worked with the K2 Workflow API before. You need to know the name of the process and its folder in which it resides to start an instance of that process. The second two properties, Entity ID Datafield and Entity Name Datafield, are less obvious. When we use this activity inside CRM they will take in the name of K2 blackpearl process data fields that will receive the ID and the type name (e.g. lead, account, etc) for the CRM entity against which the workflow has been initiated. By passing these two values to the K2 blackpearl process you can use the CRM web service or as we will see in later chapters the Dynamics CRM 4 Service Broker to access CRM entity information from within our process.

Our output property will simply be the the ID of the initiated K2 blackpearl process.

Defining an input property for Process Name.

public static DependencyProperty ProcessNameProperty = DependencyProperty.Register("ProcessName", typeof(String), typeof(DemoK2CRMStartActivity));

[CrmInput("Process Name")]
public string ProcessName
{
    get
    {
        return this.GetValue(ProcessNameProperty).ToString();
    }
    set { 
        this.SetValue(ProcessNameProperty, value); 
    }
}

Step 2 – Who Starts The Process

Now that we defined the input and output properties we can begin to flesh out the functionality of the Execute method. The first thing that we need to do is to get access to the CRM context and to the CRM web service.

// Get the context service.
IContextService contextService = (IContextService)executionContext.GetService(typeof(IContextService));
IWorkflowContext context = contextService.Context;

// Use the context service to create an instance of CrmService.
ICrmService crmService = context.CreateCrmService(true);

Using this context information we now need to retrieve the user who started the CRM workflow so that same user can start the K2 blackpearl process. We can do this easily using the CRM service and doing a look up on the systemuser entity. We get initiating user’s ID via context.UserId which returns a GUID which is the key value to the user’s instance of the systemuser entity. Using this GUID we can retrieve the systemuser entity instance and retrieve the user’s domain details. We will use the domain details in the next step.

// Retrieve the user who started the process
string[] cols = new string[] { "domainname", "yomifullname" };
Microsoft.Crm.Sdk.Query.ColumnSet myColumnSet = new Microsoft.Crm.Sdk.Query.ColumnSet(cols);

systemuser su = (systemuser)crmService.Retrieve(EntityName.systemuser.ToString(), context.UserId, myColumnSet);
string username = su.domainname;

Step 3 – Starting the K2 blackpearl Process

Now that we have the user who needs to start the K2 blackpearl process we can dive into the K2 Workflow API. Well before diving into coding we need to add a reference SourceCode.Workflow.Client which can be found in C:\Program Files\k2 blackpearl\Host Server\Bin.

// Using the K2 blackpearl API start a process
SourceCode.Workflow.Client.Connection k2Con = new SourceCode.Workflow.Client.Connection();
SourceCode.Workflow.Client.ProcessInstance k2Pi;

try
{
    // Open a connection to the K2 blackpearl server
    k2Con.Open(System.Configuration.ConfigurationSettings.AppSettings["blackpearlServer"]);

    // Create a process instance based upon the input values of the WF Activity
    k2Pi = k2Con.CreateProcessInstance(this.ProcessFolder + @"\" + this.ProcessName);

    // Impersonate as the user who started the WF in CRM
    k2Con.ImpersonateUser(crmUser);

    
    // Assign CRM Entity GUID to the process datafield
    if (this.EntityIDDatafield.Trim().Length > 0)
    {
        k2Pi.DataFields[this.EntityIDDatafield].Value = context.PrimaryEntityId.ToString();
    }

    // Assign CRM Entity Name to the process datafield
    if (this.EntityNameDatafield.Trim().Length > 0)
    {
        k2Pi.DataFields[this.EntityNameDatafield].Value = context.PrimaryEntityName;
    }                

    // Start K2 blackpearl process
    k2Con.StartProcessInstance(k2Pi);

    // set the WF Activity Output paramater
    this.ProcessInstanceId = k2Pi.ID.ToString();

}
catch (Exception ex)
{
    throw;
}
finally
{
    if (k2Con != null)
        k2Con.Close();
}

The code here is standard Workflow API code using the Connection object to get a connection to the K2 blackpearl server and the ProcessInstance object to start a new instance of the process. There are a couple of interesting elements to this code.

We use the ImpersonateUser method in combination of the user’s domain name that we retrieved from CRM so that we can start the process as the same user who initiated the CRM workflow. We use ImpersonateUser rather Connection.Open because we know who the user is but do not have access to their password so we connect to the blackpearl server as the service account and then impersonate as the respective CRM user.

The other interesting element is the assignment of the entity name and entity ID to the process data fields. Here you see how we use the input properties to determine which data fields in the process these values will be stored in.

Step 4 – Deployment

Now that we’ve developed our custom workflow activity it is time to deploy it. I chose to use the Plugin Registration tool that is available with the CRM SDK (..\SDK\tools\pluginregistration)

Step 5 – Create a blackpearl Process

Now that we’ve got our custom workflow activity deployed into CRM we are all set to use it….. but before we can we need a K2 blackpearl process. I’m sure you are all well versed in building K2 blackpearl processes and building one for CRM is no different. The only prerequisite is the two process data fields that will ultimately hold the entity name and entity ID. As a rule I generally create data fields of type string called CRM Entity ID and CRM Entity Name.

In Chapter 3 we go into detail about how to use CRM forms as client event pages in processes.

Step 6 – Putting it to the Test

Now it’s time to dive in to CRM and configure a workflow that starts out K2 blackpearl process. Open CRM and go to the Settings tab and then Workflows. Click the New button and when prompted provide a name and select the CRM entity your workflow will be associated with. Now you can define your CRM workflow (nothing like the visual modelling experience you get with K2 blackpearl), when you click the Add Step button you will see a K2 blackpearl option and the Start K2 blackpearl Process activity.

Select this activity. Now provide a nice label for this step in the workflow and then click the Set Properties button. You will now be able to configure the input properties that we defined in our custom workflow activity.

Once you’re done save and publish the CRM workflow and we’re all done. You now have a CRM workflow that when it’s kicked off with initiate a K2 blackpearl process giving you the full benefits of an dedicated business process management platform.

Next Up

In the next chapter we’ll be adding the K2 Worklist to Dynamics CRM so that users can access all of their K2 blackpearl tasks straight from CRM.

As I mentioned, all source code for this post and all other posts in this series can be found in the Microsoft Dynamics CRM 4 - blackpearl Integration blackmarket project on K2 Underground.

Jonno