Administration Guide

Workflow Overview

On this page

Workflow is configuration stored in the Alloy Navigator database: the buttons a technician sees, the rules that run when a record is saved, the e-mails that go out, and the forms people fill in. The product supplies the engine that runs this configuration and the editors that write it, but the working workflow is loaded separately. Before a configuration is applied, a new database has no workflow items or components. The Default Workflow provides a working configuration, and you can edit it or replace it as a whole; see Default Workflow Configuration.

You author workflow in the Settings App. The Admin Center covers most everyday settings, and the Settings App is the tool for advanced features such as deep workflow development; see Admin Center and Settings App.

Workflow uses these terms:

  • An item is something that can run: an action, a trigger, or a service action.
  • A component is a reusable part that an item points at: a template, a form, a function, an e-mail notification, or a push notification.
  • A process is a name used to group items for administrators.

Workflow objects

Each workflow item or component belongs to a workflow object. There is one workflow object for each class that can carry workflow, and every item and most components belong to exactly one of them. A workflow therefore belongs to one object class.

The set of workflow objects is fixed by the product. Creating a database loads 42 of them, the Default Workflow adds none, and you cannot add one. Three of them are not ordinary classes:

  • All CIs and All Tickets each stand for a whole family of classes, so workflow written against either applies across that family.
  • Global Workflow holds the functions and e-mail notifications that do not belong to any one class. A global function is offered in the function picker of every class, and it is the only kind of function that has a category.

Items

Every item belongs to one of these families:

Item What it is for
Step Action A technician runs it on an existing object.
Create Action An object is created through a form.
Trigger on Condition The engine reacts on a schedule, or after an object has been saved.
Trigger on Created/Modified The engine reacts when an object is created, changed, or either.
Trigger on Deleted The engine reacts when an object is deleted.
Service Action A background component creates or updates an object on the product's behalf.
Scheduled Task Authored with the Automation Server's jobs rather than with a class's workflow.

Service actions come in create and update pairs, because a connector decides for each incoming record whether it is making something new or changing something it made before. For how actions are built, see Actions.

Components

An item points at no more than one form, one template, one program, and one icon. Because an item only points at them, a component can be shared by several items.

Component How an item uses it
Form The form of the item. A Create Action without a form uses the object's full form; a Step Action without a form runs with no form.
Template The item's data template.
Function The item's program.
Icon The item's icon.
E-mail notification Referenced by a step of the item's program.
Push notification Is itself a step of the item's program.
Macro Expanded from the item's text when the item runs.
Workflow parameter Expanded from the item's text when the item runs.
Lookup filter Referenced by a field of a form.

Deleting items

The database enforces the rules for deleting an item, so they are the same in every editor:

  • A system item cannot be deleted.
  • An action that a Request Fulfillment refers to cannot be deleted.
  • Deleting an item also removes its security role grants, its process memberships, its trigger history, its workflow log rows, its parameter bindings, its service field mappings, and its toolbar bindings.
  • The components that belonged to the item alone are deleted with it, and so is its icon unless it is the shared default icon. A form, template, or function that is shared is left in place.

Programs

An item's program is a function: a list of steps, called operations, arranged in conditional groups. The engine walks the program from the top. An IF group runs its steps when its condition holds; otherwise the engine tries each ELSE IF or ELSE group of the same statement in turn and takes the first that matches. A disabled step or group is skipped. Conditions are turned into database queries and evaluated against the database, with two exceptions that the running application decides itself: a PowerShell condition, and a program group's condition made only of PowerShell conditions and simple comparisons of the object's own non-calculated fields. The condition dialog offers a PowerShell condition only for a function's condition; see Conditions and Expressions. For what each operation does, see Operations Reference.

Most operations do not take effect at the point where they appear in the program. A run has three phases:

Phase What happens If something fails
1. Program The steps run in order. Field updates, related-object work, and variables are applied in memory; SQL, message box, external command, and push notification steps are queued. The run stops before anything is written.
2. Transaction All changed objects are saved and push notifications are recorded, then the changes are committed together. A Scheduled Task whose transaction option is turned off saves each object without a transaction, and a run that starts inside a transaction that is already open adds none of its own. The changes are rolled back and the run is logged as failed.
3. After commit Notifications are created and queued, deletions are performed, queued SQL runs one statement at a time, and triggers that run after a save are run. Then external commands are dispatched and message boxes are shown. The committed changes stay. The failing step is logged as failed; a failed SQL statement or message box stops the steps queued after it.

