Administration Guide

Operations Reference

On this page

An operation is one step of a workflow program (see Workflow Overview). This reference lists every operation kind, the values and targets each one takes, and how the operation windows and the operations list of the Settings App work.

The operation catalog

Twenty operations are available from the operations list. Create Object and Act on Related Object each reach their target either through a reference field or through a custom relation, and each keeps one label for both routes.

Operation What it does When it takes effect
Update Field Applies an update operator to a field of the object, or adds an activity record. In memory.
Execute Function Calls a named function, passing values for its parameters. In memory.
Create Object Creates a new object and can run its own operations against each created object. In memory.
Act on Related Object Runs a block of operations against the related objects that match its target and filter. In memory.
External Command Runs a command on the client or on the server. After the save is committed: a server command is queued, a client command is handed to the client.
Message Box Shows a message, or, in the services and tools listed under Message Box, writes it to their log. After the save is committed.
Execute SQL Runs a SQL statement. The statement is composed during the run and executed after the save. After the save is committed.
Abort Stops the whole run without saving its pending changes; see Abort for the After-Save exception. Immediately.
E-mail Notification Queues an e-mail notification; see E-mail Notification, and Notifications Overview for how notifications are authored. After the object's changes are written.
Relate To Creates a relationship between the object and another one. In memory.
Declare Variable Introduces a typed variable into the run. In memory.
Set Variable Changes the value of a declared variable. In memory.
Comment A note in the operations list; it does not run. Never.
Add Attachments Adds attachments to the object. In memory.
Push Notification Adds a push notification; see Push Notification and Notifications Overview. With the object's changes, inside the same save.
Unrelate Removes relationships between the object and other objects. In memory.
Iterate Collection Loops over a script object or one of its collections, binding each element to a context variable. In memory.
Iterate String List Splits a calculated string on a delimiter and loops over the parts. In memory.
Return Ends the current named function, or the program if no named function contains it. A Scheduled Task can also discard pending changes; see Return. Immediately.
Break Leaves the loop it is in. Immediately.

Break outside a loop is refused with the error "\"Break\" is not allowed outside of a loop."

On the Mail Connector and Scheduled Task objects and on the Global Workflow object that global functions run on, a run skips Update Field, Add Attachments, Relate To, and Unrelate without an error, because there is no persistent object to apply them to.

Update operators

Update Field stores one of eleven update operators. The table lists the ten that are offered for a field type; the eleventh, auto calculate, is offered for none. The Update Field window itself writes only Set to (for a literal value) and Calculate (for an expression); see Update Field.

Operator Effect Offered for
Set to Assigns the value. Every field type.
Clear Assigns an empty (null) value. Every type except yes/no (Boolean).
Increase Adds the value. Numeric fields.
Decrease Subtracts the value. Numeric fields.
Set today Sets today's date at midnight. Date/time fields.
Set to now Sets the current date and time. Date/time fields.
Invert Flips 0 and 1. Yes/no (Boolean) fields.
Select Picks the first matching lookup row. Lookup fields.
Copy from Copies another field's value. Numeric, text, date/time, yes/no, and lookup fields.
Calculate Evaluates an expression. Numeric, text, date/time, and yes/no fields.

A user-defined lookup field accepts only Set to and Clear. Set Variable only tells Calculate apart from every other case: a calculated value is evaluated, any other value is assigned as written with its placeholders expanded, and an empty value clears the variable.

Where functions are authored

In the Settings App, a class's workflow items are under Workflow and Business Logic > module > object class > Workflow. Not every class row has that node: All Tickets/My Tickets, All Configuration Items, and Software Catalog have none, and the Workflow row of Stock Rooms opens the class's toolbar actions instead of its workflow items. A class's functions are at object class > Workflow > Components > Functions, and the functions of the Global Workflow object are at Workflow and Business Logic > Global Components > Functions. The global node requires the administrative right named Global Components; a class's node requires that class's own right ("Allows managing class business logic"). Both open the same function list and the same Function window, whose General tab holds the function's operations list. See Functions for how a function is created and named.

The operations list

The operations list is on the Programming tab of a workflow item and on the General tab of the Function window. It is a tree. Its New menu offers the operations in four groups: the object operations (Update Field, E-mail Notification, Push Notification, Execute Function, Create Object, Act on Related Object, Relate To, Unrelate, External Command, Message Box, Execute SQL, Add Attachments), the terminal ones (Break, Return, Abort), the variable and loop ones (Declare Variable, Set Variable, Iterate Collection, Iterate String List), and Comment. A separate group adds an "IF" Group, an "ELSE IF" Group, or an "ELSE" Group (see Workflow Overview for how the groups run and Conditions and Expressions for their conditions).

