Administration Guide

Functions

On this page

A function groups workflow operations into a program. Use a named function when several workflow items need the same operations, and pass values through its parameters. A workflow item's own program also consists of operations; see Operations Reference.

A function of the Global Workflow object is a global function. The Global Workflow object exists so that class-independent functions have a home. A global function is offered from every class's function picker and is the only kind of function that carries a Category. The other functions belong to one class.

Return a value from a function

In the Settings App, add Return to the named function's operations and set Value: to a literal value or an expression. Only a Return in a named function returns a value; a Return in an embedded block does not.

Update Field, Declare Variable, and Set Variable can use a function as their value source. The returned value must fit the field or variable's type. Execute Function runs the function but ignores its returned value.

For saving or discarding changes when execution stops, see Return and Abort.

In the Settings App

Before you begin

  • To work with a class's own functions, you need that class's own administrative right, the one named after the class ("Allows managing <class> business logic").
  • To work with global functions, you need the administrative right named "Global Components".

Create or edit a function

  1. Open the function list. Both routes open the same function list and the same function window:
    • For a class's own functions, go through that class's Workflow node.
    • For global functions, go to Workflow and Business Logic > Global Components > Functions.
  2. Create a function, or open an existing one. The window is titled Function, with the function's name in brackets, and has the General, Parameters, and Callers tabs. The Parameters and Callers tabs show how many rows they hold.
  3. On the General tab, Object Class shows the workflow object's name and cannot be edited. Enter a Name; it is required.
    • A new function starts with a generated name made of the workflow object's name, the word Function, and a five-digit number, with spaces removed, for example IncidentFunction00007. The number comes from one counter shared by all functions of all classes, so it is not the class's own sequence.
    • The ID shown on the tab is a separate number, shared with the other kinds of workflow items.
  4. For a global function, you can select a Category. The list offers the categories already used by global functions. The field is shown only for global functions.
  5. Build the function's program in the operation tree, which fills the rest of the General tab. See Operations Reference for the operations and the Operation window.
  6. Save the function.

A function name must be unique within its class, ignoring case. If the name is taken, the save stops with the message "This <field> is already in use. Please use a different one.", where <field> is the caption of the Name field, and the General tab opens. The check is per class, so the general and the class-specific workflow object of one class share the same names.

A global function that is a system function opens read-only: an information panel shows the message "This is a system function that cannot be modified. To view all details or make changes, create a copy of the function." Its operation tree and parameter grid are view-only, and the parameter toolbar is hidden.

Declare parameters

  1. Open the function and go to its Parameters tab. The grid shows Name, Type, and Default Value.
  2. Use New, Edit, Remove, Move Up, and Move Down to manage the list. INSERT, ENTER, and DELETE do the same as the first three, and a double-click on a cell opens the parameter.
  3. In the Parameter window, enter a Name and select a Type. For a reference type, select a lookup in Reference to, which is available only for a reference type.
  4. Under Default value, enter a literal of the chosen type or a calculated expression.
  5. Click OK, and then save the function.

OK stays unavailable until a name and a type are set and, for a reference type, a lookup is selected. A name already used by another parameter of the same function is refused.

A function parameter's Type list is the ordinary parameter type list plus Attachments and Script Object. It offers no Lookup, Multi-select, Duration, Encrypted, or Image type.

The order of the rows is the order callers see the parameters in. Moving a row renumbers the list. A removed parameter is deleted only when you save the function.

If you change a parameter's type to one its current value cannot be converted to, and a caller passes this parameter a literal (not calculated) value, clicking OK refuses the change with the message "You cannot change the data type of this parameter. One or more operations use this parameter to pass the value, and the new data type is not compatible with the current one. Modify the operations first. You can access these operations via the Callers tab."

How a call passes values

Parameters are declared once on the function and bound at each call site. The Settings App binds them in the step's Parameters grid and its Assign Parameter window. When the function runs, it takes the call site's binding if one exists and the declared default otherwise, and evaluates it in the caller's context. See Operations Reference for the binding grid.

An Attachments parameter passes a list of attachment ids, not files. When the binding is calculated, the list is the result of an attachment-selecting expression. When it gives an attachment area's id, the list is the contents of that area. Otherwise it is the calling run's parameter of the given name.

Find where a function is used

The Callers tab is read-only and lists what calls the function. Open opens the caller: a workflow item's editor, a scheduled task's properties, or another Function window.

To open a function by the number its window shows, use Go To... on the Search menu (Ctrl+G) and enter the number in Workflow Item #. The same number space covers workflow items, notifications, and named functions, and the field's drop-down lists up to twenty numbers you opened before, newest first. A match selects the owning class's workflow node and opens the item's window. If nothing has that number, the message "Workflow Item # <n> was not found." appears and the dialog opens again. If you may not view the class, a no-rights message appears instead.

Find... (Ctrl+F) and Find Next (F3) on the same menu search the text of the program being edited. Search in Workflow on that menu opens a search window with an empty box; what you type is matched as free text. A macro's or a parameter's own references are listed on its Usage tab; see Macros Reference for a macro and Workflow Configuration for a workflow parameter.

Delete a function

A function that anything calls cannot be deleted. The delete stops with the message "Unable to delete function "<name>" because one or more workflow items refer to it. Remove dependencies first.", and the function opens on its Callers tab, which lists what refers to it.

How functions are called

A function runs in one of these ways:

  • As a workflow item's own program.
  • Embedded in a Create Object or Act on Related Object step, where it runs once per target object.
  • Embedded in an iteration step, where it runs once per element. Before each pass, the loop binds the current element to a context variable and removes it afterwards, so a nested function sees exactly one element at a time and cannot reach the previous one.
  • From an Execute Function step, or as the source of the value in an Update Field, Declare Variable, or Set Variable step.
  • As a global function, from the REST API (see Global functions and the API).

A named function and an embedded function behave differently:

  • An embedded function sees the caller's variables. Declared parameters and their stored bindings are loaded only for named functions.
  • Values from the calling function's parameters, and from the virtual form fields of the calling Action or Service Action, are passed into an embedded function by name and arrive unchanged; they are not evaluated again.
  • A Return ends the nearest named function, and that function's caller continues with its next step. A Return inside an embedded block passes up through the surrounding blocks to that named function. If none contains it, the whole program ends. An Abort stops the whole run even inside a named function.
  • Only a named function's name appears in error and log text.

Global functions and the API

Only a global function can be called from outside the product, and the REST API is what calls it; a class's own function cannot be reached this way. The function runs through the ordinary workflow engine with no record to act on, and its parameters take the values the call supplies, or their declared defaults. How to call a global function, how to read its result, and what such a call does not do are described in Global Workflow Functions.