Live Instance Management (LIM) in Sourcecode.Workflow.Management

The SourceCode.Workflow.Management API (SourceCode.Workflow.Management.dll) is used to administer a K2 Workflow server and active process instances. Note that the account that runs the methods in this API requires ‘Admin’ rights on the K2 workflow server.

For sample code and binaries that demonstrate the use of the Live Instance Management API, please see the following K2 community project:
http://community.k2.com/t5/K2-blackpearl/Process-Version-Migration-Utility/ba-p/73689

For a better understanding of the effects of managing live instances, please read the Important Notes topic.
SourceCode.Workflow.Management
Class Name Method Name Argument Name Argument Description
WorkflowManagementServer SetProcessInstanceVersion ProcInstID Id of the affected Process Instance.
TargetProcVersion Destination Process Version Id that should be applied to the Process Instance.
GotoActivity ProcInstID Process Instance on which the Goto should be performed
FromActName The Activity Name to use as the source when expiring Activity Instances
ToActName The Destination Activity Name to where the Process should go to.
GotoActivity ProcInstID Process Instance on which the Goto should be performed
FromActivity The name of the activity which the workflow will resume from after expiring all existing activity instances.

SetProcessInstanceVersion (int ProcInstID, int  TargetProcVersion)

Migrates the specified process instance from its current version to a different version of the process definition.

Parameters:
  • ProcInstID is the ProcessInstanceID for a process that is in Active, Stopped or Error state (SourceCode.Workflow.Management.ProcessInstance.ID)
  • TargetProcVersion is the version number of the process definition that the specified process instance should be migrated to. (SourceCode.Workflow.Management.Process.VersionNumber)

GotoActivity(int  ProcInstID,string  ActivityName)

Expires all current activities (including concurrent activities) and forces the process instance to start the activity specified in the ‘ActivityName’ parameter.

Parameters:

ProcInstID is the ProcessInstanceID for a process that is in Active, Stopped or Error state (SourceCode.Workflow.Management.ProcessInstance.ID)

ActivityName is the name of an activity in the process’ current definition to redirect the process instance to. (SourceCode.Workflow.Management.Activity.Name)

Copy

GotoActivity expire all example

//open connection to workflow management server
WorkflowManagementServer svr = new WorkflowManagementServer("localhost", 5555);
svr.Open();
//force the process instance to expire all current activities, and create an instance of the activity “activityName”
int procInstId = 10;
string activityname = "[ActivityName]";
svr.GotoActivity(procInstId, activityname);
svr.Connection.Close();

GotoActivity(int  ProcInstID, string FromActName ,string ToActName)

Expires only the named activity in the ‘FromActname’ parameter, and forces the process instance to start the activity specified in the ‘ToActName’ parameter. Any concurrent activites are not affected and remain in their current state.

Parameters:
  • ProcInstID is the ProcessInstanceID for a process that is in Active, Stopped or Error state (SourceCode.Workflow.Management.ProcessInstance.ID)
  • FromActName is the name of an activity in the process’ current definition to expire. (SourceCode.Workflow.Management.Activity.Name)
  • ToActName is the name of an activity in the process’ current definition to redirect the process instance to. (SourceCode.Workflow.Management.Activity.Name)
Copy

GotoActivity expire one example

//open connection to workflow management server
WorkflowManagementServer svr = new WorkflowManagementServer("localhost", 5555);
svr.Open();
//force the process instance to expire all current activities, and create an instance of the activity “activityName”
int procInstId = 10;
string fromActivityname = "[CurrentActivityName]";
string toActivityname = "[ToActivityName]";
svr.GotoActivity(procInstId, fromActivityname, toActivityname);
svr.Connection.Close();

If there has never been an instance of the activity specified in the ‘fromActivityName’ in the Process Instance, an error will be thrown. This is expected behavior.

The API does not check whether the activity in the ‘fromActivityName’ parameter is active. If the activity is not active at the time the command is executed, the process will still create an instance of the activity specified in the ‘toActivityName’ parameter. The only difference is that the Activity listed in the ‘FromActname’ parameter will not be expired, since it is not currently active. Developers may need to check whether the activity in the ‘FromActname’ is currently active before executing this method. This behavior is by design.

It is possible to inadvertently create ‘duplicate’ instances of activities. If there is already an instance of the ‘toActivityname’ active in the process, and this method is called, a duplicate instance of the Activity in the ‘toActivityName’ parameter will be created. This is expected behavior, and developers should cater for this expected behavior in their code where applicable.

Considerations

  1. If a process instance is in ‘Error’ state when migrating between versions, K2 will not automatically ‘Retry’ the processes in error state – it is up to the developer to determine which instances in error state can be retried after migration.
  2. Processes that are in ‘Running’ state because they have entered into an infinite loop, cannot be managed through the Management API. When a process instance is in ‘Running’ status, it means that K2 server is busy executing code for the specific process instance. It is NOT possible to intercept the executing code, or to manage the process instance while it is in ‘Running’ status. Therefore, the only statuses supported for managing process instances are ‘Active’, ‘Error’ or ‘Stopped’.Should you need to manage process instances that are in an infinite loop-like "Running" state, please log a support ticket with support. (Please refer to the ‘Exclusions’ section)
  3. When migrating process instances to definitions with additional activities, only the activities that are executed will appear in the process reports. Activities that were not executed will not appear in the process reports.
  4. New PROCESS-level datafields are available to client events without requiring a GoToActivity (see the important notes below). New ACTIVITY-level datafields may require the developer to perform a GoToActivity call, for those instances that are already at the activity where the changes were made.

Related Topics