Choosing an operation adds its row after the focused row, or as the first row inside a focused IF, ELSE IF, or ELSE group, and opens the operation's window; Cancel removes the row again. Break and Abort are added without a window, and so is Return on an ordinary workflow item's Programming tab. In a Scheduled Task, Return opens a window; see Return. Comment opens the Comment window, and Create Object and Act on Related Object first ask for their target (see Picking a target). Return in a function, of a class or of the Global Workflow object, opens in the operation window (see Return), and so does every other operation, Iterate Collection and Iterate String List included (see The operation window).

On the Mail Connector, Scheduled Task, and Global Workflow objects, Act on Related Object is relabeled Act on Object, and Update Field, Relate To, Unrelate, and Add Attachments are shown but disabled. On the Approval Request, Purchase Order Item, Vendor Product, and Invoice Item classes, Relate To and Unrelate are not in the menu at all. Break is enabled only while the focused row is inside a loop.

Command Where Shortcut
New, Edit, Delete Toolbar
Move Up, Move Down Toolbar Ctrl+Up, Ctrl+Down
Expand All, Collapse All Toolbar Left and Right collapse and expand the focused group
Find Toolbar Ctrl+F
Find Next, Find Previous Right-click menu F3, Shift+F3
Copy, Paste Right-click menu Ctrl+C, Ctrl+V
Enable Operation / Disable Operation Right-click menu

Rows are not edited in place: a double-click outside the row's indent, or Enter, opens the operation's window, the condition window for an IF or ELSE IF row, or the Comment window for a comment. Selection is multi-row, and Move, Delete, Copy, and Enable act on the whole selection. Delete asks first: "Are you sure you want to delete the selected operation?" for one operation, "Are you sure you want to delete the selected condition?" for one conditional group, and "Are you sure you want to delete the n selected records?" for several rows.

Moving past a group. Move Down past a collapsed IF, ELSE IF, or ELSE group jumps over it, so the operation lands after the whole block; Move Down past an expanded group makes the operation the group's first child. Move Up mirrors this. A group counts as expanded when it is empty or its row is expanded, and a click in the group's indent expands or collapses it.

Enabling and disabling. The right-click command reads Disable Operation when the focused row is enabled and Enable Operation when it is not, and toggles the whole selection at once. It is available only when every selected row has the same state and every one is either an operation other than a comment or an IF / ELSE IF / ELSE group. A comment can never be enabled or disabled. A disabled row and everything nested under it are drawn in gray; disabling an IF group disables its ELSE IF and ELSE branches with it.

Copy and Paste. Copy and Paste use a list inside the Settings App, not the Windows clipboard. Copy is available once one selected row is an operation, an IF group, or an ELSE IF group, and takes the whole selection. Paste is offered whenever something has been copied, inserts after the focused row, and makes every pasted operation a new one:

  • A pasted Declare Variable whose name is taken is renamed Name_1, Name_2, and so on.
  • A pasted loop or Create Object block gets a new context variable.
  • The parameter binding of a pasted Execute Function or E-mail Notification survives only when the copy came from the same workflow object or from the Global Workflow object; otherwise its parameters arrive unassigned.
  • A pasted ELSE IF group with no IF or ELSE IF before it becomes an IF group.
  • On the Mail Connector, Scheduled Task, and Global Workflow objects, a paste that contains Update Field, Relate To, Unrelate, or Add Attachments outside a Create Object or Act on Related Object block is refused as a whole with "Invalid context. Cannot copy because some operations do not fit the context of the global function."

Comments. New > Comment adds the row and opens a Comment window with one multi-line box; canceling it removes the row again. Edit or a double-click reopens it. A comment row is green while it is not focused and may grow to eight lines; every other operation shows one line.

Blocks. Create Object, Act on Related Object, and the two Iterate operations each open a block. The opening row shows CREATE, LOOP, or FOREACH, and a generated row closes it: END CREATE, END LOOP, or END FOREACH. New with a row of the block selected adds the operation inside the block, where it runs against the created or fetched object. A Create Object or Act on Related Object block declares a reference variable for its object, named after the target class with the spaces removed and a $ in front ($Person, $Computer), with _1, _2 added when the name is taken; none is created when the block's object is a service object. The Iterate operations name their variable after the iterator.

