Skip to main content

xSuite Interface Windows Prism 5.x – Online Help

Variables

In configuration, variables serve as:

  1. A dynamic part of some configuration values in scenario configurations.

    Variables are primarily used to set configuration values depending on the content of a document that is being processed. The use of variables is therefore limited to configuration properties that are evaluated in the context of document processing. Variables cannot be used for higher-level properties important for functions like initializing a connection to an input system or an output system.

    The syntax for including variables in configuration values is %VariableName%. Unlike constants, variables are not treated as string values by default. If variables represent the contents of a field from the field catalog, they can also have typed values. However, since the replacement of the placeholder by a variable value is a pure text replacement, any needed conversion of a typed value into a string value takes place implicitly. The syntax that is used for constant macro expressions (see Data Types, Variables, and Constants) is also used for variables. Numeric values are given a period as a decimal separator; date values are formatted as yyyy-MM-dd, with the time unit HH:mm:ss; and Boolean values are output as TRUE or FALSE.

  2. An element in a configuration value that is a macro expression.

    The syntax %VariableName% can also be used for these kinds of values. However, in the process, the text substitution of the variable values then precedes the parsing and execution of the macro. The result of the substitution must therefore remain a syntactically valid macro expression: In the case of string expressions, for example, the values must be written in quotation marks according to the macro syntax. If the value is defined by a variable, "%VariableName%" must be written in the macro instead of %VariableName%. If the variable value itself already contains the required quotation marks, this is not necessary. However, the native and therefore generally preferable variant within macros is the use of typed variables of the form @VariableName. This notation can be used for all types of variables.

Field Variables

Field variables reference fields from the active field catalog of a document. Therefore, the field name (i.e., the .Name property of the field definition) also serves as the variable name. For tabular fields, the field name would thus have the form {table name}.{column name} (see the syntax of the property FieldCatalog[].Field[].Name).

However, such a specification is only sufficient if, in the context of processing, it is clear which line of the table is being addressed. This would be the case when, for example, initialization macros are executed for a field catalog. For table fields, this is done successively across all lines. If there is no additional line specification, table field variables always refer to the fields of the line that is currently being processed.

If, on the other hand, fields of another row are to be explicitly referenced or if the current execution context does not refer to table rows, then specify the row number explicitly in the variable name. The syntax for this is {table name}[{row number}].{column name}. The row number count starts at 1.

Constants as Typed Values

Constants are primarily used to maintain certain configuration values in a central location. These configuration values are inserted into the configuration data at the relevant points by pure text replacement at program start. The syntax %constant name% is used for textual insertion.

Constants can also be used in macro expressions at runtime. The syntax @ConstantName is used for this. Constants are always defined syntactically as a string. Typed values must be specified in the syntax of a literal (constant value) (see Data Types, Variables, and Constants). Text values must be written in additional quotation marks, for example. If a constant value cannot be interpreted as a syntactically correct literal, the value is implicitly treated as a text value.

Document Variables

Document variables are fixed by name. These variables contain the system's metadata for the document that is currently being processed.

Variable Name

Description

DocId

Database key (database field "Id") of the document

DocUuid

UUID (database field "FixedGuid") of the document

DocNo

Consecutive number of the document (database field "Number") within the batch

Counting starts at 1.

DocName

Name of the document (database field "DisplayName")

DocExtId

External ID of the document (database field "ExternalId")

DocScenario

Name of the processing scenario of the document (database field "Scenario")

BatchUuId

UUID of the parent batch (database field "FixedGuid")

BatchId

Database key of the parent batch (database field "Id")

BatchName

Name of the parent batch (database field "DisplayName")

BatchExtId

External ID of the parent batch (database field "ExternalID").

TrackingId

Tracking ID (database field "TrackingId") assigned to the document via .TrackingIdMacro

TrackingKey

Tracking key (database field "TrackingKey") assigned to the document via .TrackingKeyMacro

CustomKey

Key value (database field "CustomKey") assigned to the document via .CustomKeyMacro

File Variables

File variables are variables that can be used when processing a file attachment of a document. The use of file variables is limited to file macros and to some macro functions in configuration properties of output formats and output systems.

Variable Name

Description

FileId

Database key (database field "Id") of the file attachment

FileUuid

UUID (database field "FixedGuid") of the file attachment

FileNo

Serial number of the file attachment in the document or in the context of processing

FileName

Full name of file attachment (database filed "Name")

FileBaseName

Base name of the file attachment without file extension (from database field "Name")

FileExt

File extension of the file attachment (from database field "Name")

In certain contexts, additional variables are available that include the folder of a file. In particular, this applies to the use case where references to attachments yet to be added to the file system are to be evaluated. For file attachments that have already been added to a document, on the other hand, there is no longer any access to their original folder via a file variable.

  • FilePath: complete path of the file (i.e. folder and filename)

  • FileBasePath: path of the folder and base name of the file

  • FileFolder: path of the folder

System Variables

System variables are fixed variables that contain general system information and environment information. The contents of the system variables partly overlap with that of the environment variables. However, in contrast to environment variables, the values of the system variables are determined and prepared internally in the program.

The date and the time are used to create dynamic file paths (e.g., for backup directories). The colon is not a valid character in folder and file names in Windows, as ist is otherwise used to separate the time components. Therefore, a different separator is used here.

Variable Name

Description

Date

Current date

Formatting: yyyy-MM-dd

Time

Current time

Formatting: HH'mm'ss

Timestamp

Current time stamp

Formatting: yyyy-MM-dd HH'mm'ss

Day

Current day

Formatting: dd

Month

Current month

Formatting: MM

Year

Current year

Formatting: yyyy

UUID

Newly generated UUID

Formatting: xxxxxxxx-xxxx-xxxx-xxxxxxxxxx

ComputerName

Name of the executing computer

UserName

Name of the executing user

Environment Variables

All (Windows) environment variables of the system, the current process, and the user are available.

Other Variables

For individual configuration properties or macro functions, there might be additional internal variables that are restricted to the execution context of these elements. Variables such as these are listed in the description of the respective element.