Implementation handbook – a few words about Initialization

Facebooktwitterpinterestlinkedinmail

applies to version: 8.2.x; author: Bartłomiej Spyrka

special thanks to: Damian Matuła

When designing Processes that include Item list type Form fields (invoices, registering work hours), you may encounter a situation where it is necessary to enter a very large amount of data. Processes that require you to enter a multitude information will test the patience of even the most resilient Workflow users, furthermore it is inefficient time wise.

When the work performed by a user is sufficiently repetitious, and follows a specific set of rules, their experience can be vastly improved by a useful function – Item list Initialization

Essentially, Initialization is the automated filling out of Form fields, with minimal effort from the employee.

Example:

In this article, we will demonstrate the Initialization function for Item lists on a simple workflow, which registers if the employees working shifts are present or not, in a certain enterprise called XYZ.

Take a look at the following workflow;

1

Fig 1. Workflow schematic

The Registration Step is by far the most crucial, since the Item list will be created and edited here. The other steps won’t be discussed in this article, since they are not relevant in any way to the topic of Initialization.

Form design:

2Fig 2. Initialization – Form layout

The Form we will be using to discuss our initialization scenario is presented above. The entire Form is in Edit mode, however the option to manually add rows is disabled, and the button to automatically load default values is visible. Enabling/disabling the aforementioned functions is optional. If you would like to employ Initialization at some point, it’s helpful to explore the options available for Item lists on specific Steps. For more information on enabling extra Item list functions (buttons) for individual Steps [click here].

3

Fig 3. Extra Item list functions for individual Steps

 Once we have a basic Form for our workflow, we can attempt to implement Initialization.

Initialization basics

4

Fig 4. Initialization configuration screen

The Initialization process is configured from Item list settings. Select the desired Item list Form field and click Advanced configuration in the bottom right. Go to the Initialization tab.

Fundamentally, we have access to two ways of defining how many rows we want to Initialize:

  1. Static – Useful mainly for initializing one row, to avoid clicking the “Add row” button for the first time. Rarely used. This option will fill out rows according to what you enter in the settings fields (Click “Add” and fill out the information that will be entered into the desired number of rows at the start).
  2. Dynamic SQL – The advanced option, vastly superior in terms of complexity and potential uses. Allows us to use an SQL query to designate the values which will be entered into the rows of our Item list. We will be expanding on this option in the article.

We can select when to induce the Initialization process:

  1. Initialize only in the first step – Only used on the first step of the Workflow.
  2. Initialize on every step – Initialize data for sub-elements on other Steps, where they appear for the first time.

Since the launch of BPS 8.0, we aren’t realistically bound by the constraints mentioned above, thanks to the option of writing custom JavaScript codes. We will discuss creative ways of implementing JS codes later in the article.

Data Initialization via SQL query

Constructing an SQL query for Initialization purposes is relatively easy. Of course, the complexity of the query is totally dependent on the scenario, in which we want to employ it. In our example, we want to Initialize an Item list with consecutive calendar days – from a start date to an end date – this data will be loaded from appropriate Form fields. However many results the query returns (difference between the start and end date), that many rows will be initialized, including the possibility that the query returns nothing at all, and no rows are Initialized.

The SQL query doesn’t need to be defined as a function, it may be structured like a regular query.

Query structure:

SELECT ‘sample text’ as ‘DETT_att1’, ‘{12}’ as DET_Att2

The query is structured like so: ‘value’ – ‘column to which the value is loaded’. So the ‘sample text’ will be assigned to the DET_Att1 column on the Item list, and the value of the Form field with the ID of 12 will be assigned to column DET_Att2.

But how to find out what the ID or the correct DET is? Take a look at the following screenshot:

5

Fig 5. Column mapping

Let’s look back at our example and the SQL function we mentioned earlier – Let’s define an SQL function with two parameters (start date, number of days) which will generate a number of rows corresponding to the ‘days’ parameter. Below is an example how such an SQL function could be structured:

sql1

Fig 6. SQL function

Entering start parameters (Date from: 29/04/2015, 5 days) and launching the query will return the following results:

sql2Fig 7. Query result

Now that we have a working function, we can implement it in the Initialization tab.

sql3en

Fig 8. Item list Initialization SQL query – with  advanced view