Saving an object can fire triggers whose changes fire further triggers. The engine allows ten such passes. If a trigger still matches on the eleventh pass, nothing of the save is written, the trigger's run is logged as failed, and the user sees "Error while executing the workflow function. Workflow Item

n." followed by "The maximum number (10) of recursive calls for triggers

is exceeded. Please simplify your workflow definition."

Processes

A process is a label for a set of items. It changes how you can list and bulk-edit those items and nothing else: the engine does not use processes when it runs workflow.

Statuses

An object's place in its workflow is its status. Statuses are a lookup of each class, as types are, and a status can point at a lifecycle stage, which is also defined for each class and ranked. The engine uses statuses in these places:

  • An action's status list limits the objects it is offered on. Items also carry a type list; both lists hold values of the class's lookups.
  • When a run changes an object's status, the activity it logs records the old and the new status name.
  • Each class has an inactive status. A Reopen action is offered exactly on inactive objects. On a Computer, a Reopen action is refused when reopening would exceed the licensed number of nodes.
  • A scheduled Trigger on Condition never acts on an object in its class's inactive status, whatever its own condition says.

Configuration that workflow uses

Workflow items refer to configuration defined elsewhere, so that configuration should exist before you write the items:

  • Security roles. An item can be granted to security roles; see Security Roles. A role groups permissions, and an account holds the roles it is a member of; see Accounts.
  • Types and statuses. The type and status lists of an item hold values of the class's lookups.
  • Outgoing e-mail. An item's notifications are queued for outgoing mail; see Notifications Overview.
  • Macros. An item's text can expand user macros; see Macros Reference.
  • User-defined fields. Conditions and field operations can name user-defined fields.
  • Work calendars. Work calendars feed the SLA clock; see Work Calendars and Services and SLAs.

Where workflow runs

There is no central workflow server. Each application that runs workflow runs it itself, against the database.

An item that a user runs, such as an action, runs inside the application the user is working in: when a technician runs an action in the Web App, the Web App runs it, and the same holds for the Self Service Portal and the API. The action's changes to the object are complete by the time the request returns. Its notifications are queued during the same request.

Every run is recorded with the application or service that started it:

Started by Recorded as
Web App Web Portal
Self Service Portal Self Service Portal
API API
Automation Server, for Triggers on Condition Scheduled Trigger Agent
Automation Server, for recurring objects Recurrent Ticket Agent
Mail Connector Mail Connector
Scheduled Task Agent Scheduled Task Agent
Active Directory import Active Directory Import
Alloy Discovery connector Alloy Discovery Connector
AlloyScan connector AlloyScan
Data archiving Data Archiving

The same value decides how the outgoing mail of that run is classified.

Not every message the product sends comes from workflow. The password e-mail sent when a self-registration is approved is built from a fixed e-mail template of its own: no workflow item or e-mail notification is involved in sending it, and only macro expansion and the outgoing mail queue are shared with workflow.

The Automation Server and the agents

The Automation Server runs three kinds of scheduled task:

Task What it runs Where a failure shows
Trigger Triggers on Condition that have a schedule The Automation Server's own log
Recurring object The recurring objects users define, created through workflow The Automation Server's own log
Tool An agent program, which the Automation Server starts and waits for The agent's log

For the logs, see Logs.

The Scheduled Task Agent checks that the scheduled task it was started for exists as a workflow item. If it does not, the agent stops before running anything, with "A job with the ID '<id>' was not found."

Scheduled workflow and scheduled services share one list of Automation Server jobs. A job is one of these: a scheduled workflow item (a Trigger on Condition), a recurring object, the Mail Connector, Active Directory synchronization, a scheduled report command, the Alloy Discovery connector, data archiving, the Scheduled Tasks agent, or the AlloyScan connector.

When you save a Trigger on Condition with a schedule, its job is written with it. The job and the trigger are always enabled or disabled together, and deleting the job deletes the trigger.

The Mail Connector, Active Directory import, Alloy Discovery connector, AlloyScan connector, Data Archiving, and Scheduled Task agents each run workflow themselves, under their own service person. All of them except Data Archiving run the items of their own family: service actions or scheduled tasks. A ticket created by the Mail Connector therefore goes through the same items, programs, and e-mail notifications as one created by a technician.

