Actions

Labels provide a simple way to show workflow states on objects but by default any user with labelling permissions can add or remove a label from an object.

Sometimes you may want more control over workflow states. For example, a "Tested" label should only be applied to an Edit Check by a user with a Study QA role and only when the object already has a label of "Requires Testing". When the "Tested" label is applied, the "Requires Testing" label should be removed.

Actions provide a way to formalize these kinds of workflow steps. They allow you to:

Provide a name for the action e.g. "Mark as Tested"
Define which object this action can work on e.g. Edit Checks
Set a pre-condition on when this action is allowed to run. e.g. "Only when the user has a study QA role and the object is already labelled "Requires Testing"
Define a set of activities which the action will perform e.g. Add label "Tested", Remove label "Requires Testing". This is similar to the Check Actions of an Edit Check.

Actions are created at the URL level. In order to create or edit an Action the user must have the URL level Manage Actions permission.

Action topics

Creating Actions

Action Name

The name of the Action appears to users in the list of available Actions for an object or object listing.

Action Description

Set a description for an Action which summarizes the purpose of the Action and any preconditions for its use. The description is shown to users when the select the Action to be run on an object or a set of objects.

Applies to Object

An Action is related to a particular object type. Actions may be associated to one of:

Projects

Tickets

Drafts

Forms

Folders

Matrices

Data Dictionaries

Unit Dictionaries

Edit Checks

Derivations

Custom Functions

Test Cases

Custom Objects

For example, the Form listing will not show an option to apply an Action if has not been associated with Forms. If you want a similar action such as "Mark Tested" for both Edit Checks and Derivations, create two separate actions both called "Mark Tested", one for Edit Checks and one for Derivations.

Precondition Logic

A logical expression that determines whether the Action may run on an object. If it evaluates to True the Action's operations run on that object; if False the Action is not offered for that object. The functions and values available in a precondition — labels, custom properties, compliance status and more — are described on the Precondition Logic page.

Action Active

If an Action is not active then it will not be shown to users. This allows you to disable an action for all objects in a URL.

Action Type

Each action has a type that determines how it is triggered and where it appears. The action type is set using the Action Type dropdown when creating or editing an action. The available types are:

Type	Description
User action	The default type. User actions appear in the list of actions that users can choose to apply to objects. They support role restrictions, data collection, and preconditions.
Auto action	Automatic actions run every time an object is saved and cannot be manually applied by any user. They do not appear in the list of actions that a user can choose from. Auto actions cannot have data entry requirements or role restrictions.
Agent action	Agent actions are exclusively for use with agent hooks. They do not appear in the list of actions that users can choose from. Agent actions support role restrictions and data collection, like user actions. The Agent type is only available when LLM Agents are enabled for the URL.

Automatic Actions

Having an action run every time an object is saved can be useful for enforcing a workflow via Labels, especially when combined with labels which are reserved for actions meaning that the label cannot be added/removed by human action, only by an action Operation.

Note

Automatic Actions are not run by bulk maintenance of a Custom Property's value list — renaming or merging a choice value, or converting or deleting a text value. Those operations change the vocabulary rather than editing the objects that use it. See Effects of a Bulk Value Change.

Data Collection

When a user performs an action, you may wish to collect some data from the user related to that action. For example, the subject identifier and/or environment where an Edit Check was tested. The Data Collection page of the Action editor allows you to select Custom Properties to show to the user for data collection. You can also set whether a Custom Property value is required. Each property is shown with the input appropriate to its type — a date picker for a Date property, a rich-text editor for an HTML property, and so on.

When an Action that collects data is run on a single object, any values that object already holds for the selected Custom Properties are shown pre-filled in the data collection fields. This lets the user see the values that will be overwritten and use them as a starting point.

When the Action is run on more than one object, the fields are pre-filled from the first applicable object. Selecting any object in the list of objects shown in the dialog updates the fields to display that object's current values. The data collection fields are shared, so the values shown when you apply the Action are written to every selected object.

Operations

An Action performs one or more Operations when it runs — adding or removing labels, setting or clearing custom property values, sending email, creating tickets, assigning users, and so on. The full list of operation types and their parameters, and how operations interact with custom properties, is on the Operations page.

Applied by Roles

Actions may only be initiated by users with a defined Role in the Project. For example, you may only want users with a Tester Role to be able to run the "Mark Tested" Action on Edit Checks in your study. The Applied by Role section of the Action editor allows you to select which roles can see and execute this Action from the list of Project Roles defined in your URL.