The operation window

Each operation other than Comment that has a window opens in one modal window captioned with the operation's name. It shows Object Class: with the name of the class the operation works on: the workflow object's, or, inside a Create Object or Act on Related Object block, that block's class. Below it come the operation's own controls, an Enable operation check box (checked by default), and OK / Cancel.

  • OK stays disabled until the operation's own test passes.
  • While Enable operation is checked, an operation whose called function still has unassigned parameters is refused with "This operation can not be executed, because not all parameters of the called function are assigned." For an E-mail Notification, the message is "This operation can not be executed, because not all parameters of the notification are assigned." The same message appears when you check the box. Clearing the check box lets you save the operation incomplete; the operation is saved disabled, and a run skips it.
  • Closing the window after a change asks whether to save, with Yes / No / Cancel.
  • The placeholder browser of an operation window offers the object's fields, the common event macros, the caller's parameters, the program's variables, and the form's attachment areas; three operations leave the attachment areas out (see Picking a target).
  • When you add the operation inside a Create Object or Act on Related Object block, the window adds "Warning! You are working with .... See the relationship between objects in the list of operations."

Filling in a value

In Update Field, Declare Variable, and Set Variable, a value can be typed, picked, built as an expression, or produced by a function. The slot's Function... drop-down lists the Global Workflow object's functions, one submenu per category, beside a Function... entry that opens the full function selection and an Expression... entry for the expression editor. A chosen function's name is a link that opens its definition.

One slot accepts a record list, a SQL query whose single column becomes a list of values: the Where ID in expression of Act on Related Object through a custom relation with By Object IDs (GUID). A query that returns more than one column is refused with "The SQL expression returns more than one column. It must return only one column." A column of an unexpected type raises "The SQL expression returns data of an unexpected type. Expected data type: type." as a warning you can override.

Calculated values. A calculated value whose first line is <SQL> runs as a SQL script, exactly as written, and gives the first column of its last result set. One whose first line is <PS> runs as a PowerShell script. Any other calculated value is a SQL expression. The marker must be written in exactly that case: a lowercase <sql> line leaves the value a SQL expression. A SQL expression or script gives the first row of the first column, or, for a multi-value target, every row of it joined with ;, and the result is converted to the target's type; a result of a type the target does not accept raises a type-mismatch error. A value that comes out empty yields null. A Set to value on a text field is not calculated; only its placeholders are filled in.

Placeholders in SQL. In a SQL expression, a SQL script, or a condition expression, a placeholder is replaced with a finished SQL literal, so write it bare, without quotes of your own:

Placeholder value Written into the SQL as
Text: string, memo, lookup, multi-value, encrypted, or HTML The text as N'...', with every ' doubled
Empty text ''
Empty value of any other type NULL
Date/time {TS'yyyy-mm-dd hh:nn:ss'}
GUID '...', without the N prefix
Integer The number, unquoted
Decimal The number, unquoted, with .00 added when it has no decimal separator and no exponent
Yes/no (Boolean) 1 or 0, unquoted
%[SYS Now]% GETDATE()
%[SYS Today]% CAST(FLOOR(CAST(GETDATE() as float)) as datetime)

For a knowledge base article whose Version is 1.0, CAST(%[DBF Version]% as float) runs as CAST(N'1.0' as float), while '%[DBF Version]%' becomes 'N'1.0'', which is not valid SQL. In a condition, an HTML value is first reduced to plain text. In a text or HTML value, the same placeholder is written as display text, without quotes. A PowerShell script formats its placeholders its own way; see External Command.

Checking on save.

  • A SQL expression, SQL script, or condition that fails to parse does not block the save: "Expression validation error:" shows the SQL Server error and asks whether you are sure you would like to save, and Yes saves it.
  • A placeholder or macro the checker cannot resolve stops the save with no override, and so does a record-list query with more than one column.
  • In the Build Expression window, an empty condition is refused with "The expression is not specified."
  • A PowerShell-typed value is never syntax-checked, only its placeholders: a script with invalid PowerShell syntax saves without a warning, while an unresolvable placeholder stops the save.
  • Closing the Build Expression window with Yes instead of OK does not run the same check; see Conditions and Expressions.

Picking a target

