Saturday, December 26, 2009

Call WCF from K2 blackpearl event


I recently had the task to integrate some enterprise WCF services with a K2 blackpearl process for a company. If you need an introduction on WCF, please read this blog I wrote on how to write a WCF service.

There was not much stuff on the K2 Underground so I figured I write a short blog on how to go it. Thank you to Bob Maggio at K2 for giving some pointers.

There are really two ways you can do this.

  1. Call WCF endpoint through server side event handler in K2.
  2. Use the Dynamic WCF SmartObject Service.

Server Side Code Event

To all a WCF endpoint from a server side code event is pretty simple but there are a few things you should know. First, you may be used to right clicking on references in class library project and selecting the "Add Service Reference". What this does use the Svcutil tool to generate a client service class for you to call. That equivalent is not available in a K2 blackpearl project. You can try to add a reference by going to the K2 blackpearl process properties and then select references. In there you have the ability to add a "web reference" but that is for a Web Service. Even if the WCF service is deployed in IIS, you cannot use that methodology as it will give you errors. Just trying doing in a command line application outside of K2 and you will see what I mean.

The only way to do call the WCF service in clean manner is to create a class library project and call to it from your server side code event. The steps are:

  1. Add a class library project.
  2. In the K2 process properties, add a reference to that new project.
  3. Add the client service interface to that project and create a helper class that calls the WCF endpoints. Follow my instructions that I wrote about in this blog.
  4. In the K2 process server side event, add code to call your helper class.
  5. You will need to take the WCF client endpoint configuration (discussed in this blog) and add it to the C:\Program Files\K2 blackpearl\Host Server\Bin\K2HostServer.config.
  6. You will need to restart the K2 service to take effect.


  • In step five I discuss adding the WCF client endpoint configuration to the K2HostServer.config. This configuration is global to all K2 processes running on that server.
  • To test you helper class outside of K2, just create a command line project that reference the helper project. Place the client side endpoint configuration in the app.config of that project.

Dynamic WCF SmartObject Service

In my solution I elected to not use this even though it is a pretty good approach. Why? We really were not using SmartObjects as part of the overall architecture. First, I really did not want to have to pass through SmartObject layer just to do WCF call. Second, SmartObjects are great for doing visual development inside your K2 blackpearl processes. However in this solution we were already doing lots of server side code events so writing code into the process was not big deal and really quick to do anyways.

If we had decided to use the Dynamic WCF SmartObject Service I really liked to deployment better than the first option we went over. The configuration of the WCF service endpoints would have been in the SmartObject service on each K2 Server rather than having to modify the K2 Service config file and restarting the K2 server when there is a change.


Only consideration I always mention is that K2 processes version controlled. That means your WCF services MUST be version controlled. What can happen is:

  • You deploy process version 1.
  • You create 10 process instances on version 1.
  • You make a change to the process and the WCF interface and deploy version 2 of the K2 process.
  • BOOM, process instances on version 1 start bombing because changed the WCF interface.

So if you were to:

  • Remove a WCF service method.
  • Change the parameters, data or contract of an existing WCF service method.
  • Drastically change the internals of an existing WCF service method.

There will be a high chance that you will run into this issue. You need to account for this because making changes to WCF services. This is really nothing new; you will run into this issue when calling external databases or web services. If you are practicing good SOA methodologies you will be able to handle service versioning.

No comments: