BPM - Business process design

Introduction

This manual explains how to design a process using Q-flow’s Business Process Web Designer.

Manual organization

This manual is divided into the following sections:

Quick guide: this section explains how to design a simple process using an example, so the reader can become familiar with the most basic concepts and the way the tool’s most important operations work.
User interface operation: this section gives a detailed explanation of how the user interface works. It also shows some of the most common operations and contains instructions to design a process (i.e. build the process diagram).
Process items: this section gives a detailed description of each type of process item (application data, roles and other items that are used so that processes can handle data, assign tasks, access other software systems, etc). It also includes in-depth descriptions of each item’s properties.
Process design elements: this section gives a detailed description of the elements that can be included in the design of a process: what each one is used for and its properties.

Quick guide

The goal of this section is to give a quick introduction to Q-flow using a practical example, so the reader can start using the product and become familiar with it as soon as possible.

A simple complaints process

A business wants to improve its customer complaints handling system through a Q-flow process. The complaints system they will implement is as follows:

A customer calls the business to express a complaint.
The call receiver starts a Q-flow process with the following data:
- Customer name
- Customer e-mail address: it will be used to send them a message once the complaint is handled.
- Complaint text: a description of the customer’s complaint.
- Text to send to the customer: the text that will be sent to the customer in an e-mail once the complaint is handled.
The commercial manager chooses an employee as the complaint handler.
The complaint handler handles it and writes a text to send to the customer in an e-mail.
An e-mail is automatically sent to the customer, using the text from the previous step.
The process execution ends.

Building the process in Q-flow

To build the process, it is convenient to first create a package in which the process template will be saved (see Creating a package). Once the package has been created, you should create a process template named “Complaints” inside the package (see Creating a process template). The process template represents the process specification.

When you create a process template, a version named 1.0 is automatically created. The version contains the process design. The process design is a graphical representation of it. A process template can have several versions, but only one is the production version, i.e. the one used to start flows based on the template. When the production version is changed, the flows that are already being executed continue using the version with which they were started.

Once the template has been created, the process elements can be added to the design. Fig. 325 shows the proposed design, which will contain the following elements:

Start event: it indicates where the process execution starts. All designs must have a starting element. When a version is created, the design comes with a start event and an end event.
Select the complaint handler: it is a user task. User tasks assign tasks to users. This elements assigns the task of selecting the complaint handler to the commercial manager. When the process reaches that element, Q-flow will notify the commercial manager, who will log in to the Q-flow site and access the task form. There, they will be able to see the process data, select the task handler and indicate that it has finished.
Handle the complaint: it is also a user task. This task is assigned to the user that the commercial manager selected in the “Select the complaint handler” task. The complaint handler will access the task form, see the process data and input the text that will be sent to the customer.
Notify the customer: it is a mail task, which sends an e-mail to the specified address.
End event: when a process reaches an end event, its execution ends. This process only has one end event, but it is possible for a process to have several of them.

Add the elements to the process design

To add the elements to the process design:

Right-click on the template version and select “Check Out” in the menu that will appear.

Fig. 326 Check out a version using the context menu

Right-click the template version again and this time select the “Process Design” option. This makes Q-flow open the process design. The design comes with a start event and an end event that are connected to each other (Fig. 327). Click on the connection and press the “Delete” key. This will disconnect the steps.

To add the “Select the complaint handler” task, select the icon that represents an activity in the toolbar (Fig. 328, “Button to add an activity”). Click on it and then click on the design. This will add the activity, although without specifying that it is a user task. Note that when the activity is added, a column with icons appears on the right (Fig. 328). If you select the icon that represents an activity (Fig. 328, “Button to add an adjacent activity”), you can quickly add another activity that will be automatically connected to the first one. Click that icon to add another activity (this activity will be the “Handle the complaint” task).

Finally, repeat the operation to add the activity that will be used to notify the customer. The design will look similar to the one in Fig. 329.

Fig. 328 Design with a recently added activity

Fig. 329 The design after adding three activities to it

Select the connection tool in the toolbar (Fig. 330). Click the start event and then the first activity. This will connect both elements, indicating that the process must go from the start event to that activity.

Fig. 331 Create a connection from a step

Connect the last activity to the end event as well, as Fig. 333 shows.

Diseño con todo conectado — Fig. 333 The design, once the start event has been connected with the first activity, and the last activity with the end event.

The activities do not have a type yet: it is unknown whether they are user tasks, service tasks, etc. The first activity must be a user task. To specify this, select it and click the green icon with two white arrows that point in opposite directions (Fig. 334, “Button to specify the element subtype”). When you do this, a menu will sppear to choose the activity type. Select “User task”. Repeat this procedure for the second activity. For the third one, do the same, but instead of selecting “User task”, select “Mail task”.

Specifying an activity's type — Fig. 334 Specifying an activity’s type

The design already has the steps that are needed for the process. Now you still have to specify the elements’ names and properties. For example, the first user task should have a descriptive name such as “Select complaint handler”. You should also indicate: who is the first task addressed to? Which e-mail address is the message from the mail task sent to? To be able to specify that, first you must define the items that will be referenced by those properties: to indicate who to assign a task to, a template role is required; to save the e-mail address application data is required.

For more information on how to design a process, see the Designing a process version section.

Process roles

The process requires two roles:

Commercial manager: they are the one who selects the complaint handler. A user can be assigned to this role during the process definition (the identity of the commercial manager is known). This role is the addressee of the “Select the complaint handler” task.
Complaint handler: they are the one who receives the “Handle the complaint” task. A user is assigned to this role during the process execution: it is what the commercial manager does. This role is the addressee of the “Handle the complaint” task.

The roles will be added to the process template, not the version (see the Process template roles section for more information about roles). Thus, when new versions are created, those roles will be available in them and creating new ones will not be necessary (items that belong to a process template are available in their versions; items belonging to packages are available in all their descendant packages, as well as those descendants’ templates and versions).

To create the “Commercial manager” role:

Check out the template: find it in the packages tree and right-click it. In the the menu that appears, select “Check Out” (Fig. 335).

Fig. 335 Check out the “Complaints” template

Now right-click the template again. Select “Items” in the menu and then “Template roles”. This will make a screen with the roles list appear. The list will be empty (Fig. 336).

Click the button with the “+” symbol to add a role.
In the form that appears, write the role name (Fig. 337). Then, to assign a user to it, use your own user account. To do that, where it says “Start typing a user”, start writing the name of the account you are using to try Q-flow. If you do not know what that name is, check the name that appears in the top right corner (Fig. 338). That is the name you have to write. When you start typing, a list of users will appear. As you type, the list will show less elements (it shows elements whose names contain what you are writing). When you see the name of your user account, click it and your user account will be added as a role member.

“Commercial manager” role properties — Fig. 337 Role properties: the name “Commercial manager” was entered and the user “Viviana Luongo” is being assigned as a member

Fig. 338 Part of the screen on which the current user name is shown (“Viviana Luongo”, in this case)

Click the Save and add another button (Fig. 337, “Save and add another”). This will create the role (it will appear in the roles list) and will let you continue creating roles without closing the panel, but clearing the previous data.

Once the “Commercial manager” role has been created, create the “Complaint handler” role. It is not necessary to assign any members to it since the commercial manager will select a user to assign to that role in the “Select the complaint handler” task. In this case, since you do not need to create any other role, you may save it using the Save button. When you attempt to save the changes, Q-flow will warn you that the role has no members and will ask you if you wish to continue anyway. Answer affirmatively. The role list will look like in Fig. 339.

Process application data

The necessary appplication data is:

Customer name
E-mail address
Complaint text
Text to send to the customer

To create the “Customer name” application data:

Right click the process template, select “Items” and “Application data”.
Click the button with the “+” symbol to add an application datum.
Enter “Customer name” as name, “Text” as data type, which is the default option, and click the “Save and add another” button (identical to how it was done in the Role panel). This will create the datum and you will be able to add another.

Repeat step 3 for the rest of the application data (for the last one, use the Save button to save). For more information about application data, see the Application data section.

Fig. 340 Creation of the “Customer name” datum

The data list will look like in Fig. 341.

Design elements properties

Now you may configure each of the design’s elements.

Start event

To configure the start event, double-click it. The only thing you need to modify is the scope, which does not appear in the start event’s properties by default. To see it, click the Expand form icon (Fig. 342, “Expand form”). This expands the start event’s form to show more properties, which are organized in various sections. Click “Scope” to show the properties that are related to said form.

The scope lets you specify which data and roles are visible and modifiable in interactive activities, such as a user task or a start event. At the start of the process, it is desirable for the user to be able to assign values to the application data. Therefore, in the “Data scope” section, mark all of the application data by clicking on the box that appears next to the “Data name” column header. This marks all the application data (Fig. 343). After that, click the button corresponding to the “Editable” scope (the second from the left, Fig. 343).In the “Scope” column, all data will then have the “Editable” value. Click the Save button (✓) to save the changes. For more information about scope, go to the Data, roles, attachments and comments scope section.

Fig. 343 Assigning the “Editable” scope to all application data

“Select the complaint handler” task

Press the “E” key in the user task that comes immediately after the start event and write “Select the complaint handler” in the name (Fig. 344).

Next, click “Message” to expand the message properties section in the properties form (Fig. 345).

The first property in that section is the task subject (when e-mail is used to notify a user that they have a task, the e-mail message subject is the one entered in this property). Write “Select the handler for the complaint from ”. The “from” at the end (followed by a space) is because the customer’s name will be included in the subject. The customer’s name is not available when the process is being designed, but during its execution it will be in the “Customer name” application datum. It can be included in the subject using a tag (see Tags). A tag lets you take the value of some process item and use it in a property of some element.

The properties for which tags can be used are indicated with an icon that represents a tag (Fig. 346).

To specify a tag, after the text you wrote in the subject, write the “#” symbol, which means that a tag will be used. Q-flow shows the items that can be selected as a tag (Fig. 346).

Fig. 346 Inserting a tag in the subject

Select the “Customer name” application datum from the list. In that moment, Q-flow adds the tag to the subject. The tag is represented by a text with special symbols that indicate that said text is a tag, a text that indicates what item type is being used (in this case, “Data”, which means application data) and the item name (“Customer name”). See Fig. 347.

Under the task subject the possible responses for the task must be entered. When a user is assigned a task, they must log in to the Q-flow site to respond to it. Some tasks have various possible responses. For example, a process task could be “Do you approve of this expenditure?” and that task would have two responses, “Approve“ and “Reject”. In this case, only an answer that indicates that the complaint handler has been selected is necessary and the process can continue.

To add a response, click the button with the “+” symbol that appears underneath “Responses”. This makes Q-flow add a response to the response list, which was empty. The added response has “Response 1” as its default text (Fig. 348).

Click on “Response 1”. This will let you modify the text, as Fig. 349 shows.

Write “Finished” and press the “Enter” key. In the response row there is a Type column whose selected option is “Final”. Do not change it; this indicates that, once a response is selected, the process must continue and go to the next element in the design (the different task response types are explained in more detail in the Message section inside User task).

Afterwards, the task addressee must be selected. The addressee is the role to which the task will be assigned (through the role, the task is assigned to users: the role members). In this case, the addressee is the “Commercial manager” role. To select it, in “Addressees”, write “Commercial manager”. As you type it, a list will appear in which that role will be available to select. Select it. During the process execution, Q-flow will send the task to the user account that was specified as a member of that role (Fig. 351).

Finally, the data and roles scope has to be specified. To do that, the form must be expanded, the same way it was done with the start event. In this case, the scope must be modified so that the “Complaint handler” role is modifiable and required. Additionally, the user that performs this task should see the complaint data, so in the data scope it should be specified that application data be visible but not modifiable (“Read only” scope). After this, select, in “Roles scope”, the “Complaint handler” role and click on the “Required” button (Fig. 352).

In “Data scope”, select all the data and click the “Read only” button (Fig. 353).

“Handle the complaint” task

Type “Handle the complaint” as the step name.

In the subject type “Handle the complaint and write the text to send to the customer” and then use the application datum “Customer name” as a tag, just as you did with the other user task.

The addressee is the “Complaint handler” role, which for the moment does not have any members, but when the process is being executed, it will have the user that the commercial manager selected in the previous task as a member.

Afterwards, add a response as final so the user can respond to the form. For example, with “Resolved” as its key and text.

The message configuration should look like Fig. 354 shows.

Fig. 354 Message form in the “Handle the complaint” task

In this task, no role must be visible or modifiable, but all data should be visible and in particular the “Text to send to the customer” datum must be modifiable. Therefore, this datum must have the “Editable” scope, and the others, the “Read only” scope.

Fig. 355 Data scope in the “Handle the complaint” task

Mail task

Where the mail task name goes, type “Notify the customer”.

You also have to specify that the addressee should be taken from the “E-mail address” application datum. This is done with a tag as well, but in this case you must select the “E-mail address” application datum. Then, a subject for the message must be written, type “Complaint resolution” (Fig. 356).

Fig. 356 Mail task configuration until now

Finally, you have to specify that the message body must be what was entered in the “Text to send to the customer” datum by the complaint handler. This is done using a tag, but in this case, to open the list of items that can be used as tags, you must click the text area and press Control + Space (Fig. 357). This is how properties that use a text area work (for example, the code in a script task).

Lista de ítems que aparece al pulsar Control+Espacio — Fig. 357 If you select a text area, when you press Control+Space a list of items that can be added as a tag will appear

When you select the tag, it will appear as in Fig. 358.

Check in template and version

Once the process has been defined, check in the template and the process version. To check in either of those tree items, right-click them and, in the context menu, select “Check In” (Fig. 359).

Set production version

Finally, you must indicate that version 1.0 (the only one for now) is the production version. Otherwise, when you log in to the Q-flow website to start a process, you will not find the template you just designed. To do that, find the version in the packages tree, right-click it and select, in the menu, “Set production version” (Fig. 360).

Start a process

To start a process and be able to run tests, use the Q-flow site (Fig. 361). Consult the Web site manual for instructions.

Second version of complaints process

The previous process has the defect that the commercial manager always has to intervene to select the complaint handler. If this decision could be automatized, at least for some cases, the process could be improved.

A possibility is to categorize the complaints and define a handler for each category. When a process is started, the starter sees a list of complaint categories and selects one. Once the process has been started, the task of handling the complaint is assigned to the handler corresponding to the selected category. An “Other” category can be included to consider complaints that do not adjust to any of the defined categories. Complaints in that category behave as before: the commercial manager decides who will handle them.

To make this change, a new datum is necessary for the category. A datum is associated to a domain, which indicates, among other things, how it is shown and what type of data it contains. A domain can also define a set of possible values for the datum (to learn more about domains, see the Domains section). For this reason, we will create a new domain that will indicate that your data, rather than appear as a text box when it is editable, must appear as a drop down list (“Combo box”). The domain will also define the categories that will appear in the list. In the example, the categories will be three: “Defective product”, “Poor attention” and “Other”. In the Q-flow website, it could appear as Fig. 362 shows.

For each category there will be a user task directed to the handler of that category. To decide which of them the process will go to, an exclusive gateway will be used, which is connected with several elements and associates a condition to each of them. When the process reaches an exclusive gateway, it evaluates the conditions and continues its path by going to the element that is associated to the fulfilled condition. In this case, the exclusive gateway will be connected to each of the user tasks corresponding to each category. Therefore, if the category is “Defective product” or “Poor attention”, the process will continue its path through the task with its respective name. If it is “Other”, it will go to the same task as in the previous version (“Select the complaint handler”).

The new version’s design will look like in Fig. 363. To continue, a description of how to design the new version is provided.

New version creation

Check out the process template.
Right-click it and, in the context menu, click “Add version” (Fig. 364).

Select, in “Template version pattern”, the “1.0” version (this will create a new version as a copy of the selected one) and enter “2.0” as the version name (Fig. 365).

Creating the new domain

To create the list type domain “Complaint category”:

Check out the process template.
Right-click the template and in the menu select “Items” and then “Data domains” (Fig. 366).

Click the Add button. In the properties form, aside from entering “Complaint category” in the name, select the “Combo box” control type (a drop down list) and in “Data source”, select “List”. Click the gear icon next to it so that Q-flow will show the list’s properties.

Click the Add button. This will add a row. Click “Item 1” in the “Text” column and type “Defective product”. This value will be automatically copied in the “Key” column (Fig. 368).
Repeat the procedure to add two more rows: “Poor attention” and “Other”. After that, save the changes.

Save the changes in the list using the “Save” button.
Save the changes in the domain using the “Save” button.

New datum creation

Create an application datum, name it “Category” and where it says “Data domain” select “Complaint category”.

Process design modification

To modify the design:

Add an exclusive gateway. To do that, it is necessary to create space between the Start event and the user task. Use the create/delete space tool like Fig. 370 shows.

Add two tasks.
Connect the exclusive gateway with the two new tasks.

Fig. 371 Add two tasks after the exclusive gateway

Connect the two new tasks with the “Notify the customer” task.
Rename the new elements so they will look like the ones in Fig. 372.

Fig. 372 Finished Complaints 2.0 process design

Modify the start event’s scope so that the “Category” datum has a “Required” scope. Remember to check the “Show missing scope data” box to be able to see it, since by default Q-flow will only show you data with editable scope.

Fig. 373 Edited scope to include the “Category” datum

Creating two new roles

Create two new roles: “Products handler” and “Attention handler”. Assign your user account as a member (this is only for testing: naturally, in a real case, each one would have a different member).

The roles list should look like in Fig. 374.

Fig. 374 Complaints 2.0 process roles list

New steps configuration

Configure the “Handle poor attention” task so the addressee is the “Attention handler” role. Do the same with the “Handle defective product” task so the addressee is the “Products handler” role (Fig. 375).

Fig. 375 “Handle poor attention” and “Handle defective product”

Open the exclusive gateway’s properties form.
Expand the form by clicking on the Expand form button and open the “Conditions” section. It will be divided in three subsections, one for each of the tasks to which the gateway is connected (Fig. 376).

Exclusive gateway's Advanced section — Fig. 376 Exclusive gateway’s Advanced section

In the subsection corresponding to the “Handle defective product” task, click “+Condition”. This adds an empty condition (Fig. 377).

Where it says “Start typing”, write “Category”. When a list with the “Category” application datum appears, select it (Fig. 378).

In the text box that appears on the right side of the condition, next to the “equals” operator, type “Defective product” (Fig. 379).

Do the same in the subsection corresponding to “Handle poor attention”, but typing “Poor attention“ instead of “Defective product” in the condition. Fig. 380 shows what the exclusive gateway’s configuration will look like.

Fig. 380 Exclusive gateway configuration

Click the connection that links the gateway to the “Select the complaint handler” task. Click the green icon that shows two white arrows and select “Default connection” (Fig. 381). This way, if none of the other conditions are met, this connection will be used.