Adding Act on Related Object opens Select Related Object(s). Its left pane offers three routes, and the right pane lists the targets:

Route Targets
Referenced Object References pointing away from this object (its parents).
Neighboring Objects References pointing at this object (its children and siblings).
Related Objects Every processed class that is neither general nor deprecated, reached through a custom relation.

Adding Create Object opens the same window captioned Select Object Class, without the left pane. Every route offers only classes you have workflow rights to and that are licensed, and a reference only when workflow may change it. A route with no targets is removed from the list, and Related Objects is removed on the Approval Request, Purchase Order Item, and Vendor Product classes. A double-click in the right pane is the same as OK; canceling the window abandons the new operation.

The windows of Act on Related Object, Relate To, and Unrelate do not offer attachment-area placeholders, though other operations of the same item do.

When the workflow log's details show Create Object, Act on Related Object, Relate To, or Unrelate, the logged object can read "All records" or "All class list name" instead of one object (see Log Entry Details).

Self-notification is turned off by selecting Do not send notifications to users who trigger them, which in the Settings App is on the Notifications > Global Settings page, under Common notification options (see Outgoing E-mail Settings, which also covers the Admin Center). With self-notification turned off, a push notification to the user running the workflow is not sent, and neither is an e-mail whose To list holds only that user once CC and BCC are empty too; the log shows such a step as "Ignored to prevent self-notification", with the recipient shown as <Initiator>.

Operation reference

Update Field

Field: lists the object's fields except calculated, image, excluded, system, read-only, and hidden HTML fields and the Ticket and OID fields. The activity fields, including user-defined activity fields, are added under the Activity. prefix, except on a few classes, among them Approval Request, Purchase Order Item, and Vendor Product; the HTML details field is left out in favor of the plain details field, and the published activity field is offered only for Incidents, Service Requests, and Reservations.

The value can be typed, picked, built as an expression, or produced by a function; the window stores Set to for a literal and Calculate for an expression, and the other operators are not reachable from it. Choosing another field clears a value that is not an expression. OK without a field says "The Field is not selected."

Setting an activity field does not change the object: the run adds an activity record instead, but only when the calculated value is not empty. The record is filled in with the object, the user who ran the workflow, the status before and after the run, and the workflow item and event that started it. When the chosen activity field is the plain-text form of an HTML activity field, the run writes the value to that HTML field and calculates it as HTML.

Set Variable

Variable: lists the variables in scope at that point, without the context variables of a Create Object, Act on Related Object, or Iterate block. The value slot is the same as in Update Field. Picking a variable of an incompatible type clears the value. OK without a variable says "The Variable is not selected."

Declare Variable

The Variable group asks for Name:, Type:, and Reference to:, and the Default value group holds the value slot with its Expression Builder button.

  • Name: accepts one to fifty word or space characters. A name already used by another variable of the same program is refused as not unique.
  • Type: offers Integer, Logical, Currency, String, Memo, Date, Date/Time, Float, Reference, HTML, and Script Object.
  • Reference to: is enabled only while the type is Reference. Its drop-down lists the workflow objects that can be looked up as a whole class, leaving out deprecated and general classes and classes that are not licensed, each expandable to its named lookups (such as Status, Type, and Category), and groups that belong to no class: All CIs, Asset CIs, Physical CIs, Configuration CIs, All Tickets, Brand, Software Product, Technician, Technician Group, Vendor Product (by Vendor), Work Calendar, Workspace, and Currency Code. Asset CIs, Physical CIs, All Tickets, Software Product, and Vendor Product (by Vendor) appear only when licensed. The box then reads object -> lookup, or the group's name alone.
  • The default value may be a literal, an expression, or a function call.

OK is enabled only when the name is not blank, a type is chosen, and, for Reference, a class is picked.

Iterate Collection

The Collection group names what the loop runs over. Under Script object, a drop-down lists the program's variables of the Script Object type; after a dot, the Collection box takes a collection property of that object, with the hint "Enter the collection property after the dot if passed as a nested object".

The Iterator group holds Iterator variable name:, after a $ prefix: the context variable each element is bound to (see the Blocks paragraph under The operations list). You can leave the name to the window, which proposes script object_Iterator and adds _1, _2, and so on when that name is taken. A name is at most fifty characters long.

OK without a script object says "The script object is not selected.", and a name already in use says "This Iterator variable name is already in use. Please use a different one."

