Administration Guide

Macros Reference

On this page

A placeholder is written %[<TOKEN> <name>]% in workflow text, expressions, scripts, and notification bodies, and is expanded to a value when the workflow uses it. System macros and user macros are two kinds of placeholder: the product ships a fixed set of system macros, and user macros are named text bodies you define. How placeholders are used in e-mail notifications is described in Author E-mail Notifications.

Placeholder syntax

Placeholder Written as What the name is
Object field %[DBF <field>]% A field of the object in context
Old value %[DBF OLD.<field>]% The same field's value before the change
Activity field %[DBF Activity.<field>]% A field of the activity in context
System macro %[SYS <macro>]% One of the system macros
User macro %[USR <macro>]% A user macro
Parameter %[PAR <name>]%, or %[VIR <name>]% for a virtual field A declared function, item, or e-mail parameter
Service attribute %[EML <name>]% A service attribute
Variable %[VAR <name>]% A program variable
Section %[SEC <name>]% An e-mail body section
Attachment area %[ATT <name>]% A form attachment area
Workflow parameter %[WFP <name>]% A workflow parameter

The older notation with angle brackets, from version 6.x, is still read.

  • Object fields follow references as a dotted path of field names, for example %[DBF Related_Problem_ID.Requester_ID.Full_Name]%. A reference that can point to several classes also offers one field per licensed workflow class, named *As<ClassName> without spaces, which narrows the path to that class: Related_CI_ID.*AsComputer.CPU_Speed.
  • Workflow parameters are named, typed, categorized configuration values, each with a default and a current value. Every application caches them, so a changed value reaches a running application when it notices the change.
  • Variables include the context variables the engine declares inside a nested block. A Create Object or Act on Related Object step whose body is an embedded function gets a variable named $ plus the target object's name without spaces, such as $Incident, with _1, _2, and so on added when the name is taken. An iteration step gets $ plus its iterator's name. A service object gets none. A context variable exists only inside its block, where the Variables category of the placeholder browser lists it; referring to it outside the block is reported as an undeclared variable when the program is checked. See Operations Reference.

System macros

The system macros include:

Macro Yields
Now, Today The current timestamp; the current date
Activity List All, Activity List Published The object's activity history, all of it or the public entries only
PO Items All The purchase order's line items
Object Changes All, Object Changes EndUser What this run changed, in full or in end-user form
Action ID, Action Name The item that started the run
WF Item ID, WF Item Name The item currently running
Notification ID, MessageID Tag The e-mail notification's identity and its threading tag
Initiator The initiator of the run, as an object with properties
License Information The license, as an object
Current User The acting person, as an object
Job Settings, System Settings The running job's options; the system options; each as an object
Web Portal Link, Self Service Portal Link, API Link The configured base URLs
System Information The notification system-information block
AI Features Enabled Whether AI features are enabled
Default Currency Code The system's default currency
  • Current User, Initiator, License Information, Job Settings, and System Settings are object macros: they are followed by a property name rather than used bare. In the placeholder browser, selecting License Information or System Settings itself leaves the Placeholder: box empty; choose one of its properties.
  • Now and Today inside a SQL expression or a condition are evaluated by the database server. In any text, they take the clock of the application that runs the item, formatted with that computer's regional settings.
  • The placeholder browser offers Default Currency Code only when the license carries multiple currencies.
  • In the placeholder browser, every system macro carries a description and, where one can be computed, its current value or an example.
  • No macro or workflow operation runs an AI request itself.

Object macro properties

