Custom Macro Functions

In addition to the macro functions that are permanently integrated into the program (see Macro Functions), you may see the need to define your own functions. You can define these functions in global configuration. The functions will be available in all scenarios that are executed by the respective program instance. JavaScript code is used for user-defined functions, which is executed using a special interpreter in the .NET runtime environment.

Caution

The JavaScript-based macro functions are just one way of implementing your own functions. The other variant is based on an external .NET class library and requires a separate .NET development environment.

A separate .NET development environment may be helpful when developing and debugging more complex functions. A library such as this is suitable for building a collection of your own functions that are to be reused regularly. The purpose of the JavaScript functions, on the other hand, is to add smaller function extensions on the fly.

Property	Description
CustomJsMacro.Macro[].Type	Type of macro function: `Field`: field macro function (default value) `Document`: document macro function `General`: general help function Custom functions are restricted to field macros and document macros that are executed in the context of document processing. A field macro returns a result value for further processing. A document macro, on the other hand, does not return a result value, but typically makes direct changes to a document (see Functions). A field macro can be used to generate a field value, but also, for example, to evaluate a condition (`.ConditionMacro`). A function of the type `General` cannot be called directly in a macro expression of xSuite Interface. This function serves as a sub-function, working out of a custom field macro or document macro. This function is used to outsource parts of your own functions to make the required separations between functions. This way, they can be reused in multiple places.
CustomJsMacro.Macro[].Name(*)	Name of the macro function The macro function is called up under this name. The name of the macro function must be unique and not collide with the names of the integrated functions. In order to distinguish the custom functions from the integrated functions, we recommend prefixing them by name (e.g., with a prefix `Js` for JavaScript).
CustomJsMacro.Macro[].Description	Description text of the macro function (optional) The description text is only displayed in the macro editor of the configurator.
CustomJsMacro.Macro[].Params	Parameter list of the function if it is to have call parameters Syntactically, the parameter list must be a comma-separated list of the parameter names. In other words, it should be written exactly as it would be in the header of a JavaScript function within the round brackets.
CustomJsMacro.Macro[].Code(*)	JavaScript code to be executed within the function body The function header does not need to be specified as it is generated implicitly by the program from the `.Name` and `.Params` properties. The code of a field macro function usually ends with a `return` command for the return value. The return value must be compatible with the data types supported by xSuite Interface. The value must therefore be of the JavaScript type "String," "Number," "Boolean," or "Date," or must represent an array of these types. We recommend that you avoid returning `NULL` values, as the internal macro interpreter and the internal macro functions are not explicitly designed to handle these values. As an option, a document macro function can also return a text value. This value is only output as additional information in the log (e.g., as a summarized status message regarding the result of the macro execution).
CustomJsMacro.AllowClr	Boolean value determining whether classes of the .NET-CLR (Common Language Runtime) from the namespace "System" should be available in the JavaScript environment This is a special function of the JavaScript interpreter used. This function extends the JavaScript language scope by objects and methods of the .NET namespace. Out of the JavaScript code, a text file can be written with the.NET method `System.IO.File.WriteAllText('c:/temp/test.txt'' 'Hello World');`. Default value: `TRUE`

User-defined macro functions are called syntactically in a macro expression, in the same way as integrated functions are called. The call is made via the name of the function and, if necessary, a list of call parameters. The two function types (field macro and document macro) can be combined to form the required expression. However, no integrated macro functions can be executed from your own JavaScript code. Only the methods provided by the JavaScript interpreter can be used here. With a few exceptions, this includes the ECMAScript 2023 standard. If the AllowClr property is activated, certain .NET methods will be available.

The call parameters and return values are automatically converted to the equivalent .NET types and JavaScript types. This also applies to the properties of the objects described below. However, these objects do not have to be sent explicitly as parameters; rather, they can be accessed globally in the JavaScript environment. The doc object represents the object that is currently being edited. The vars object provides access to all variables that are available in the execution context. The log object is a method for writing log information. As JavaScript is case-sensitive, always pay attention to capitalization when handling these objects and their properties.

Object / property / method	Description
doc.id doc.uuid doc.name doc.extId doc.scenario doc.number doc.trackingId doc.trackingKey doc.customKey doc.batchId doc.batchName doc.batchExtId	Internal properties of the document (analogous to the field macro function `GetDocProperty()`)
doc.fields doc.fields.{fieldname}	Sub-object of all header data fields that are addressed via their field name according to the field catalog The values of these properties represent the corresponding field contents. The value of a field named `Field1` can be retrieved via `doc.fields.Field1` (or, alternatively, via `doc.fields['Field1']`).
doc.tables doc.tables.{TabName} doc.tables.{TabName}.rows[] doc.tables.{TabName}.rows[].fields doc.tables.{TabName}.rows[].fields.{FieldName}	Sub-object of all table fields In this context, no hierarchically nested tables are supported, only top-level tables. If a tabular field is defined in line with the name syntax `{table name}.{column name}` (e.g., as `Table1.Column1`), the table can be addressed as `doc.tables.Table1`. The rows of a table can be called up via an array `rows`. The individual fields of a row can be accessed via `fields`. To access the value of the `Column1` field in the first table row, use the expression `doc.tables.Table1.rows[0].fields.Column1`.
doc.extKeys doc.extKeys.{key name} doc.metaData doc.metaData.{metadata name}	Sub-objects of the external keys and metadata of the document The value can be retrieved via the name of the key or metadata. For example, the piece of metadata `Meta1` can be retrieved via `doc.metaData.Meta1`.
doc.files[] doc.files[].id doc.files[].uuid doc.files[].name doc.files[].number doc.files[].type doc.files[].originalFile doc.files[].size doc.files[].fileType doc.files[].extKeys doc.files[].extKeys.{key name} doc.files[].metaData doc.files[].metaData.{metadata name}	Array of the document's file attachments The internal properties of each file attachment can be read (analogous to the field macro function `GetFileProperty()`). The external keys and metadata can be accessed in the same way as for the parent document object. Only this descriptive information of a file is made available here and not the binary data of the file content.
vars vars.{variable name}	Sub-object of all available variables A single variable can be read via the variable name. The `DocName` variable, for example, can be read via `vars.DocName`. In the context of document processing, the document variables are available (identical to the document properties listed above) as well as general system and environment variables (see Variables).
log( {Text} )	Method for writing a custom entry in the xSuite Interface log active in the current execution context The entry is always of the "Debug" type. Such an entry can be used, for example, to output your own analysis information on the execution of the JavaScript code. The text to be logged must be of type "String" (example: `log('Hello World');`).