Save the changes (using the button on the toolbar to the right).

When you are done with the changes, check in the process template and set the new version as the production one (see Set production version).

Other possible improvements

In this section, other improvements that could be made to the process are described and it is explained, without going into detail, how they would be implemented, with the objective of showing how other Q-flow features that have not been mentioned are used.

Using a web service and your own database

Something fairly common when using Q-flow is to use a database to store process data. The data that has to be available in application data, such as data used for tags or gateway conditions is left in application data, but other data is moved to a database to avoid overloading Q-flow’s database or other motives related to the system architecture.

In general, a web service (SOAP or REST) is used to access the database and provide Q-flow with the functions that allow the user to obtain and save data in it, as well as implement operations related to the businesss logic. For Q-flow to be able to access that web service, an Integration (see Integrations) is used. An integration is defined in a similar manner to how application data, domains and roles are defined. You must also specify how to connect to a component (in this case, a web service) and which operation to use (a web service method). It also defines how to exchange data between Q-flow and the web service (application data is associated to the parameters of the operation that is invoked and to the result that said operation returns).

Data for the connection to the web service (or to other components, in the case of integrations with components of other types) is usually stored in application parameters, which are also defined in a similar manner to application data, roles and domains (see Application parameters).

Process data manipulation in own code

Another common practice is to develop code that obtains and modifies process data. This allows you to handle some aspects of the process in a more flexible way, so as to facilitate future changes. For instance, in the second version of this process, a user task is used for each complaint category. But this would not be practical if there were a lot of complaint categories. It would also be impractical if the categories were expected to change, since every time a category was added, the process design would have to be modified, probably creating a new version.

It is more practical to use a single user task and a single role, instead of a user task and a role per category. To do that, the “Complaint handler” role can be used, since it does not have a predefined member and can be assigned during the process execution, as was done in the first version. The difference is that it must be done automatically and not manually as in that version. For that, a script task may be used.

In a script task, code that accesses the process data can be written. It is possible to write code that reads the value of an application datum and assigns a member to a role. In this case, you would write code that reads the value of the “Category” datum and, according to its value, the complaint handler would be selected, assigning them as a member of the “Complaint handler” role.

This code may be written in the script task’s properties (see Script task), but it can also be written in an ad-hoc integration (see Integrations).

The functions that Q-flow provides to interact with your process data are described in detail in the Scripting interface manual.

Work queues

Another common practice is to use work queues as role members instead of user accounts. Instead of assigning the tasks to particular users, they are assigned to work queues (“Shipping department”). A work queue is associated to permissions that indicate who can take tasks assigned to it. For example, only the users from the shipping department can take tasks from the “Shipping department” queue. That way, when a task is assigned to that work queue, everyone who can take tasks from that queue is notified and any of them can take the task for themselves and take care of it. The concept of a work queue is explained in the Organizational Model Manager manual. That manual also explains how to create work queues.

User interface operation

This section explains how to use the business process web designer.

General user interface description

Fig. 382 shows the web designer’s main screen.

The main interface elements are:

Upper menu: it has options to go to the home, close the session and access the settings screen
Sidebar: it allows you to perform operations with packages, process templates, versions and find elements.
Packages tree: it allows you to see the hierarchical structure of process templates, packages and versions, as well as select the element on which you wish to operate.
Edit zone: it shows the elements that are being worked on and it is where the version diagrams are designed.

Web designer's main screen — Fig. 382 Web designer’s main screen

Upper menu

Fig. 383 shows the upper menu. Next, each of the functions available through it are explained.

If you click on “Information”, you will see links to the product news and to this manual, as well as the version of the product you are using.

When you open the “Current user” option, the system displays the user’s preferred time zone. This time zone is used in all of Q-flow’s dates and times for the current user. The preference is shared by all the product tools, so its modification in one of them affects the others.

To edit the time zone, you must select the “Current user” option from the menu. This will open a right panel with the list of available time zones. After the time zone has been selected, when you save the panel, the page will be automatically refreshed so that the change takes effect. If you have more open windows with some of Q-flow’s tools, these have to be refreshed manually so that the change takes effect.

The settings function has the option for the tool’s permissions management, which is explained in the Organizational Web Model manual.

Sidebar

The sidebar allows you to show or hide the packages tree, access common operations that are also available through the tree elements’ context menu (these operations are explained in the section about the packages tree) and search for application elements.

The options that require clarification are explained:

Search

To open the element search panel, you can access it by pressing the magnifying glass icon in the sidebar or pressing “Ctrl + Shift + F”.

Quick search

A quick search consists of typing part of the name of the element you are searching for in the text box. The elements that can be found in this mode are those belonging to the tree, that is, the whole solution’s packages, templates and versions, as well as the roles, domains and data located in the package that is selected in the tree or one of its parents. Q-flow filters the elements that are shown in the edit zone, hiding those that do not contain the entered text (Fig. 386).

Advanced search

The advanced search (Fig. 387) is accessed by clicking on the “Advanced search” checkbox. It allows you to easily find items that are used in the processes’ specifications (for example, application data). This is especially useful when you remember part of an element’s name, but not in which package, process template or version it is located. The search screen allows you to enter the following data:

Name: name of the element that is being searched for.
Type: you will be able to filter which types of elements you wish to search for (packages, steps, application data, process template roles, data domains, custom forms, integrations, event handlers, worklets, validations, bots and/or application parameters). Additionally, it is possible to select two or more types, allowing you to obtain the different required data in a single search.
Look in: it allows you to specify in which packages, process templates or versions to search (the options mention “packages”, but process templates and versions are also considered packages for this purpose). Restricting the packages in which to search reduces the search time. Options are:
- Current package and parents: it searches the current package and the ones above it in the hierarchy. It does not search the packages contained in the current one.
- Current package: it searches the current package and its descendants.
- Entire solution: it searches in the entire hierarchy among the elements that already existed the last time it was checked in, not the new ones that were added in the case it is checked out.

Difference in versions

Custom forms and worklets are not available in the advanced search in the Cloud version.

Once you click the search button, the results will appear in descending order by item name in the lower part of the screen and you will be able to access the listing or process design to which the element belongs by clicking “Go to item” (→). In the case that you want to access a package, process or process version, a button will be enabled that will allow you to see the element in the tree (Fig. 386).

Packages tree

The packages tree is similar to a hard drive’s folder structure, which may contain subpackages (child packages), which may in turn contain subpackages, in the same way that a file system has a root folder with subfolders, which in turn may contain subfolders.

Additionally, a package can contain process templates and these can contain versions. All these elements are shown in the packages tree and can contain process items (for example, application data), which are not shown in the tree. However, the options to see them, create them and modify them are indeed accessible from the packages tree.

A package or template can appear open (their children are shown) or closed (they are not shown) (Fig. 388). To open a package or template, click the triangle to its left, which indicates if it is open or closed.

If you double click a tree element, its properties form is opened in a panel (the tree elements’ properties are described in Working with packages, process templates and versions). On another note, tabs are created when, via an element’s context menu, one of its item lists is accessed (for example, a package’s application data list; see Items lists). Several tabs can be open simultaneously, as you can see in Fig. 389.

Fig. 389 Tabs. The open one shows application data

A tab can be closed by clicking the cross that appears when the mouse cursor hovers over it (Fig. 390).

For each element, there are several operations available which are accessed through a context menu that appears when you right-click it. The options that can appear in the context menu are the following:

Items: when you click this option, a submenu to select the type of items that you wish to see or modify appears. When the item type is selected, Q-flow opens a screen that shows the items of the selected type belonging to the package. In that screen, the existing items can be seen and modified, aside from creating new ones. Items lists are described in general in Items lists. Each item type and its properties are described in detail in Process items.
Change control options: change control options prevent an element from being modified by more than one user simultaneously. This prevents modifications losses that would occur if this control was not done.
- Check Out: it unblocks the element for the user who checked it out, allowing them to modify it, and blocks it for everyone else.
- Check Out compatible: it unblocks a process template or version for the user who checked it out, but it does not allow them to make some changes that might affect processes that are being executed (for instance, the user is not allowed to delete steps).
- Check In: it saves the changes that a user made to an element they had checked out before and it frees the element so that another user may modify it.
- Undo Check Out: it frees the element so that another user can modify it, but without saving the changes (changes are lost).
- Check In and continue editing: it saved the changes that a user made to an element they had checked out before, but keeps it checked out (it is like checking it in and immediately checking it out). This lets others see the changes that the user made to the element without the user having to forfeit keeping it checked out to be able to continue modifying it.
Set production version: only available for versions that are not production ones, this options allows you to mark the selected version as the production version (the one that is used to start new flows). If there was another production version in the same template, that one is no longer the production one (there can only be one production version for a template).
Unset production version: only available for production versions, this option allows you to mark the selected version as no longer being the production one. Note that, if you unset a production version, you will not be able to start flows for the template to which it belongs anymore, since there will not be any production versions.
Add sub package: it allows you to add a package inside the selected one (this option is only available for packages). When this option is selected, Q-flow shows a form to enter the new package’s name and description in the edit zone.
Add process template: it allows you to add a process template inside the selected package (this option is only available for packages).
Delete: it allows you to delete the selected element. This option is only available if the selected element does not contain other elements. For example, if a package contains other packages or if it contains process templates, it is not possible to delete it without previously deleting its contents.
Refresh: it updates the selected element and its descendants on the screen to reflect the last changes occurred. For instance, if a user recently added a package and another user does not see it because it is too new, when they refresh the container package, the tree will reflect the change and show the new package.
Stages: it shows a screen with the defined stages for the selected template and it allows you to modify them. (For more details, check the Stages section.)
Add process version: it adds a new version to a template.
Process design: it opens a version’s process design (diagram).
History: it shows the history of actions performed on the element (who did what and when). The time zone in which the dates are shown is also indicated.
Properties: it shows the element’s properties form (it is like double clicking it in the case of packages and templates).
Process forms: it opens a submenu with two options: “Flow edit form” and “Flow form”. These options allow you to open those forms’ properties windows to:
- Define the data, roles, attachments and comments scope (see Data, roles, attachments and comments scope).
- Define custom forms (see Custom forms).
- Associate validations to the forms (see Validations).
- Associate event handlers to flows (see Event handlers).
Export: it exports the element to an XML file, so that it can be imported somewhere else Q-flow is installed. There is more information in the Exporting packages, templates and versions section.
Import: it imports an XML file that contains packages or templates definitions. There is more information in the Importing packages, templates and versions section.

Exporting packages, templates and versions

To export a package, template or version, do the following:

Right-click the package, template or version in the solutions explorer. Q-flow will show a context menu.
In the context menu, select the “Export” option. Q-flow will show you a window like the one in Fig. 392.
In the case of versions, select the format in which you wish to export it. The options are Q-flow’s native format and BPMN XML format. The native format keeps all the process’ elements, while the BPMN XML format only exports the design.
For packages and templates, if you do not wish to export all the package’s descendants, uncheck the “Export child packages recursively” option.
Click “Export”.

Importing packages, templates and versions

To import a file created by a previous export, do the following:

Select the package or template where you wish to import the file’s content and right-click it.
In the context menu, select “Import”. Q-flow will show a window like the one in Fig. 393.
Select the file to import’s format. The supported formats are Q-flow’s native one and BPMN XML.
Select the file to import and mark the options you desire:
1. Update existing application parameters: if this option is checked, the application parameters’ values will be substituted by the values of the imported application parameters. Otherwise, this will not happen. This is useful because the same parameters can have different values in different environments.
2. Fix missing references: this option indicates to Q-flow that it should correct references to elements that do not exist in the database in which the import is being done. For instance, if a user that a role references is not found, Q-flow will ignore that user in the import. If this option is not checked, when Q-flow finds a missing reference, it will interrupt the import and leave the database in the same state as it was previously.
Click “Import”. If the package, template or version contained in the file already exists, Q-flow will let you opt between updating the existing package, template or version with the imported data or creating a new one. This allows you to update processes that have been imported from development environments.

Edit zone

The edit zone shows the forms in which the selected item’s properties and items lists are shown. It is in the edit zone that the properties of items that comprise Q-flow’s processes are modified and it is also where processes are designed.

Home page

When a user logs in to the process web designer, or when they click the home icon in the upper menu, Q-flow shows them the home page. The edit zone, in this case, is similar to what is shown in Fig. 394.

The “Create template” option allows you to create a process template, if in the packages tree a package is selected, or to create a version, in any other case. The template or version is created inside the element that is selected in the tree at the moment of creation (unless a template version is selected, in which case another version of that template is created). The following section has more details about the creation of these elements.

The production templates indicator shows how many templates have a production version.

The “Recent tabs” section shows the most recent tabs grouped by package, template or version. The icons correspond to the tab types (application data, roles, etc.) Click the icon to open the tab.

Working with packages, process templates and versions

In this section how to create and modify packages, process templates and versions is explained. However, how to design a version diagram is not explained. For this, check the Designing a process version section.

Creating a package

To create a package:

In the packages tree, right-click the package inside which you wish to create a new package. This makes Q-flow show the context menu for the selected package.
Select the “Add sub package” option. This makes Q-flow show a form like in Fig. 396, in which it is indicated in what package the new package will be added and in which there are two text boxes to enter the new package’s name and description.
Enter the new package’s name and description and click the Save button.

Creating a process template

To create a process template, do the following:

In the packages tree, right-click the package inside which you wish to create a template. This makes Q-flow show the context menu for the selected package.
Select the “Add template” option. This makes Q-flow show a form like in Fig. 397, in which it is indicated in which package the new template will be added and in which there are two text boxes to enter the template’s name and description. You must also select the template pattern (in Fig. 397 the only option that appears is “Empty BPMN template”).
Type the new template’s name and description and click the Save button.

Creating a version

To create a version, do the following:

In the packages tree, right-click the process template in which you wish to create the version. This makes Q-flow show the context menu for the selected template.
Select the “Add process version” option. This makes Q-flow show a form like the one in Fig. 398, in which it is indicated in which template the new version will be added. There are also two text boxes to enter the new version’s name and description. If the selected template already has versions, in the “Template version pattern” field you can select one of them for Q-flow to copy. For example, in Fig. 399 versions 1.0, 1.1 o 1.2 can be selected. If the selected version has a name that follows Q-flow’s standard (“1.0”, “1.1”, etc.), Q-flow will automatically enter the name that, according to that standard, would belong to the next version (if the selected version is “1.1”, Q-flow will write “1.2” in the name text box). You can also create a version without copying any other (“Template version pattern”). In this case, the new version will be created with a start event and an end event.
Enter the new version’s name (if it is necessary) and description and click the Save button.

Modifying the properties of a package, process template or version

Packages, process templates and versions have additional properties apart from the ones that are shown when they are being created (name and description). To modify the properties of a package, template or version, find it in the packages tree, right-click it and select the “Properties” option. This makes Q-flow show the selected element’s edit form (Fig. 400). In the case of packages and templates you can simply double click the element.

This edit form has two groups:

General: it shows and allows you to modify the name and description, aside from the following data (all dates and times are shown in the user’s preferred time zone):
- Date and time in which the element was created and who created it.
- Date and time of the last modification made to the element and who made it.
- Whether the element is checked out or not. If it is checked out, the date and time in which it was checked out is indicated, as well as who has it checked out.
- If the element is a process template, the production version is shown and you are allowed to change it.
- If the element is a version, it is shown if it is a draft or not. A draft is a version that is not valid to be set as a production one (it would produce errors when executed), but which can be saved. Once a version is set as the production one, it is not possible for it to be a draft again.
Advanced: the advanced subform’s properties are:
- Common to packages, process templates and versions:
  - Owner: it indicates which user is the element’s owner. The element’s owner is a system user. The owner can be removed by clicking the cross that appears in the rectangle containing their name, so the element no longer has an owner. To specify an owner, start typing their name and when the username of the person who you wish to assign to the element appears, select it.
  - Notify changes in content: if this box is checked, each time the element is modified, Q-flow sends a notification to its owner.
- Templates also have the following advanced property:
  - Notify flow in error: if this box is checked, each time a flow based on that template has an error, a notification is sent to the owner.

Manage package, process template and versions permissions

To manage the permissions of a package, template or version, find it in the packages tree, right-click it and select the “Manage package settings” option (Fig. 401). This makes Q-flow show a form like the one in Fig. 402. That form shows a table with all the defined permissions. For each one it is shown which role the permission is for, the role description, a list of allowed actions and a list of denied actions. The list can be filtered as shown in Items lists and it can also be modified by adding, removing and modifying elements.

To add a permission:

Click the Add button. This makes Q-flow show a role search bar (Fig. 403).
Select the permission recipient. To do that, type part of their name in the search bar (where it says “Start typing a role”) and when you see it in the list that appears, select it. A permission’s recipient can be an element of any of these types:
1. Security role (do not confuse it with a process role; process roles are used to assign tasks in a process and cannot be selected as permissions recipients)
2. Node
3. Group
4. Work queue
5. User

For each of the permissions shown in that window, check if it is allowed or denied and whether it is inheritable. If a user has an inheritable permission on a package or process template, they have the same permission on the descendants of that package or template, unless in some descendant package it is explicitly denied.

The permissions that can be assigned are:

View item: it allows you to view the package and the elements defined in it, such as application data, process roles, etc.
Edit item: it allows you to modify the package and the elements defined in it, such as application data, process roles, etc.
Create item: it allows you to create elements inside the element.
Delete item: it allows you to delete the element.
Audit: it allows you to view the element’s audit information.
Manage security: it allows you to add and modify permissions on the element for users, groups or roles.

A user has permission to perform an action if the following requirements are simultaneously met:

The user is associated to some security role, group, node or work queue that has permissions to perform that action or their own user account has that permission directly.
The user is not associated to any security role, group, node or work queue to whom that permission was denied or their own user account has been denied that permission.

It can also happen that the user does not meet these conditions, but is the substitute of one that does. In that case they would also have permission. For more details on permissions management in Q-flow, check the Organizational Model Manager manual, where it is also explained how to associate users with security roles, nodes, groups and work queues.

Items lists

A process design also involves defining items that the process uses. For example, to assign tasks to people, roles are needed. To handle data, some of which may be necessary to define the process flow, application data is nedeed. To access external systems’ functions, integrations are necessary and it is recommended to use application parameters that contain information to access those systems. This section explains how to use the business process web designer to create, modify and delete items. It does not explain what each item type is for or what properties it has. To find information on this topic, check the Process items section.

Fig. 405 shows the application data list, which is a typical items list. The items list is shown as a table with several columns, the first of which contains boxes that allow you to select one or more items (if the header box is checked, all items are selected).

In the upper left section are icons corresponding to the following operations:

