Skip to content

Using values in the process

Overview

With values, information that is needed in many places is maintained only once: for example the company address, the payment term or a large HTML template for invoices. Each place then contains only a placeholder such as {{value:firma}}.

There are two kinds:

  • Process values apply within one process and belong to its deployment.
  • Account values apply in all processes of the account. A change takes effect immediately, without a new deployment.

In brief

Values are created in the Process Designer via ⋮ → Values and used in the process through a placeholder:

{{value:name}}           whole value
{{value:firma.iban}}     one field of an object

If a value changes, it is adjusted in one place. All mappings, templates and fields of the process use the new state after the next deploy.

Why this helps

Instead of copying the same invoice template into four tasks, it is stored once in the process. The process stays clear and considerably smaller, and a change can no longer be forgotten in one of the copies.

Types

Type Example Usage
Text sender e-mail {{value:absender}}
Number payment term 14 {{value:zahlungsziel}}, also for calculations
Yes/No test mode {{value:testmodus}}
Object company address with name, street, IBAN {{value:firma}} or {{value:firma.iban}}
HTML template invoice template {{value:rechnung_vorlage}} in the PDF or e-mail template

Names consist of lowercase letters, digits and _ and begin with a letter, e.g. firma or rechnung_vorlage.

No passwords in values

Values are visible to everyone who may edit processes, and they appear in the data of the instances. Passwords, API keys and tokens belong in Secrets; a value may contain a secret placeholder, for example in a configuration. Account values can be up to 900 KB in size; values can be created by anyone who may edit processes.

Creating and managing values

Creating a new value

  1. Open the Process Designer.
  2. Select ⋮ → Values at the top right.
  3. Select New value.
  4. Fill in the form:
    • Name: identifier in the placeholder, e.g. firma.
    • Display name: readable name for the overview, e.g. “Company address”.
    • Type: text, number, yes/no, object or HTML template.
    • Value: the content. An HTML template is maintained via Edit HTML in the HTML editor, an object is entered as JSON.
  5. Select Create.

The finished placeholder is shown under the name. Copy placeholder copies it to the clipboard.

Overview

The list has the tabs This process and All processes and shows the placeholder, the type and a short preview of the content for each value. Usages names the places in this process and the deployed processes that use the value; clicking a place jumps to the element in the diagram.

Editing or deleting a value

  • A value is edited with the pencil icon.
  • A value is deleted with the trash icon. If it is still in use, the confirmation prompt names the number of places.

If a value in use is deleted or renamed, the process can only be deployed again once the placeholders have been adjusted. The BPMN validation shows the affected elements.

Using values

In mappings (JSONata)

A placeholder can be placed anywhere in the mapping where a value is needed:

{
  "verkaeufer": {{value:firma}},
  "faellig_in_tagen": {{value:zahlungsziel}} + 7,
  "betreff": "Rechnung von {{value:firma.name}}"
}
  • If the placeholder stands on its own, the value is inserted with its type: an object as an object, a number as a number.
  • If it is inside quotation marks, the value is inserted as text into the text.

The check and the preview in the JSONata editor work with the values of the process.

In templates and text fields

In PDF and e-mail templates, subject, file name, business label and other text fields, the value is inserted as text, e.g.:

<p>IBAN: {{value:firma.iban}}</p>

Placeholders of the template itself such as {{rechnungsnummer}} are not affected.

Conditions at gateways

A value can also be used in gateway conditions, e.g. $(betrag) > {{value:freigabegrenze}}.

One template for several tasks

Often the same PDF template is used in several tasks, for example in the preview of the start form, in “Rechnung bearbeiten” (edit invoice) and in “Rechnung erstellen” (create invoice). This is how it becomes a value:

  1. Select ⋮ → Values → Take over template from task.
  2. Choose the task. The list shows how often the same template occurs in the process.
  3. Check name and display name, choose whether the value applies to this process or to all processes, and select Create.

Only the value is created in this step. The tasks remain unchanged until they use the value themselves.

Using the template at a task

At every task with a PDF template or e-mail text, Template from value: Use value ▾ is shown next to the template:

  1. Open Use value.
  2. Select the HTML template. If the task still has its own template, a confirmation is requested first; this can be reverted with Undo.

The button then shows the name of the value. Unlink (own copy) gives the task its own template again with the current content.

Continuing to edit the template at the task

If the PDF designer or the HTML editor is opened at a linked task, the template from the value appears. The save button is then called Save to value “…”: the change applies to all tasks that use the value.

Values for all processes (account values)

Information such as company address, bank details or logo is usually needed in many processes. Account values exist for this:

  1. Open ⋮ → Values and choose the tab All processes.
  2. Select New value and under Applies to choose the option All processes (account value).
  3. Enter name, type and value and select Create.

An account value is used with the same placeholder as a process value, e.g. {{value:firma.iban}}.

  • Precedence: If a process has its own value with the same name, the process value applies there. The list indicates this with “overrides account value”. With {{value:global:firma}} the account value is used explicitly.
  • Usages: Usages shows where the value is used in the open process and which deployed processes use it.
  • History: Every change stores the previous version. An earlier version is restored via the history icon.
  • Deleting: An account value can only be deleted once no deployed process uses it any more.
  • Renaming: Account values keep their name because other processes use it.

“Take over template from task” can also create a template directly as an account value – for example when invoice and cancellation invoice are to use the same template.

When does a changed value take effect?

  • Process values belong to the process. A change is saved like any other change in the Designer and applies to instances from the next Deploy onwards.
  • Account values are saved immediately and apply from the next step of every instance, including running instances. A new deployment is not necessary.
  • Exception start events: The schedule of a timer start and the fields of a start form are fixed at deploy time. If an account value used there changes, the process is redeployed.

Frequently asked questions

Can a value be used in several processes?

Yes, as an account value in the All processes tab. It applies in all processes of the account.

Are placeholders in form data replaced?

No. Only what is in the Process Designer is replaced. If someone types {{value:…}} into a form, the text remains unchanged.

What happens with a placeholder without a value?

The BPMN validation reports “Value does not exist”, and the process cannot be deployed.

Can an HTML template itself contain values?

Yes, e.g. {{value:firma.name}} in the footer. Nesting is possible up to three levels deep.

Next step

Secrets: passwords and keys separate from the values.