Task calculations

The Calculations tab in the task editor holds scripts that run on the server at set points in a task's life: on start, at the end, on recalculation, manually and before takeover. Calculations read and write case variables, change task data and call system functions. Every task type has this tab. For an automatic task, the calculation is its only work. The number on the tab shows how many calculation sections there are.

This article describes how to set up task calculations and when they run. The functions you can call in calculations are described in the Calculations and scripts section.

No.ElementPurpose
1AllShows all calculation sections. The number in brackets is how many there are.
2Active calculation sectionsShows only sections that have at least one run point checked.
3Inactive calculation sectionsShows only sections that do not run.
4Create variableCreates a new template variable without leaving the task.
5Expand all / Collapse allExpands or collapses all sections.
6ActiveSection switch. It can only be turned off: turning it off clears all run points. It turns on by itself when you check a run point.
7On startThe calculation runs when the task starts.
8At the endThe calculation runs when the task is completed.
9On recalculationThe calculation runs when the solver chooses Recalculate in the task.
10ManuallyThe calculation runs when a user opens a waiting Event task in the case's Event window.
11Before takeoverThe calculation runs just before the task is offered for takeover.
12Collapse / expandCollapses or expands this section.
13CopyInserts a copy of the section directly below it.
14RemoveDeletes the section without confirmation. The change takes effect when you save the task.
15MoveDrag the icon to change the order of the section.
16Insert variableInserts an expression at the cursor that reads a template variable or a system value of the task or case.
17ScriptsCalculation scripts from administration that are attached to this section. You can then call their functions in the code. The script label opens its detail.
18SourceThe calculation code as you write it.
19ES6 syntaxThe code the server generated from your source, which is what actually runs. The tab becomes active only after saving.
20HelpOpens the help for calculations.
21Full screenOpens the code in the full-screen Calculation code window.
22Add calculation sectionAdds a new section. The new section stays inactive until you check a run point.

When calculations run

Run pointExactly when
On startWhen the task is activated. For a user task, after the solver is determined. For an email notification, before the email is sent, so the calculation can adjust the values used in the email. For a Smart Event, after it has been executed, so the calculation can process the result. For an external event trigger, before the event is invoked. For a subprocess, before the child case is created. For an event, when it starts waiting.
At the endWhen the task is completed, for all types including automatic ones.
On recalculationWhen the solver chooses Recalculate in the task's More menu. The form is saved first. The item is active only when the task has such a calculation.
ManuallyWhen a user opens a waiting Event task in the Event window in the case detail, before its variables are displayed.
Before takeoverWhen the task becomes a task for takeover, before it is offered to users and notifications are sent.

Within one run point, sections run in the order they appear on the tab. If a calculation ends with an error, the action that triggered it is not completed and the user gets an error message. When debugging, save and test on a test case.

Code and attached scripts

You write the code on the Source tab. The editor suggests template variable names and functions from the available libraries. You read and write variables through the vars object, for example:

const dep = vars['departureDate'].getValue();
vars['travelAllowance'].setValue(days * 600);

After saving, the server generates the code on the ES6 syntax tab from the source, and that code is what runs. The code of attached scripts is inserted before the section code, so their functions are available in the section.

Editing ES6 syntax overwrites the source
You can edit the ES6 syntax tab. The editor asks first and allows the change only after you type ES6 in the confirmation field. After saving, the edited code replaces your source.

The Insert variable field offers template variables and system values of the task and case, for example the task name and comment, due date, solver, case name, status and owner, or a link to the case. An expression that reads the value is inserted into the code.

Example: travel allowance calculation

The automatic task Calculate travel allowance in the sample template “Travel request” has one section with the On start run point. It calculates the number of days of the trip from the departure and return dates and stores CZK 600 per day in the Travel allowance variable. In a test run with a three-day trip, the calculation stored CZK 1,800 and the task was completed immediately.

The Fill in the travel request task has an On start calculation that fills the Traveller variable with the case owner if it is empty.

How to add a calculation

  1. Open the task and click the Calculations tab.
  2. Click Add calculation section.
  3. Check the point when the calculation should run, for example On start.
  4. Write the code in the editor. Insert variables using the Insert variable field.
  5. If you need functions from a shared script, select it in the Scripts field.
  6. Click Save.

Related: Task types, Dynamic conditions: builder, Calculations and scripts section.

Automatic task completion and cancellation
Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)