Macro Properties
Initiator Interactive, SQL Server, Database, Use Windows Authentication, Login, Name, Type, SSP Access Level, Host Name, Host IP Address, Host Site, Client Workstation, Client IP Address, Client Locale, Application Name, Operating System
License Information Serial Number, Language, Expiration Date, User, Organization, Audit Nodes, Named Users, Concurrent Users, SQL Server
System Settings Plain Text Email
Job Settings Create SSP Accounts, Create Organizations, Create Locations
  • Initiator Host Site is the URL of the Web App instance and is filled only when the run was started from the Web App. Interactive is true only when a person, not a service, started the run. SSP Access Level is the portal account's level.
  • Job Settings is offered only inside synchronization service actions: Create SSP Accounts in an Active Directory create or task service action, and Create Organizations and Create Locations in the Active Directory, Alloy Discovery, AlloyScan, and Chromebook create and task service actions. It is not offered in an ordinary action, trigger, or notification. The properties' descriptions name the Active Directory synchronization job in an Active Directory action and the Alloy Discovery synchronization job in an Alloy Discovery action; an AlloyScan or Chromebook action shows the Active Directory wording.

When a condition or an expression compares an Initiator property, the value list offers:

Property Values offered
Type Active Directory Import, Alloy Discovery Connector, AlloyScan, API, Data Archiving, Mail Connector, Mobile Portal, Recurrent Ticket Agent, Scheduled Task Agent, Scheduled Trigger Agent, Self Service Portal, Web Portal
Operating System Windows, macOS, Linux, iOS, Android, Unknown
Application Name The mobile applications registered in this installation; none if none are registered
SSP Access Level Regular User, Manager, Group Manager, Department Manager, Organization Manager
Client Locale The locales the Settings App's Windows computer supports

A run can also carry initiator types that the Type list does not offer, such as Reporting Service; a condition on one of them is typed by hand.

Web Portal Link, Self Service Portal Link, and API Link hold the base URLs of the Web App, the Self Service Portal, and the API. In the placeholder browser, each describes itself as the actual URL of the application, used for generating direct links, followed by its current value. The description directs you to the Admin Center: Web App > Admin Center > Apps and Portals.

In the Settings App

Workflow and Business Logic > Advanced > System Macros shows a Links group with Web Portal Link:, Self Service Portal Link:, and API Link:. The page requires the administrative right System Macros (see Permissions Reference).

  1. Enter the URLs.
  2. Click Apply. It is available only while something has changed; Refresh only while nothing has.

A trailing / is added to a non-empty value that does not end in one. An emptied box is saved as empty.

In the Web Configuration tool

While the Web Configuration tool creates a new instance, its URL page sets the link macro of that instance's kind: Web Portal Link for the Web App, Self Service Portal Link for the portal, and API Link for the API. The page is not available when you configure an existing instance.

  • URL: shows the detected instance URL.
  • When the stored macro differs, System Macro: shows the stored value with the warning Mismatch detected and the line "Your instance URL URL does not match the system macro value value. Update one to match the other.", and the buttons Update system macro with instance URL and Update instance URL with system macro.
  • Next stays unavailable until the URL is longer than eight characters and starts with https://.

The tool writes the same setting as the System Macros page.

User macros

A user macro is a named text body with a type, an output, and an optional object class.

Type Output Shown in the list as
Text Plain Text Text
Text HTML Text (HTML)
SQL Script Plain Text SQL script
SQL Script HTML SQL script (HTML)
PowerShell script Plain Text PS script
PowerShell script HTML PS script (HTML)
  • A Text macro is substituted as written. A SQL Script macro, with either output, is run as a SQL script when the placeholder is expanded. A PowerShell script macro with Plain Text output (PS script) is run as a PowerShell script; with HTML output (PS script (HTML)) it is substituted as written, not run. The HTML output declares that the result is HTML rather than plain text.
  • A SQL script macro first has the placeholders in its script replaced, then runs the whole script as one batch and yields the first column of the first row of the last result set. A result set with no rows, or a script that is empty after its placeholders are replaced, yields no value. A text result is not expanded again, even if it contains something that looks like a placeholder.
  • A SQL script (HTML) value goes into an HTML template as it is and into a plain-text template converted to plain text. A SQL script value going into an HTML template is HTML-encoded, so any tags in it appear as text.
  • The object class decides where the placeholder browser offers the macro. It does not restrict where the macro is expanded.

User macros in the Default Workflow