Iterate String List

The Source string group holds Values:, the string to split, given as a value or as an expression through the button beside the box, and Value delimiter:, which offers Semicolon (;), selected when the window opens, Line break, and Space(s), and also takes a delimiter you type. Below it, the Iterator group holds Iterator variable name:, after a $ prefix.

OK refuses a missing value with "The string value is not specified.", "The value delimiter is not specified.", or "The iterator variable name is not specified."

Return and Abort compared

Both operations stop execution. The main difference is whether the program's pending changes are saved.

To do this Use What happens to pending changes
Finish the program early and keep its work Return Changes are saved when the program finishes normally.
Stop the whole run and cancel its work Abort Changes are discarded.
Finish a Scheduled Task successfully but discard its work Return with Discard all changes Changes are discarded; the job is still Succeeded.

For example, an Action's program updates a field and then reaches Return. The field change is saved, and the steps after Return are skipped. If that step is Abort instead, the field change is not saved, and the remaining steps are skipped too.

Return inside a named function ends that function rather than the whole run; see Return. Neither operation can undo an already completed save or an external effect of a script; see Abort.

Return

Use Return to stop the remaining steps without discarding the changes already made by the program. When the program ends normally, those changes are saved.

Where execution stops depends on where Return is placed:

  • In a named function, it ends that function. The calling program continues with its next step.
  • In an embedded block, such as a Create Object, Act on Related Object, or iteration block, it also leaves the surrounding blocks up to the nearest named function. If there is no named function around it, the whole program ends.

For returning a value to a calling operation, see Return a value from a function.

Configure Return in the Settings App

In a named function, Return opens a window with Value:. Enter the value the function returns, or build an expression with the button beside the box. On an ordinary workflow item's Programming tab, Return is added without a window.

In a Scheduled Task's Programming tab, the Return window offers Discard all changes instead of a value. Select it to end the task without saving the program's pending changes. The task still finishes with a Succeeded job status. Clear it to keep the changes when the task finishes. The operations tree labels the selected option Return (discard all changes). See End a task with Return or Abort.

The check box is not available inside a Create Object or Act on Object block for another object class within the task. There the value field is disabled.

Abort

Use Abort to stop the whole run without saving its pending changes. An Abort inside a named function, embedded block, or loop also stops the caller; its next step does not run.

An Abort in an On Create, On Change, or On Delete trigger also prevents the save that started that trigger. An After-Save trigger runs after the original save: Abort discards the trigger's own pending work but cannot undo that completed save.

NOTE: Abort and Return with Discard all changes do not undo effects of SQL or PowerShell scripts already evaluated as values, including external calls those scripts made. Queued Execute SQL operations are separate: they do not run when the program exits before saving.

For the messages and log statuses produced by each operation, see Return and Abort results.

Execute Function

The window holds a read-only Function: box, a Select button, and the parameters grid. A new operation opens the function picker as soon as the window appears. Select opens Select Function, which lists the functions of the operation's own workflow object and of the Global Workflow object, never another class's, with the current one preselected. Its New opens an empty Function window, and a saved new function is selected in the list; Open opens the focused function. OK, Enter, or a double-click brings the choice back. Clicking the Function: label opens the chosen function; Backspace or Delete in the box clears the choice and the grid. OK is refused while no function is chosen.

The Name / Value grid has one row per parameter of the called function:

The row shows Meaning
<Default> Unbound; the function declares a default value.
<Double-click to assign value>, in red Unbound and no default; this blocks the operation.
<Empty> Bound to an empty value.
A literal, lookup value, or attachment area name Bound to that value.
An underlined expression Bound to a calculated value.

Enter or a double-click on a row opens Assign Parameter, which shows the parameter's name in a disabled Parameter: box and one value slot: an attachment parameter gets the list of the form's attachment areas, and a reference parameter the lookup of its class. The right-click menu offers <Empty>, then False and True for a logical parameter, then the caller's parameters, the form's attachment areas, and the program's variables, each only when its type and lookup match the parameter's. Delete or Backspace clears a binding, and Ctrl+Alt+Q binds every unbound parameter to an empty value. A binding whose type no longer matches the parameter is dropped the next time the grid is filled. See Functions for how a function and its parameters are declared.

E-mail Notification

The E-mail notification group shows, top to bottom, the notification the operation sends, an Attach group, and the Parameters: grid. See Author E-mail Notifications for how a notification and its parameters are authored.

