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.

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

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

Example:

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

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

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

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

Example:

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

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

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

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

Example:

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

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

Substr(<param1: string>, <from: number>, <length: number>). Extracts a part of the text, starting with the specified character <from> and continuing for the specified number of characters <length>.

You can fill in only <from> to keep all the text after the specified character.

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

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.

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

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:

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

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 EEE")

The letters in the syntax represent the following:

X is the main number.
E is the extension number.

If a user enters the phone number with less digits than the mask represents, the excessive X and E letters will not appear in the document.

The phone number is filled in with digits from left to right.

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

{ToString({$phone1}, "+7—XXX—XXX—XX—XX")} —> +1-650-499-88-77.
{ToString({$phone1}, "X—XXX—XXX—XX—XX EEE")} —> 1-650-499-88-77 159.
{ToString({$phone1}, "XX—XX—XX E")} —> 99-88-77 3.

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

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

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

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

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 BRIX 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. Resolution up to 300 DPI is supported.
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.

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

Module id. Characters from the module URL coming after /ext_. For example, if the module URL is mycompany.brix365.com/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.
Additional parameters. An optional parameter that is passed to the specified method, for example, an app property. In the request body the additional parameters are displayed as p1, p2, etc. The are passed in the ExtText function separated 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.

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

Example:

You can apply the ExtText function in naming app items. To do that:

Create a module and set up an API method that will be used for generating app item names.
Create a name template by using the ExtText function.

For example:

{ExtText("4c34-822c", "name", "Example text", {$_index})}

The function will trigger the method that will process the passed parameters. After the conditions specified in the method are executed, the result can be used as an app item name.

Example of an API method script for creating app item names:

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

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 BRIX On-premises Enterprise in the values-elma365.yaml configuration file. For more details, see Modify BRIX Enterprise parameters.

For BRIX On-Premises Standard in the config-elma365.txt configuration file. For more details, see Modify BRIX Standard parameters.

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".

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

Example 1:

{if {$user_name} = "Jacky Jones"} Best regards, Jacky Jones {end} —> the function's condition checks the user's name. If the name coincides, the specified text is displayed.

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

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

Example 2:

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

Bye, have a great weekend!

{else}

Bye!

{end} —> in this example, the current day of the week is checked. Depending on the day, one of the text options will be displayed.

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

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

When using multiline conditions for .xlsx files, you should not place additional text in the lines with the {if <condition>}, {else} and {end} operators. It will be removed during document generation.

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

Please note that for Yes/No switch variables you need to specify options from the Options field. By default they are Yes and No.

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

Example:

{if {$options} <> "No"} Example text {end} —> the text will be displayed only if the value is Yes.

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

You can use a function to check if an app item's properties have values. If the field on the form is filled in, you can display its value.

For App or Files properties, the condition function is applied only if there is one value, e.i. the One option is selected for the property. If the Many option is selected, use the for loop.

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

Example:

{if {$document}} {$document} {end} —> if a document is uploaded to a File field, its name will be displayed n the generated file.

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

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 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.

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

For .xlsx files, additional text should not be placed in lines with the {for <expression>} and {end} operators. It will be removed during document generation, except for text in merged cells.

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

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

Example

{for fr in {$appListField} }

{$fr}

{$fr.__name}

{$fr.money}

{end}

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

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

In system versions 2023.12 and lower, specify field names in templates without the data prefix when working with apps. Starting with 2024.1, generation will work correctly with the prefix.

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

For loop in tables

To let the loop work correctly, when you add a template to the system, specify the Table data type for a 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 BRIX.

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

In table rows with the {for <expression>} and {end} operators, additional text should not be placed. It will be removed during document generation, except for text in merged cells.

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

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

You can also add an if condition to the for loop. You can see an example in the Templates for approval sheets and lists of informed users article. Please note that for .xlsx files, you should not place any text in rows with the {for <expression>} and {end} operators, as this text is deleted during generation. The exception is vertically merged cells.

Template for a table in a .docx file

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

Separate the first row of the table using the Split table option.
In the empty row that appears, declare a for loop.
Configure the template in the table by specifying variables from the business process context.
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

Nested tables

The for loop can be used to create a nested table. When referencing columns of a nested table, instead of prefix row.data or row use a different prefix. For example, subrow.data in system versions 2023.11 and older or prefix subrow for system versions 2024.1 and up.

for-brix-00

Please note that is rows with operators {for <expression>} and {end} you cannot place any other text as it will be deleted during generation. Cells merged vertically are an exception. For example, when generating a document from such a templte, the value of variable {$row.author} will be shown in the table:

for-brix-01

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 360012267032.html

Was this helpful?

Variables

Functions

Functions for working with strings

ToString() function

Number

String

Category

Yes/No switch

Money

Full name

Phone number

Date/Time

DateTime() function

Now() function

Barcode function

JobPosition() function

PasteImage function

HYPERLINK function for tables

ExtText function

Conditions

Operators

OR and AND logical operators

For loop

For loop in apps

For loop in tables

Template for a table in a .docx file

Nested tables

Show index number in tables