A new 2026.1 database created with the Default Workflow (see Default Workflow Configuration) contains two SQL script user macros that assemble input for AI. A database upgraded from an earlier version need not have them, and an administrator may have changed them.

  • Activity List For AI Analysis renders a record's whole activity history as plain text.
  • Category List For AI Analysis renders the active categories of a class as id: name lines.

Neither macro calls AI.

Manage user macros

In the Settings App

User macros are listed in two places:

  • Workflow and Business Logic > Macros lists every macro of a licensed class and every macro that belongs to no class. It requires the administrative right Macros.
  • Each class's own Macros node lists the macros of that class, of its general class, and those that belong to no class. It requires the class's own administrative right, the one that allows managing that class's business logic.

The list is grouped by the Object Class column, which reads All Objects for a macro with no class. Expand All and Collapse All work on the groups, Ctrl+F opens the quick filter, and the toolbar offers New, Copy Item, Edit, and Delete.

To create or edit a macro:

  1. Click New to open New Macro, or select a macro and click Edit to open Macro [name].
  2. On the General tab, enter Name: and Description:. The read-only Placeholder: box shows %[USR <name>]% as you type.
  3. Choose the Type: (Text, SQL Script, or PowerShell script) and the Output: (Plain Text or HTML).
  4. Choose All objects, or Object class: and a class. The class list leaves out invisible and unlicensed classes, Stock Room, and Task Parent.
  5. Enter the macro's content. Insert Placeholder... opens the placeholder browser; the macro window allows every system macro that the System Macros category can show (see Pick a placeholder), and old values only when the macro belongs to one class.
  6. Click OK.

The window checks the macro:

  • OK is available only while the name is not empty. A name any other macro already has, in any class, is refused with "This macro name is already in use. Please choose another one."
  • A SQL script macro with empty content is refused.
  • Content that fails its check is reported with a Yes/No question; Yes saves it anyway.
  • Switching a text macro's output from HTML to Plain Text first asks "All HTML formatting will be lost. Do you want to continue?".

Some value editors of workflow operations can also make a macro from text: the macro window opens with the selected text, or the whole text when nothing is selected, and saving the macro replaces that text with the macro's placeholder.

See where a macro is used

The Usage tab lists the workflow items and components whose text uses the macro. It is unavailable for a new or copied macro that has not been saved yet; in a macro window opened to make a macro from text, it is available but lists nothing. When an existing macro opens on its General tab, the tab's caption shows the count, as Usage (n), when anything uses the macro, and the list loads when you first open the tab.

Each row names the workflow object (All Objects when there is none), the item kind, the item's name followed by its number when it has one, the placement (such as Criteria, Operation, Form Field, or Section Content), and for some placements the details, such as a parameter or section name. The rows are sorted by these columns in that order. The item kind is one of Step Action, Create, Trigger on Condition, Trigger on Created/Modified, Trigger on Deleted, Service Action, Macro, Function, E-mail Notification, Form, Template, HTML Template, SSP E-mail Template, Mail Connector, Logs, and Preview Template; it is blank for some items, such as a scheduled task or an AlloyScan create or task service action. Open opens the item's editor on the tab the placement belongs to, or opens the item itself, such as another macro or an HTML template; for a scheduled task it opens the task's properties. For a Chromebook or AlloyScan service action, or for the Function Runner, Open does nothing.

To open the definition behind a placeholder, right-click it in a text box, an HTML editor, or a preview and choose Placeholder Definition.... The command reads the selected text, or the text between the nearest % signs on either side of the cursor, and is available for a user macro or a workflow parameter only. It opens the Macro window, or a read-only workflow parameter window, and reports "Macro was not found." or "Workflow Parameter was not found." when no such macro or parameter exists. Opening a macro this way requires the Macros right; without it, a no-rights message appears instead.

Rename or delete a macro

  • Saving a macro under a new name rewrites its placeholder everywhere in the workflow, so existing items keep working.
  • Deleting a macro that a workflow item still uses is refused with "Unable to delete macro "name" because one or more workflow items refer to it. Remove dependencies first.", and the macro opens on its Usage tab.
  • When one macro is selected and it is marked as a system record, deleting it is refused with "This is a system record and it cannot be deleted." When several macros are selected, the ones marked as system records are left out.