Add: when you click this icon, Q-flow shows the item’s basic properties form. To create an item, fill its properties and click the Save button. If you click the button with three vertically placed buttons, the form expands and in some cases more properties are shown (Fig. 406). If you click that button again, the form returns to its original format. A detailed description of each item type’s properties can be found in Process items.
Modify: when you select an item and click this icon, Q-flow shows the item’s basic properties form (Fig. 406), which is the same form as the one used to create an item.

Formulario normal y formulario expandido — Fig. 406 Normal form and expanded form: the expanded one has an additional properties section, “Advanced”.

Cut: it allows you to cut elements in order to paste them in another package: when they are pasted, those elements are deleted from the original package. IMPORTANT: if you cut an element and paste it in a tree branch that is different from its origin one, inconsistencies might be created, because other elements from the origin branch that used the element will no longer have access to it. Additionally, it is a good practice to check in both packages, the origin one and the destination one, to save the changes.
Copy: it allows you to copy elements to paste them in the same package or another one. When they are pasted in the same package, the new elements will be renamed, adding “_1” or changing “_X₁” for “_(X₁ + 1)” if the name ended in “_X₁”, with “X₁” being an integer number.
Paste: it pastes the cut or copied elements.
Delete: when one or more elements are selected and you click this icon, the selected elements are deleted, confirming it previously.

These icons are enabled or disabled according to which elements are selected. For instance, the “Modify” icon is only enabled if there is exactly one selected item, because if there are no selected items, there is no item to which the modification operation can be applied, while if there is more than one, it is impossible to determine to which of them the operation applies. Additionally, if the package is checked in, the only one of these actions that is possible is “Copy”.

Also in the upper section, but towards the right, there is a text box that allows you to filter the elements that are shown in the list. When you write text in that box, the list will hide those elements that do not contain the written text in any of the columns.

Finally, to the right of that text box, there is a button that allows you to specify which columns you wish to see (Fig. 407).

Fig. 407 Configuring the visible columns in listings

Stages

Q-flow allows you to define stages for a process template. A stage defines an “Expected time” and a “Maximum time”, which determine two deadlines for the stage’s end. Both for the expected time and the maximum time, a list of process template roles can be specified. These roles will be notified if, once the specified time has passed, the stage has not finished yet. The expected time is an estimate of how long the stage should last in a normal case. The maximum time indicates a more important deadline than the expected time: the process is not supposed to remain in the same stage for longer than it is indicated in the maximum time.

When a process is divided in stages, it has more tracking options in the web site.

Stages are linked to process sections through the start event and intermediate events.

To access the form that allows you to define stages, open the template’s context menu by right-clicking it in the packages tree and select the “Stages” option (Fig. 408).

The stages definition form behaves in the same way as the items lists. To be able to specify the expected time and the maximum time, you must expand the form so that the sections containing those properties may appear (Fig. 409). The expected time and maximum time are defined in the same way as other deadlines (it is explained in Timing).

The “Use calendar” option allows you to select a calendar to be used when expirations are calculated. If this option is not checked, expirations will be calculated without considering weekends, holidays, etc (Fig. 410).

Designing a process version

To modify a version’s design, you must check it out first. To do that, right-click the version and select “Check Out” in the context menu.

Once the version has been checked out, right-click it again and select “Process design” or simply double click the version. This makes Q-flow show the process designer in the edit zone (Fig. 411).

In the designer’s left section there is a toolbox, which is divided in two parts. The first one shows design tools, while the second one has elements that can be added to the diagram. In the designer’s right section, there is a series of buttons whose objective is to facilitate the viewing of the diagram, apart from allowing you to save it and export it. All these options are explained next.

Design tools

Fig. 412 shows the design tools.

Activate the hand tool: if you select this tool and keep the mouse button clicked on the design surface while you move the mouse, you will move the design surface. For example, if there is no more available free space on the surface and you wish to add something under the elements that are already on it, you can use the tool and, keeping the button clicked, move the mouse upwards. This will move the design surface upwards, as though the surface were a sheet of paper and you pressed it with your hand and pushed it up, so the paper’s upper half was no longer visible and the lower half was visible.
Activate the lasso tool: with this tool you can draw a rectangle on the design surface. The elements that remain inside the rectangle and their connections will be selected.
Activate the create/remove space tool: with this tool you can create space between two parts in the diagram, by keeping the mouse button pressed down and moving the mouse to the right. The effect is as if all the elements that are on the mouse’s right were pushed to that side, generating space between their new positions and the ones they occupied before. In a similar way, you can do the same but moving the mouse to the left, which has the opposite effect: the middle space is removed.
Activate the global connect tool: this tool allows you to connect two elements, although it is not the only way to do this.

Elements that can be added to the diagram

Fig. 413 shows the elements that can be added to the diagram. The ones that are events, gateways and activities are described in more detail in the Process design elements section.

Fig. 413 Tools to add elements to the design

Start event: it marks where the process execution starts.
Intermediate event: it allows you to mark a milestone in the process execution (for example, that a phase of the process is over). It can also be attached to an activity, in which case it is an intermediate boundary event.
End event: it marks where the process execution ends: when a process reaches an end event, it finishes its execution.
Gateway: it allows you to control the process flow. Exclusive gateways allow you to choose a path between several possible ones in a process. Inclusive gateways allow you to create several parallel paths.
Activity: it represents an action or task. It can be a task performed by a person, but it can also be an action automatically executed by some system component.
Subprocess: it groups several elements.
Data object reference: it is a decorative element that represents data that is used in some activity. It is connected to another element, typically an activity, with a dotted arrow.
Data store reference: the same as a data object, but it represents a data store (for example, a database).
Pool: it allows you to create pools to organize the process, grouping related elements in the same level.
Group: it allows you to create groups, to better view a series of related steps. This element is purely a visual one, since it does not influence the execution of the group’s steps in any way.

Graph viewing tools

Fig. 414 shows the buttons that appear on the designer’s right.

Full screen: it allows you to enter full screen mode, in which the edit zone will be expanded to your screen’s maximum available space. This will allow you to focus on the diagram’s creation and configuration without visual interruptions. To exit full screen mode, press the “Esc” key or click the Exit full screen buton (Fig. 415).
Reset zoom: it places the zoom level back where it initially was.
Zoom in: it increases zoom.
Zoom out: it decreases zoom.
Save temporarily: it saves the changes made in the diagram, which will be saved in the server, allowing you to access them at a different time to continue editing them. It is recommended to save changes every now and then, to avoid losing them in case of an unexpected error.
Export diagram: it allows you to export the created diagram design. When you click the button you will have the options to export the diagram image, by selecting the “Export diagram” option, or its bpmn file, by selecting the “Export document” action, as Fig. 416 shows.
Keyboard shortcuts: it shows a popup message that indicates all the available keyboard shortcuts, as Fig. 417 shows.

Process design

To design the process, the design tools are used to add elements and connect them. Each element has properties that can also be modified from the design.

Add an element

To add an element to the design, select it in the toolbox and drag it towards the design zone (you can also click it and then click the design zone). If you wish to add an element next to one that already exists, so it is connected to it, you may follow these steps:

Select an element.
Among the icons that appear on the right, select the one that corresponds to the type of the element that you wish to add next.
The new element also has icons to its right and you can repeat the operation with that element and the next ones.

In Fig. 419 you can see an example where, from a Start event, an activity is created.

Add boundary event

To add a boundary event to the design, select the intermediate event in the toolbox and drag it towards the design zone over one of the activities that allow it (Fig. 420). To see more information about boundary events and which activities allow them, see the Intermediate boundary events section.

Fig. 420 Create boundary event in user task

Change element subtype

Once you’ve added an element to the design, it may be necessary to change its subtype. This depends on the element type and whether it was added through the toolbox or through the icons that allow you to do so from the design.

If an activity is added, either from the toolbox or the design, the new activity does not have any subtype, so you must always select one. You cannot check in a design that contains an activity for which a subtype has not been selected.

To change an element’s subtype, click the subtype change icon (Fig. 418). Q-flow then shows the list of subtypes that can be assigned to the selected element, select the one you want and Q-flow will assign it to the element (Fig. 421).

Delete element

To delete an element, select it and press the “Delete” key or click the Delete icon that appears when you select the element (Fig. 418).

Connect elements

To connect two elements you can use the toolbox’s connection tool (DesignTools); you click the icon corresponding to the tool and then click the element from which you wish the connection to exit and, without letting go of the button, move the mouse to the element with which you wish to connect the first one.

You can also use the connection icon that appears when you select an element. In this case, the element from which the connection exits is the selected one and you proceed in the same way, moving the mouse with the button clicked until the cursor is on the element to which you wish to connect the selected element.

See or modify an element’s properties

If you click an element and press the E key, you will be able to edit the element’s name. On another note, if you click an element’s “See or modify properties” button, on the design zone’s right, a form will appear that shows its basic properties (generally, the step’s name and description) in the upper half and another form with advanced properties in the lower half. This other form does not appear expanded: to show it, click the icon with a + symbol. Each element type’s properties are explained in Process design elements.

Modifying a connection

A label can be added to a connection. You can also add break points to the connection, to turn it into a polygonal line.

To add a label to a connection, double click the connection. This makes Q-flow show a text box on the connection. Write the text that you wish for the label and press the “Enter” key (Fig. 422).

To change the connection’s shape, place the mouse cursor over the line. This makes Q-flow show a small circle. Click it and, while holding the mouse button down, move the mouse. This creates a break point in the place you clicked and when you move the mouse, the line that was straight before is broken in two, forming an angle in the break point (Fig. 423).

You can also move a connection’s segments in a horizontal or vertical way, as shown in Fig. 424.

Process items

To specify a process, aside from specifying a design, you can also define other items, which can be defined in a version, a template, the package where the template is or one of its ancestors. Where to define an item depends on design considerations and the structure organization. For example, an item that is specific to a version should be defined in a version, while they are usually defined in the template to share them between versions. On the other hand, in a package you define items that are common to several processes that belong to that package (for example, if many processes use the same web service, it is convenient to store that web service’s connection data in an application parameter belonging to a package that contains all those processes).

The item types that can be defined for a process are the following:

Application data: it is data that a process handles, especially data that is necessary for user notifications or to define which paths the process will follow (other data can be stored in external databases, with the help of integrations). The process elements have access to the application data: it can be used to specify the messages that are sent to the users (see Tags). It is also useful to change the flow direction: by using gateways (see Gateways), an application datum’s value can determine that the flow should follow one path instead of another, for instance.
Process template roles: if an activity is performed by a person, a role specifies who performs it or who can perform it. User tasks (see User task) are assigned to users through roles. They are not directly assigned to users.
Domains: they define application data types (“Number”, “Text”, “Date”) or, in more complex cases, they allow you to restrict the values that application data can have through arbitrary lists, results of queries to databases or other systems. A domain also defines how application data belonging to it is shown (for example, a date type domain is shown as a date picker).
Custom forms*: they define which web pages to use to show information to a user who performs one of the tasks defined in the process (the web page itself is not defined through the business process designer, but has to be built by a programmer; check the Custom Form Design manual for more information). Note that this option is not available in the Cloud version.
Integrations: they define how to access external systems (for instance, services offered by the company’s existing software) to send them data or to receive data from them (for example, so that a process may save data in one of those systems’ databases or to get data from it). Service tasks use integrations.
Event handlers: they are small programs that are executed when some predefined event occurs during a process’ execution.
Worklets*: they allow you to define a part of a process to use it in various different processes. Note that this option is not available in the Cloud version.
Validations: they are small programs that are developed to validate the data that is entered in flow forms.
Bots: like integrations, they specify interactions with external programs, with the difference that they are asynchronously executed to handle process data (the programs themselves are not defined in the process designer, but must be developed by a programmer).
Application parameters: they specify configuration information (database connections, service access specifications, passwords) to be used from the process.

How to work with the previously described items will now be explained. The purpose of this section is to describe these items’ properties and what they are used for. In the case of some item types’ specific aspects, how to use the user interface to define them is explained, but more general operations, common to all of them (for example, how to delete an item) are described in the Items lists section.

Difference in versions

Custom forms and worklets are not available in the Cloud version.

Application data

Application data is data that Q-flow handles in processes. Each datum is associated to a domain, which is in turn associated to a data type and and a control type that determines how the datum will be shown in process forms.

Application data properties

An application datum’s properties form has the following sections.

General: it contains the name, description, domain and other options that define the datum’s behavior.
Presentation: it contains properties that define aspects of how the datum will be shown in Q-flow’s website.
Advanced (it appears when the form is expanded): it allows you to define default values for the datum.
Dependencies (it appears when the datum has dependencies): it allows you to define what application data is used to provide values for the domain parameters.

A list of properties for each section, with explanations, will now be shown. It is mandatory to fill the properties that appear with an asterisk (this applies for all panels). This means that, if you do not complete them, you will not be able to create the element you wish and Q-flow will show you an error message when you attempt to save.

General

Name: it is recommended not to have repeated names between different pieces of data, given that it may cause errors.
Description
Domain: it is the data domain, which defines the type and control (the user interface element) used to show the data. The data domain can be any of the basic domains provided by Q-flow, but it can also be a user-created domain that is in the same package as the data, in the parent package or one of its ancestors (see Domains for instructions on domain creation). The basic domains are:
- Boolean: data of this type only has two possible values: true or false.
- Date: data of this type stores dates.
- Time: data of this type expresses time.
- Number: data of this type stores numbers.
- Text: data of this type stores text.
- Text area: data of this type stores multiple-line text.
- Money: data of this type can store decimal numbers.
- Date time: data of this type stores date and time.
- Document: data of this type stores a reference to process attachments.
Group: name of the group to which this datum will belong. To assign the datum to a group, write the group name. If the group already exists, while you type it will appear in a list underneath the name that you are typing and you will be able to select it. If it does not exist, it will be automatically created when you save the changes. Data in the same group is shown together in the data list when it is ordered by group, with the group name as a title (the list can be ordered by group by clicking the “Group” column header). This data is also shown together in the website’s forms.
Line block: it indicates the line block to which the datum belongs. The concept of a line block is explained in Line blocks. To be in a line, the datum must be a multi-valued one.
Allow multiple values: if this option is checked, the datum can have many values. It is a data set instead of a datum.

Presentation

Label: it is the name with which the datum will be shown in the website. The users will not see the datum’s name, but its label. The label can have symbols that are not allowed in the datum’s name.
Tab order: it indicates the order in which data will be shown in the website’s default forms. For example, the datum with tab order value 0 will be shown first; the one with value 1 will be shown second and so on. In the case of line block data, in which each datum corresponds to a table column, the datum with index 0 will occupy the first column, the one with index 1 the second one and so forth.
Tool tip: it is the text that is shown when, in the website, you view the help for the data group to which it belongs.

Advanced

Default values: a list with the values with which the datum will begin when a process is started. If the datum does not accept multiple values, only one default value can be defined.
New instances: if the datum accepts multiple values, when a user clicks on the website to add a value, the added value will be the one indicated in this property.

Dependencies

The Dependencies section only appears if the application datum is associated to a domain that accesses a database, web service or SharePoint list, and which has input or output parameters (check the Data sources section to see how those domains are configured).

If a domain has input parameters, you must specify from what application data the values will be taken that will be used in those input parameters. This is done in the “Dependencies” section: an application datum is associated to each of the domain’s input parameters.

The same thing happens with the output parameters: when a domain has output parameters, you must specify in what application data the ouput parameters’ values will be stored. This is also done in the “Dependencies” section, by associating an application datum to each output parameter.

The “Dependencies” section shows the domain’s parameters in a table with three columns. In the first column the parameter names are shown. In the second one you can see the type: input or output, indicated by an icon. In the third one you must choose, for each parameter, which application datum you wish to associate to it.

Fig. 428 shows the dependencies section for a datum from the “Customer” domain. This domain has an input parameter (“id”) and four output parameters (the rest). In the “Application data” column you can select, for each parameter, an application datum. In this case, the “Id” application datum was selected for the “id” parameter. This means that in order to obtain data, the domain will use the value of the “Id” application datum. For example, when a user logs in to Q-flow’s website to respond to a task, they will be able to enter a value for the “Id” datum and when they do, the domain will obtain data using the entered identifier.

The domain also has output parameters associated to application data. For example, the “name” parameter is associated to the “Name” application datum, so when the data is obtained, the value of the “name” parameter will be loaded in the “Name” datum.

Line blocks

When a data set belongs to a line block, that data is shown grouped under the same label in the website. For a datum to belong to a line block, it must accept multiple values.

In the website, a block’s data is shown as a table: each row in the table has as many values as there is data in the block. For example, the Employees row (Fig. 429) has three pieces of data. This block is shown in the website as a table with three columns, one for each piece of data: Address, Name and Phone number. See the website’s manual for details on how a user interacts with line blocks.

Scope: which data can be seen and modified in each interaction with a process

By default, users cannot see or modify application data when they start a process or during its execution. To allow a user to see or modify application data, configure its scope in the steps where you wish for it to be seen or modified. It is also possible to configure it in the flow’s form and edit form. The data scope also specifies, for the case of line block data and multi-valued data, if users can add or delete instances, as well as the limits to the number of instances than can exist. To obtain information about it, check the Data, roles, attachments and comments scope section.

Process template roles

Roles represent one or more users who will perform a certain function during a process’ execution. When a process template specifies that Q-flow must send a task to a user, it does not specify a concrete user, but a role. This makes maintaining process definitions easier.

For example, the “Approve expense” task can be asssigned to the “Finances manager” role. If John Doe is the finances manager, the role will have him as a member. If one day John Doe leaves the company and is substituted by Joseph Smith, it is not necessary to update all the user tasks in which John Doe intervenes due to being the finances manager: it is enough to modify the “Finances manager” role, removing John Doe and adding Joseph Smith as a member.

When Q-flow must send a message belonging to the task, it will verify which users are performing that role and send the message to those users.

Role properties

A role’s form has the following sections:

General
Restrictions (only available in the expanded form): it allows you to restrict who can be a role member.
Presentation: it allows you to specify how the role is shown in the website.

General

The “General” section has the following properties:

