Getting Started

Components Overview

Here is a brief summary of the installed components.

TWorkflowStudio component

component tworkflowstudio

This is the main component of the package. A single TWorkflowStudio instance should be added to the whole application, and from this component you have access to various methods and properties needed to work with Workflow Studio programatically.

The global variable WorkflowStudio contains a reference to the main TWorkflowStudio component of the application.

TWorkflowStudio component provides the following main object properties:

property WorkflowManager: TWorkflowManager;

The TWorkflowManager object provides methods to manipulate workflow definitions and workflow instances (creating, deleting, signaling, etc.).

property TaskManager: TTaskManager;

The TTaskManager object provides methods to manipulate tasks, specially task instances.

property WorkflowEngine: TWorkflowEngine;

The TWorkflowEngine object provides methods to the workflow engine, which runs the workflow instances.

property UserManager: TWorkflowUserManager;

The TWorkflowUserManager object is used to manipulate workflow users and groups.

property ScriptEngine: TWorkflowScriptEngine;

The TWorkflowScriptEngine object is used to parse and evaluate expressions and scripts.

property UserInterface: TCustomWorkflowUserInterface;

The TCustomWorkflowUserInterface object provides methods for displaying the predefined windows and dialogs of Workflow Studio, like the task list dialog, workflow definition editor and workflow definition dialog.

property WorkflowDB: TWorkflowDB;

The TWorkflowDB object is the component which makes the layer to save/load data to/from the database. You must specify which TWorkflowDB component you want to use to access database.

TWorkflowDB component

component tworkflowdb

The TWorkflowDB component provides a layer between application-level workflow data and the database server. This component builds all SQL commands used to insert, delete and update data in the database, but when it comes to execute the SQL statements, it does nothing.

You must provide event handlers for the events OnCreateQuery, OnExecuteQuery and OnAssignSQLParams.

TCreateQueryEvent = procedure(Sender: TObject; SQL: string;
  var Dataset: TDataset; var Done: boolean) of object;

Here you must provide your own code to create a TDataset descendant which provides connection to the database. You must also set the SQL statement (SELECT) provided . You must return a TDataset object in the parameter Dataset, and set Done parameter to true.

TExecuteQueryEvent = procedure(Sender: TObject; Dataset: TDataset;
  var Done: boolean) of object;

Here you receive your created TDataset descendant and call its specific method to execute an SQL statement. The SQL statement should have already set in the component in the OnCreateQuery event.

TAssignSQLParamsEvent = procedure(Sender: TObject; Dataset: TDataset;
  AParams: TParams; var Done: boolean) of object;

Here you receive a list of parameters (AParams) and you must set the parameters in your TDataset descendant, provided in Dataset parameter. Each component has a specific issue with parameters, and here you might deal with those specific issues, specially with blobs and memos.

This way you have total flexibility to use the component package you want to access your preferable database.

Workflow Studio provides some TWorkflowDB descendants form some widely used component sets (like ADO and dbExpress). In that case, you just drop the component you want to use (like TWorkflowADODB), assign it to the TWorkflowStudio component, and that's it, you don't need to set anything else.

TWorkflowADODB component

component tworkflowadodb

Provides ready-to-use ADO layer to the database. Use it if you want to use ADO components to access your database.

All you have to do is to set the Connection property to a valid TADOConnection component.

TWorkflowDBXDB component

component tworkflowdbxdb

Provides ready-to-use dbExpress layer to the database. Use it if you want to use dbExpress components to access your database.

All you have to do is to set the Connection property to a valid TADOConnection component. Optionally, you can also set DBType property to the database you are going to use, this will provide specific issues treatment for each database.

TWorkflowpFIBDB component

component tworkflowfibdb

Provides ready-to-use FIBPlus layer to the database. Use it if you want to use FIBPlus components to access your database.

All you have to do is to set the Database property to a valid TpFIBDatabase component.

Installing the component

Since not every Delphi environments have the FIBPlus components installed, TWorkflowpFIBDB component is not installed by default. To install it, do the following steps:

  1. Add {$WS}\source\drivers\fibplus directory to the Delphi library path, where {$WS} is the root directory of Workflow Studio files.

  2. Open package wspFIBpck.dpk located in the directory above and install it.

  3. If Delphi suggests changes to the package like adding required packages (it will at least include FIBPlus package to the list of required packages), accept it and install again until all warnings are gone.

TWorkflowFireDACDB component

Provides ready-to-use FireDAC layer to the database. Use it if you want to use FireDAC components to access your database.

All you have to do is to set the Connection property to a valid TFDConnection component.

Installing the component

Since not every Delphi environments have the AnyDAC components installed, TWorkflowAnyDACDB component is not installed by default. To install it, do the following steps:

  1. Add {$WS}\source\drivers\anydac directory to the Delphi library path, where {$WS} is the root directory of Workflow Studio files.

  2. Open package wsAnyDACpck.dpk located in the directory above and install it.

  3. If Delphi suggests changes to the package like adding required packages (it will at least include AnyDAC packages to the list of required packages), accept it and install again until all warnings are gone.

Auxiliary components

The following components are provided with Workflow Studio, although you might not need to use them. They are componentes and controls used internally by the Workflow Studio framework, and you can use them if you want to customize Workflow Studio, like building your own dialog windows.

TWorkflowDiagram

component tworkflowdiagram

Contains the workflow definition diagram. It's used in the workflow definition editor. Although you will probably not add a new TWorkflowDiagram component to a form, you might often use some of its methods and properties when using Workflow Studio programatically.