In the Admin Center

The Macros tile in the Workflow section lists the user macros grouped by object class. The Type column shows a label for each of the six combinations of type and output, and the text is previewed in up to four lines, without tags for a macro whose Type is Text and whose Output is HTML. The toolbar offers Copy Item for one macro and deletes several macros at once. A copy's name gets - Copy, or - Copy (N) while that name is taken.

The macro's drawer holds:

  • Name, which no other macro may have, the read-only Placeholder (%[USR <name>]%, updated as you type), and an optional Description.
  • Type (Text, PS script, or SQL script) and Output (Plain text or HTML).
  • This macro available for: with All objects or Object class: and a list of the workflow classes, available once Object class: is chosen. Invoice Items is listed only when invoice item processing is turned on.
  • Text Content, an HTML editor when the output is HTML and a required multi-line text box otherwise, with Insert Placeholder....
  • A Usage tab listing where the macro is used: object class, item kind, item name, placement, and placement details.

Switching the output from HTML to text while the text contains a < asks you to confirm. Accepting strips the tags from the text; declining sets the output back to HTML.

When a macro change takes effect

Every application caches the macros and reloads them when it notices that a macro was saved. The Web App checks at most every 30 seconds; the REST API and the Automation Server at most every minute. Renaming or deleting a macro in the Settings App also tells the Automation Server to reload its macros.

A change saved on the System Macros page is announced the same way, and the applications pick up the new link values on the same schedule.

Pick a placeholder

In the Settings App, placeholders are chosen in the Select Placeholder window. Editors open it with Insert Placeholder...; the workflow Filter window's button reads Insert Field/Placeholder.... In an editor's content box, the button takes the selected text as the search term and replaces the selection with the chosen placeholder.

  • The panes are Category:, Item:, and SubItem:. An item drawn with -> has children, which open in SubItem:.
  • The composed text appears in the read-only Placeholder: box, and Description: explains the item.
  • A double-click accepts an item. Both trees search as you type. The window remembers the width of its Item: pane for each user.
  • The Build Expression window embeds these panes below the expression; Insert writes the chosen placeholder at the cursor.

The window offers up to twelve categories, each only where it has something to offer:

Category Offered
Object Fields When the editor has an object. Under Current Values, and Old Values where the editor allows old values
Parent Object Fields In place of Object Fields, in the criteria of a Create Action on a child class
System Macros The system macros the editor allows, without Job Settings
Job Settings Inside synchronization service actions only
User Macros The macros of the object's class, its general class, or no class, of a type the editor accepts
Lookup Fields When the editor names a lookup table
E-mail Fields For an address field or a mail-connector rule
Parameters or form fields When the editor passes its own list, named by the editor
The e-mail section list When the editor passes a section list
The service-attribute list When the editor passes an attribute list
Variables Inside a program
Attachment Areas When the item has a form with attachment areas and the target accepts attachments
Workflow Parameters When at least one workflow parameter exists; grouped by parameter category

An ordinary editor offers only Object Fields, System Macros, User Macros, and Workflow Parameters.

  • In Object Fields, an ID field reads ID (Global ID - GUID) and an OID field gets (Object ID - String). Where the editor asks for it, Activity Record comes first with the activity fields. Old values leave out calculated and image fields.
  • User Macros offers no HTML macro to a plain-text target, and no SQL or PowerShell macro to an editor that accepts no script. Each macro is shown with its own description, and a user macro is always chosen whole.
  • Parent Object Fields lists the parent's fields. The child classes are Purchase Order Item (parent Purchase Order), Invoice (Purchase Order), Invoice Item (Invoice), Approval Request (Approval Stage), Vendor Product (Product), and Task (its own parent object). In a Create Action on any other class, the condition window's Insert Placeholder... leaves out object fields, because the object does not exist yet; the expression and script editors opened from that window still offer object fields.