Variables are used to dynamically insert the value of form fields, the results of actions, certain system properties and more. They are available to templates, most settings of actions and data base queries.

As a common use case, consider a form allowing a user to enter their email address. When you would like to send an email to the address they entered, variables must be used.

Contents

Using variables

Using variables for actions

Form fields can be selected by clicking on the variable icon to the right of each action setting supporting variables.

Using variables for templates

The variable selection menu can be opened either by clicking the button the the right hand side of the template editor or by pressing Ctrl + Space.

Variable types

Form elements

Syntax: [%<FormFieldName>%]

This variable takes the value of the form field with the specified name. They are used mainly for actions such as Email, Create text file, Database query as well as for Templates.

Example: The variable [%tfEmail%] will take the value of the input field named tfEmail.

Form elements with repetitions

Syntax: [%<FormFieldName>_<index>%]

By default, the variable of repeating form elements will list the values separated by commas. Individual repetitions can be accessed in the workflow via an index in the variable. The index starts at zero and is incremented by one for each repetition. For all repetitions of a form element, the variables must be added according to the maximum number of repetitions (option "Max repetitions").

Example for repetitions of the variable [%tfName%]: [%tfName_0%], [%tfName_1%], [%tfName_2%]

Question element variables

To access the values of select elements displayed as questions, you can use the following variables. Assume the select element is named sel1, has got 3 questions Q1, Q2, Q3 and 3 answers A1, A2, A3, and also assume these answers are selected:

Then:

• [%sel1%] resolves to A1;A1,A2;A1,A2,A3
• [%sel1_0%] resolves to A1, [%sel1_1%] resolves to A1,A2, and [%sel1_2%] resolves to A1,A2,A3

Function placeholders

Function placeholders are not actually placeholders in their own right. This is more about additional functions for a form placeholder. An example form for the available functions is available in the formcycle templates.

Note: The function placeholders are intended for the workflow. They are not supported within calculation elements and formula conditions.

Syntax: [%<fieldname>.<function>(<parameter>)%]

lst("value")

Syntax: [%selectionfield.lst("value")%]

The lst function can be used on selection elements that obtain their values from a data source and enables access to the values of any columns (data source / database). For example, it is possible to realise that if "Ms" is selected in a selection, a different value is returned via the lst function. For example, "Dear Mrs".

Example Data source/Designer/Workflow:

lsttitle()

Syntax: [%selectionfield.lsttitle()%]

The lsttitle function returns the value of the title for selection elements. In contrast to lst, no data source is required as a basis here. However, the example "Dear Madam" can also be implemented here.

Example Designer/Workflow:

lsttxt()

Syntax: [%selectionfield.lsttxt()%]

The lsttxt function returns the value of the text for selection elements. In contrast to lst, no data source is required as a basis here.

Example Designer/Workflow:

Other function placeholders

cnt()

Syntax: [%element.cnt( )%]

Returns the number of elements of the selection element. This function can only be used if the element is dynamic.

con("value")

Syntax: [%element.con("value")%] or [%element.con("value" | "value" | "value")%]

Returns 1 if one of the specified values applies, otherwise 0 is returned.

empty()

Syntax: [%element.empty( )%]

Returns 1 if the specified value is empty, otherwise 0 is returned.

