search string side menu

Business process designer > Document templates / Template syntax

Template syntax

Document templates that you use in the system can contain text, variables, functions, conditions, and loops. When adding a template to a business process, these components are bound to process context variables so that the generated document is completed with process data.

Variables

All the variables in a template must be unique and have the following form: {$variable_name}. For example, you can use the {$contractor} variable to insert the contractor’s name in an agreement created within a business process.

In the template you can use field attributes from the app context, i.e. access nested variables. Available for fields of the Files, Users, App, Arbitrary app, etc. type.

For example, an order has the Contract field (code contract), where the contract file is loaded, and the Client field (code client), where the Contacts app item is added. In the generated document you can display the file name or phone number of the client. To do this, the syntax of the template uses the code of the field from the source appl and the code of the nested variable separated by a dot: {$contract.__name} or {$client.phone}.

When writing functions, arguments and variable values are enclosed in quotation marks. The following types of quotation marks are allowed: “ ”, «», " ", " ", ' '.

Functions

Functions for working with strings

These functions allow you to display text in different formats.

For illustration, we will use the $string1 variable and the phrase Order shipped as its value.

  1. UpperCase(<param1: string>). Converts text to uppercase.

начало примера

Example:

{UpperCase({$string1})} —> ORDER SHIPPED

конец примера

  1. LowerCase(<param1: string>). Converts text to lowercase.

начало примера

Example:

{LowerCase({$string1})} —>  order shipped

конец примера

  1. Capitalize(<param1: string>). Capitalizes the first word in the text.

начало примера

Example:

{Capitalize({$string1})} —> Order shipped

конец примера

  1. Substr(<param1: string>, <length: number>, <from: number>). Removes part of the text according to the specified number of symbols. Example:

начало примера

Examples:

  • {Substr({$string1}, 0, 3)} —> Ord;
  • {Substr({$string1}, 4)} —> r shipped.

конец примера

 

ToString() function

The ToString function allows you to insert the following data types into your document:

You can read more about the types of data used in the system in the System data types article.

Number

Syntax: ToString(param1: number, <format: string>, <locale: string>)

For illustration we will use the variable $int1 and its value 546.

начало примера

Example:

{ToString({$int1})} —> 546

конец примера

By default, the number is displayed as digits. Use the astext format to write it as text.

начало внимание

Please note that fractions cannot be displayed as text.

конец внимание

начало примера

Example:

{ToString({$int1}, astext)} —> five hundred forty-six

конец примера

You can specify a locale to output as text in another language. Available locales:

  • English: en-US or en
  • Russian: ru-RU or ru

начало примера

Example:

{ToString({$int1}, astext, en–US)} —>five hundred forty-six

конец примера

 

String

Strings allow you to add text-based information to your document.

Syntax: ToString(param1: string).

For illustration, we will use the variable $str1 and its value sent for approval.

начало примера

Example:

{ToString({$str1})} —> sent for approval.

конец примера

Category

The Category data type is used for selecting a value from a list, for example, when users choose the payment method: credit card or cash.

Syntax: ToString(param1: category).

When a context variable of this type is created in a process, it is given a name and a code. Specify the code in the ToString function so that the name of the variable is added to the document.

For illustration, we will use the variable $enum1 and payment with credit card as its value: { "code": "card"; "name": "credit card" }.

начало примера

Example:

The selected payment method is {ToString({$enum1})} —> The selected payment method is credit card.

конец примера

Also, for the Category data type, you can output the category name and code to the template without using the ToString function.

начало примера

Example:

  • The selected payment method is {$enum1.name} —>  The selected payment method is credit card.
  • The selected payment method is {$enum1} —> The selected payment method is credit card.
  • Code of the used category: {$enum1.code} —> Code of the used category is card.

конец примера

 

Yes/No switch

This data type has two variants: Yes and No. You can rename them, for example, to Approved and Rejected.

For illustration, we will use $bool1 = true. The Yes variant (yesValue) is renamed as Approved.

начало примера

Example:

{ToString({$bool1})} —> Approved.

конец примера

Money

You can convert an amount of money to text in various formats.

Syntax: ToString(param1: money, <format: string>, <locale: string>).

The following format values are available:

начало примера

Example:

short  —> 1,005.56 (separators depend on the locale)

sign —> USD1,005.56

full —> 1,005 US dollars 56 cents

astext —> One thousand five US dollars 56 cents

wildcard —> you can specify your custom format, for example, {ToString({$money1}, "%i usd %f cents")}. In this case the amount will be converted to text in the following manner: 1005 usd 56 cents (%i is the integer part, %f is the fractional part).

конец примера

Full name

You can insert a person’s full name into a document.

Syntax: ToString(param1: full name, <format: string>, <case: string>).

Available format values:

long. Use it to insert the last name, first name, and the middle name (Anna Maria Quan).