Name: it is recommended not to have repeated names among roles, given that it may cause errors.
Description
Role members: a list of users, roles, system roles, groups and work queues that perform the role. There can only be more than one member if the role allows multiple users. For a work queue or a group to be able to be a role member, it is also necessary for the role to allow multiple users. To add a member, start typing their name where it says “Start typing a user…” and when you see the role you want in the list that appears, select it.
Allow multiple users: if this option is checked, the role can have many members or members that have many users (for example, groups).
Apply rule: it applies a rule that determines who the role members are.
- Managed by: if this rule is applied, the role members are not the ones in the member list, but those users who are managed by them. For instance, user Smith is a manager of Brown and Jones. If Smith is in the list and the “Managed by” rule is applied, the role members will be Brown and Jones, not Smith. Additionally, the rule is applied at the time the role is used. This means that, if at the time the role is defined, Brown is managed by Smith, but shortly before a process sends a task to that role somebody changes their manager, they will not receive the task, because they will no longer be a member of the role.
- Manager of: if this rule is applied, the members will be the managers of the ones included in the member list.
- User with least tasks: if this rule is applied, Q-flow considers the user who performs the role to be the user with the least pending tasks at the time of using the role. For instance, let us suppose that the role has three users as members: Smith, Brown and Jones. A task is addressed to that role and uses the “User with least tasks” rule. If when the process reaches that task, Smith is, of the three users, the one with the least pending tasks, the task will be assigned to Smith.
- Direct manager of: if this rule is applied, Q-flow considers each direct manager of the members that have been added to be a user that fulfills that role. A direct manager of a user is the one assigned as manager in the organizational node where the user is located.
- User with least tasks for template: if this rule is applied, Q-flow considers the user who fulfills that role to be the user who has the least pending tasks belonging to flows from the same template. For example, let us suppose that the role has Smith, Brown and Jones as members. A task is addressed to that role, which uses the “User with least tasks for template” rule. The process template is called “Approvals”. If when the flow reaches the mentioned task, Smith is the one who has the least pending tasks in flows from the “Approvals” template of the three users, then the task will be assigned to Smith. Note that this rule is similar to “User with least tasks”, except that not all tasks that each user has pending in the system are counted, but only the ones from the process template to which the task belongs.

Restrictions

The “Restrictions” section (Fig. 431) allows you to restrict the users that can be selected for this role. If you wish to restrict who can perform that role to a user list, mark the “Restrict role member selection” option. Then you will be able to add restrictions to the list. Only users that comply with the specified rules will be able to perform the role. To add a restriction, click the button with the “+” symbol. This adds a row.

Click the “Name” column in the selected row to write the name of the member (user, group, node or work queue) you wish to restrict the role to. You can also select a rule by clicking the “Rule” column in the same row. The rule indicates how that member is used to define the restriction. For instance, the easiest possible restriction is to select a user as a member and use the “None” rule. In this case the restriction will indicate that the selected user can perform the role, but not other users (unless some other restriction indicates that they can). The possible rules are:

None: the selected role member can perform the role.
Manager of: the managers of the selected role member can perform the role.
Managed by: the users who are managed by the selected role member can perform the role.
Members of: the members of the selected role member can perform the role. For example, if the selected role member is a group, the rule references the members of that group. Naturally, this rule cannot be applied to a user.
Visualizers of: this rule is only valid if the role member is a work queue. It means that users who have visualization permissions in that work queue can perform the role.
Actuators of: this rule is only valid if the role member is a work queue. It means that users who have actuation permissions in that work queue can perform the role.

Presentation

Label: it is the name with which the role will be shown in the website. Users will not see the role name, but the label. The label can have symbols that are not allowed in the role name.
Tab order: it indicates the order in which roles will be shown. For example, the role with value 0 will be shown first; the one with value 1 will be shown second and so forth.
Suggestion: it is the text that is shown when, in the website, you view the roles group’s help.

Scope: which roles can be seen and modified in each interaction with a process

By default, users cannot see or modify a process’ roles during its start or execution. To allow users to see or modify a process’ roles, configure the roles scope in the design elements where you wish for them to be seen or modified. The roles scope also specifies, for those that accept multiple values, if users can add or remove members, and sets limits to the number of members that users can add or remove.

For information on how to configure the scope, check Data, roles, attachments and comments scope.

Domains

A datum’s domain specifies the set of values that the datum can take and is associated to a data type. For example, if a datum must only store values corresponding to dates, that datum’s domain is the set of all possible dates. In Q-flow, each application datum is associated to a domain, which is in turn associated to a data type.

The domain’s data type determines the application datum’s type. For example, if an application datum is associated to the “Date” domain, its value must be a date. Thus, through its data type, the domain defines the values that the data associated to it can take. These values can be limited further if the domain is associated with an operation that defines a more restricted set of values (for example, the result of a database query).

A domain also defines the way in which its data will be shown and edited in Q-flow’s website. For instance, data from the “Date” domain is shown through a control (form item) that allows you to select a date (i.e. a date picker).

Q-flow offers a set of basic domains, but it is possible to define additional domains.

Q-flow’s basic domains

Q-flow’s basic domains are the following:

Boolean: it is associated to the “True”/“False” data type and the “Check Box” control.
Date: it is associated to the “Date” data type and the “Date picker” control.
Number: it is associated to the “Number” data type and the “Text box” control.
Text: it is associated to the “Text” data type and the “Text box” control.
Text area: it is associated to the “Text” data type and the “Text area” control.
Money: it is associated to the “Number” data type and the “Text box” control.
Time: it is associated to the “Time” data type and the “Time picker” control.
Date time: it is associated to the “Date” data type and the “DateTime picker” control.
Document: it is associated to the “Text” data type and the “Document” control.

For more information on domains’ control types, check the Control types section.

Domain properties

A domain’s properties form has the following sections:

General
Properties

General

Name
Description
Control type: it is the control type that will be used to enter or show values of that domain’s data. A control is a user interface element, like a list, a text box or a button, that lets the user interact with the system. Further down each control type is described in greater detail.
Data type: it is the type of the values that the application data associated to the domain will take. Not all types are compatible with all controls. For instance, if the control is a date picker, the data type must obligatorily be Date. The data types are the following:
- Text
- Number
- True/False
- Date
- Time
Data source: this option is only valid for some control types. It allows you to select a data source type to then specify how to obtain data from a data source of the specified type. Once you have selected the data source type, click the configuration button (Fig. 434) to specify how data is obtained. The available data source types are:
- None: leave this option in place if you do not wish for the domain to access a data source.
- Database: it allows you to specify a connection to a database and a query to obtain the data.
- Web service: it allows you to specify a connection to a web service and a web service method to obtain the data.
- REST web service: analogous to the previous one, but for a REST type web service.
- SharePoint list: it allows you to specify a SharePoint list and a CAML query to obtain the data.
- List: it allows you to manually define it, enumerating the set of possible values through a list. Each list element has a key and a text associated to it.

Properties

In “Properties” you can specify a set of style sheets to apply, in Q-flow’s website, to the control that is used to show the domain data.

Behavior:
- Add empty option to the Combo Box: it allows you to add an option to a domain with the “Combo Box” control type that, when selected in a form, indicates that none of the domain’s values were selected.
- Special mode: this property is only available for domains with the “Text box” control type and it allows you to add an additional property to the control with which the domain data is shown. This property is an HTML5 characteristic that lets you take advantage of this standard’s validation and semantics features. The special modes available are:
  - E-mail
  - Phone
  - Number
  - Password
- AM/PM format: this property is for domains that use the “Time” data type or “DateTime picker” control type. If its value is “True”, the domain data will be shown in the AM/PM format (“one in the afternoon” - 1:00 PM). Otherwise, it will be shown in 24 hour format (“one in the afternoon” - 13:00).
- Display seconds: this property is for domains that use the “Time” data type. If its value is “True”, the domain data will be shown with seconds. Otherwise, seconds will not be shown.
Layout:
- Style sheet: name of the styles class to show in all cases.
- Read only style sheet: name of the styles class to show when a datum has read-only scope.
- Container style sheet: name of the styles class of the element that contains the control.
- Container read only style sheet: name of the styles class of the element that contains the control when a datum has read-only scope.
- Attributes: set of name-value pairs of HTML attributes that Q-flow will add to the control that shows the domain data. Use the button with the “+” symbol to add a row to the attribute list and then modify the key (attribute name) and the value to specify the attribute.
- Direction: this property is only available for domains whose control type is “Radio button” or “Check Box list”. It allows you to specify if these controls’ options should be shown one next to the other (“Horizontal”, the default option) or one on top of another (“Vertical”).
Restrictions:
- Regular expression: this property only exists when the domain data type is “Text” or “Document”. It allows you to specify a regular expression to validate the text that is written or the name of the file that is being uploaded. If a user enters a text that does not match the regular expression, Q-flow will show them the error message specified in the “Format error message” property.
- Format error message: the text of the error message that will be shown to the user if they enter a value that does not match the regular expression defined in the “Regular expression” property.
- Comparison operator: it allows you to specify the operator that will be used to compare a user-inputted date with the date specified in “Date to compare”.
- Date to compare: this property only exists when the domain data type is “Date”. It allows you to specify a date with which Q-flow, when validating the domain’s application data values, will compare the user-inputted dates. The “Comparison operator” property allows you to specify what comparison will be made.
- Max length: this property only exists when the domain data type is “Text”. It allows you to specify a maximum length for the values of the data associated to that domain.
- Max value: this property only exists when the domain data type is “Number”. It allows you to specify a maximum value for the values of the data associated to that domain.
- Min value: this property only exists when the domain data type is “Number”. It allows you to specify a minimum value for the values of the data associated to that domain.

Data sources

This section explains how to configure the data source access for each type. The configuration usually has two parts: the source connection specification and the specification of which data it takes (the query). The exception to this are the List sources, for which you directly specify the list elements.

Connection configuration

To specify the connection, there are always two options (Fig. 436):

Use application parameter: in this case, select the application parameter that contains the connection specification.
Define in data source configuration: in this case, click the configuration button.

It is recommended to use an application parameter (for information on how to define application parameters, see Application parameters).

If you decide to specify the data location in the data source configuration, you must complete the same connection data that you would if you were defining an application parameter.

Fig. 436 Data source connection options

Database query definition

Defining a database query requires you to know how to use SQL.

Fig. 437 shows the form in which a database query is defined. To define the query, you can write it directly in SQL or you can use the query builder (Fig. 438). The first column in the “Select” sentence must be the column that contains the data key. The second column must be the one that contains the description (for example: “Select Id, Name From Customers”). More columns can be included. In that case, to use the data that comes in the additional columns, it must be associated to output parameters. Under the query, there is a section dedicated to these parameters, which is explained further down.

Queries can have input parameters. To create an input parameter, click the “+” button in the table that appears in the upper half of Fig. 437. “Test value” is the value that said parameter will have to test the query. You can edit and delete existing parameters. To insert an input parameter in the query, click the button indicated in Fig. 437.

The input parameters are represented in the query with braces. In Fig. 437, there is an input parameter called “Country”.

The query builder makes the query definition easier by showing the names of the available tables. Additionally, once the tables in the “From” section of the query have been selected, the available columns appear to be selected in the “Select” section. In “Order by” the columns that you wish to use to order the result are added and in “Where” the filter conditions are defined through an interface like the one used to define gateway conditions (see Conditions specification).

Test query

Before saving the domain’s configuration, you must test the query. To do that, click the Test query button (Fig. 437, “Test query”). If the query works, Q-flow shows the result of executing it.

Output parameters

To define output parameters, it is necessary to test the query by clicking on the right button as shown in Fig. 437. Instead of the query form, the columns obtained as a result of said query will be shown. Close this result and you will return to the previous form, but now, as you can see in Fig. 439, the parameters are enabled and can be edited. Click the name in blue to edit it.

The names you write are the ones you will see when you configure some application data to store these parameters’ values in it. Parameters are associated to application data in that data’s properties form, in the “Dependencies” section (see Dependencies).

Once the query has been defined, click the Save button to save it.

SOAP web service query definition

Once you have specified the connection to a SOAP web service (see Connection configuration), you must click the Load button (see Fig. 440) to load the list of methods from that web service. After that, where it says “Select web method”, select the method you wish to use for the domain. When you select the method, its parameters are loaded. The method parameters are associated to input parameters. The selected method must return a list of simple objects.

Input parameters

A fixed value can be assigned to each parameter. If the control type is Lookup, Item selector or Combo box, that value can also be set to a parameter. To do that, in the parameters table (Fig. 440) you must select each parameter’s type. There are two parameter types:

Custom: a custom parameter works like domain parameters that obtain their data from a database: when an application datum for that domain is defined, another application datum is defined as a parameter (see Dependencies). For a parameter of this type, enter a name (Fig. 440).
System: a system parameter is used with a web service method specially developed to interact with the domain in such a way that the query is more efficient. For example, instead of a Lookup that retrieves all of a table’s elements and only filters the data by key in the client code, you can develop a method that obtains the key as a parameter and returns only the record that has the key that was sent. System parameters are not associated to application data. Q-flow determines how to invoke a method based on which system parameters are defined. There are four system parameter types:
- Filter by key: it is meant to be used with a method that receives a key (identifier) as a parameter. Q-flow uses it, for example, with Lookup type controls. An example of a method to use with this parameter is GetCustomer(string key).
- Filter by text: it is meant to be used with a method that receives a description as a parameter. Q-flow uses it, for example, to send the text that was entered in the item selector. An example of a method to use with this parameter is GetCustomer(string filter).
- Maximum quantity of items: it is useful if the web service method receives a parameter (of “int” type) that indicates the maximum number of elements that it must return. An example is GetCustomer(string filter, bool startsWith, int maxQuant). Another example is GetCustomer(string key, int maxQuant).

Column mapping and output parameters

A data source query for a domain must return at least two columns: one for the key and one for the description of the returned entities. If the source is of database type, the first returned column is taken as the key and the second one as the description. But if the source is a web service, there are no columns but object properties and there is no way to determine which of the properties corresponds to the key and which to the description. To do that, the column mapping is used.

Column mapping consists of defining columns and associating each of them to an object property. The first two columns are used for the key and description respectively. Additional columns are optional and can be associated to output parameters (see further down).

By default, the mapping table has all the properties mapped to a column name. If you wish to change a name, click the text corresponding to “Column name” to input the column name and afterwards press “Enter”. If you wish to remove a mapping, click the row and then the “Clean mapping” button (indicated in Fig. 440). You can also change the mapping order with the corresponding buttons.

After this, each defined column is associated to an output parameter through the “Output parameters” button (analogous to a database query): each column is assigned a parameter name. Both input and output parameters are associated to application data through the “Dependencies” section of application data belonging to the domain (see Dependencies).

REST web service query definition

Once the connection to a REST web service has been specified (see Connection configuration), the action to be performed must be specified, which is a URL corresponding to the web service you wish to query (Fig. 441). After that the required HTTP method must be selected (GET, POST or PUT).

Input parameters have the same type as in SOAP web services (see the Input parameters section), but unlike those, they are not automatically loaded. Instead, the user must enter them manually. You can give them a name and value (both must be unique) aside from the type. These parameters are used to load values in the headers, as is explained below, and the input object, as is explained in Input object.

HTTP headers

HTTP headers, which are key-value pairs, can be specified to be sent in the request. The key is a text and the value must be a parameter of type “None” or “Custom” that has been defined in the “Parameters” section table.

Input object

The input object is of JSON type and is an object with properties. These properties can be values (that are taken from the input parameters) or subproperties, which in turn have more values.

To create a new property, click the button indicated in Fig. 441. This will open a menu as in Fig. 442.

If you wish to add a property with subproperties, select the “Add property” option (later you will be able to add subproperties to the main property). Otherwise, select the “Add property with value” option. This will allow you to give a value to the property from an input parameter. Analogous options are shown when you click the “Add sub property” button.

Fig. 443 shows an example of a tree with properties and subproperties.

To edit the name of a property or subproperty, you can use the button indicated in Fig. 441 or press F2. Remember that, when the query is made, the properties that are in the same tree level must have different names. You can also delete a property by using the corresponding button (Fig. 441). These two options are also shown in a context menu if you right-click the property.

Once your tree structure has been created, you must enter the necessary values. All values must be assigned a parameter; if you wish to send a property with an empty value, create a parameter whose value is empty (it must not be of System type). To assign a value to a parameter, right-click the value. This will open a context menu like Fig. 444 shows.

If you place the cursor on the “Set value” option, on the right a submenu will be displayed with all existing parameters. Click the one you wish to assign and the value will be shown with that parameter’s name. You can assign the same parameter to more than one value. The Clean button allows you to remove the parameter that is currently assigned to the value.

In Fig. 445 an example of a final result is shown.

Fig. 445 Tree with loaded properties and parameters

Once your input object has been created, you must test the query, like in SOAP web services, using the button to this end (analogous to Fig. 440). The query result must be an array of JSON objects. Since a JSON object could potentially have several levels of subproperties, there is a limit to the shown depth. This can be seen in Fig. 446, where fields with an information symbol are those that have more subproperties, but they are not shown.

Fig. 446 Query result with an unsupported depth level

After the query has been tested, the Column mapping table will be loaded with the discovered properties. You can then proceed to create the corresponding mappings and load the output parameters as was explained in the Column mapping and output parameters section.

SharePoint list query definition

The definition of a SharePoint list query is similar to the one of a database query (see Database query definition), with the difference that the query is written in CAML instead of SQL. There is also a query builder to make the task easier.

Control types

This section explains the control types that can be used by data domains. The possible control types are:

Text area
Check Box
Combo Box
Text box
Text box autocomplete
Rich text box
Document
Label
Hyperlink
Check Box list
Lookup
Radio Button
DateTime picker
Date picker
Time picker
Item selector

Text area

An area where several lines of text can be written. It is ideal for data whose values are long texts.

Check Box

A square box to check or uncheck an option. It is only useful for true/false type data.

Combo Box

A list that, when it is expanded, shows options for possible data values. It is appropriate when the user must select one of several options.

Text box autocomplete

A text box autocomplete allows a user to write part of a text and it shows them a list of values whose texts begin with what the user wrote. Those values are obtained from some data source. For example, let us suppose that a user has to select the name of a product among the products a business offers. If the business has many products, it may not be so practical to have a combo box. It may be more practical for the user to start typing the product name and for a list to progressively show the products whose names are similar to what the user is typing, until they are finally so few that the user can find the one they wish easily and select it.

Text box

A common text box with a single line (like the text box where the name of a domain is written).

Rich text box

Similar to the text area, but it allows you to modify the text’s format properties such as using bold, italics, aligning the text, adding lists or other elements.

Document

A datum from a domain that uses this control type is shown, if it is editable, as a control to upload files (otherwise, only the data value is shown). When a user uploads a file using this control, the file is attached to the process and additionally, in the data value the new attachment identifier, version and path of the uploaded file are stored, separated by a semicolon (“;”). This way, the user not only attaches a file, but it is associated to a datum that gives meaning to the file. For example, you can require the user to upload a resume by having a “Curriculum Vitae” control.

For a user to be able to upload a file, not only must the datum be editable, but the scope must allow them to add files (see Attachment scope).

"Document" control type, modifiable — Fig. 453 “Document” control type, modifiable

Label

A control that shows a text, but does not allow you to modify it, even when the data scope defines that you have permission to edit the data in the step you are responding to or the start event.