An external command step that is set to run on the server is not started by the application that runs the program. It is queued, and the Automation Server starts it. A command set to run on the client is handed to the client, and the Web App, the Self Service Portal, and the API cannot see its result.

How changes reach running applications

Each application keeps a copy of the workflow it has loaded. Saving or importing workflow items and components, e-mail notifications, workflow parameter values, or macros, or saving a settings page the engine reads, marks the change, and each application reloads the affected part when it notices the mark. Until then, an edited action can still run in its old form:

Application Notices a change within
Web App 30 seconds
Self Service Portal 1 minute
API 1 minute
Automation Server 1 minute; a schedule change is picked up at once

In the Web App, when a request names an action other than a Step Action, a recurring-ticket rule, or a dependent lookup that the Web App's loaded workflow no longer resolves, the Web App returns the error "You cannot complete the action because Alloy Navigator business logic has been modified. Please save the data you have entered, close the window, and launch the action again. If you have problems accessing the action, contact your Alloy Navigator administrator."

What the platform and the Default Workflow supply

A newly created database holds the 42 workflow objects, two icons, and no items, functions, forms, templates, e-mail notifications, processes, parameters, macros, or filters. There is no working workflow in a database until a configuration is applied.

A new 2026.1 database created with the Default Workflow also holds the working workflow: items, functions, forms, templates, e-mail notifications, processes, workflow parameters, macros, lookup filters, and Automation Server jobs. The Default Workflow is a starting point, not a fixed part of the product: everything it supplies arrives as ordinary configuration, and you can edit or delete any of it that is not flagged as system. It describes what a new database starts with: an upgraded database need not have the current Default Workflow content, and an administrator may have changed any of it.

Trigger history, recurring objects, and queued external commands start empty and fill as the system runs, so their being empty in a new installation is normal. For how the Default Workflow is applied and upgraded, see Default Workflow Configuration.

Workflow in the Settings App

The Settings App's workflow editors cover items and components (actions, triggers, functions, e-mail and push notifications, service actions, templates, forms and their fields and validation), the operations of a program, expressions and conditions (including the macro dialog, a PowerShell console, and a SQL checker), and processes.

Find workflow in the navigation tree

Workflow lives in the Workflow and Business Logic group of the Settings App. Its areas are, in order: Workflow Configuration, Macros, Global Components, Service Desk, Service Management, Project Management, Asset Management, Purchasing, Configuration Management, Software Asset Management, Organization Management, and Advanced. Service Management, Project Management, Asset Management, Purchasing, Configuration Management, and Software Asset Management appear only when your license includes the module each of them requires. For how administrative rights decide which nodes you see, see Work in the Settings App.

Each class sits under its business area, and a class node carries up to six children in this order: Fields, Shared Views, View Form (Web App), Macros, Classification, and Workflow. Shared Views appears only when the database uses the old views option. Not every class has all of them.

  • Workflow Configuration sets the values of workflow parameters without opening a workflow item. The parameters themselves and their categories are defined under Advanced > Configuration Parameters. A new 2026.1 database created with the Default Workflow starts with a set of them; see Default Workflow Configuration.
  • Advanced > Processes lists the processes and their items.
  • A class's Workflow node opens the class's workflow tree. For Stock Rooms, the Workflow node opens the toolbar actions editor instead.

The workflow tree of a class

The Workflow node of a class shows three folders:

Folder Nodes
Actions Create Actions (not for Approval Stages), Step Actions, Service Actions, and Built-in UI Actions (Project Tasks only)
Triggers On Condition, On Created/Modified, On Deleted
Components Templates, Forms, Functions, E-mail Notifications, Push Notifications

The Global Workflow object's tree has only Functions and E-mail Notifications.

The toolbar offers New, Edit, Delete, Copy Item, and an ordering command: Display Order... on Create Actions and Step Actions, and Order... on the Actions and Triggers folders and the trigger nodes. Service Actions has no ordering command. The ordering command opens the Display Order dialog on the Actions folder, Create Actions, and Step Actions, and the Execution Order dialog on the triggers; see Actions and Triggers. The right-click menu adds New, Enable and Disable (for items, not components), and Export Selected Settings….

  • New opens an empty editor window.
  • Edit, a double-click, or Enter opens the selected row's window.
  • Copy Item copies the selected row and opens the copy.
  • OK saves a changed window and closes it. A window's title starts with an asterisk while it holds unsaved changes.