short. Use it to insert the last name and the initials (A M. Quan).

Available case values (for languages where they are applied):

nominative — nominative;

genitive — genitive;

dative  — dative;

accusative — accusative;

instrumental — instrumental;

prepositional — prepositional.

If you want to specify a person’s first name, last name, or middle name by itself, use values from the Full name variable, for example, {$executor.fullname.firstname}, {$executor.fullname.lastname}, and {$executor.fullname.middlename}.

Phone number

You can set up a mask for phone number input by using the following syntax: ToString({$phone1}, "+1–XXX–XXX–XX–XX")

The phone number is filled in with numbers from left to right. Let’s use 16504998877 as an example.

начало примера

The phone number is filled in with numbers from left to right:

  • {ToString({$phone1}, "+7—XXX—XXX—XX—XX")} —> +1-650-499-88-77
  • {ToString({$phone1}, "X—XXX—XXX—XX—XX")} —> 1-650-499-88-77
  • {ToString({$phone1}, "XX—XX—XX")} —> 99-88-77

конец примера

Date/Time

You can add a date and time to you template, for example, to specify the delivery date in a supply contract.

Syntax: ToString(param1: date/time, <format:>, <locale: string>)

This data type has three options: Date/Time, Date, and Time.

Without specifying any additional arguments, the document displays the current date and time.

начало примера

Example:

{ToString({$date1})} ->

  • Date/Time: 8/24/22 1:30:00 pm
  • Date: 8/24/22
  • Time: 1:30:00 pm

конец примера

If you use the short format in the function ({ToString({$date1}, short)}), seconds won’t be indicated.

начало примера

Example:

{ToString({$date1}, short)}->

  • Date/Time: 8/24/22 1:30 pm
  • Date: August 24, 2022
  • Time: 1:30 pm

конец примера

When using the long format, the time will include seconds, and the date the month name:

начало примера

Example:

{ToString({$date1}, long)}->

  • Date/Time: 8/24/22 1:30:00 pm
  • Date: April 24, 2022
  • Time: 1:30:00 pm

конец примера

You can specify a locale:

  • English: en-US or en
  • Russian: ru-RU or ru

начало примера

Example:

{ToString({$date1}, short, en–US)} ->  8/24/22 1:30: pm

конец примера

Please note that the Date/Time type takes into account the time zone of your company and shows the date accordingly. The Date and Time types show absolute values.

Example

To illustrate the use of the function in document templates, we created an agreement template and completed it with different variables and functions.

Then we added it to a business process and bound the template variables to the process variables.

sodt1

During process execution, users fill in the data, and once the process flow reaches the Generate from template activity, the system automatically creates the agreement.

8.PNG

Click here to download the template used in this example.

DateTime() function

The DateTime() function is used to display date and time in any format. You can also specify the locale.

Syntax:DateTime(<format:string>,<variable:date\time>,<locale>).

For example, you can specify the date and time an app item was created.

начало примера

Example:

{DateTime(«YYYY–MM–DD hh:mm:ss»,{$__createdAt},"ru_RU")} —> 2021–01–21 08:30:56

конец примера

The template supports the following quotation marks: " ", « », “ “, ” ”, ' '.

начало примера

Examples:

  • {DateTime('"DD" MMMM YYYY',{$__createdAt},"en_US")} —> "31" August 2023;
  • {DateTime("«DD» MMMM YYYY",{$__createdAt},"en_US")} —> «31» August 2023;
  • {DateTime(«'DD' MMMM YYYY»,{$__createdAt},"en_US")} —> '31' August 2023.

конец примера

Data formats

Display options:

M: month (1)

MM: month (01)

MMM: month (Jan)

MMMM: (January)

D: day (2)

DD: day (02)

DDD: day (Mon)  

DDDD: day (Monday)

YY: year (06)

YYYY: year (2006)

hh: hours (15)

mm: minutes (04)

ss: seconds (05)

Locales:  

English (United States): en_US

English (United Kingdom): en_GB

German: de_DE

French:fr_FR

Russian:ru_RU

Spanish: es_ES

Now() function

To add the current date and time with regard to your time zone, use the Now function.

Syntax: Now(<format: string>, <locale: string>, <timezone: string>)

With each format value the date is displayed differently.

Available format values

  • date —> date (8/12/22);
  • time —> 10:34 am;
  • timelong —> 10:34:22 am;
  • datelong —> April 13, 2019.;
  • short (default) —> 8/12/22 10:52 am.

English language en–US and Russian ru–RU are available for locale.

timezone is set in the format America/Toronto.

начало примера

Examples of function syntax:

  • {Now(datelong, en-US)}. Long date, en-US.
  • {Now(datelong, en)}. Long date en.
  • {Now(datelong, en)}. Date only en.
  • {Now(datelong, ru-RU)}. Long date ru-RU.

