Variables in BPS

Facebooktwittergoogle_pluspinterestlinkedinmail
applies to version: 8.1.x; author: Marcin Wiktor

Note: In BPS 2016.1.x Reference Tags have been renamed to Variables. Their function remains unchanged


1. Introduction – what is a tag and how to use it

While developing new workflow, it is often necessary to refer to some value from certain form field, comparing dates, checking numbers or permissions to such data as document ID, document number or document type. Instead complicated database queries, it is possible to use tags. Tags in BPS are queries restricted by brackets – { i }, used in fields allowing to enter SQL queries, for e.g. default value of form field, visibility restriction query, condition of action execution or simply query limiting visibility of given path. Moreover tags may be used in many different places as for example: document number, email template or statements connected to menu button actions.

If we know name of our tag, it is possible to enter it manually, but it is also possible to use query creator, which contains list of all available tags, which we may use in given place. List of all available tags is always generated in context of place in which we run query creator, so there is no possibility to execute a tag which is not supported in given place.

For example – tags connected with automatic document numeration, will be displayed only in places allowing to define document number/document type.

To see which tags are available, it is necessary to go into creator by clicking edit button under field we are interested in. in this example it is going to be field allowing to configure default value of form field.

1

By default, query creator is always opened in basic mode, where tags used in a query are always displayed in user-friendly form, telling exactly to which value, tag will be changed. Tags may be added by double-click (tag will be placed in front of cursor) or dragged in any place.

Name of the tag may be also entered manually, which is easier in advanced mode as we also see tag names for every element. In advanced mode, tags are displayed only in text form.

2

After entering advanced mode, tags are displayed in text-form and in menu, on the right side, new columns – “Tag” and “Database field” appear.

“Tag” column is nothing else than name of the tag. “Database field” column concerns “Form fields” part and list of fields form “Object identifiers”. Such column displays name of the table WFElements, in which value of given form field is stored.

Another interesting function in query creator is browser available in right-upper corner. In basic mode it allows search by element name (current date or name of given form field), and in advanced mode also by “Tag” and “Database field” columns.

Last function of query creator is preview of query results in context of given document. In “Element ID” found at the bottom of creator, enter ID of document for which we want to see results of query.

3 buttons are available:

–          Show – displays content of query, which is executed for document with given ID after changing tags for certain values.

–          Test – performs an attempt of executing query

–          Load ID – downloads ID of last created document in which we currently work and puts it in “element ID” field.

 

2. Tags construction, “Form fields” and “Object identifier” groups

Among tags we may distinguish two types – those with names that are always the same for every process and those which are generated dynamically – “Form fields” and “Object identifier”. Such tags have predefined names which is then changed to specific value. For example: tag {STP_NAME} will always be changed to step name in which the document currently is and {COM_NAME} tag will always return name of chosen company, for which the document is registered.

Things look different for tags which are form fields or object identifiers’. For every process we use completely different form fields, so elements for which it is possible to use tags are always going to be different. For form fields, tags are always created according to given scheme {Formfield ID}.

We may see ID of every form field in their configuration in “General” tab.

3

Instead posting field ID, we may also give its field name from database, for example: {WFD_AttDateTime1}. Value for which tag would be changed is the same as if using {44}. It is just another way of notation.

In case of some form field types, we may additionally format displayed value. For fields which are saved in database in form: ID#name we may define if we want to display ID, name or both parts. It applies for: choice fields, choice list or choice tree.

4

As we can see in creator, tag {49} itself, for value field will display both ID and name. If we would like to display such value in different place, then while choosing tag in such form, “2#value 2” will be displayed. Users rather will not be interested in ID of chosen value, so we may use tag which will display only name of chosen value – Name {N:49}.

Prefixes I: and N: may be easily remembered as these are first letters of ID and Name.

In example: we may use form filed given above: Value. It has 3 possible values to choose: value 1 (ID 1), value 2 (ID 2), value 3 (ID 3). On first step we choose one of these options and then move to next step where 3 new text fields will be displayed:

–          ID value – field which default value is ID of “Value” field

–          Name – field which default value is name of “Value” field

–          ID and name – field which will display ID and name of “Value” field

Effect should look as follows:

5

There are many possible applications of such functionalities and they are widely used in practice.

While creating for example: conditions restricting visibility of form fields, conditions of action execution or validation actions themselves, it is much better to compare picker ID than its value (name).

Name may be changed in future, ID will always be the same for specific values. Other example worth notation, may be workflow available for few companies from different countries, using translations and dictionaries with the same values but in different languages. One choice field, may use different dictionaries, considering given company, with the same values but in different languages.

On the other hand, if we want to display value chosen from picker in different place, it is better to display only name as (except some special cases) ID is irrelevant for user.

In case of “Date and time” we have very wide possibilities of data formatting.

6

Displaying certain parts of data from given form field may cause creating of a query much faster – we do not have to remember specific SQL functions, which for example will return only number of the month from given date. You just need to use proper tag.

Tag {L:44} may need some explanation, as it displays localized value. Its value depends on internet browser language.

It is worth to note, that prefix L: may be also used for tags from Yes/No form fields. Choice will be also displayed in browser language.

In case of Floating-point number fields we may divide integer part from decimal part. Depending on browser language, different standards may be used. For example for American English, a dot will be used by default and for polish, comma is a standard form.

7

If we want PDF printout of WorkFlow document, we do not want different standards on our printouts, so it is possible to impose displaying of only one standard.