Some nodes offer fewer commands:

  • Push Notifications offers no New, Delete, or Copy Item. A push notification is created and deleted as a step of the program that sends it; the list opens and edits existing ones.
  • Built-in UI Actions offers no New, Delete, Copy Item, Enable, or Disable, and no ordering command.

On Service Actions, New is a submenu with a create and an update entry for each connector and for the Self Service Portal, offered only on the classes each of them serves; see Service Actions:

Connector Menu entries Create action offered on Update action offered on
Mail Connector Create Action for Mail Connector, Update Action for Mail Connector every class every class
Active Directory import Create Action for Active Directory Import, Update Action for Active Directory Import Persons Persons
Alloy Discovery connector Create Action for Alloy Discovery Connector, Update Action for Alloy Discovery Connector Computers, Hardware, Persons Computers, Hardware
AlloyScan Create Action for AlloyScan, Update Action for AlloyScan Computers, Hardware, Persons Computers, Hardware
Alloy Discovery connector, Chromebooks Create Chromebook Action for Alloy Discovery Connector, Update Chromebook Action for Alloy Discovery Connector Computers Computers
Self Service Portal Create Action for SSP (on Persons, the entry ends in (Self-Registration)), Update Action for SSP Incidents, Persons, Reservations Incidents, Approval Requests, Reservations, Service Requests

Edit an item's program

The program is edited in the operations list of an item's window, of a Function window, or of a Scheduled Task's window.

  • The New menu of the operations list ends with "IF" Group, "ELSE IF" Group, and "ELSE" Group. "ELSE IF" Group and "ELSE" Group are available only while the focus is inside a statement, and "ELSE" Group is unavailable once the statement has one.
  • Adding an IF group adds an IF row and an END IF row with nothing between them. Adding an ELSE IF or ELSE group moves every row that followed the focused row into the new branch. An IF group added while an operation inside a branch has the focus becomes part of that branch, and nothing limits how deeply statements nest.
  • Double-click an IF or ELSE IF row to open the Criteria window and set the group's condition. A row without a condition reads "(<Double-click to add criteria>)".
  • Changes to the operations list stay in the window until you save it. Save writes without closing and is unavailable while nothing has changed, and OK saves and closes. In an item's window, the item's mandatory fields and form are checked first, and a refused save writes nothing. Writing the program itself is not a single transaction in an item's window or a Function window: if a save fails partway through, the rows already written stay. A Scheduled Task's window saves the program, the task, and its run record in one transaction, and rolls all of them back together if the save fails.
  • Cancel on a window with unsaved changes asks "Do you want to save the changes?". Yes saves, No closes the window and discards the changes, and Cancel keeps the window open.

A Function window, titled with the function's name, has a General tab with Object Class:, Name: (required), ID:, and, for a function of the Global Workflow object only, Category:. Its Parameters and Callers tabs show how many entries each holds.

Group items into processes

Under Workflow and Business Logic > Advanced > Processes:

  • The Process List node offers New, Edit, Delete, Move Up, and Move Down for the processes themselves.
  • Each process has its own node, which lists its items and offers New, Open (also a double-click), Remove, Enable, and Disable.
  • New offers the item kinds (Create Action, Step Action, Trigger on Condition, Trigger on Create/Modify, and Trigger on Delete), each with a list of classes, and opens the new item's window. Saving the item adds it to the process. Invoice Items is in these class lists only when the workflow parameter for Invoice Items processing enables it.
  • Remove takes the item out of the process and does not delete it.

See where a macro or a field is used

  1. Open the Macros grid, under Workflow and Business Logic > Macros or under a class's Macros node, or the Fields grid, under General > Fields or under a class's Fields node.
  2. Double-click the macro or the field. A macro opens in the Macro [<name>] dialog; a system field opens Field Properties, and a user-defined field opens User Defined Field. A shared ticket field opens a dialog of its own instead.
  3. In the dialog, open the Usage tab. While references exist, the tab reads Usage (<n>).
  4. To go to a referring item, select its row and click Open.

In the macro dialog, Open opens the referring item's editor on the tab where the reference is; for some service actions, among them Chromebook and AlloyScan service actions, it does nothing. In a field's dialog, the Usage tab also offers Open in New Window.

A user-defined field that workflow items refer to cannot be deleted. The attempt fails with "Unable to delete field "<label>" because one or more workflow items refer to it. Remove dependencies first." and opens the field's dialog on the Usage tab.