Administration Guide

Workflow Configuration and Parameters

On this page

A workflow parameter is a named, typed configuration value filed in a category. Workflow reads it through the placeholder %[WFP <Name>]%. Each parameter keeps two values: the initial value it is defined with, and the current value that workflow uses.

  • You change current values on the Workflow Configuration page, in the Admin Center or in the Settings App.
  • You define parameters and their categories only in the Settings App, under Configuration Parameters.

The workflow engine loads the parameters once and keeps them, so a changed value reaches a running engine only when it notices that the parameters were modified; see Workflow Overview.

What you can see and change

Application Page Who sees it
Admin Center Workflow Configuration tile Holders of the Workflow Configuration permission.
Admin Center Class-group tiles, such as Service Desk Holders of rights on the classes the group contains. A group you hold no matching permission for is not shown.
Settings App Workflow Configuration Holders of the page's own administrative right.
Settings App Configuration Parameters Holders of the administrative right named Configuration Parameters.

In the Admin Center

Change parameter values

  1. In the Workflow and Business Logic section, click the Workflow Configuration tile.
  2. In the category tree, open the category that holds the parameters. The page shows one control for each parameter of the category, of the parameter's kind. A category that also has subcategories shows its controls, a divider, and then a link to each subcategory; one with no parameters of its own shows only the links.
  3. Change the values. Save and Cancel appear once you change a field.
  4. Click Save.

Saving writes only the current values of the category's parameters; the parameter definitions stay as they are. If you leave the page with unsaved changes, the page asks "You should save you changes before leaving this page. Do you want to leave this page?".

A parameter's control depends on its kind: integer, floating-point number, reference, Boolean, lookup, multi-select, string, currency, duration, encrypted, memo, date, or date and time.

The Workflow and Business Logic tiles

The Workflow and Business Logic section opens as a page of tiles: Workflow Configuration, Macros, Tag Management, Service Desk, Service Management, Project Management, Asset Management, Purchasing, Configuration Management, Software Asset Management, and Organization Management.

Under a class-group tile, each class offers its fields, preview, form layouts, view forms, and classification, where the class supports them. A class is listed only for holders of the right on that class, and some of its entries need a further permission of their own; an account that holds one of the permissions that lift this check sees every class and entry. Under a license for IT asset management only, the Service Desk group keeps only approval stages, approval requests, and announcements.

In the Settings App

Change parameter values

  1. In the navigation tree, select Workflow and Business Logic > Workflow Configuration.
  2. Select a category. The page shows an editor for each parameter of the category, labeled with the parameter's label, or with its name when it has no label, together with its description. It also shows a link to each subcategory directly under the category. The editors follow the order set in Configuration Parameters.
  3. Change the values.
  4. Click Apply. Only the current values are written; the initial values stay as defined.

If you select another category while values are unsaved, the Settings App asks what to do: Yes saves the values of the category you are leaving, No discards them, and Cancel returns you to that category.

The page shows the value of an Encrypted parameter decrypted. A value you change on this page is encrypted before Apply writes it. Workflow receives the decrypted value when a rule reads the parameter.

When the workflow defines no parameters, the Settings App shows "There are no configuration options for your workflow." instead of the page. Categories cannot be created or changed on this page; they are managed in Configuration Parameters.

Define parameters

Parameters are defined under Workflow and Business Logic > Advanced > Configuration Parameters. The left pane is the category tree. The right pane lists the parameters of the selected category with Name, Type, Initial Value, Label, and Description. Each pane has a toolbar of its own: the tree's toolbar holds the commands for categories, and the list's toolbar holds, in this order, New, Edit, Delete, Copy Item, Move Up, and Move Down for parameters, followed by the filter box.

  • The filter box narrows the list to the parameters whose name, initial value, type, label, or description matches, and hides the categories that keep nothing.
  • Expand All and Collapse All expand and collapse the list's groups.
  • Apply writes your pending changes.

Manage categories

The category tree shows the categories at every level they have. The commands for categories are on the tree's toolbar:

  • New > New Category creates a category at the level of the selected one, under the same parent. New > New Subcategory creates a subcategory and is available only for a top-level category.
  • More > Properties opens the "Modify Category" window, where you change the category's name and description. It is the only way to rename a category.
  • A category name can be up to 50 characters, for a new category and for a renamed one.
  • Move Up and Move Down move a category among the categories at its level under the same parent. Both are unavailable while the filter box holds text.
  • More > Move to > Top Level moves a category from a lower level to the top level. More > Move to > Category moves a category that has no subcategories under a top-level category, which you choose in the "Choose Category" window.
  • More > Delete is available only for a category that has no subcategories and no parameters.