конец примера

 

Barcode function

To encode a String type field in an app and add it to a document as a barcode, use the Barcode function. For instance, you can use it to generate a barcode for a contract’s registration number or another unique number assigned to a document. Later you can use this barcode to match the hard copy of a document with its digital version.

You can use barcode scanning software in ELMA365 if you configure an appropriate integration module. Read more about it in Standard modules and Introduction to Web API.

The system allows you to generate barcodes for Word and Excel files.

Syntax:GenerateBarcode(<text: srting:1>, <format: code format:2>, <height of the generaed barcode in pixels>). Specifying the height is optional.

[1]: the content of the string depends on the format specified in the second parameter.

[2]: available barcode formats and requirements to the string:

  • QR Code: any string.
  • EAN-8: a string consisting either of 7 digits or of 8 digits (seven digits and a check digit).
  • EAN-13: a string consisting either of 12 digits or of 13 digits (twelve digits and a check digit).

[3]: barcode height in pixels is an optional parameter. For correct recognition, the height is specified based on the number of characters used.

If you have system version 2023.11 or higher, you can specify the EAN format without specifying the type. In this case, the barcode will be generated and its type will depend on the number of digits in the transmitted string.

If the template uses the same string to generate a QR code twice, but specifies a different size, a QR code of the same size will be generated in both cases.

начало внимание

If no checksum was specified when using EAN formats, it will be added automatically. For correct operation, the barcode scanner must be configured to work with these formats.

конец внимание

It is recommended to use the QR Code format, as it can be applied to a greater variety of data, while the EAN formats are limited.

For example, there is a variable $numberstring, and its value is 5901234123457. From this string, a QR code or an EAN-13 can be generated.

начало примера

Examples:

  • {GenerateBarcode({$numberstring}, "QR Code", "125" )};
  • {GenerateBarcode({$numberstring}, "EAN-13", "125" )}.

конец примера

For an EAN-8, the string can only include 8 digits: $numberstring = "59012341".

If a QR code is generated twice based on the same string in a template, but the size in pixels is different, the generated QR codes will be of the same size.

JobPosition() function

This function is used to get a user’s job position.

Syntax: JobPosition(<param1: user>, <format:string>)

You can use the «first» variable to get only the first job position or the "all" variable to get all job positions of a user.

начало примера

Example:

{JobPosition({$__createdBy},"all")} —> The function will pass all job positions of the user specified as the app item’s Author.

конец примера

 

PasteImage function

To paste an image from a context variable into a document template, use the PasteImage function.

Syntax: PasteImage(<param1: image/file>, <width in pixels>, <height in pixels>, <crop instead of compression: true/false>)

Начало примера

Examples:

  • {PasteImage({$image})}. The image will be displayed with the original width and height values;
  • {PasteImage({$image}, 200)}. The image will be displayed with a width of 200 pixels. The height value will change, the original proportions will be preserved;
  • {PasteImage({$image}, 200, 400)}. The function scales the image to a strictly specified size;
  • {PasteImage({$image}, auto, 400)}. The image from the variable will be displayed with a height of 400 pixels. The width value will be scaled, the original proportions will be preserved;
  • {PasteImage({$image}, 200, 400, true)}. The function will crop the image to the specified size without taking into account the original proportions.

Конец примера

HYPERLINK function for tables

When generating a template in a .xls and .xlsx file, you can use the HYPERLINK function. This is a standard Excel function that allows you to convert a given value into a hyperlink.

You can use variables of type String from the app context as arguments, as well as set values manually. For the function to work correctly, the full URL of the link is specified.  

Syntax: HYPERLINK("{$param1: string}" or "<complete url adress>";"{$param2: string}" or "<hyperlink value>").

начало примера

Examples:

  • =HYPERLINK("{$site}";"See the official site"). The site address is specified as a string in the app item, the hyperlink value is set manually;
  • =HYPERLINK("https://elma365.com/en/";"{$__name}"). The site address is specified manually, the hyperlink value is formed from a field in the app item..

конец примера

ExtText function

In case system functions are not enough to customize a template, you can create a custom ExtText function. The function allows you to call API methods described in custom modules and apply them to the generated template.

For example, you can create a watermark function that will place text or an image on a document.

Syntax: {ExtText("module id", "method address")}:

  • module id. Characters from the module URL coming after /ext_. For example, if the module URL is mycompany.elma365.ru/admin/extensions/ext_12ab-1212, then 12ab-1212 should be inserted into the function;
  • method address. . The value of the Address field from the table located on the API Methods tab in the settings of the module.

If additional parameters are used in the request body in the module, the values for them are specified in the ExtText function with a comma after the mandatory parameters. Please note, the values will be assigned to the parameters in the order in which they are declared in the method request body.