The notification. E-mail Notification: shows the chosen notification's name, read-only; once a notification is chosen, the label is a link that opens it. Select opens Select E-mail Notification, which lists the notifications of the operation's own workflow object and of the Global Workflow object, never another class's. Its New creates a notification in place. A new operation opens that list as soon as the window appears.

Attach. Three check boxes, each of which enables its own control:

Check box What it attaches
Files attached to this object (checked for a new operation) The files that earlier steps of the same program attached to the object, not the files the object already had.
Files attached using this control: The files supplied in the chosen attachment area of the form, or in the chosen attachment parameter of the caller.
Other files: The files an expression resolves to. The button beside the box opens the Build Expression window.

What the second check box offers depends on the program the operation is in:

  • In a function, it reads Files passed with this parameter: and lists the function's attachment parameters.
  • In the program of an action (a create action of any kind, a step action, or a Self Service Portal action), it reads Files attached using this control: and lists the attachment areas of the action's form. For a form with no fields the list is empty, and the check box stays available. A service action's program shows the same caption.
  • In a trigger's program, it reads Files attached using this control:, but the check box and its list are disabled.

On the Mail Connector, Scheduled Task, and Global Workflow objects, the first two check boxes are disabled, so a notification sent there attaches files only through Other files:. The Other files: expression runs as SQL, like an Add Attachments expression: an attachment's id brings that file, and an object's or an activity's id brings its attachments. An expression that returns %[DBF ID]% therefore attaches the files the object already has.

The combined size of everything the operation attaches is checked against the installation-wide limit on notification attachments. The limit is off by default, and its default size is 1 MB. When the attachments exceed it, the operation is aborted and its log is cleared. In the Settings App, the limit is set under Notifications > E-mail Notifications > Settings, in the Message options group, with the Limit the total size of attachments to check box and its size box, in MB. In Cloud, both are disabled, and the Admin Center shows the check box selected with the size at 1. See Outgoing E-mail Settings, which also covers the Admin Center.

Parameters. The Parameters: grid, with the columns Name and Value, lists the notification's parameters in the order they are declared. It works like the grid of Execute Function: the same <Default>, red <Double-click to assign value>, <Empty>, and underlined-expression rows; Enter or a double-click opens Assign Parameter; Delete or Backspace clears a binding; and Ctrl+Alt+Q binds every unbound row to an empty value. The right-click menu offers <Empty>, then False and True for a logical parameter, then the caller's parameters, the action form's fields, and the attachment areas, and then the program's variables, each only when its type and lookup match the row's.

Assign Parameter shows the parameter's name, read-only, in Parameter:, a Value: box that fits the parameter's type (a lookup list for a reference parameter, the attachment areas for an attachment parameter), and a button that opens the Build Expression window for Parameter "<name>". Choosing SQL expression, SQL script, or PowerShell script there stores the binding as an expression; see Conditions and Expressions.

Changing a parameter's type or lookup on the notification drops the bindings that no longer fit it.