Create or edit a parameter

  1. Select a category and click New on the toolbar of the parameter list. To start from an existing parameter, select it and click Copy Item; to edit one, select it and click Edit, or double-click it.
  2. In the Workflow Parameter window, fill in the General tab:
    • Name: (required). The name must be unique among all workflow parameters.
    • Label:, up to 100 characters.
    • Type: (required). The types are those of an ordinary parameter, without HTML, plus Lookup, Multi-select, Duration, and Encrypted.
    • Reference to:.
    • Lookup values:, for a Lookup or Multi-select parameter.
    • Description:. Its button opens a full-size editor.
    • Category: (required). Its button opens the Select Category tree.
    • The Initial value group, which takes a single value.
  3. For a Lookup or Multi-select parameter, click the button of Lookup values: and type the values. The list is always a fixed list you type in; it cannot draw its values from a query. Each entry pairs a value with a display text, which follows the value until you type a different one.
  4. Click OK. A Lookup or Multi-select parameter with an empty list of values is refused, and the focus returns to Lookup values:.

What happens to the current value when you change a parameter:

  • A new parameter takes its initial value as its current value.
  • When you change the initial value of an existing parameter and the current value differs from the new one, the window asks "You are about to change the initial parameter value. Note that the current parameter value is %s. Do you want to change the current parameter value as well and reset it to the new initial value?", with the current value in place of %s, or <Unassigned> when it is empty. No leaves the current value as it is. An Encrypted parameter is never asked.
  • When you change the type, a current value that can be converted to the new type is converted and kept; otherwise it is reset to the initial value without asking. Changing the type away from Lookup or Multi-select drops its list of values.
  • When you change the lookup the parameter refers to, the current value is reset without asking.

Other rules:

  • A duplicate name is refused.
  • Renaming a saved parameter rewrites %[WFP <old name>]% to the new name in the workflow items that use it.
  • Copy Item creates a copy in the same category with the original's type, initial value, lookup, label, and description, names it as a copy, gives it the next free position in the category, and opens its window.
  • Moving a parameter to another category in its window places it last in that category.

Order parameters

Select one parameter and click Move Up or Move Down on the toolbar of the parameter list to move it within its category; these two commands are not those of the category tree. A parameter does not move across a category boundary. Both commands are unavailable while the filter box holds text and while more or fewer than one parameter is selected.

The Settings App's Workflow Configuration page shows the parameters in this order. The Workflow Parameters category of the placeholder browser does not: it sorts the parameters of each category by name.

Delete a parameter

  1. Select one or more parameters and click Delete on the toolbar of the parameter list.
  2. Confirm the deletion.

If any selected parameter is used by a workflow item, nothing is deleted: the Settings App shows "Unable to delete %s because one or more workflow items refer to it. Remove dependencies first.", with the parameter's name in place of %s, and opens that parameter's window on its Usage tab.

See where a parameter is used

The Usage tab of the Workflow Parameter window lists the workflow items that use the parameter's placeholder, one row per use, with the object, the item kind, the item name, and where in the item the placeholder is placed. It is unavailable for a parameter not yet saved, and its caption shows the number of uses while there are any, as in Usage (<count>). Select a use and click Open to open the referring item on the tab where the parameter is used; when the use is in one row of that tab, that row is selected.

Export definitions and values separately

Parameter definitions and parameter values export as two separate parts of a configuration, so a package can carry a parameter's definition without your site's value, or the value without the definition.

  • An export from Configuration Parameters carries the definitions: name, type, category, and initial value. With the parameter list focused, it carries the selected parameters; with the category tree focused, the parameters of the selected category.
  • An export from Workflow Configuration carries the values. With the category tree focused, it carries the values of the selected category.
  • With the focus elsewhere, the export carries all of them.

Parameters after an upgrade

An upgrade adds the parameters that are new in a version to the workflow you keep. It does not change the current value of a parameter that already exists. Only reinstalling the Default Workflow, which clears the configuration first, replaces existing parameters; see Default Workflow Configuration.

After an upgrade, review the parameters on the Workflow Configuration page.