Hyperlink

A control that, when clicked, navigates to a web page. It is useful when the data represents web addresses.

Check box list

A set of check boxes. It is useful when you wish to present the user with a list of options and the user can select several of them. The options’ texts are copied in the data value one after the other, separated by line breaks (only text type domains accept this control type).

Lookup

A control that allows you to obtain, from an identifier, a value belonging to said identifier. It can be taken from a database, a list or a web service. The user types the identifier in a text box and Q-flow shows the value corresponding to that identifier.

Radio button

It is similar to a check box, but when there are several “radio buttons” in the same area, only one of them can be checked. Thus, when one is checked, the others are automatically unchecked.

DateTime picker

A combination of a date picker and a time picker. If you place the mouse over the world symbol, you will see the user’s preferred timezone.

Date picker

A control that displays a calendar to select a date.

Time picker

It is a control that allows you to enter times and automatically validates them.

Item selector

A list that allows you to select a particular element from a set with a large number of elements (for example, taken from a database). The elements are shown in a list and Q-flow filters them as the user types the name of the sought element.

Integrations

Integrations allow Q-flow to interact with other systems through the execution of software component operations. A process can execute an integration’s operations through a service activity (see Service task).

An integration’s definition requires technical IT knowledge. That is why Q-flow separates an integration’s definition from its use.

To define an integration, one or more operations must be defined. An operation is a set of calls to an external component. For example, in an integration with a web service, it is a set of calls to that web service’s methods. One of the operations is selected as the production one and it is the one that is executed when the integration is called.

Integration properties

An integration’s properties form has the following sections:

General: aside from allowing you to specify the integration’s name and description, it allows you to select the production operation.
Parameters: it allows you to define the integration’s parameters. Parameters let the process send data to the integration when it calls said integration, as well as receive data from it when the integration finishes its execution.
Operations: it allows you to define the integration’s operations. An integration operation that accesses a web service, for example, is specified through the web service’s URL, the name of the method that must be invoked and the parameters that are passed to that method.

General

“General” section properties:

Description
Execute in transaction: it allows you to specify whether the operation should be executed in a transaction, i.e. in a context in which many operations are executed and, if at least one of them fails, then they are all cancelled and rolled back. This is only possible with some operations (for example, database operations). TECHNICAL NOTE: this option is implemented by executing the integration code inside a TransactionScope.
Production operation name: it indicates which of the operations defined in the integration is the one that will be used (see further down how to define operations; initially there are no defined operations and it is therefore not possible to select one). To select the production operation, click the selected option (it can be “None”) and choose an operation from the list that Q-flow shows you.

Parameters

The parameters section shows a table (which is initially empty) with the integration’s parameters. Parameters allow you to send data to the operation that is being executed or to receive data from the result of executing the operation. For example, if the integration invokes a method from a web service that has two parameters and returns a number, three parameters must be created: one for each method parameter and one for the result. When the integration is selected in a service task (see Service task), each integration parameter is associated to a datum or application parameter.

To add a parameter, click the “+” button. That makes Q-flow add a row to the table. To modify a parameter property, click its value (for instance, to modify the parameter’s name, click the text that appears in that parameter’s “Name” column).

To delete a parameter, select it and then click the delete button (✗).

A parameter’s properties are:

Name: the name that identifies the parameter.
Data type:
- Text
- Number
- True/False: a datum with two possible values: true or false
- Date
- GUID: an identifier
Direction:
- Input
- Output
- Input/Output
Required: if this option is checked, it is mandatory to associate an application datum or parameter to the parameter in the service tasks that use the integration that is being defined.

Operations

Operations are also shown in a table (Fig. 465). When an operation is added, the form of the wizard to generate it appears (Fig. 466). In the “General” section of that form the operation’s name and, optionally, description, are entered. Underneath these options are the options to add the components that Q-flow must use to generate the operation. Once the components have been defined, you must click the Next button to go to the next step. At the end of the process, Q-flow will generate the code that executes the operation.

If the “Create AdHoc operation” option is checked, it is not necessary to specify anything: an ad-hoc integration is created with code that does not execute anything. It can be used for testing or to generate an operation whose code will be hand-written later.

Otherwise, you have to specify one or more components for the operation. The available component types are:

Database: a stored procedure or a script to make queries or insert or update data (Upserts).
Rest web service: a REST web service.
SharePoint: a SharePoint list. Documents can be uploaded and elements created in a list or documents library.
Web service: a web service.

Note

In Q-flow’s OnPremise version, operations of other types can be handled: COM, Assembly (.Net component) and Qflow Assembly (.Net component which implements a Q-flow predefined interface). These operations are not available in the web designer, but in the classic designer. Once defined, it is possible to see these operations’ code in the web designer.

To add a component, click the button to configure the operation (Fig. 466). A menu will then appear that allows you to select the component type. When you select the component type, a form will appear to specify the connection to the component. That form has two options:

Use an application parameter: if you mark this option, instead of specifying the connection, you can select an application parameter for Q-flow to obtain the connection data from. If the list of application parameters to choose is empty, it is because there are no available application parameters for the selected component type (for example, the component type is “Database” and there are no available application parameters of “Database connection” type).
Define in data source configuration: if you mark this option, you must specify the connection data. This data is specified in the same way as if you were defining a connection in an application parameter. For instructions on how to configure a connection, check the corresponding section in Application parameters.
- Database connection: See Configuring a database connection for instructions.
- SharePoint list connection: see Configuring a SharePoint connection for instructions.
- Web service connection: see Configuring a web service connection for instructions.

In the case of a Rest Web service type component, to configure the connection you must specify the following data:

Url: the web service URL. For example: “http://webServer/api”
Web method: supposing you wish to access the employee creation, update and deletion operations, an example would be to write “employees”.
Http method: the Http method (get, post, put or delete), which depends on which operation you wish to perform (obtaining an object, creation, update or deletion).
Headers: they allow you to specify headers for the connection with the REST web service. For the key values you must specify an integration parameter that is of input or input/output type.
Parameters: it allows you to specify the structure of the objects that are received through parameters. If the parameter is a simple value (for example, an entity’s identifier), it is enough to click on “Add property” (Fig. 468) and assign it a name by selecting it, clicking “Edit property” (Fig. 468) and entering the name. This name will later be used to associate the parameter to one of the integration’s input parameters. The “Add subproperty” button is used to specify complex objects. By combining “Add property” and “Add subproperty” you can specify an object that contains other objects. It is not necessary to include all object properties: only those to which you wish to assign values that are in the integration’s parameters.
Return object: it works in the same way as Parameters, but for the return object.

Fig. 467 Connection configuration for REST web service type integration

Configuración de parámetros y objeto de retorno — Fig. 468 Parameters and return object configuration. In this case, the object receives a simple parameter, “id”, and returns an object, from which you wish to obtain the “Name” property (the integration has an input parameter for “id” and an output parameter for “Name”).

Once a component has been specified, if you click the Save button, the component is added to the components list (Fig. 469).

Fig. 469 Two components added to an operation

When you are done adding components, you have to specify which of these components’ operations will be executed in the operation. To move on to this stage in the operation definition, click the arrow button (Fig. 469, “Next”). The screen changes to show the available classes and methods (Fig. 470). When a class is selected, the list of available methods changes to show the methods of the selected class. The shown classes are the following:

For databases: since databases have no classes, what are shown are classes generated by Q-flow to represent commands that can be sent to the database. The classes are of the following types:
- [Database].Queries: these classes allow you to execute simple queries automatically generated by Q-flow. When this option is selected, in the “Available methods” list an element is loaded for each database table. Each of these elements represents a “SELECT” command to retrieve the data from the corresponding table. For example, if the database has a table named “Employees”, in “Available methods” the “EmployeesQuery” “method” appears. If you also have a table called “Products”, the “ProductsQuery” method appears, etc.
- [Database].StoredProcedures: these classes allow you to execute stored procedures. When this option is selected, in the “Available methods” list the database’s stored procedures are loaded.
- [Database].Upserts: they allow you to execute sequences of SQL commands that are automatically generated by Q-flow to update tables. When you select this option, in the “Available methods” list an element is loaded per database table. Each of these elements represents a command that inserts or updates a record in a table, according to whether the values that are passed correspond to an already existing record or not. For example, if the database has a table that is called “Employees”, in “Available methods” the “EmployeesUpsert” method appears.
For web services: the class that implements the web service’s operations is shown. If that class is selected, the methods that the web service exposes are shown.
For REST web services: the class associated to the configured component is shown, with a single method.
For SharePoint lists: the available classes correspond to the content types available for the selected list. There is also the [DynamicContentType] option, which allows you to add an element or upload a document by specifying the content type through a parameter. Once the class has been selected, two available methods usually appear: one allows you to create an element (“CreateItemX”, where X is the name of the content type selected in “AvailableClasses”). The other one allows you to upload a document (“UploadDocumentX”). In this case, aside from the parameters corresponding to the content type’s fields, there is one that must contain the path of the file that will be uploaded. If the selected class is [DynamicContentType], only the option to create an item will appear (“CreateItemDynamicContentType”).

To add a method, select it and click the “+” button. When you add a method, its input and output parameters appear. Each of those parameters can be associated with one of the parameters defined for the integration. The icon next to a method parameter indicates if it is an input or output one; if you place the mouse cursor over a parameter, a label appears that reads “Input” or “Output”.

To associate a method parameter to an integration parameter, right-click where it says “Value” and select “Set value”. This makes the list of integration parameters compatible with the selected method parameter appear: the compatible parameters are those that have a convertible type and the same direction (input or output). For example, if the method’s input parameter is of “Number” type, you will be able to select the parameters that have been configured as Input or Input/Output and of “Number” type. However, if the method’s input parameter is of “Text” type, all parameters configured as Input or Input/Output will be selectable regardless of their type, since a value of any type can be converted into text. In an analogous way, if the method’s parameter is an output one of “Text” type, all parameters configured as Output or Input/Output will appear regardless of their type (Fig. 471). Select, from the list, the integration parameter that you wish to associate to the method parameter and both will be associated with each oher.

An example (Fig. 472): an integration invokes a web service method, GetProductName, which receives an integer number, productId, as a parameter and returns a text.

For the integration two parameters are defined: ID, of “Number” type and Input direction, and Result, of “Text” type and Output direction. ID can only be associated to the method’s productId parameter. It cannot be associated with the method’s result because the latter is a text, while the former is a number. Additionally, ID is an input parameter, so even if the method’s result were a number, it would not be possible to associate them. The same happens with Result, which can only be associated to the method’s result.

To remove a method, select it and click the Delete method button (Fig. 471).

Fig. 472 Integration with two parameters and how they are associated with a method’s parameters.

Once the methods with their parameters have been specified, click the Next button again. Q-flow will generate the code to call the method and save the result in the output parameters. Click the Save button to save the operation.

Once an operation has been created, you can access the generated code through the Edit button (Fig. 473).

Fig. 473 Generated code for an operation

Code editor

When an operation is added to an integration, Q-flow generates the code that it will execute to invoke the operation. This code can be seen and modified. The code is shown in the code editor, which is also used when editing event handlers, script tasks and validations. The Compile button allows you to compile the code. If there are errors, they are shown in the “Error” tab. In some cases, like script tasks, it is possible to execute the code with an “Execute” button. Be careful when using it: if, for example, the code modifies a database, when executing it from the editor, the database may be modified as if the code were being executed from a process. In the case of integrations, this option is not possible.

Difference in versions

The Execute button is not available in the Cloud version.

Application parameters

Application parameters are entities that allow you to separate configuration data from the entity that uses it. For example, it could happen that many process templates use the same web service from service tasks. It is uncomfortable to have to specify the service Url in each task. Additionally, if it changes, all the tasks have to be modified. Due to this it is more convenient for that data to be stored in a single place and for each web service task, instead of specifying the web service Url, to specify where that data is stored.

In the same way, there can be several different integrations that use the same web service (each invoking a different operation, for example). In that case it is also preferrable to store the web service information in a single place from which all integrations obtain the connection data. Application parameters allow you to store such data and use it in service tasks, data sources for domains that use them, integrations and as tags or parameters in other steps.

Application parameter properties

An application parameter’s edit form allows you to define the parameter type and assign a value to it, aside from modifying its name and description. The parameter types are:

Password: the parameter value is a text that is encrypted to be saved in the database.
Text: the parameter value is a text.
Database connection: the parameter has all the necessary data to connect to a database.
Web service connection: the parameter has all the necessary data to connect to a web service (SOAP or REST).
SharePoint connection: the parameter has all the necessary data to connect to a SharePoint list.

To assign a value to the parameter, for example its value or the data to connect to a database, click the Configure button (Fig. 475). To configure an application parameter of “Password” or “Text” type, you must simply enter the parameter’s password or text (in the password’s case, it is entered twice).

The configuration for database, web service and SharePoint connections is explained next.

Configuring a database connection

A database connection’s properties (Fig. 476) are the following:

Provider type: the database access provider (for example, SQL, OleDb, ODBC, Oracle provider). It depends on the type of database for which you are defining the connection.
Server: the name of the server where the database is.
Integrated security: this option is for SQL Server databases. If this option is checked, the connection is created using integrated security. Otherwise, Q-flow enables the “User” and “Password” properties to enter the database user’s name and the corresponding password.
Additional parameters: it is a grid in which you can add parameters to the connection string. The grid has two columns, one for the parameter name and another one for the value. For example, if you wish to specify a 60-second timeout for the connection to an SQL Server database, you can add an additional parameter named “Connection Timeout” with a value of “60”.
Test connection: click this button to check that the entered data is correct. If the data is correct, you will be able to select a value for the “Database” property.
Database: the database to which you wish to connect.

Fig. 476 Database connection configuration

Configuring a web service connection

A web service connection’s properties (Fig. 477) are the following:

Url: the web service URL (it can be SOAP or REST).
Network credentials: leave this option checked if you wish to use the credentials of the user whose account is used by Q-flow’s services. If you wish to use other credentials, uncheck this option and enter the username and password you wish to use.
Test connection: if you click this button, you will be able to check if the entered URL and credentials are correct. If they are, Q-flow will open the web service’s page in a new browser tab.

Fig. 477 Web service connection configuration

Configuring a SharePoint connection

A SharePoint connection’s properties (Fig. 478) are the following:

Site URL: the URL of the SharePoint site in which the SharePoint list you wish to access is located.
Network credentials: check this option if you wish to use the Q-flow services account to connect to SharePoint or else uncheck it and enter a username and password. Use the “Test connection” button to verify that you can access the specified SharePoint site with the entered credentials. If the test is successful, you will be able to select the SharePoint list.
List: this field is enabled once you have checked that the previous data is correct, through the Test connection button. Select the SharePoint list you wish to access here.

Fig. 478 SharePoint list connection configuration

Using an application parameter

A parameter can be used in many contexts in which it is necessary to specify the type of information that is stored in an application parameter. In a domain that uses a web service as its data source, for example, it is necessary to specify the web service URL. The user can decide to specify the URL in the domain’s own properties (“Define in data source configuration”) or use an application parameter. Application parameters can also be used in integrations. A “Text” type application parameter can be used as a tag (check the Tags section). An application parameter of this type can also be associated to bot and integration parameters, in async and sync service tasks respectively. Additionally, these parameters are available in code written in script activities or Q-flow type assemblies (which contain classes derived from CodeScriptBase; see the Scripting Interface manual).

Custom forms

Difference in versions

Custom forms configuration is not available in the Cloud version, nor is the Web Forms site or the Custom Forms Design manual for said site available.

Q-flow allows you to substitute the forms that appear in the website with custom forms. Q-flow does not have a tool that allows you to design these forms, but you can use another tool to design them (Visual Studio is recommended) and then include them in one of Q-flow’s two sites.

Q-flow includes two sites to work with flows, with two different technologies:

MVC site
Web Forms site

This manual does not explain how to design custom forms, only how to associate those forms to processes, through creating and configuring “Custom form” type items. For more information on how to develop custom forms, check the two manuals on the subject. If you are using Q-flow Cloud, you will only find the Custom Form Design manual available.

There are three types of forms in Q-flow and thus, three types of custom forms:

Start forms: they are the forms that appear when a user clicks a process template to start a process. They allow you to enter their name and description and can also allow you to add application data values, roles and attachments.
Response forms: they are the forms that allow you to respond to a Q-flow task.
Flow forms: they are the forms that show information about the flow itself and not one of its steps. There are two types:
- Flow forms: they show flow data, but never allow you to modify it. They are the forms that appear when a user clicks a flow. They show flow information.
- Flow edit forms: they show flow data and allow you to modify it. For example, in a flow’s edit form you can modify its name. It is also possible to modify data, roles and attachments, if the defined scope allows it.

Standard forms show application data grouped by group (see Application data). For the Web Forms site, Q-flow also includes three forms that work as custom forms and have the same look as the standard forms, except that they show application data without grouping it. The same can be achieved in the MVC site if application data is defined without a group. Fig. 479 and Fig. 480 show the difference between a case and the other. Both show the same four pieces of data. Two of these pieces belong to a group named “Professional data” and the other two to a group named “Personal”. In the first case (Fig. 479), data appears grouped in different boxes and it is indicated, for each box, the name of the group to which it corresponds. In the other (Fig. 480), data is all shown in the same form titled “Application data”.

Fig. 479 Application data in a standard form

Fig. 480 Application data in a non-grouping form

Custom form properties

A custom form’s basic properties form shows the following properties:

Use MVC: this option indicates that the form is an MVC form, developed to be used from the MVC site. To specify a form for Q-flow’s Web Forms site, check the “Use Web Forms” option, which appears if you expand the form. The properties of forms that use MVC are the following:
- Is area: it indicates that the form is a portable area, which is one of Q-flow’s custom form types. The other type is “view”.
  - View type forms properties:
    - View: the name of the view to use. View type forms use the default area (“CustomForms”) and a default controller (“Flow”), so for these forms no more properties need to be specified.
  - Area type forms properties:
    - Area: the name of the area that should be used.
    - Controller: the controller’s name.
    - Action: the action’s name.
Use Web Forms: this option only appears if in BPM’s Web.config file the value of “ShowWebFormsProperties” is “true” and is only shown when the properties form is expanded.
- Url: type the relative (with respect to Q-flow’s Web Forms site basic URL) URL of the ASPX page that contains the form. The forms provided by Q-flow are in the Web Forms site’s CustomForms folder (the corresponding files have the “Default” suffix). You may take them as a reference, but do not modify them, because you would be risking the operation of the flows that use those forms (all flows that do not use custom forms).
Aplies to: this option allows you to indicate for which types of form you can use this custom form. The form types are explained at the start of this section.

Assigning a custom form to a design element

