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, andSystem Settingsare object macros: they are followed by a property name rather than used bare. In the placeholder browser, selectingLicense InformationorSystem Settingsitself leaves the Placeholder: box empty; choose one of its properties.NowandTodayinside 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 Codeonly 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 |
InitiatorHost 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 Settingsis 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.
Link macros
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).
- Enter the URLs.
- 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: namelines.
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:
- Click New to open New Macro, or select a macro and click Edit to open Macro [name].
- On the General tab, enter Name: and Description:. The read-only
Placeholder: box shows
%[USR <name>]%as you type. - Choose the Type: (Text, SQL Script, or PowerShell script) and the Output: (Plain Text or HTML).
- Choose All objects, or Object class: and a class. The class list leaves out invisible and unlicensed classes, Stock Room, and Task Parent.
- 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.
- 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
IDfield readsID (Global ID - GUID)and anOIDfield 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.
Related topics
- Author E-mail Notifications - use placeholders in notification bodies.