Introduction

K2.net 2003 offers several interfaces (APIs and web services) that developers can utilize to interact with the K2.net environment. The goal of this document is to highlight the differences between these APIs and provide some example scenarios of how the APIs can be used. This document is not intended to be a complete description of the APIs. If you need documentation on specific functions or usage please consult the help files that were installed with K2.net 2003. It should be assumed that any other K2.net interfaces that are not discussed in this document are considered internal and are not for use by the general public.

K2.net Runtime Object Model (K2ROM)

The Runtime Object Model (SourceCode.K2ROM) is the client interface into K2.net processes. It provides the functionality to start new process instances, retrieve worklist items, manipulate process data and complete worklist items. All custom interfaces that interact with running process instances from a client perspective will make use of the K2ROM.

From a high level perspective the K2ROM passes the client requests to the K2.net Server and then the K2.net Server connects to SQL to retrieve the information. Once SQL has retrieved the information it is passed to the K2.net Server and then on to the client application.

 
 

The worklist section of the Workspace makes use of the K2ROM to retrieve the worklist items for the logged on user and provide the links to the web forms that will allow the user to complete their tasks. Additionally the web form associated to the worklist item makes use of the K2ROM to retrieve the process instance data and allow the user to complete the task.

This behavior is different from the management interface, the K2MNG (described later), which can retrieve similar process information but has a very limited ability to interact with processes on a user level.

The business scenario for the K2ROM is fairly easy to imagine because in any human workflow you will need some sort of interface that allows the destination users to make decisions or manipulate data. If you were for example building an expense claim process you could build an ASP.net web form with all the required fields and controls that the person making the claim would need and then you would utilize the K2ROM to take the data from the form and map it to fields in the process. Once the data is mapped then the process can be started. At each human review step in the process you would follow a similar model of building the form and then using K2ROM to map and submit the data. The example here mentions web forms but you could use windows forms, InfoPath*, or any other technology that can reference a .net assembly**.

* The K2ROM code for InfoPath projects is actually already written for you in the form of an InfoPathWebService that installs with K2.net 2003.

** For integration with non .NET technologies the K2ROM could be wrapped in a web service.

 

K2.net Management Object Model (K2MNG)

The Management Object Model (SourceCode.K2MNG) provides an administrative interface to the K2.net Server. The ability to assign process permissions (Start, View, etc), to view the status of running instances, and to view errors associated with process instances are a few examples of what you can do with the K2MNG. The K2.net Service Manager for instance, is an application that makes use of the K2MNG API.

As you can see in the diagram below the K2MNG operates in a very similar manner to the K2ROM. It connects to the K2.net Server and requests information. K2.net Server then connects to SQL retrieves the information and then passes it back to the client application.

 

It is important to note that the K2MNG does not provide Super User functionality. Though you can view all the process instances and see all the worklist items you cannot manipulate process data or action worklist items.

The K2MNG does provide a lot of process level information, but it should not be used as an end user process reporting mechanism. There are two main reasons for this. The first is that in order to retrieve information using the K2MNG you need to be a K2.net administrator. This means that if you wanted to use this for end users you would have to either give them all administrative permissions or specify a username/password for an administrator account in your code. The second reason for not using the K2MNG as a reporting mechanism is that the K2MNG connects to the K2.net Server to retrieve the process information which if heavy reporting is done can degrade K2.net Server performance. The reporting web service that the workspace uses for reporting (described later) connects to the K2Log database directly and thus does not impact the performance of the K2.net Server service.

The business scenario for the K2MNG is probably the fuzziest of all the interfaces because if you need a strict management interface you can use the K2.net Service Manager. Most likely you would want to make use of the K2MNG to provide additional functionality to certain workflow users. If, for instance, you needed a business user to be able to see all the worklist items for a particular process you could utilize the K2MNG in your application. The caution here is that you will either need to give this user admin privileges to the K2 Server (not recommended) or you will need to make use of a dummy admin account that is specified in the connection string. If you use the latter you will want to then build custom authentication into your application.

 

K2.net Reporting Web Service (FilterService)

The FilterService web service (aka K2MIS) is the reporting interface for K2.net processes. This web service connects to the K2Log database directly rather than going through the K2.net Server so it will not negatively affect the performance of the K2.net Server service.
 
 

The FilterService is specifically designed to report on the process level data rather than the business data. So for example if you wanted to figure out the execution path, the duration, or the status of a process instance you should use the FilterService. If you are more interested in reporting on the business data such as an average invoice price you should look into using other tools such as SQL Reporting Services. To more easily utilize SQL Reporting Services or other tools to access your business data it is highly recommended that the business data not be stored in any of the K2.net data bases but rather in a separate database. This way the data can be stored in a more report friendly manner and also be indexed.

When implementing custom reports using the FilterService you can either build your own reporting environment or you can integrate your custom reports into the workspace. There is a KB article referenced at the end of this document that can give you more information on the implementation.

 

K2.net Studio Object Model (K2STUDIO)

The K2.net Studio object model (SourceCode.K2STUDIO) provides the methods for programmatically designing and deploying K2.net processes.

In the help files there is example code that does a complete programmatic process design from defining the data fields and line rules all the way down to exporting the process to the K2.net Server.

The most obvious business use for this interface would be to build an alternate process design tool however an alternate scenario would be to build a custom deployment tool. The deployment tool could, for instance, take a designed process from a development machine save the project files to a central repository for safe storage, update values in the process to reflect the desired deployment environment, and then export the process to the K2.net Server. You could event take this example a bit further and use the K2MNG to automatically set the process permissions for the newly exported process.

It should be noted that this interface is design time only so it cannot be used to programmatically redesign running processes.

 

K2.net Object Model (KO)

The K2.net object model (SourceCode.KO) provides an interface to all the K2.net objects in K2.net Studio. KO is an internal object model used to model the runtime environment of the Process Instance during execution. Objects such as the ServerEventContext, the EscalationRuleContext, and the ExceptionContext are part of the KO object model. Since the objects are used by the K2.net server during the execution of the process there is no practical use them in any kind of external application. The only application that you could build where you would want to use the KO is if you were building your own K2.net Server and if you are doing that you might want to revisit your design.
 
 

The place where you will make use of the KO object model is in the code behind for the events of a process. The simplest way to see this is by using a default server event which passes into the main function a server event context. This context is part of the KO and gives you the ability to access datafields, process instance information, and process flow functions such as gotoActivity.

For implementation samples you can get into the code behind for any of the event templates by selecting the use code option in the properties of the event action.

Some of the code behind the templates will make use of a K2Utilites interface which is an internal and non-supported interface. If you want to make use of it be prepared for the fact that there is no documentation or help available.