rep("source" # "target")

Syntax: [%element.rep("source" # "target")%] or [%element.rep("source1" | "source2" # "target1" | "target2")%] 

rep stands for replace. If the first value matches, it is replaced with the second value. 

Example 1: 

If the value of the element is "on", it is replaced by "x".

element.rep("on" # "x")

element.rep("Ms" | "Mr" # "female" | "male")

Special form elements

There are some special variables available:

[%xf-action%]

The name of the button used for submitting the form. Could be used to execute an action in the workflow only when a certain button was used (by adding an appropriate condition to the action).

[%lang%]

Refers to the language of the form when it was filled out, eg. de, de-CH, en, or fr-FR.

Insert multiline text (from editor) with breaks

If an editor field is inserted via a form placeholder in e.g. an e-mail or text file (HTML), the breaks are removed, because the system tries to interpret HTML here.

To achieve this, call up the source code viewin the e-mail action. The following section must then be inserted at the desired position. The form placeholder must then be modified accordingly:

<pre style="font-family: inherit;white-space: pre-line !important">
[%edExplanation%]
</pre>

System variables

Syntax: [%$<Name>%]

System variables take the value of the corresponding system value. The following system variables are available for actions and templates:

[%$CLIENT_ID%]

The client ID of the client of the current form.

[%$DEFAULT_MAIL_SENDER%] 7.3.0+ 

Returns the e-mail sender (system) for the configured mail server. If a separate mail server is configured under Client > Settings, these configuration will be used, otherwise the system e-mail server.

[%$DEFAULT_MAIL_SENDERNAME%] 7.3.0+ 

Returns the sender name (system) for the configured mail server. If this is not configured, an empty string is returned.

[%$CLIENT_MAIL_SENDER%] 7.0.4+ (deprecated)

Returns the mail sender address of the client. If none has been set then an empty string will be returned.

[%$CLIENT_MAIL_SENDERNAME%] 7.0.4+ (deprecated)

Returns the mail sender name of the client. If none has been set then an empty string will be returned.

[%$FORM_LINK%]

The URL of the current form.

[%$FORM_PROCESS_LINK%]

Absolute Internet address for viewing a submitted form, pre-filled with the data of the process. A login is not mandatory unless the current status of the form requires it.

[%$FORM_REVIEW_LINK%] 

Absolute Internet address for viewing a submitted form, pre-filled with the data of the process. A login is mandatory.

[%$FORM_VERIFY_LINK%]

The URL to confirm Double opt in. Can only be used once.

[%$FORM_INBOX_NAME%]

Returns the inbox name the form record currently resides in.

[%$FORM_INBOX_LINK%]

Returns the inbox link the form record currently resides in.

[%$FORM_INVITE_LINK%]

Returns the invitation link of the form.

[%$FORM_HISTORY_HTML%] 7.2.0+ 

Returns the the history of a form record as (HTML) table.

[%$PROCESS_ID%]

The current process ID of the form record.

[%$PROJECT_ALIAS%]

The alias of the current form.

[%$PROJECT_ID%]

The form ID of the current form.

[%$PROJECT_TITLE%]

As of version 7, [%$PROJECT_NAME%] is now called [%$PROJECT_TITLE%] .

The title of the current form.

[%$RECORD_ID%]

The ID of the current form record.

[%$RECORD_READ%]

Whether the current form record was read. Evaluated as a Boolean, i.e. true or false.

[%$RECORD_UNREAD%]

Whether the current form record was not read. Evaluated as a Boolean, i.e. true or false.

[%$RECORD_ATTR.<customAttrKey>%]

  Read user-defined form record attributes (e.g. [%$RECORD_ATTR.loopCount%]). This allows values to be stored on the form record and accessed in any action.

[%$SOURCE_SERVER%]

The name of the server that has provided the current form, either the name of the frontend server or the local server.

[%$SOURCE_SERVER_URL%]

The URL of the server that has provided the current form, either the name of the frontend server or the local server.

[%$STATUS_ID%]

The ID of the current state.

[%$STATUS_NAME%]

The name of the current state.

[%$STATUS_TYPE%]

The type of the current state. These four values are possible: RECEIVED , SAVED, ERROR and CUSTOM (Custom status created by user).

[%$TRIGGER.actionName%]

The name of the action of the providing event.

[%$TRIGGER.taskName%]

The name of the task where the action of the event is located.

[%$TRIGGER.triggerName%]

The name of the event where the action of the event is located.

[%$COUNTER_CLIENT.<name of the counter>%]

The current value of a client counter.

System variables with parameters

Syntax: [%$<Name>(<Parameter>...)%]

[%$DATE("<format>", <lang>)%]

Current date. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the java.text.SimpleDateFormat for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: 

[%$DATE("yyyy/MM/dd", en-GB)%]

[%$FORM_DATE_CREATED("<format>", <lang>)%]

Creation date of the form record. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the java.text.SimpleDateFormat for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: 

[%$FORM_DATE_CREATED("yyyy/MM/dd", en-GB)%]

[%$FORM_DATE_MODIFIED("<format>", <lang>)%]

Available with formcycle version 6.0.5{{/info}} Last change date of the form record. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the java.text.SimpleDateFormat for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: 

[%$FORM_DATE_MODIFIED("yyyy/MM/dd", en-GB)%]

User variables

User variables may be used in actions, templates, data base queries or directly in form elements for prefilling the form (see figure).

There are three user objects available which can be used to access information about the user (user profile). If a user variable is being used without any attributes (e.g. [%$USER%]), all user information will be returned in JSON format.

For sensible use of the user variables it is necessary to enable form login. If this is not configured the user object will be set to an anonymous user.

User objects

[%$USER%]

User object for accessing the current user.

[%$LAST_USER%]

User object for accessing the last user.

[%$INITIAL_USER%]

User object for accessing the user that submitted the form.

Attributes

Using attributes on user objects permits access to specific user information. The following attributes are available for all users but may not always have a value. If the attribute contains a value depends on the authenticator being used for logging into the form.

Example: The user variable [%$USER.mail%] returns the email address of the user that has logged into the form.

authTypeId

ID of the authenticator the user chose for login.

displayName

Display name of the user

familyName

Family name of the user

firstName

First name of the user

gender

Gender of the user

groups

Group names of the user

id

ID of the user. (system ID for formcycle users)

linkedId

A user profile may have a linked identifier, which is the identifier of another user profile.

locale

Language of the user

location

Location of the user

mail

email address of the user

phone

phone number of the user

pictureUrl

URL to the profile picture of the user

profileUrl

URL to the profile of the user

rawData

All the information about the user in a JSON format. Depending on the chosen authenticator, the raw data may include additional information about the user that can otherwise not be accessed through attributes.

role

Role of the user

title

Title of the user

typedId

Type of the authenticator the user chose for login.

userName

user name

Appointment variables

Appointment variables can be used when appointments are booked with the form.

Syntax: [%$<Name>%]

[%$APPOINTMENT_LIST%]

Creates a summary of the dates booked with the form record in the form of a ul HTML list. For each appointment a button is also created, with which the booked appointment can be added to a calendar. This variable is intended for use in HTML templates.

[%$APPOINTMENT_LINK%]

Creates a link to an iCal file that contains all the dates of the form record.

System variables for HTML templates

Syntax: [%$<Name>(<Parameter1>,<Parameter2>)%]

In addition to the system variables available to both workflow actions and templates, the following variables can be used only in HTML templates. They are used for downloading attachments and are valid for the same browser session that was active when the form was submitted.

[%$ATTACHMENT_LIST%]

Inserts a list with all available attachments that can be downloaded. This will create an ul element.

[%$ATTACHMENT_ZIP=fileName,linkText%]

Creates a link for downloading all attachments as a zip archive. Optionally you may specify the parameters fileName and linkText. The following variations are possible:

[%$ATTACHMENT_ZIP=fileName,linkText%]

Creates a link with the text linkText for downloading all attachments a zip archive that will be named fileName.

[%$ATTACHMENT_ZIP=fileName%]

Creates a link with the text fileName for downloading all attachments a zip file that will be named fileName.

[%$ATTACHMENT_ZIP%]

Creates a link with the textattachment.zip for downloading all attachements as a zip file named attachment.zip

[%$ATTACHMENT=attachmentName,linkText,fileName%]

Creates a link for downloading a single attachment with the given name that must have been created as part of the workflow processing. The parameters linkText and fileNameare optional, allowing for the following combinations:

[%$ATTACHMENT=attachmentName,linkText,fileName%]

Creates a link with the text linkText for downloading a single attachment with the name attachmentName as a file named fileName.

[%$ATTACHMENT=attachmentName,linkText%]

Creates a link with the text linkText for an attachment with the name attachmentName.

[%$ATTACHMENT=attachmentName%]

Creates a link for downloading an attachment with the name attachmentName.

When the specified attachment does not exist, these variables will not have any effect and will be removed from the rendered HTML template.

Template variables

Syntax: [%$$<Name>%]

A template variables takes the value of the content of a template (for example text, email, or link) and can be used by workflow action such as Email.

Action variables

Syntax: [%$<actionName>.<returnValue>%]

Some actions have got return values that can accessed by action variables.

These variables look similar to system variables, but they contain a period as a separator for the action name and the return value. The following action variables are available.

[%$<actionName>.SUCCESS%]

Whether the action could be processed successfully. Evaluates to a boolean, ie. true or false.

[%$<actionName>.RESULT%]

A single return value. Evaluates to a string value.

[%$<actionName>.RESULT.<Identifier>%]

Returns a specific value from a result. Evaluates to a string value.

[%$<actionName>.RESULT[<Index>].<Identifier>%]

Most actions may return more than a single value, but a set of named values. Which values are available depends on the type of action. You can click on the small info icon at the top right corner of an action to see a list of available values and the corresponding placeholders to access those values.

[%$<actionName>.RESULT[<Index>].<Property>%]

Some actions return a JSON array with the results, for example database statement. Each entry in the JSON array is a JSON object, with the key corresponding to the name of the database column. The index i starts with 0. Which properties are available depends on the action. You can click on the small info icon at the top right corner of an action to see a list of available values and the corresponding placeholders to access those values. 

[%$<actionName>.RESULT.rows.length()%]

If several results are returned, the number can be returned in placeholder values using .length().

[%$<actionName>.ERROR_CODE%]

In case of error the thrown error code of the action.

[%$<actionName>.ERROR_MESSAGE%]

In case of error the thrown error message of the action.