TWorkDefListView

component tworkdeflistview

It's a TListView descendant which shows a list of the workflow definitions in the database. Used in the workflow definition dialog.

TTaskListView

component ttasklistview

It's a TListView descendant which shows a list of task instances based on some filters (assigned to a user, or belonging to a workflow instance). Used in the task list dialog.

TAttachmentListView

component tattachmentlistview

It's a TListView descendant which shows the attachment files in a specified attachment. It's used in the task definition properties windows and also in the task list dialog.

TTaskStatusCombo

component ttaskstatuscombo

It's a TComboBox descendant which shows the current status of a task instance, and the drop down list shows the available status. If user changes the combo value, it automatically changes the value of the status in the task instance object. It's used in the task list dialog.

TTaskLogListView

component ttaskloglistview

It's a TListView descendant which shows the audit log for the changes in a task instance. It's used in the task list dialog.

"Hello world" tutorial

Workflow Studio provides basic online tutorial in Flash which display the basic steps to get an application running. Watching that tutorial will help you to understand the basics to start. The link to the online tutorial is included in tutorials folder.

Here we will provide a very simple list of tasks you should do to get Workflow Studio to run:

1. Install the product.

2. Create the tables and fields for Workflow Studio in your database.

Workflow Studio provides several SQL scripts for creating needed tables and fields for some database vendors (e.g., Oracle, Microsoft SQL Server, etc.), but you can create yourself in the database server you want.

3. Create a new VCL Application in Delphi.

4. Drop a TWorkflowStudio component.

5. Drop one of available TWorkflowDB components (TWorkflowADODB for ADO, TWorkflowDBXDB for dbExpress, etc.).

6. Drop a component for database connection and configure it to connect to your database (TADOConnection if you're using ADO, TSQLConnection if you're using dbExpress, etc.).

7. Associate your TWorkflowDB component to your database connection component using Connection property (or analog property).

8. Associate your TWorkflowStudio component to your TWorkflowDB component using WorkflowDB property.

9. Add valid users to your TWorkflowStudio component before application starts.

It can be done in FormCreate method of application's main form, for example.

10. That's it, you have it configured. Now you can use some methods to call the standard dialogs in Workflow Studio, like workflow definitions dialog and task list dialog.

E-mail notifications

There are several points in the workflow definition where an e-mail can be sent. An example is when a task instance is created for an user. If the task definition properties of this task instance is marked as "Send e-mail notification", an e-mail will be sent to the user notifying him that the task instance was created and assigned to him.

However, there is no built-in code to send e-mails in Workflow Studio. When an e-mail is to be sent, the event OnSendMail of TWorkflowStudio component is fired. So, if you want your workflow so support e-mail sending, create an event handler for TWorkflowStudio.OnSendMail event, and send the e-mail yourself from there, using your own method.

The signature for the OnSendMail event is below:

type
  TEmailInformation = record
    ToAddr: string;
    From: string;
    Bcc: string;
    Cc: string;
    Subject: string;
    Text: string;
  end;

procedure(Sender: TObject; TaskIns: TTaskInstance; AUser: TWorkflowUser;
  AEmailInfo: TEmailInformation; var Sent: boolean) of object;

So, use AEmailInfo parameter to build your e-mail message, using ToAddr, From, Bcc, CC, Subject and Text properties.

Set Sent parameter to true when the e-mail is sent. For extra information (you will often use only AEmailInfo), you can use TaskIns and AUser parameters to know which task instance generated the e-mail, and for each workflow user the e-mail is about to be sent.

Monitoring expired tasks (task timeout)

Workflow Studio supports task expiration (timeout). It means you can define a lifetime for a task. After a task instance is created, the workflow waits for it to be finished. If the task doesn't finish until the expiration date, the task will expire automatically, and the workflow will follow the path you have defined for expired tasks.

In the task definition properties you can define the expiration settings.

For the tasks to be effectively expired, you must have some kind of monitor that checks for all pending tasks in a regular interval, and then perform the correct operations on the expired tasks. TWorkflowStudio component provides a single method to perform this operation, but nevertheless, you must build this monitor yourself. Read more in section "Running workflow instances for expired tasks".

Localization

Workflow Studio provides an easy way to localize the strings. All strings used in user interface (messages, button captions, dialog texts, menu captions, etc.) are in a single file names wsLanguage.pas.

In the languages folder, included in Workflow Studio distribution, there are several wsLanguage.pas files available for different languages. Just pick the one you want and copy it to the official directory of your workflow studio source code.

If the language you want does not exist, you can translate it yourself. Just open wsLanguage.pas file and translate the strings to the language you want.

As a final alternative, you can translate the wsLanguage.txt file, also included in ws_languages.zip file, and send the new file to us. The advantage of this approach is that this file is easier to translate (you don't have to deal with Pascal language) and can be included in the official Workflow Studio distribution. This way we keep track of changes in translable strings and all new strings are marked in the upcoming releases. This way, you will always know what is missing to translate, and do not need to do some kind of file comparison in every release of Workflow Studio.

So, in summary, to localize Workflow Studio strings:

Option 1

  • Pick the correct wsLanguage.pas file from the ws_languages.zip file, according to the language you want.

  • Replace the official wsLanguage.pas (in source code directory) by the one you picked.

Option 2

  • Translate the official wsLanguage.pas directly.

Option 3

  • Translate the wsLanguage.txt file and send it to us (support@tmssoftware.com).

  • We will send you back a translated wsLanguage.pas file and this translation will be included in official release.