Using Workflow Studio programmatically

This chapter describes how to use Workflow Studio programatically. It lists some common tasks and how to do them from Delphi code.

Running an instance based on a definition name

It might be a common task to run a workflow instance based on a workflow definition name. The code below shows how to do that. See also the full example of running a workflow instance from Delphi code.

function TForm1.RunSomeWorkflow(ADefinitionName: string);
var
  wdf : TWorkflowDefinition;
  wfi : TWorkflowInstance;
begin
  wdf := WorkflowStudio.WorkflowManager.FindWorkflowDefinitionByName(ADefinitionName);
  wfi := WorkflowStudio.WorkflowManager.CreateWorkflowInstance(wdf);
  WorkflowStudio1.WorkflowEngine.RunWorkflow(wfi);
end;

Workflow with workflow instance variables

Workflow variables are a very used feature. You will often need to set or read workflow variable values to/from Delphi variables in order to make a strong integration of workflow with your application. The code below ilustrates how to set a variable value. See also the full example of running a workflow instance.

var
  wfi : TWorkflowInstance;
  wvar: TWorkflowVariable;
begin
  wvar := wfi.Diagram.Variables.FindByName('OrderNo');
  if Assigned(wvar) then
    wvar.Value := AOrderNo;
end;

Running an instance from code: full example

The following procedure below is a small example which shows how to run a workflow instance from Delphi code.

It runs the instance based on a workflow definition name, passes an order number so that it is included as a variable in the workflow instance (the variable "OrderNo" must already exist in the workflow definition), runs the instance and retrieve the record id for the newly created instance.

// Run a workflow definition from a specified definition name, and return the record key
// in the function result. Set the workflow variable "OrderNo" from the AOrderNo parameter
function TForm1.RunSomeWorkflow(ADefinitionName: string; AOrderNo: integer): string;
var
  wdf : TWorkflowDefinition;
  wfi : TWorkflowInstance;
  wvar: TWorkflowVariable;
  i: integer;
begin
  wdf := WorkflowStudio.WorkflowManager.FindWorkflowDefinitionByName(ADefinitionName);
  wfi := WorkflowStudio.WorkflowManager.CreateWorkflowInstance(wdf);
  result := wfi.Key;
  wvar := wfi.Diagram.Variables.FindByName('OrderNo');
  if Assigned(wvar) then
    wvar.Value := AOrderNo;
  WorkflowStudio1.WorkflowEngine.RunWorkflow(wfi);
end;

Retrieve the list of tasks for a specified user

The code below retrieves the list of tasks for a specified user. You can also check the Count property of the list to see if the user has no open tasks assigned to him/her (Count = 0 means no tasks).

function TForm1.CreateTaskListForUser(UserID: string): TTaskInstanceList;
begin
  result := TTaskInstanceList.Create(TTaskInstanceItem);
  WorkflowStudio.TaskManager.LoadTaskInstanceList(result, tfUser, UserID, true);
end;

Creating and editing a workflow definition

The code below creates a new workflow definition in database named "order processing" and opens the workflow definition editor for editing the newly created defition.

procedure TForm1.CreateAndEditDefinition(AName: string);
var
   wdf : TWorkflowDefinition;
begin
  // First check if the workflow definition already exists
  wdf := WorkflowStudio.WorkflowManager.FindWorkflowDefinitionByName(AName);
  if not Assigned(wdf) then
  begin
    wdf := TWorkflowDefinition.Create(nil);
    wdf.Name := AName;
    WorkflowStudio.WorkflowManager.SaveWorkflowDefinition(wdf);
  end;
  // Optionally set dimensions of workflow editor window
  WorkflowStudio.UserInterface.WorkflowEditorWidth := 1024;
  WorkflowStudio.UserInterface.WorkflowEditorHeight := 800; 

  // Open the editor
  WorkflowStudio.UserInterface.EditWorkflowDefinition(wdf);
  wdf.Free;
end;
...
begin
   CreateAndEditDefinition('order processing');
end;

Running workflow instances for expired tasks

Workflow tasks can have defined a date/time for expiration. If a task has a defined expiration date/time, when it exceeds this date/time without being closed by an user (changed to a completion status), its status is automatically changed to an expiration status.

However, this expiration of tasks is not done automatically by Workflow Studio. Since it requires a monitor being executed periodically to run the pending workflows and check for the tasks to be expired, you have to implement this monitor in your application, according to your needs (for example, a program scheduled in system task scheduler, a service, or even a timer inside the application).

All that needs to be done by this monitor is call a method from workflow engine:

WorkflowStudio.WorkflowEngine.RunPendingWorkflowInstances;

Status Templates

You can programatically create status templates to make it easy for your end-user to define a list of status when using Task blocks.

A status template is just predefined named list of status items like "Open", "Approved" and "Rejected". When the user is creating status items in the task definition properties, he can select one of the templates to automatically define all the status items without needing to insert each one individually. To indicate a status is a completion status you must prefix the status name with "*" (asterisk) character.

To create the templates, you use WorkflowManager.Templates property of TWorkflowStudio object, this way:

uses
  {...}, wsClasses;

var
  Template: TWorkflowTemplate;

Template := WorkflowStudio1.WorkflowManager.Templates.Add(wttTaskStatus, 'Approvation');
Template.Lines.Add('Open');
Template.Lines.Add('*Approved'); // completion status
Template.Lines.Add('*Rejected'); // completion status

Template := WorkflowStudio1.WorkflowManager.Templates.Add(wttTaskStatus, 'Open/Done');
Template.Lines.Add('Open');
Template.Lines.Add('*Done'); // completion status