To assign a custom form to a design element, be it a start event, a user task or a user notification task, double click the element to open its properties form. Then, click the button to expand the form so that the “Form” section may appear. Select the form you wish there (Fig. 482). Only those forms whose type applies to that element will appear.

Assigning flow forms and flow edit forms

To specify a custom form as a flow form, right click the version on which the flows that must use it are based and in the menu select “Flow forms”, “Flow form”. Q-flow shows a form with a “Form” section, where you can select the form you wish (as long as its type applies).

To specify a custom form as a flow edit form, do the same, but selecting “Flow forms”, “Flow edit form” in the menu.

Custom forms design

Custom forms design is a task of a higher technical complexity, which requires either ASP.NET MVC or Web Forms knowledge, depending on which Q-flow site you will use the form in. The MVC Custom Form design manual and Web Forms design manual have useful information for whoever has to develop those forms.

Event handlers

Event handlers are small programs that Q-flow executes in their context (they have access to the flow data) when a certain event occurs during a flow’s execution. The events that can trigger a handler’s execution are predefined. Defining a handler consists mainly of defining its code. Later it is associated to an event, so that when it occurs, the handler’s code is executed.

Event handler properties

An event handler’s properties form has the following sections:

General: name and description
Handler information (it appears when the form is expanded): it allows you to define the handler’s code and determine if it is synchronous or asynchronous. This section’s properties are explained below.

Handler properties

Handler type:
- Synchronous: the handler is executed in such a way that the flow waits for it and does not continue until the handler’s execution ends. The handler can modify flow data.
- Asynchronous: the handler is executed in such a way that the flow does not wait for its execution to finish. The handler cannot modify flow data.
Order: it is a useful number when there is more than one handler associated to an event. In that case, handlers are executed in ascending order using that number. For example, if there are three handlers for the same event, Q-flow first executes the one whose value for this property is 0, then the one with value 1 and finally the one with value 2.
Use integration: if this option is checked, the handler uses the code of an already defined integration, instead of using code written specifically for the handler. When this option is checked, the screen changes so you can select an integration and the options that allow you to write the handler’s code disappear (Fig. 484). The screen’s lower half changes to show the integration’s parameters, so you can associate application data to them, in the same way as in a service task (see Service task).
- Properties if an integration is used:
  - Integration: a list to select the integration that contains the code that you wish to assign to the handler.
  - Parameters: a specification of the correspondence between application data and integration parameters. Check Integrations for details.
- Properties if an integration is not used:
  - Language: it allows you to specify the programming language in which the handler’s code will be written. The options are C# and Visual Basic .NET.
  - Code: under the language options a text area appears that allows you to write the handler’s code in the selected language.

Event handler's properties — Fig. 484 Event handler’s properties

Associating an event handler with an event

For Q-flow to execute an event handler, it has to be associated to an event so that when it happens, Q-flow executes the handler’s code.

There are two event types:

Flow events: these events are not associated to any particular step.
Design elements events: they are events that are associated to design elements.

Associate a handler to a design element event

To associate an event handler to a design element, select the element and click the properties icon for Q-flow to show the element’s properties form. Then expand the properties form so that the “Handled events” section appears. That section contains a list of the events to which the handler can be assigned:

Error: it happens when an error occurs during the step’s execution.
Step finalize: it happens when the step finishes its execution.
Step start: it happens when the step’s execution starts.
Step news: it happens when there are news in the step. For example, in the case of a user task, when an addressee responds to the question. Note that the fact that there are news in a step does not necessarily imply that the flow or thread have changed their status. For example, if a user task has several addressees and the flow waits for five of them to responds before continuing, the flow will not leave the waiting status until five addressees have responded, but when the first one to respond does so, they will create news in the step.

To assign the handler to an event, select the event and click the Modify button. In the event’s properties form, select the handler and click the button with the ✓ symbol.

Fig. 485 Associate a handler to a design element event

Associate a handler to a flow event

To associate an event handler to a flow event, right-click the version to which the flows that will use the handler belong and select “Event handlers” in the menu. This shows a list with the flow events. Check the event to which you wish to associate the handler, then click the Edit button or double click the corresponding row. A handlers list will then appear, check the desired handler and click the button with the ✓ symbol.

The flow events are the following:

Thread status change: it occurs when a thread changes its status. For example, if a thread was waiting for someone to execute a task and that person responds to the task, the thread goes from Waiting to Executing.
Flow status change: it occurs when the flow changes its status. For example, if the flow arrives at a task step, there is a status change, given that the flow enters a state in which it is waiting for that task’s end or cancellation.
Thread error: it occurs when an error takes place during a thread’s execution.
Stage on time: it occurs when the flow’s current stage exceeds the time defined as the expected time. For more information on stages check the Stages section.
Stage out of time: it occurs when the flow’s current stage exceeds the defined maximum time.
Flow finalize: it occurrs when Q-flow ends the flow.
Thread finalize: it occurs when Q-flow ends a thread.
Thread wait: it occurs when a thread ends and waits for its sibling threads’ end.
Flow start: it occurs when Q-flow starts the flow.
Thread start: it occurs when Q-flow starts a new thread’s execution.
Thread fork: it occurs when a thread is divided into several threads. This occurs when a thread reaches a divergent parallel gateway or a divergent inclusive gateway that starts several threads.
Thread join: it occurs when two or more threads are joined. This occurs when the flow reaches a convergent parallel gateway or a convergent inclusive gateway that joins several threads.

Associate a handler to a flow event — Fig. 486 Assign a handler to a flow event (in this case, the “Send alert” handler is assigned to the “Stage out of time” event).

Worklets

Attention

This feature is deprecated and cannot be used in the web designer.

Worklets are sets of a design’s elements and connections between them. These sets can be used in several designs as if they were a unit. A worklet has its own design, but is not independent, but rather must be used inside a design.

Currently, the business process web designer does not allow you to add worklets or see their content, although it does allow you to see a package’s worklet list. If you need to work with worklets, use the business process desktop designer (the tool’s classic version).

Validations

Validations are small programs that are defined to execute operations in flow forms. To develop validations it is necessary to have knowledge of client-side scripting (Javascript). There are two types of validations:

The ones that are executed when Q-flow loads a form on the screen. These validations allow you to modify the form data status before the user can modify it. To do this, the formLoad() method can be implemented.
The ones that are executed when the user clicks the form’s answer button (the button that starts the process in the case of start forms; the button that responds to the task in the case of response forms; the “Save” button in a flow edit form). These validations can be used to verify the data and emit an alert when it is not valid, thus preventing the user from making mistakes that hinder the form’s correct functioning. To do this, the formSubmit() method can be implemented.

Like custom forms, validations are defined in a package, process template or version and then associated to the forms in which you wish to use them. A validation can be used in various forms of many different flows. A validation can be associated to a form of any type (start form, user task response form, flow form and flow edit form).

Validation properties

A validation’s properties form has the following properties that can be modified:

Name
Description
Under the description there is a text area to write the validation’s code.

In previous Q-flow versions, the validation’s programming language could be selected, with JavaScript and VBScript as options. However, VBScript is considered obsolete. For this reason, the posibility of selecting the language is only shown if the existing code is already of VBScript type. Otherwise, the shown language will be JavaScript, without the possibility of changing it.

Associating a validation to a form

To associate a validation to a process design element, double click the element to open its properties form (the element can be a start event, to associate the validation to a start form, a user task or a user notification task). Afterwards, expand the properties form. In the “Validations” section, check the validations you wish to associate to the selected element.

To associate a validation to the flow form or the flow edit form, open the form properties, by right-clicking the version and selecting “Flow forms”, “Flow form” or “Flow edit form”. This opens the selected form’s properties window. In the “Validations” section, check the validations you wish to associate to the selected element.

Selecting a form's validations — Fig. 488 Selecting a form’s validations

Bots

A bot is a computer program that performs tasks that are assigned to it by flows, with which it communicates asynchronously. Generally, tasks that are processed by bots are tasks that use a large amount of the hardware’s resources (memory, CPU) and thus must be performed by a process separate from the processes that Q-flow’s services execute. A bot can even work in a different server from the one that hosts Q-flow’s services. Bots are not meant for easy tasks that are executed in a few seconds and can be run in service or script tasks.

An interaction between a flow and a bot happens in the following manner:

A flow creates a task for the bot via an async service task. The task creation consists of storing the task’s information in a queue. That information includes the task’s parameters and indications of which bot must execute it. These indications are what is defined in the business process web designer.
The bot checks if it has pending tasks and when it does, it finds the new task and attempts to process it. The bot is a service or at least a process that periodically checks if it has new tasks in the queue. To that end, it uses the WebBot web service, which provides methods for accessing the queue and obtaining the pending tasks’ data to process them. It also provides methods for aborting a task or indicating that the task has been completed. Since the functionality to obtain tasks and update them is provided by a web service, the bot can be in a different server from the one with Q-flow’s services.

Bot properties

A bot’s properties form has the following sections:

General: it allows you to enter a description and, in the “Executable by” property, the name of the user whose credentials will be used to execute the bot and invoke the WebBot web service.
Parameters: it allows you to define the bot’s parameters. The bot’s parameters are defined in the same way as an integration’s parameters. Check Integrations for instructions.
Notification:
- Do not notify: if you select this option, Q-flow will not notify the bot when it assigns it a new job. The bot will have to periodically consult the WebBot web service to discover if it has pending jobs.
- Notify to message queue: in this case, Q-flow will notify the bot that it has a new pending job through a message queue. The bot, in this case, must not periodically consult the WebBot web service, but rather suscribe to an MSMQ message queue and implement a handler for the event that will be triggered when there is a new job. If you select this option, you must specify the path of the message queue that will be used.

Time out: it allows you to define a time limit for the bot to process the job. Once the limit has been reached, if the bot has not finished processing the job, the flow will continue its execution through the timeout connector of the async service task in which the job was assigned to the bot. If the async service task does not define a follow-up step through the timeout connector, it will be left in an error state. Check the Timing section for instructions on how to define timeouts.

Process design elements

This section gives a detailed description of the properties of each of the elements that can be part of a design. The first sections are about aspects that are common to several steps. For example, both a user task and a notification task require you to select one or more addressees.

General properties

There are properties that are common to all elements that can be added to a process design: the element’s name and its description.

The name always appears in an element’s properties form’s upper section, next to the Save, Cancel and Expand/Contract form buttons (Fig. 491).

The description appears in the properties form’s “General” section. This section usually also includes the following properties, generally available in activities and events (there are exceptions), but not in gateways:

Progress: the flow’s progress percentage. For example, if you consider that finishing a certain user task means that half the flow has already been executed, you can write “50” as the value of this property in that user task.
Start flag: the flow flag is a text chosen by the person who designs the flow. When the flow reaches an element that has a value for the start flag, the flow flag changes to the value indicated there. The flag, then, is a way of indicating the flow status. When the flow data is viewed in the website, one of the pieces of data that appears is the flag.
End flag: a value that the flow flag will take when the element’s execution ends. Intermediate events have a property named “Flag”, which works both as a “Start flag” and an “End flag ” (i.e. these events only modify the flag once).
Flow importance: “Low”, “Normal” or “High”. It does not influence the flow’s development, but it is shown in the website.
Form help: they are messages in the form that can be useful for whoever is filling it. It is configured with a rich text box, so it is possible to format the message.

Timing

For some design elements timeouts can be defined. For example, user tasks have options to control time limits and prevent or mitigate delays through alerts, reminders and delegations (collectively called “actions”) that are triggered when a time limit is exceeded. Another example is the timer event, which stops a flow thread to wait for a time limit to be exceeded. This section describes how to define the timing for any element that uses it. These elements’ properties form usually have a section with the following properties:

Use calendar: when Q-flow calculates a timeout, it uses a calendar that defines working hours and business days to take into account, for example, holidays and weekends. This option allows you to specify the calendar that you wish to use for the calculations (if none is specified, the default calendar is used). These calculations are done considering the time zone configured in the calendar. For more details on calendars, check the Organizational Model Management manual.
Time information: in this property the timeout is specified, which can be defined in four ways:
- Fixed date: it allows you to specify a date.
- Variable date: it allows you to use the value of an application datum of Date or DateTime type. Q-flow will execute the action in the date indicated by the value of the application datum. To be able to select this option, you must have a Date or DateTime type datum defined.
- Fixed time: it allows you to indicate a time interval in seconds, minutes, hours or days. Q-flow will execute the action once that interval has passed, from the moment the flow was started. Non-working days and hours do not count when doing this calculation, unless a calendar is used.
- Variable time: this option is similar to the previous one, but it allows you to use the value of an application datum of Number type to indicate the interval’s value. This value can be interpreted as being expressed in seconds, minutes, hours or days. To be able to select this option, you must have a Number type datum defined. Non-working days and hours do not count when doing this calculation, unless a calendar is used.

Data, roles, attachments and comments scope

Q-flow allows you to define what application data, process roles and attachments can be seen or modified by users during a flow’s execution and where they can do this. The same occurs with comments, but in this case they can be added or the existing ones seen.

Interaction points between users and flows are flow forms.

Flow start form: it is the form that appears when you start the flow and is related to the start event.
Flow response forms: they are the forms that users use to respond to flow tasks. They are associated to user tasks.
Flow form: it is the form that appears when someone clicks a flow to examine its information. It is associated to the flow and does not allow you to modify the data.
Flow edit form: it is a form similar to the flow form, but which allows you to modify data.

To define the level of access to the flow information, it must be defined for each of these forms and in the case of response forms, for each user task. It is not necessary to define the information access in those forms where you do not wish for data, roles, attachments or comments to be available, since by default, these are not present in the response form.

The flow start form is associated to the start event, since it appears when the flow is being started. To modify the level of access to the flow information during its start, open the start event’s properties form and find the “Scope” section. There, you will be able to specify which roles and data are present and shown in the form and which can be modified by the user. There are also the attachments and comments scope options. Further down these options are explained in detail.

The case of response forms is similar. Q-flow’s response forms are associated to user tasks, since they appear when a user wishes to respond to a task assigned to them. To modify a user task’s scope, you should proceed in the same manner as with a start event.

To modify the level of access in a flow form, access the flow form’s properties window by right-clicking the version and selecting the “Flow forms”, “Flow form” option. That window has a “Scope” section. Do the same to modify the scope in the flow edit form, but selecting “Flow forms”, “Flow edit form”.

Data scope

Application data scope is modified through a table (Fig. 493) that shows the application data list. All application data will be viewed if all of it has the “Missing” scope, with the “Show missing scope data” option being automatically checked. Otherwise, the data with a scope other than “Missing” will be shown, with the “Show missing scope data” option left unchecked. This is useful, since a great set of data not relevant to the form could exist, typically with the “Missing” scope.

If you have two pieces of data with the same name and a scope other than “Missing”, an error will be shown when saving.

To modify a datum’s scope, select it and click one of the buttons that appear above the table (Fig. 494 shows which button corresponds to which scope; to see it in the site’s own screen, place the mouse cursor over the button). Several pieces of data can be selected simultaneously. The possible scopes are:

Fig. 494 Scope buttons with their meanings

Required: the user can see and modify the data value. If the data does not have any values, they are obligated to enter one (they will not be able to start the flow, if they are in the start form, nor will they be able to respond to the task, if they are in a response form, if they do not provide a value for the data).
Editable: the user can see and modify the data value.
Read only editable: the user can see the data value, but not modify it. Page scripts can edit the data and these changes are saved.
Read only: the user can see the data value, but cannot modify it. If a script modifies the data in the screen, changes are not saved.
Hidden editable: the user cannot see the data value, but the data is present in the form, although invisible and if a script modifies it, the change is saved.
Hidden: the user cannot see the data value. If a script modifies the data value, changes are not saved.
Missing: the data is not in the form. It is not shown nor can it be accessed by a script. It is as though it did not exist.

If a datum accepts multiple values and has a scope that allows its modification (required, editable, read only editable or hidden editable), the last button is enabled (“Instances”, see Fig. 494), which allows you to modify scope properties specific to that type of datum (Fig. 495):

Allow addition: it specifies whether adding new instances to the datum or new lines to the line block (if the datum belongs to one) is allowed.
Allow removal: it specifies whether removing data instances or lines from the block (if the datum in question belongs to one) is allowed.
Maximum number of instances: it specifies the maximum number of instances that a datum can have or the maximum number of block lines if the datum belongs to a line block. If the datum has that number of instances, no more can be added, even if addition is permitted.
Minimum number of instances: it specifies the minimum number of instances that a datum can have or the minimum number of block lines if the datum belongs to a line block. If the datum has that number of instances, no more can be removed, even if removal is permitted.

If a datum belongs to a line block, the scope properties that are edited will apply to the entire line block. Therefore, these properties can also be modified through a grid that appears in the screen’s lower half. This grid apears when at least one of the pieces of data belonging to the block has a scope that allows its modification (Fig. 493, where it says “Line instances configuration”; in the figure, there is a block named “Categories”). To modify the maximum or minimum number of instances, click the number and enter the desired value.

Fig. 495 Additional scope options for data that accepts multiple values

Group ordering

In those elements that use a form (start event, user tasks and flow forms configuration), data scope has an additional possibility, which is group ordering. Under the instances section you will find a checkbox that, when checked, will show you the groups corresponding to the data that has a scope that makes it appear in the form (editable, required, read only or read only editable).

You can select the group you wish to move and then click the arrows to move it up or down. You can also drag the groups to order them. This group order will be reflected in the form. Data that does not have a group will remain inside the “Application data” group, which cannot be ordered.

Roles scope

The roles’ scope works in the same way as data scope.

Attachment scope

Attachment scope options are the following:

Accessibility: this property indicates the level of access that users will have to attachments. The possible options are:
- None: Q-flow does not show attachments in the form.
- List only: Q-flow shows attachments, but does not allow you to open them or modify them.
- Read only: Q-flow shows attachments and allows you to open them.
- Editor: Q-flow shows attachments, allows you to open them and modify them.
- Total: Q-flow shows attachments, allows you to open them, modify them and remove them.
Allow addition: if this option is checked, users will be able to add attachments to the form.
Limits:
- Maximum number of attachments: it indicates the maximum number of attachments that the step can have. Q-flow will not allow you to add attachments over this value, unless it is 0, which means there is no maximum.
- Minimum number of attachments: it indicates the minimum number of attachments that the step can have. Q-flow will not allow you to remove attachments if doing so implies that the attachments number becomes less than this value.
Maximum size of an attachment (KB): it allows you to specify the maximum size in kilobytes that attachments can have (the default option, 0, means there is no limit). If you specify a value, Q-flow will not allow you to attach files with a size greater than the one specified.
Show only: it makes Q-flow show only the files that match one of the regular expressions entered in this property. (*)
Edit only: it makes Q-flow allow the modification of only the files that match one of the regular expressions entered in this property. (*)
Add only: it makes Q-flow allow you to add only the files that match one of the regular expressions entered in this property. (*)
Delete only: it makes Q-flow allow you to delete only the files that match one of the regular expressions entered in this property. (*)