Next type of form fields for which we may format displayed data is “Person or group”. We may display basic data (name, login, email) about person, which was given in certain field and basic information about his/her superior, designated by company structure.

8

Results may look as follows:

9

Important information is fact that in “form fields” section, item lists will not be available. It is because list may contain many verses, so there is no one, certain column value which we may relate to. Downloading data from item list is a bit more complicated than from normal form field, but it does not mean that creating such query is hard.

Group “objects identifier” is helpful while constructing a query. Tags from this group are changed to ID/Name (depending on user) indicating specific object in process. It may be process, form field, document type, workflow, step or path.

Let us imagine situation in which we have item list with one column – single line of text “Value”. We want to put value “Bazinga!” in one of the verses, on exit from the step. In order to do that, create SQL validation action on exit from the step.

Configure action as follows:

10

To download all verses “Value” for our list, we have to know name of such field from database. Open “Object identifiers”, look for our process and then item list. In advanced mode, field name DET_Att2 will be displayed (n0. 1 on screenshot).

WFElementDetails table contains all created verses for position lists. DET_WFDID column contains ID of document with our Item list, so it may be use to narrow all records to those which concern only currently browsed document (no. 2 on screenshot). We could end narrowing here but it is good to additionally narrow query result to given item list, even if there is only one list in workflow.

In this example there is only one list, so for document with ID: 22, it will find only verses from “Item list” list.

If in future we would like to add second list to our workflow, then there will be two lists containing DET_Att2 fields and query will check values for both lists. It is worth to protect ourselves from such situation before it occurs by narrowing results to certain item list.

Tag of our item list, which will be changed to its ID, may be also found in menu “Object identifier” – (no. 3 on screenshot).

In the end we will define a message which will pop up if SQL query would return 0, which means that it will not find verse with “Bazinga!” value.

Let us test our solution:

11

According to our assumption, we cannot go any further. But after addition of verse with “Bazinga!” value, system should let us go without any notifications.

Another widely used example of tags usage from “Objects identifier” group may be checking the document type. In situation where we have 2 document types and we want to enforce that every of them uses another path (for example to make; validation, task assignment or omitting some steps, easier). We do not want to allow a situation in which user will make a mistake and will use a path intended for the second document type.

For such purpose, we will use tag from system fields group, indicating document type ID for our document and tag from object identifier group, which indicates one of document types.

We will prepare simple query, which should be pasted to path settings, in “Restrict visibility (SQL)” field:

12

3.Remaining tag groups

System fields” tag group contains elements connected to given document, for which query is executed. Following tags may be found:

–          Document ID, ID of parent document (if exists)

–          Author (name, login, email, login without domain)

–          Document number

–          Assigned person (direct or CC)

–          Affiliated company (all fields describing given company are available)

–          Current step (ID, name, description)

–          Document type or sub-type (if exists)

And couple more elements:

Another group, almost always available, are “Context variables”. It contains such elements as currently logged user, current date, entry-point or information about paths (default path or path chosen to move document)

Third group of tags is “Document number”. It is only available in places where we may define document number for document or workflow. Following tags may be found:

–          Current date (day, month, year)

–          Document entry-point

–          Continuous enumeration (with possibility to configure autocomplete up to 10 signs)

–          Enumeration for given year, month or day

–          Enumeration in context of chosen form field (only for date and time fields)

Additionally, after expanding enumeration tree for given period, we may choose enumeration option also in context of given day/month/year and company. It is worth to note that tough creator allows only autocomplete up to 10 signs, it is possible to manually extend it up to 20 signs.

Last group of tags, which similarly to “Document number”, is available only in couple places, is group: “email template”. This group is available only in places allowing to modify email templates. It contains basic template elements, such as: Element address, site address, list of form fields or message content.

There are also single tags, not available in creator, but it is possible to enter them manually:

–          {AD:parameter} – value of given parameter from AD profile for currently logged user. Acive Directory parameters are available in every place which supports tags. Size of characters in parameter is irrelevant.

–          {R:name} – value of parameter given in request. Values from request are not supported for actions (except Hyperlink action) and for generating documents and printouts (HTML, PDF, docx)

–          {WSS:parameter} – value of parameter given in WSS profile for currently logged user. WSS parameters are not available in every place in which tags are. Size of characters is also irrelevant.

List of all available tags is always available in BPS help (F1 button) in “Tags” topic.

4. Good practices

Why is it worth to use tags in all possible places? Greatest advantage is automatic substitution of tags while cloning process or while moving it between environments. Imagine a situation in which condition of execution of some action is simple IF condition:

If (‘{DTYPE_ID}’ = 54) select 1 else select 0

For our process, an action will always be executed, but if in future we would like to move our process to different server (e.g. from test to production server), there is a risk that after import, ID of such document will be different than 54.

If we will modify query above in given way:

If (‘{DTYPE_ID}’ = ‘{DT:54}’) select 1 else select 0

Then, during process import, BPS will automatically substitute ID of such document type for new ID which was assigned to it.

For example: if ID will change from 54 to 75 then query above would be substituted with:

If (‘{DTYPE_ID}’ = ‘{DT:75}’) select 1 else select 0

Second advantage of tags is higher clarity of BPS process in Studio, which is visible even in example above. If we would see first condition, we would have to search for document with ID = 54 to understand a condition. If we will use second condition, then tag {DT:54} will be automatically changed for name of given document type.

In the end it is worth to add something which should be obvious after reading this article – using tags make work easier and more efficient.

Leave a Reply

Your email address will not be published. Required fields are marked *