In the above configuration, take note that the query returns columns named date and dateName which need to be mapped correctly to corresponding columns in our Item list (in our case: DET_Att2 and DET_Att3). On the ‘Advanced view’ part of the screenshot, take note of the values of two Form fields used (‘Date from’ taken from ID=738, number of ‘days’ taken from ID=740).

Initialization in practice

When we want to verify our initialization process in practice, we need to do three things inside the Form interface:

  1. “Start date” field (Enter the date from which the function will start counting)
  2. “No. of days” field (Enter the number of rows the function will generate)
  3. “Load default” button – button launching the Initialization process

6

Fig 9. Form view

Filling fields 1 and 2 and pressing the button will cause our parameters to be delivered to the SQL function which will generate the necessary amount of rows.

6el2

Fig 10. Initialization result with “Days” being three

Technically we could end the article right here, however it begs the question “Can we automate this process even more?” – Yes we can! Amongst many other functions, we can:

  1. Calculate the number of days between the start and end date automatically
  2. Changing the „Date to” automatically launches the Initialization process

Automating the Form

We will discuss how to implement the two points mentioned above. The first point can be realized with a JavaScript function which calculates the number of days between “Date from” and “Date to”. This function is configured in the Workflow node, in the ‘Style and behavior’ tab

sql4

Fig 11. JS function calculating the number of days between two dates

Enter the above function code into the “Script to be executed on value change” field found in the “Style and behavior” tab, do this for every relevant Form field. In our case this would be the “Date to” Form field. The result from this script should be automatically entered into the “Days” (AttText1) Form field .

JAVA1en

Fig 12. Scripts for calculating the difference between two dates.

Thanks to the above configuration we have automated the process of calculating days between the two dates available in the Form. In result, the “Days” field which states the number of days is not relevant anymore and can be relegated to existing only as a technical field – the user won’t have to ‘manually’ count the number of days between the start and end dates. The “Days” Form field can now also be hidden from the user.

The second point is also relatively easy to carry out. Version 8.0+ introduced support for extra JavaScript functions, specifically for operating on Item lists. Click the Edit button under a „JavaScript code” field, and the editor should pop up. Navigate to the Item list tab.

java2en

Fig 13. JavaScript and Item lists

Our goal for this exercise is to: – automatically copy updated data to the Item list after registering a change in the “Date to” field – to that end, we will employ the following function:

SubelementInitialization(741);

Where 741 is the ID of our Item list (Initialization).

Executing the above JS function is as simple as typing it into the correct JavaScript code field (“Date to” Form field options -> Style and behavior -> Script to be executed on value change section). However, you must keep in mind that the order in which “… on value change” scripts are executed does matter.

Below is the correct JavaScript code “to be executed on value change” for the “Date to” Form field (found in the “Style and behavior” tab)

java3en

Fig 14. JavaScript for changing the „Date to” field.

The final result is an Item list, which automatically generates a number of rows based on 2 parameters entered by a user.

7

Fig 15. An automatically generated Item list

Summary

BPS version 8.0+ brings a few interesting Item list features to the table. One of them is Initialization which can be tweaked to benefit the Workflow user greatly, automating a lot of menial labor and improving their general experience with Item list type Form fields.

 

2 thoughts to “Implementation handbook – a few words about Initialization”

  1. Greetings
    In the workflow I need to add some rows in one step and in another step edit only some columns in stored rows. In the second step i dont want to add or delete more rows.
    Does it exist in Webcon javascript functions which enable or disable item list Action buttons like Add, Delete or Clone ?

    1. Hello,
      Yes, it is possible even without JS, very easily in fact!

      In BPS 2016:
      You will need to go to the configuration of the step where you want the buttons to be disabled, so: go to your Workflow -> General tab -> Double-click “Step 2” to open step configuration -> Forms

      Now find the Item list and open its configuration (the icon that looks like a screwdriver crossed with a wrench).
      At the very bottom, you will see “Break inheritance” – click this to edit this Item list’s behavior independently from its global configuration. So in your case, you will want the “Allow add/delete/clone” buttons to be left unchecked.
      And that should do the trick.

      Editing an Item list’s behavior on individual steps is also available in older versions (8.2, 8.3), only the form configuration looks different.
      If you need more directions feel free to ask!

      Thanks,
      Grzegorz Straś

Leave a Reply

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