At run time. An unbound parameter takes its default value. A SQL script gives a parameter the first column of the first row of its last result set, as a closing SELECT returns it (every row's first column, joined with ;, for a multi-value parameter), and an attachment parameter's expression is read like Other files:. The parameters take the values the run has at the operation's position in the program. The operation only registers the notification during the run; the e-mail is composed after the object's changes are written, once per changed object, in program order. So a notification reports the values its step saw, a failure while composing it cannot undo an object change already committed, and a run that aborts before that point sends no e-mail.

Push Notification

One Notification group, top to bottom:

  • To: a Person, picked in Select Person from the active Persons, or an expression, through the button beside the box, that the run evaluates to one Person's identifier.
  • Title: with a button that opens Select Placeholder and inserts the chosen placeholder.
  • Tapping on the notification will open: Current Object (followed by the class name) or Another Object, whose box takes only an expression that the run evaluates to one object's identifier. On the Mail Connector, Scheduled Task, and Global Workflow objects, Current Object is disabled and shows no class name.
  • Send notification to: Technician Apps (selected by default), Self Service Apps, or All Apps.
  • Content: a multi-line box with Insert Placeholder.... The content is optional.

OK stays disabled until To: and Title: are filled and Current Object is chosen or Another Object has a value. OK also checks the placeholders of the title and the content, so a placeholder that cannot be read is refused when you save the operation, not during a run.

Send notification to: selects which of the recipient's registered devices receive the notification: Self Service Apps the Self Service Portal app devices, All Apps either kind, and Technician Apps the technician app devices. A recipient with no registered device of the chosen kind receives nothing, and the operation still counts as sent.

Create Object

After you pick the class, the window shows Object Class: as a fixed label, Relationship: with the class's reference fields, its custom relation types, and a first No relationship entry, a Template group with the template picker, and an Additional group with Object Count: (a number or an expression) and two check boxes: Open created object when action is executed interactively, and Execute triggers on created object, which is checked by default. On the Mail Connector, Scheduled Task, and Global Workflow objects, the Relationship: row is hidden and OK does not wait for it. On every other workflow object, OK is refused only while nothing is selected under Relationship:; No relationship counts as a choice.

Through a reference. The Act on group shows the reference under Related Object:. For a child or sibling reference only, the label reads Related Objects: and a Where: panel adds a read-only criteria box and Criteria..., which opens the condition window used by rules. A parent reference reaches exactly one object and has no filter. Skip remaining objects in the loop appears beside Criteria... only for a child or sibling reference that is also many-to-many through a join table, or whose target is an approval request or an approval stage. Execute triggers on updated object(s) is checked by default. If the stored reference is no longer supported for the class, the window does not open: "This type of relation between ... is not supported." appears inside "Unable to modify this operation. ... Add a new operation instead and configure it as necessary."

Through a custom relation. Related Objects: shows the target class, Relationship: lists the relation types between the two classes, and Where: holds the criteria box and Criteria.... The list always ends with By Object IDs (GUID), which replaces the criteria with Where ID in and a SQL expression that must return the object identifiers; OK is refused while it is empty. Execute triggers on updated object(s) is checked by default.

Objects the run has not saved yet. Both windows can show "Exclude new, unsaved objects." under the filter: in the reference window when a Where criterion is set or the reference runs through a join table, and in the custom-relation window for every relationship except a By Object IDs (GUID) expression that resolves to one valid GUID. The loop is built from a query, so these objects are outside it. A reference loop with no criteria and no join table also takes the objects the same run has created or changed and not yet written, and drops a child or sibling that the run has re-pointed elsewhere. With By Object IDs (GUID), when the query finds nothing and the expression gives one valid GUID, that object is taken from the run.

Relate To

Object Class: lists the licensed classes that can take relations, Object: takes a picked record or an expression that returns its identifier, and Relationship: lists the relation types between the two classes in both directions, plus Member of, offered first, between a Person and a Group. Changing the class clears the relationship, and the object picker then reads "Select class". The class list is sorted by name, and a new window opens with its first class selected, so the class is missing only when the list is empty. OK reports the first missing value: "The object class for relation is not specified.", "The object for relation is not specified.", or "The relation is not specified."

At run time, relating two objects that are already related that way, or an object identifier that comes out empty, does nothing, without an error or a log entry.

Unrelate

The Relate To window with <any object> added to the class list and <any relation>, always first, added to the relationship list, which offers every relation type of the workflow object's class. Choosing <any object> disables and clears Object:. With <any relation> chosen for a Person and Group pair, a note reads "\"<any relation>\" does not include \"Member of\"". OK requires a class and a relationship, not an object.

At run time, Unrelate removes whatever matches and reports nothing when nothing does. An empty object means every record of the chosen class, <any object> ignores the second object, and <any relation> removes the object's relations in both directions. An object expression that comes out empty does nothing, though the step is still logged.

Add Attachments

One Attachments: slot, whose list holds the form's attachment areas and the caller's attachment parameters. When a new operation finds neither, the slot takes an expression instead. OK with nothing chosen says "The Attachments value is not specified." Acting on the action's own object, the list offers only the areas whose Automatically attach files to the object box is cleared; acting on another object inside a Create Object or Act on Related Object block, it offers every area of the form.

An expression runs as SQL (a first line containing <SQL> makes it a script) and must return identifiers from the first column of each row: an attachment's id brings that file, an object's id brings that object's attachments, and an activity's id brings that activity's attachments. An identifier that matches none of the three is dropped without an error, and the log lists the file names resolved. An E-mail Notification's attachment expression follows the same rule.

Message Box

One memo, with an Insert Placeholder... button and, on the right-click menu, Create New Macro..., which turns the selection, or the whole text when nothing is selected, into a named user macro and puts its placeholder in its place. Both commands appear only while the memo has the focus. OK is refused on a blank message and checks the placeholders.

An interactive application shows the message as an information dialog. The Mail Connector, the Scheduled Tasks service, the Discovery Connector, the Inventory Scanner connector, the directory import, the Database Archiver, and the report command-line tool write it to their own log instead: as an information entry, or, when a Scheduled Task started the run, as a plain line with a timestamp.

Execute SQL

One memo with an Insert Placeholder... button, offered while the memo has the focus. OK is refused on blank text, replaces every non-breaking space in the statement with an ordinary space, trims the end of the statement, and then runs it through the SQL checker, and the window stays open when the checker rejects it. The checker only parses the statement, unless its first line is <SQL>, in which case it runs it. The check runs inside a transaction that is always rolled back, so it leaves no committed change.

Execute SQL, Message Box, and External Command also offer Placeholder Definition... on the right-click menu while the caret is inside a user macro or workflow parameter placeholder; it opens that macro's or parameter's window, or warns when no macro or parameter of that name is stored.

External Command

Run command on offers Client (selected by default) and Server. Run holds Command:, a button that opens it in a larger Command editor, and Insert Placeholder.... Display PowerShell window appears only for Client, and Timeout (min): only for Server; it starts at 1, and 0 means no limit. OK is refused on a blank command and checks the placeholders. With Display PowerShell window cleared, the client runs PowerShell with its window hidden; with it checked, the PowerShell window stays open after the command.

How the command runs.

  • The whole command text becomes a PowerShell script. Nothing splits it into a program and arguments, so a bare program name must be found by PowerShell on the computer that runs it: the technician's for a client command, the Automation Server's host for a server command. A client command's working directory is %USERPROFILE%.
  • Placeholders are written for use inside a double-quoted PowerShell string, and you supply the quotation marks. An empty value of a non-text field becomes $null, a logical becomes $true or $false, and a value of a text, memo, GUID, date, time, date/time, lookup, multi-value, attachment, encrypted, or HTML field is written as plain text with each of `, ", $, “, ”, and „ escaped with a backtick. A value with a space, $, or quotation mark in an unquoted placeholder reaches PowerShell as a different command.
  • A command that is a web link is URL-encoded and started with Start-Process on the client. A web link sent to the server is not run.

Client commands. A client command runs when the workflow was started from the Web App, the Self Service Portal, or the Mobile App. When the API started the run, the command is accepted and recorded in the workflow log without an error, but it is not run: the API returns the command, with its placeholders already filled in, in its response to the action. When a service started the run, the command is refused, the service log records that the workflow can run external commands only on the server, and the run continues. The client needs Alloy Integration Launcher, which the Alloy Navigator Windows applications installer installs with the applications. When the installed launcher is older than the server expects, the run stops with "Cannot run the action because your Alloy Integration Launcher version is outdated. Please upgrade the launcher and try again."; OK downloads and starts the new installer. In the Web App, a technician without the launcher gets a four-step install dialog: download the installer, run it, confirm the Windows install prompt, then close the dialog and run the action again. In the Self Service Portal, when an action needs the launcher, the portal opens the launcher's link and checks up to five times, with growing delays, whether the launcher took the job. Only when it did not does a warning dialog open, with a title, a warning, a description, and a download note. Nothing downloads by itself: the dialog's Download button starts the download of the launcher installer in a new browser tab and closes the dialog, and Cancel closes the dialog without doing anything else.

Server commands. A server command is queued after the save is committed, and the Automation Server starts it under the account its service runs as. The workflow does not wait for it and never learns its result. With a positive timeout, the process tree is ended when the timeout passes.

Starting the Settings App. An External Command can start the Settings App (AlloyNavigatorMngr.exe) signed in, with /AUTOLOGIN, /CONNECTION= (a connection's GUID or name), /SQLSERVER=, /DATABASENAME=, /WINAUTH= (YES or TRUE, in any case, for Windows authentication; any other value means SQL authentication), /USERNAME= (or /USER=), /PASSWORD= (the encrypted form, not plain text), and /ACCESSKEY=. These override the stored connection's account, and /AUTOLOGIN skips the login dialog when they suffice.

  • Conditions and Expressions: the conditions of the IF, ELSE IF, and ELSE groups, and the expressions inside operations.
  • Functions: creating, naming, and calling the functions an Execute Function operation invokes.