(*) See Regular expressions of attachment filters, for more information.

Regular expressions in attachment filters

Attachment filters are used specifically via regular expressions similar to the ones that Windows uses for its file system, in which an asterisk (“*”) substitutes any number of characters. For example, the expression “*.zip” means “every file with .zip extension”.

A filter can use several expressions separated by “;” or by “|”. For example, if the “Read only” filter has the expression “*.zip;*.rar;License.pdf”, Q-flow will only show files with “zip” and “rar” extensions, as well as the file named “License.pdf”.

Character “?” substitutes an occurrence of any character. Some examples: expression “*.???” represents any file with a three-character extension; expression “document?.doc” represents any file whose name starts with “document” and has an additional character before the extension (“document1.doc”, for instance, but not “document12.doc” or “document.doc”).

Character “!” allows you to negate an expression. It can only be used at the start of the filter. For example, if in the “Show only” filter the expression “!*.exe;*.bat” is written, Q-flow will only show files that do not have “bat” or “exe” extensions.

Comment scope

Q-flow forms have the option of adding comments when filling them (in the case of those that are not of read only type) and seeing the existing comments. This allows users to give and obtain extra information about the flow that is considered important but is not part of its data. The scope options for these comments are the following:

Allow addition: the user can add a comment to the flow if they wish.
Required: the user is obliged to add a comment; if they do not, they will not be able to complete the form. This option can only be selected if you have already selected “Allow addition”.

If viewing and adding comments is allowed, when you respond to a task, for example, you see the form as in Fig. 500.

The comments congifuration differs for user tasks, in which we have the ability to choose whether comments are required depending on the response chosen by the user, as well as the option to add said response to the comment log. For more information, see the User task section.

Tags

Many properties of Q-flow’s steps allow you to use tags. This means that the values of these properties do not have to be determined during a process’ design, but Q-flow can obtain them from where it is indicated when it needs to use them. For example, it is common to include the value of some application datum (like a customer’s ID number or their name) in user task’s subjects. In this case, instead of the task saying something like “Process the customer’s request”, it can say something like “Process the request of customer John Smith, ID 111111”.

Properties for which tags can be used have an icon with a tag next to it (Fig. 501). If you click this icon, a list appears with the items that can be selected for the tag. If, when you see this list, you type, the list will limit itself to the elements that contain the text you entered. You can also choose to only show items of a specific type in the list (for example, only application data). To do that, click the corresponding icon in the list’s lower section (Fig. 501, where it says “Data”, “Roles”, etc).

You can also enter a tag without clicking the tag icon, by simply entering the “#” symbol in the property: this will also make the list of items that can be used for the tag appear.

The item types that can be used in tags are:

Application data: the data value is used.
Process template roles: the name of the user who performs the role is used.
Text type application parameters: the parameter value is used.
Flow information: for example, the flow name or its start date.
Others: for example, the current date.

Step types

In general, steps are divided into three types: events, activities and gateways. An event represents something that happens in the step and there are three types: start, intermediate and end. An activity represents a work unit to do in the flow and it can be a task, an automatic process or a subprocess.

Start events

The start event that Q-flow implements is the simple start event, which we will call Start event.

The start event marks the beginning of a new flow. It also represents the point at which a user starts a flow. For example, in order to select a custom form as the flow’s start form, it should be associated to the start event. When a flow is started, its execution is started in the start event, which must be unique.

A start event’s properties form (Fig. 503) has the following sections:

General: it contains general properties (see General properties), aside from the “Stage” property, which allows you to associate the start event to a flow stage (see Stages). There is also Form help, which allows you to specify a help text for the step. When a user is starting a flow in the website, they will be able to see the defined help message if they click the help icon. This message can contain HTML code.
Scope: see Data, roles, attachments and comments scope.
Advanced: it contains options to automatically generate the flows’ names and descriptions.
Form: it allows you to assign a custom form as a flow start form (see Assigning a custom form to a design element).
Validations: it allows you to select validations from the existing ones to execute in the start form (see Associating a validation to a form).
Handled events: it allows you to associate handlers to the element’s events. See Associate a handler to a design element event.

Advanced

The third tab, “Advanced”, has the following properties:

Autogenerate name and description: these properties allow you to specify the flows’ names and descriptions beforehand, using tags, so it is not necessary for the user to enter them when they start a flow.
- Auto-generated name: a text with tags to indicate how the flows’ names must be formed.
- Auto-generated description: a text with tags to indicate how the flows’ descriptions must be formed.

Start event's properties form "Advanced" section — Fig. 503 Start event’s properties form “Advanced” section

End events

The end events that Q-flow implements are the Simple end event, which we will call End event (Fig. 504), and the Terminate end event (Fig. 505).

End and terminate end events finish flow executions. A terminate end event finishes the flow’s execution even if some threads are still executing. In that case, Q-flow finishes those threads and the flow ends its execution. An end event, on the other hand, waits for all threads to finish and once they have, it ends the flow.

These events’ properties form has the following properties:

General: see General properties. The box that reads “Progress = 100%” allows you to indicate that when the flow ends, the progress must be set to 100%.
Handled events: it allows you to associate handlers to the element’s events. See Associate a handler to a design element event.

User task

A user task assigns a task to a user or set of users. The task addressees are specified through process template roles.

A user task has a set of responses. When a user accesses a task’s form in the website, they must select an response to update the task’s status. A task’s properties form has the following sections:

General: see General properties.
Message: it allows you to specify the task addressees, the message that is shown to them and the possible responses.
Time controls: it allows you to define timeouts, reminders and alerts for the task.
Advanced: it contains options on how to show the task in a Q-flow standard form.
Handled events: see Associate a handler to a design element event.
Scope: it allows you to specify the data, roles, attachments and comments access (see Data, roles, attachments and comments scope).
Form: it allows you to associate a custom form to the task (see Assigning a custom form to a design element).
Validations: it allows you to associate validations to the task (see Associating a validation to a form).

Message

Message subject: the subject text of the message that will be sent or shown to the addressees. If the task is configured to send notifications, it is used in the subject of the e-mail message that is sent to the addressees. It can be specified through a tag (see Tags).
Addressees: a list of the task addressees. The addressees are process template roles. To specify an addressee, start typing their name and select it when it appears as an option.
Responses: a table that contains the responses that will be available for whoever performs the tasks. The buttons allow you to add or remove responses, as well as reorder them through the arrows (Fig. 508). Each response has the following properties, which are modified in the table where they are shown:
- Text: the response text. It is what is shown to the user. When a response is added, the text has a default text. To modify it, click that text.
- Key: a text that identifies the response, but that is not shown to the user. The key is used to evaluate conditions that use it. The key is modified in the same way as the text, by clicking it.
- Comment required: if set to “Yes”, it indicates that the response of the task must have comment.
- Type: it indicates the response type, which can be not final, final or terminal final. When a user selects a final response, they finish their task and cannot continue working on it. When they select a response that is not final, the changes they made in the data are saved, but their task is still pending. Since a task can be assigned to several addressees, the fact that an addressee has selected a final response does not necessarily mean that the flow will continue its execution, because other addressees may not have finished their parts of the task. In this case, multiple response criteria (see below) define under which conditions the the flow will consider the task finished and continue its execution. This does not apply when the user selects a terminal final response; in this case, the task will finish even if the other addressees have not answered yet, regardless of the multiple response criteria.
Response display mode: it allows you to configure how the task responses are shown in a standard form in Q-flow’s website. Fig. 509 illustrates each of the options.
Add Reply to Comments: allows responses to be added to the Q-flow site’s comment log.
Multiple response criteria: it allows you to specify when the flow must continue, when it has more than one addressee. Options are:
- Continue after:
  - Some user has answered: when a user selects a final response, the flow will finish the task and continue its execution.
  - All the users have answered: the flow will continue its execution only when all addressees have selected a final response.
  - At least “X” users have answered: when a number (X) of users have responded, the flow will continue its execution. If this option is selected, the “Quantity/Percentage” field is enabled for you to specify the quantity (X).
  - At least “X” percentage of the users have answered: similar to the previous option, but a user percentage is indicated instead of an absolute quantity.

Time controls

Time controls are used to prevent or mitigate delays in tasks through alerts, reminders, delegations and timeouts. Alerts and reminders are notifications that are sent when a time limit expires. Delegations consist of reassigning tasks and timeouts allow the flow to take a path different from the one it would have taken if a time limit had not expired.

The time controls section shows a table with the defined controls. It has three buttons to add, modify and delete time controls (Fig. 510).

When you edit a time control, a form is shown like the one in Fig. 511.

This form has the following properties:

Action type: several buttons are shown. Each one corresponds to an action class. A class is selected by clicking it. Possible classes are:
- Reminder: Q-flow sends a notification with a reminder for the selected addressee.
- Alert: Q-flow sends a notification with an alert for the selected addressee.
- Delegation: Q-flow reassigns the task, giving it to the selected addressee.
- Time out: Q-flow interrupts the wait, abandoning the step’s execution and continuing with the flow execution through the timer boundary event. For more details on how to add boundary events see Add boundary event.
Timer information: these properties define the time limit for the time out that the action specified above will trigger. For instructions, check Timing.
Addressees: select the action’s addressees here. For alerts and reminders, addressees are those who will receive the notifications. For delegations, they are who the task will be reassigned to. Time outs do not have addressees. To add an addressee, start typing the name of a role that is available in the template you are using and when you see it in the list that appears, select it.

Advanced

Sends notifications: it allows you to define if you wish for the step to send notifications via e-mail to its addressees. If the option is unchecked, Q-flow will not send e-mail messages to notify the task’s addressees that they have a pending task.
Task manager: it allows you to specify a role who will be the task manager. The manager can respond in place of any of the addressees. They can also delegate the task and send alerts.
Alternative addressee: it allows you to specify a role so that, if the task’s original addressee cannot complete it, it is possible to select that role’s members as addressees when delegating it.

User notification task

A user notification task sends a notification to Q-flow’s users. Users usually receive notifications by e-mail, but they can also see them in Q-flow’s website. In that regard, a user notification task is similar to a user task. The difference is that it does not require any actions from its addressee, but simply lets them access a form that shows them the information. This form can be, like in the case of other steps that use forms, a custom one.

A user notification task’s properties form has the following sections:

General: see General properties. It also allows you to specify a help text for users (it is only shown if the panel is expanded). When they see the notification in the website, they will be able to see the help text by clicking the help icon (“?”). The text can contain HTML code.
Message: it allows you to specify the properties of the message that will be sent. Check the Message section inside the user tasks’ description to see a description of how that section works.
Scope: it allows you to define what application data, roles, attachments and comments are visible and modifiable in the task. See Data, roles, attachments and comments scope.
Form: it allows you to specify a custom form. See Assigning a custom form to a design element.
Validations: it allows you to associate validations to the task. See Associating a validation to a form.
Handled events: see Associate a handler to a design element event.

Fig. 514 User notification task basic configuration

Mail task

A mail task sends an e-mail message to the addresses specified in its properties. A mail task uses the SMTP service configuration to send its messages.

A mail task’s properties form has the following sections:

General: it allows you to enter a description.
Sender: it allows you to specify the message’s sender. It is shown when the form is expanded.
Addressees: it allows you to specify the addressees of the message that will be sent.
Content: it allows you to specify the text of the message that will be sent, as well as said message’s format.
Attachments: it allows you to specify which flow attachments will be sent attached to the message.
Handled events: it allows you to associate event handlers to the step’s events (see Associate a handler to a design element event).

Sender

The “Sender” section allows you to specify the message sender’s data. There are two possible options:

Use system configuration. If you use this option, the message will be sent with the sender that Q-flow uses to send notifications. This is the default option.
Use custom configuration. In this case, you will have to complete the following data:
- Sender
  - Name: the sender’s name. A tag can be used to, for example, obtain this name from an application datum (see Tags).
  - Address: the sender’s e-mail address. A tag can also be used for the address.
- SMTP server credentials (optional): the following fields are only necessary if credentials are necessary to send the message:
  - User: the name of the user who is allowed to use the SMTP service.
  - Password: the user’s password.

Addressees

The addressees section (Fig. 517) shows a space to write an addresse’s e-mail address and a button (“+”) to add more addressees. If you press this button, a space will be generated to enter another addressee’s address. In both cases a tag can be used to specify the address (see Tags). Use the “-” button that appears next to an addressee to remove it.

Content

The “Content” section has the following properties:

Subject: the message subject’s text. A tag can be used (see Tags).
Body: the message’s main text. A tag can be used (see Tags).
Programming language: it indicates whether the message body is specified in HTML or plain text.
- HTML: the message body is specified in HTML.
- Text: the message body is specified in plain text, without HTML tags.

In the lower half the message is written. You can use tags to take, for example, values from an application datum. To do this, write “#”.

Attachments

Fig. 519 shows the “Attachments” tab. It works in the same way as the addressees one: to add an attachment, click on “+” and and write the attachment’s name or use a tag to specify it. To remove an attachment, click on “-”.

Formula task

A formula task takes application data or process roles, performs operations on them and generates a result that is also accordingly stored in an application datum or role.

A formula task’s properties form has the following sections:

General: it allows you to enter the task’s description and define the formula that will be executed when the flow reaches the task, as well as the time zone for the date type data that is used.
Handled events: see Associate a handler to a design element event.

This task’s execution will perform the operations in the specified order. You can use a value that is pre-calculated and stored in some application datum or role in a later operation.

In the “Time zone configuration” subsection you can select a time zone for all the dates that are handled in the step. Dates in Q-flow have a time zone that influences the calculations performed on them. Since a flow with dates can be executed in a different time zone from the user’s (if the server is somewhere else), to avoid ambiguities, you can specifically indicate which zone the dates are considered to be in. In the case that you import a formula task from a previous Q-flow version, the “Server time zone” option will be automatically selected.

Formula

The “Formula” section of a formula task shows an initially empty table with the formula definition, which is composed of operations (each table row corresponds to an operation). To add a new operation to the formula, click the “+” button. This opens the new operation’s form, to the right of the formula table (Fig. 522).

An operation’s properties are the following (Fig. 522):

Target: it is the first property. Where it says “Start typing…”, start writing the name of the application datum or role in which you wish to store the formula’s result.
First operand: after where it says “Equals to”, you can enter the first operand, by writing where it says “Start typing…”. The operand can be:
- Value: a fixed value. In this case, write the value.
- Application data: an application datum of any type. If you start typing the name of an application datum, it will soon appear in a list that is displayed while you write.
- Function: the result of a function. For now, the only available function is GetDate(), which returns the current date according to the time zone specified in the task. This function can be selected if you start typing “GetDate()”.
- Role: a process template role. It is selected in a similar manner to an application datum.
The first operand depends on the target: if the target is a role, the operand must also be one. If the target is a datum, the value that the first operand can take depends on the target’s data type.
Transformation: this option allows you to apply a transformation to the operand before operating with it. The possible transformations depend on the operand’s data type.
- Number data: in general, these transformations only make sense if the operand is a datum that allows multiple values.
  - Average: it calculates the values’ average.
  - Count: it counts the number of values.
  - Max: it takes the maximum of the values.
  - Min: it takes the minimum of the values.
  - Sum: it takes the sum of the values.
- Text data:
  - Left: it takes only the operand’s first characters. The number of characters to take is specified in the “Length” property.
  - Left Trim: it cuts all the blank spaces that may exist at the operand’s beginning.
  - Mid: it only takes the operand’s middle characters. The position from which the characters must be taken is indicated in the “Start” property (0 corresponds to the first position). The number of characters to take from that position on is specified in the “Length” property. For example, if the operand’s value is “Hello World!”, Start = 6 and Length = 6, the transformation’s result will be “World”. For the same operand, if Start = 0 and Length = 5, the result will be “Hello”.
  - Right: it takes only the operand’s last characters. The number of characters to take is specified in the “Length” property.
  - Right Trim: it cuts all the blank spaces that may exist at the operand’s end.
  - Trim: it cuts all the blank spaces that may exist both at the operand’s beginning and end.
- Date: the values returned in these transformations are calculated according to the time zone specified in the task.
  - GetDay: it takes only the day.
  - GetHour: it takes only the hour.
  - GetMinutes: it takes only the minutes.
  - GetMonth: it takes only the month.
  - GetSeconds: it takes only the seconds.
  - GetYear: it takes only the year.
Operator: the operation’s operator. It is possible to not select any operator and only apply a transformation to the first operand, without performing any operations.
- + (sum): in the case of roles, it works as a set union (the result of adding two roles is a set with both roles’ members).
- - (substraction): in the case of roles, it works as a set substraction: the result are all the members of the first role that are not in the second role.
- * (multiplication)
- / (division)
- mod (remainder of dividing the first operand by the second)
- AddDay: it adds the number of days indicated by the second operand to the first date-type operand. The second operand must be a number.
- AddHour: it adds the number of hours indicated by the second operand to the first date-type operand. The second operand must be a number.
- AddMinutes: it adds the number of minutes indicated by the second operand to the first date-type operand. The second operand must be a number.
- AddMonth: it adds the number of months indicated by the second operand to the first date-type operand. The second operand must be a number.
- AddSeconds: it adds the number of seconds indicated by the second operand to the first date-type operand. The second operand must be a number.
- AddYear: it adds the number of years indicated by the second operand to the first date-type operand. The second operand must be a number.
Second operand: select the second operand from the options. These options are the same as for the first operand. The second operand depends on all the previous elements: the target, the first operand with its possible transformation and the operator. For this reason, some data may not appear as an option for the second operand.

Gateways

Gateways allow you to modify a flow’s route, be it by creating several parallel paths in the process or by selecting a path of many possible ones that come after the gateway.

All gateways are connected to various elements through their connectors. What changes according to the gateway type is if, once a flow goes through it, it continues using all paths, some of them or just one.

Gateways can be of the following types:

Exclusive gateway: it selects one of various possible paths for the flow to continue its execution.
Inclusive gateway: it selects one or more of various possible paths for the flow to continue its execution, so it can generate several parallel threads.
Parallel gateway: it generates as many parallel paths as it has outbound connections.

Gateways are used in pairs: a gateway is used and, in the place where the paths that started with it end, another gateway is added. In the case of the exclusive gateway, this is not mandatory. In the case of gateways that generate parallel threads (the parallel and inclusive ones), the second gateway of the pair (convergent gateway) is mandatory and has properties that allow you to define under which conditions the flow will continue its execution when one of the paths finishes its execution.

Exclusive gateway

