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.
Act on Related Object
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$trueor$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-Processon 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.
Related topics
- 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.