Object / property / method

Description

doc.id

doc.uuid

doc.name

doc.extId

doc.scenario

doc.number

doc.trackingId

doc.trackingKey

doc.customKey

doc.batchId

doc.batchName

doc.batchExtId

Internal properties of the document (analogous to the field macro function GetDocProperty())

doc.fields

doc.fields.{fieldname}

Sub-object of all header data fields that are addressed via their field name according to the field catalog

The values of these properties represent the corresponding field contents. The value of a field named Field1 can be retrieved via doc.fields.Field1 (or, alternatively, via doc.fields['Field1']).

doc.tables

doc.tables.{TabName}

doc.tables.{TabName}.rows[]

doc.tables.{TabName}.rows[].fields

doc.tables.{TabName}.rows[].fields.{FieldName}

Sub-object of all table fields

In this context, no hierarchically nested tables are supported, only top-level tables.

If a tabular field is defined in line with the name syntax {table name}.{column name} (e.g., as Table1.Column1), the table can be addressed as doc.tables.Table1.

The rows of a table can be called up via an array rows. The individual fields of a row can be accessed via fields. To access the value of the Column1 field in the first table row, use the expression doc.tables.Table1.rows[0].fields.Column1.

doc.extKeys

doc.extKeys.{key name}

doc.metaData

doc.metaData.{metadata name}

Sub-objects of the external keys and metadata of the document

The value can be retrieved via the name of the key or metadata. For example, the piece of metadata Meta1 can be retrieved via doc.metaData.Meta1.

doc.files[]

doc.files[].id

doc.files[].uuid

doc.files[].name

doc.files[].number

doc.files[].type

doc.files[].originalFile

doc.files[].size

doc.files[].fileType

doc.files[].extKeys

doc.files[].extKeys.{key name}

doc.files[].metaData

doc.files[].metaData.{metadata name}

Array of the document's file attachments

The internal properties of each file attachment can be read (analogous to the field macro function GetFileProperty()). The external keys and metadata can be accessed in the same way as for the parent document object. Only this descriptive information of a file is made available here and not the binary data of the file content.

vars

vars.{variable name}

Sub-object of all available variables

A single variable can be read via the variable name. The DocName variable, for example, can be read via vars.DocName. In the context of document processing, the document variables are available (identical to the document properties listed above) as well as general system and environment variables (see Variables).

log( {Text} )

Method for writing a custom entry in the xSuite Interface log active in the current execution context

The entry is always of the "Debug" type. Such an entry can be used, for example, to output your own analysis information on the execution of the JavaScript code. The text to be logged must be of type "String" (example: log('Hello World');).

A document macro can make direct changes to a document and therefore has read and, in some cases, write access to the above objects and properties. Changes to the following elements are transferred from the JavaScript execution environment back to the original document:

doc.fields.{fieldname}
doc.tables.{TabName}.rows[]
doc.tables.{TabName}.rows[].fields.{FieldName}
doc.extKeys
doc.metaData
doc.files[].extKeys
doc.files[].metaData

Attempts to change other elements in the JavaScript code are either ignored or lead to an execution error. The contents of existing header and position fields can be changed. However, it is not possible to add or delete fields. By default, a document and a table row includes all fields that are defined in the field catalog, with empty initial values if necessary. Other fields that are not defined in the field catalog cannot be used. The free addition of new and unknown fields is therefore not supported.

Adding or deleting entire table objects is also not supported. However, the number of rows in existing tables can be changed (i.e., elements can be deleted from the rows array or new elements can be added). If all table rows are deleted, the existing rows array must not be overwritten by a new array. For example, for a table called Table1, doc.tables.Table1.rows = []; would not be permitted. In this case, only the rows must be removed from the existing array:

doc.tables.Table1.rows.length = 0;

doc.tables.Table1.rows.splice(0, doc.tables.Table1.rows.length);

When adding new table rows, not all fields of the row must necessarily be set in JavaScript code. The following expression is permitted for a table with the three fields Column1, Column2 and Column3, as the missing Column3 field is implicitly added and assigned the initial value when the changes are applied.

doc.tables.Table1.rows.push({
   fields: {
      Column1: "Value1",
      Column2: "Value2",
   }
});

In this context, the internal properties of the document and the file attachments are generally unchangeable. However, the external keys and metadata of the document and the file attachments can be freely set. Unlike the predefined fields, you can also use your own new names. Do not replace the objects extKeys and metaData in full; only change them. When observing this rule, doc.metaData = {}; would not be permitted. To delete a property from such an object, set the property value to null or undefined (e.g., for a metadata Meta1 via doc.metaData.Meta1 = null;).

In this section:

xSuite Interface Windows Prism 5.x – Online Help

Custom Macro Functions

Caution

Search results