An exclusive gateway selects one of various possible paths for the flow to continue its execution. It defines a condition for each of its outbound connections. If some condition is true when the flow reaches the gateway, the flow will use that connection to continue its execution. If no condition is true, the flow will use the default connection to continue its execution (see Specifying the default connection for instructions on how to define the default connection). If more than one condition is true, the flow will use the first of the conditions to continue its execution. In no case is more than one connection used: an exclusive gateway does not generate parallel paths.

Parallel gateway

Parallel gateways are used in pairs: the first one (divergent parallel gateway) divides the flow in several threads. The flow reaches the parallel gateway and continues its execution by using all of the gateway’s outbound connections. The second gateway (convergent parallel gateway) joins the threads, making all the paths the flow had been divided in converge again into one.

The properties form of the gateway that performs the separation is very simple (Fig. 526) and only allows you to enter a name and description, aside from the “Handled events” section, which allows you to associate handlers to the gateway’s events (see Associate a handler to a design element event).

Fig. 526 Divergent parallel gateway form

The form in the second gateway, which joins the threads, has an advanced options section that allows you to define under which conditions the flow must continue its execution (if it has to wait for all the threads to finish, for example) and, in case it does not wait for all the threads, what to do with the threads that have yet to finish. To see the advanced options section, expand the form with the Expand form button (Fig. 527). This section’s options are described further down, in Convergent gateways properties.

Fig. 527 Convergent parallel gateway form

Inclusive gateway

An inclusive gateway is a sort of hybrid between an exclusive gateway and parallel gateway: it selects one or more of various possible paths for the flow to continue its execution, so it can generate various parallel threads. It defines a condition for each of the outbound connectors. Once the conditions have been evaluated, the flow continues its execution through all the connections whose conditions are met. If more than one condition is true, the gateway generates various parallel paths.

Like parallel gateways, inclusive gateways must be used in pairs. The second gateway of the two (the convergent gateway) has properties that allow you to define when the flow must continue its execution when it reaches the gateway and what it must do with any pending threads. These properties are in the convergent gateway’s “Advanced” section. This section’s options are described further down, in Convergent gateways properties.

The first gateway’s (divergent gateway) properties form is very simple and only allows you to enter a name and description, aside from the “Handled events” section, which allows you to associate handlers to the gateway’s events (see Associate a handler to a design element event).

Specifying the default connection

The default connection is the one that an exclusive gateway uses when none of the conditions it contains is evaluated as true. To define a default connection, select one of the gateway’s connections, right-click it and select, in the context menu, “Default connection” (Fig. 529).

Fig. 529 Specifying a default connection

Finally the connection should look like Fig. 530 shows.

Conditions specification

Exclusive and inclusive gateways contain conditions in their properties that Q-flow evaluates when it reaches one of them. These conditions determine through which path (in the case of the exclusive gateway) or paths (in the case of the inclusive gateway) the flow will continue its execution, once the gateway is left behind.

To specify a gateway’s conditions, open the properties form and click the icon with three points to see the expanded form. This makes the “Conditions” section appear. If you open it, you will see it is divided in subsections, one for each element to which the gateway is connected through an outbound connector. In each of those subsections a condition can be defined.

To define a simple condition, click the “+Condition” button. That makes Q-flow add an element to the conditions list (Fig. 531).

Fig. 531 New condition in conditions list

Once the condition has been added, its components must be specified. Where it says “Start typing…” you must type the name of the item that you wish to use in the condition. The item can be an application datum or a user task that was executed previously. Once the item has been selected, select the operator to use and finally the value with which you wish to compare it. If the selected item is a user task, you will be able to select the voting criterion, which allows you to specify how to evaluate the response if the task addressees are many:

Some user answered: if some addressee answered what is specified in the operator-value combination, the expression is true. Otherwise, it is false.
All users answered: if all of the task’s addressees answered what was specified in the operator-value combination, the expression is true. Otherwise, it is false.
None of users answered: if no addressee answered what was specified in the operator-value combination, the expression is true. Otherwise, it is false.
X answered: if X addressees answered what was specified in the operator-value combination, the expression is true. Otherwise, it is false. If this option is selected, a box is enabled to specify X’s value.
X% answered: if X% of the addressees answered what was specified in the operator-value combination, the expression is true. Otherwise, it is false. If this option is selected, a box is enabled to specify X’s value.
Most selected answer: if the most selected answer was the one specified in the operator-value combination, the expression is true. Otherwise, it is false.

The value can be a fixed value like “2”, but you can also type the name of an application datum so the comparison is made with the value of that datum or the value of a user task’s response key or name. In this last case, the comparison will be made with the key of the response that was given to the previously answered user task. This allows you to build conditions such as “If the ‘Status’ application datum is equal to the response that was given to the ‘Approve’ user task.”

If you add another condition, you must decide if the second condition must be met simultaneously with the first, that is, if what is evaluated is “The first condition is met AND the second condition is met” or “The first condition is met OR the second condition is met”. That is what the “All” and “Any” buttons are for. If you click “All”, Q-flow shows the text “AND” to the left of the conditions. If you click “Any”, it is enough for one of the conditions to be met and to the left of the conditions the text “OR” appears.

To be able to combine “AND” and “OR” you have to use condition groups. To add a group, click “+Group”. You can then add conditions inside the group. The group has its own “All” and “Any” buttons, to determine how the conditions are combined inside the group (all are combined with “AND” or all are combined with “OR”). At the same time, groups are combined in the same manner as conditions, with “AND” and “OR”. A group can contain groups: by combining groups of conditions joined with “AND” with groups of conditions joined with “OR”, you can build any complex condition.

Example

Suppose a process template has an “Amount” number datum and another “Product type” datum. You wish to build the condition “If Amount > 5000 and (Product type = 1 or Product type = 2)”.

For that you need an “If Amount > 5000” condition and a group for “(Product type = 1 or Product type = 2)”, since this last condition must be evaluated first to then compare the result with “If Amount > 5000”. Groups fulfill the same function as brackets.

First, you must create a condition with “+Condition” and enter, left to right, the “Amount” application datum, the “greater than” operator and the value “5000” (Fig. 532).

Fig. 532 Building the “If Amount > 5000” condition

Then you must add a group with “+Group”, two conditions inside it with its “+Condition” button and click “Any” (Fig. 533) to be able to fill the two conditions that are evaluated with the “OR” operator.

Fig. 533 Building a group with two conditions under the “OR” operator.

Once this is done you must complete the conditions’ fields: the first one, from left to right, with the “Product type” application datum, the “equals” operator and the value “1”. The second condition is completed in the same way but with the value “2” at the end, thus obtaining the final condition like Fig. 534 indicates.

Fig. 534 “If Amount > 5000” and a group for “(Product type = 1 or Product type = 2)”

Convergent gateways properties

Parallel gateways and inclusive gateways are used in pairs. The second gateway has options to determine under which circumstances the flow must continue when it reaches it and what to do with any pending threads. These options are:

Continue after:
- All threads have ended: the flow stops at the divergent gateway and waits for all threads to finish before continuing.
- Some threads have ended: the flow will continue as soon as a certain number of threads have ended and will not wait for the other threads to finish. The number of threads to wait for is specified where it says “Number of threads”.
- The threads coming from these steps have ended: it allows you to specify which threads the flow must wait for. The form shows the name of the last element of each thread along with a box that can be checked. The flow will continue when all the threads corresponding to the elements that have been checked are finished.
- Finalize sibling threads: if this option is checked, all threads that have not finished will be finalized before the flow continues.

Fig. 535 Convergent gateway advanced properties

Call activity

A call activity is used for a flow to start another flow, which is called “child flow” (the flow that started it is said to be its parent).

When a flow reaches a call activity, it starts a flow from the template indicated in the call activity’s configuration. Once the child flow has started, the parent flow can continue its execution without waiting for the child’s execution to end or it can stop and wait for its execution to end before continuing.

A call activity’s properties form is divided in the following sections:

General: see General properties.
Template: it allows you to specify the template that will be used to start flows from the activity and some other flow properties.
Mappings: it allows you to specify correspondences between the parent flow’s application data and the child flow’s application data, and between the parent flow’s roles and the child flow’s roles. This allows the two flows to exchange information, by copying the value of data or roles of one of them to the data or roles corresponding to the other. You can also specify that attachments should be copied from one flow to the other.
Delayed start: by checking the “Delay start” option, you can specify that the child flow does not start as soon as the parent flow arrives at the call activity, but once a certain amount of time has passed since that moment. The way to specify that time is the same as in any timeout (see Timing).
Handled events: see Associate a handler to a design element event.

Process template

Template: it specifies the process template to which the flows that are started from the call activity belong.
Version: it specifies which template version will be used to start the flows.
- Use production version: check this option if you wish to always use the version that is the production one at the time of starting the child flow.
- Template version: this option allows you to select a specific version.
Flow name: it is the name of the flow to start. A tag can be used so that the name is, for example, the value of an application datum. For more details, check the Tags section.
Flow description: a description of the flow to start. A tag can be used so that the description takes the value, for example, of an application datum. For more details, check the Tags section.
Wait for subflow end to continue: if this option is checked, once the child flow has started, the flow that created it will not continue its execution until the child has finished. The parent flow’s data can only be updated from the child flow if this option is checked.

Fig. 537 Call activity properties, “Template”

Mappings

The mappings sections shows a table that is initially empty and to which rows can be added. Each row represents a correspondence between a datum or role from the parent flow and a datum or role from the child flow. In the lower half the attachment mappings options can be found.

Above the table with the data and role correspondences are the buttons that allow you to add an applicationn data mapping, add a role mapping, and delete the selected mapping (Fig. 538). If the “Template” section’s options have not been filled yet, the buttons are disabled, given that it is impossible to know what application data and process roles are available in the flow that is started.

When you click one of the buttons that are used to add a mapping, a new row is added to the mappings table. To specify the mapping’s properties, click each cell of the new row and select the desired values.

A mapping has the following properties (each one corresponds to a table column):

Type: it indicates whether the mapping is of roles or data. This is determined by the button that was used to add the mapping and cannot be modified.
Source: the parent flow’s application datum or role.
Target: the child flow’s application datum or role.
Direction: it indicates if the value will be copied from the source datum or role to the target datum or role or viceversa:
- Input: the value of the parent flow’s datum or role is copied to the child flow’s datum or role. This is done at the time of starting the flow.
- Output: the value of the child flow’s datum or role is copied to the parent flow’s datum or role. This is done when the child flow finishes its execution and only if the parent flow waits for the child flow. If the parent flow continues its execution immediately after starting the child, without waiting for it to finish, no data or roles are copied from the child to the parent.
- Input/Output: the value of the parent flow’s datum or role is copied to the child flow at the time of starting the child flow. Once the child flow’s execution has finished, if and only if the parent waited for the child to finish before continuing, the value of the child flow’s datum or role is copied to the parent flow’s datum or role.

IMPORTANT: for a datum or role to appear in the list that allows you to select them as a Target, they must be editable in the child flow’s start event. If a datum or role does not appear in the list of possible targets, check the scope it has in the start event of the version that will be used to start the child flow.

In the form’s lower half are the options for attachment mappings:

No attachment addition: Q-flow does not copy the parent flow’s attachments to the child flow.
Add attachments to child: when starting the child flow, Q-flow copies the parent flow’s attachments to it.
Add attachments to child and update: when starting the child flow, Q-flow copies the parent flow’s attachments to it. Once the child flow has finished its execution, if there were changes in those attachments, it copies them again to the flow that started it, but only if the parent waited for the child to finish before continuing.
Incorporate child attachments: if this option is checked, Q-flow incorporates all the files that were attached to the child during its execution to the parent. This is only done if the parent waits for the child.

Subprocess

A subprocess is an element that contains various elements and allows you to handle a part of the process design as if it were a unit. It is used to simplify the process design, since it can be contracted, so it is seen as a simple activity, or expanded, showing its entire content, which can be modified as if it were a process design inside the process design.

A recently created subprocess has a start event and an end event. When the flow reaches a subprocess execution, it starts at the start event and ends its execution when it reaches an end event.

Fig. 540 Expanded (left) and contracted (right) subprocess, with the buttons that allow you to expand it and contract it

Script task

A script task allows you to write a program for a flow to execute. The script can be written in the C# or Visual Basic .NET languages and must implement an interface that is defined in Q-flow.

Script task properties

A script task, aside from the name and description, has the following properties:

Programming language: it allows you to select the programming language (C# or VB .NET).
Code: it is the script code.

The code contains a function named “Execute”. When a flow executes the code, it will call that function. The code is written inside a class derived from the CodeScriptBase class, which is defined by Q-flow. That class has a set of methods and properties that allow you to work with the flow data. For more information on how to use those methods and properties, check the Scripting Interface manual.

Service task

A service task executes an integration (see Integrations). When you configure a service task, you must specify:

The integration to execute.
For each input parameter, which application datum will provide its value.
For each output parameter, in which application datum its value will be stored.

The “General” section allows you to configure the following properties:

Integration: it allows you to select one of the defined integrations. For information on how to define an integration, check the Integrations section.
Parameter mappings: it is a table that shows the integration’s parameters. A parameter or application datum must be associated to each required integration parameter, with the former having to be of the same type as the latter. To select an application datum, click “Data” in the “Type of item” column in the row corresponding to the parameter for which you wish to choose a datum. To choose an application parameter, select “Parameter”. To choose the application datum or parameter to which you will associate the integration parameter, click “Not set” in the “Item” column of the row you are modifying. If a parameter is of input type, it will receive the value of the application datum or parameter before the integration’s execution. If the paramter is of output type, it only makes sense to associate it to an application datum (a flow cannot modify an application parameter). Once the integration’s operation has been executed, the parameter value will be copied to the associated application datum. This how an operation can return results that can be used by the flow. If the parameter is of input/output type, it does not make sense to associate it to an application parameter either. The value of the associated application datum is copied to the parameter before the integration’s execution and once it is executed, the parameter value is copied to the application datum.
Auto map: this button allows you to attempt to automatically map the correspondence between the integration’s parameters and application data or parameters. When you click it, Q-flow will, for each integration parameter, search for an application datum (or parameter, depending on the value chosen in “Type of item”) with the same name and type as the parameter. If it finds one, it will associate it to the parameter. This way, parameter mapping can be done automatically, as long as there is an application datum or parameter equal to each parameter in name and type.

The “Handled events” section allows you to configure the following properties:

See Associate a handler to a design element event.

Async service task

An async service task allows you to assign a job to a bot. A bot can have parameters, just like an integration. An async service task is very similar to a service task, the only difference being that, instead of selecting an integration to run, you select a bot (Fig. 546). For instructions on how to associate application data or parameters to the bot parameters, check Service task.

Fig. 546 Async service task properties. As you can see, they are almost identical to a service task’s

Intermediate events

They are those events that can occur between the start and end of a flow.

Timer event

A timer event allows you to specify a delay. When a flow reaches a timer event, it stops during the time specified in it.

A timer event’s properties are divided into the following sections:

General: see General properties.
Timer: it is where how long the event must wait is specified. Check the Timing section for instructions.
Handled events: it allows you to associate handlers to the element’s events. See Associate a handler to a design element event.

Simple intermediate event

A simple intermediate event, which we will call intermediate event, allows you to mark a flow’s advance, by modifying the properties that have that purpose (progress, flag and stage). An intermediate event’s properties form has the following sections:

General: in this section are the properties that allow you to mark the flow’s advance.
Handled events: it allows you to associate handlers to the element’s events. See Associate a handler to a design element event.

General

It has the usual properties (Progress, Flag, Flow importance; see General properties) and some additional ones:

Stage: it allows you to associate the event to a stage, thus indicating that the selected stage starts in that step. Starting a new stage finishes the current one. The current stage can also be finished without starting a new one. To do that, instead of selecting a stage in the “Stage” property, select the “[End the current stage]” option (see Stages).
Resume the stage if it already exists: this option is shown if the “[End the current stage]” stage is selected. It is meant for cases in which there is a step-back in the flow. If this option is checked, when the step is executed again, the stage in which it was before is also resumed so that, when the time it took to execute the stage is counted, the added time of all executions is considered.

Catch signal event

A catch signal event allows you to make the thread wait until a signal is received from a throw signal event. It is used in scenarios where it is necessary to synchronize the work of two or more threads that are executed simultaneously. The two properties specific to these events are the following:

Wait for signal from step: the throw signal step for which the step waits.
Continue if thrown: in case the signal was thrown before the attempt to catch it, this option specifies if the step should wait for a new signal or simply continue.

Catch signal events also have other properties, common to other steps (see General properties).

Throw signal event

A throw signal event allows you to notify catch signal events that are waiting for it that they should continue their execution. This event’s configuration is similar to an intermediate event’s (see Simple intermediate event).

Intermediate boundary events

Fig. 554 Generic intermediate boundary event

Intermediate boundary events are events that can be attached to certain activities. If during the activity’s execution one of the defined events is triggered, the flow continues through a path that contemplates it. The events that Q-flow admits as boundary events are:

Timer event: these events can be attached to user tasks or async service tasks, the flow will continue through this path when the time out defined in the activity itself occurs.

Error event: these events can be attached to service tasks, script tasks, formula tasks and mail tasks. The flow will follow this path when an error occurs in the activity’s execution.

Artifacts

Artifacts are objects whose purpose is to make the process more manageable and comprehensible. In the process design, they have a different behavior from other elements: they are not part of the process flow. They can be connected to activities, events and gateways, but only to signal that they are related to them. They are informative elements that do not affect the process.

The available artifacts in Q-flow are:

Data object reference: it represents a data set that is used in some activity.
Data store reference: it represents a data storage, for example a database.
Annotation: it allows you to write a text and associate it to some design element.

Data object and data store reference

Both a data object reference and a data store reference are added to the design and connected to the element to which they refer. For example, if a service task updates a database, a data store reference can be added to indicate the database that it updates (Fig. 559). To write the database name, double click the database reference. Under the object, a box will appear to type a text.

Another example: if a user uses a certain data set to perform a task, a data object can be included in the design to indicate what the data set is (Fig. 560).

Fig. 559 Database reference in service task

Fig. 560 Data object reference in user task

Annotation

When a process design element is selected, one of the options that appear is used to add an annotation. If you click the corresponding button, Q-flow will create an annotation and allow you to place it where you wish. Once the annotation has been placed, double click it to enter a text. You can increase an annotation’s size to make the text fit.

Fig. 562 Element options with the Add annotation button

Pool

A pool allows you to create lanes to organize a process by grouping related elements inside the same pool.

When a pool is added, all the design elements are left inside of it. Dragging elements outside of the pool is not allowed: all design elements must be inside.

Once a pool is created, more can be added with the buttons that appear when you select the pool (Fig. 564). The pools’ size can be increased or decreased, by selecting them and using the mouse to drag their borders to one side or the other.