When using complex custom functions, you can change their processing mode to speed up the generation of template documents. All variables and functions will be processed in parallel instead of sequentially one after another.

For this purpose, you can enable the enableConcurrencyTemplateMapper flag in some system editions:

  • For ELMA365 SaaS Enterpise contact your ELMA365 sales rep.

After enabling the flag, you can set the number of parallel processing threads using additional parameters.

начало примера

Example:

{ExtText("12ab-1212", "watermark", {$number}, "Example text")} —> -> function will run the watermark method and pass to it the value of the $number variable from the business process in which the template is being configures, as well as the specified Example text string.

конец примера

Conditions

You can display certain text in your document depending on conditions.

A condition starts with {if <condition>} and ends with {end}. <condition> is any condition, for example, {$variable_name} = "Yes"}.

Please note that for Yes/No switch type variables, you need to specify a value from the Variables field. By default, it can be Yes or No.

syntax-of-templates-1

There are three types of conditions you can use:

 

начало примера

Example 1

{if {$user_name} = "John Michael"} Best regards, John Michael {end}

конец примера

начало примера

Example 2

{if {$week.day} = "Friday"}

Have a nice weekend!

{else}

Have a nice day!

{end}

конец примера

начало примера

Example 3

{if {$boolean} <> "No"} This text is displayed {end}

конец примера

Operators

In conditions you can use the following operators:

= equals

<> not equal to

> greater than

>= greater than or equal

< less than

<= less than or equal

 

OR and AND logical operators

To create complex conditions, you can use the OR and AND, AND operators, which allow you to specify multiple conditions as a single construction.

When using OR, it is sufficient that at least one of the specified conditions is met.

начало примера

Example:

{if {$trip.location_type} = "Hotel" OR {$trip.location_type} = "Host apartment"}

{$business_trip_request.city}

{end}

конец примера

When using AND, you need all of the above conditions to be met.

начало примера

Example:

{if {$item.price} < 5000 AND {$item.isAvailable}}

{$item.name}

{end}

конец примера

Conditions with the logical operators OR and AND can be combined using parentheses.

начало примера

Example:

{if ({$business_trip_request.location_type} = "Hotel" OR {$ business_trip_request.location_type} = "Host apartment") AND ({$business_trip_request.price} < 5000)}

{$business_trip_request.city}

{end}

конец примера

For loop

Use the for loop to display a list of items in a document (for example, supplied goods listed one by one).

начало примера

{ for fr in {$goods} }

ordered {$fr}

{end}

конец примера

When you upload your template to the system, and the for loop is extracted, the field assigned for it is marked as a list.

sodt2

For loop in apps

You can use the for loop to display items in an app:

начало примера

Example

{for fr in {$appListField} }

Contract {$fr} with {$fr.__name} for {$fr.money}

{end}

конец примера

A similar loop allows you to write data to a table:

начало примера

Example

{for fr in {$appListField} }

{$fr}

{$fr.__name}

{$fr.money}

{end}

конец примера

начало внимание

When you work with apps, specify the names of fields in the template without the data prefix.

конец внимание

For loop in tables

To let the loop work correctly, when you add a template to the system, specify the type of data for the variable in the loop.

for_loop_tables

If you need to extract data from a table into a document, for example, a list of goods with their quantity and cost filled in during order processing, you can use a template in .xlsx format..

начало внимание

In systems version 2023.12 and below, when working with tables, you should specify the row.data prefix before the field names in the template. Since version 2024.1, using data does not affect the correct generation of the file.

конец внимание

When configuring the template, use a for loop and specify the process variable that stores the table data.

When creating a template in a .xlsx file, the for and end commands must be in the first column of the table, otherwise the entered text will not be displayed correctly. Next, you need to specify the codes of the corresponding app fields in the template.

For example, for the column where the price will be displayed, let’s specify {$row.data.item_price} or {$row.item_price}, in case you have version 2024.1 and higher.

In the item_price function, this is the code for the Price field. The prefix row.data or row. refers to the item in a loop and allows as many rows to be filled in the document as are filled in the table in ELMA365.

A .xlsx document template for a table that contains an item, its cost, quantity, and total amount payable may look like this

01.PNG

 

Template for a table in a .docx file

To generate a table from a template in a .docx file:

  1. Separate the first row of the table using the Split table option.
  2. In the empty row that appears, declare a for loop.
  3. Configure the template in the table by specifying variables from the business process context.
  4. Under the table, close the loop with the end command.

For example, the template for a table in a document might look like this:

template_table_doc

Show index number in tables

You can use for for loop to add a row's index number to the table template. This is done via the row.data prefix and the __index system property.

For example, a table template with the row number, product name and product price may look like this:

table-index

360026936731.html access_permissions.html

Found a typo? Highlight the text, press ctrl + enter and notify us