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:

  1. Provide a name for the action e.g. "Mark as Tested"

  2. Define which object this action can work on e.g. Edit Checks

  3. 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"

  4. 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.

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

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 which determines if the Action can be applied to an object. If the expression returns True then the operations defined by the Action are run on the object. If the expression returns False then the Action will not be run for that object.

Expression

Description

Example

 
True

Returns logical True.

 
True

False

Returns logical False.

 
False

not

Logical reversal. Turns True into False and False into True

 
not(1 == 1)

and

Logical AND. Returns True if both sides of the and evaluate to True

 
1 == 1 and 2 == 2

or

Logical OR. Returns True if either side of the or evaluate to True

 
1 == 3 or 2 == 2

to_integer("1")

Returns an integer value. Useful when a custom property value contains a numeric string but you need to compare it to a number. Note that any decimal point will be truncated (rounds down).

 
to_integer(p("expected subject count")) > 2

to_float("2.1")

Returns a float value. Useful when a custom property value contains a numeric string but you need to compare it to a floating point number.

 
to_float(p("pi")) > 3.1

has_label("Label Name")

Returns True if the object has the label "Label Name". It is typical to check that an object is already in one state (represented by an existing Label on the object) before performing an Action to remove that label and add another. This allows you to move an object which is labelled "Ready for testing" to "Tested" for example.

 
has_label("Tested") or not(has_label("Blocked"))

p("project property")

Returns the value of the Custom Property named "project property" for the Project to which the object belongs. If the object of the Action is a Project itself then these values are also available.

 
p("therapeutic area") == "CNS"

attribute("object custom property")

Returns the value of the Custom Property named "object custom property" for the Object on which the action runs. If the object of the Action is a Project then this is the same as p("object custom property").

 
attribute("standards number") == "123"

draft_approved_by_role("Project Role")

Returns True if the Draft has been approved by a user with this Project role. This is only valid for Actions which are applied to Drafts and to objects within Drafts (Forms, Test Cases etc).

 
draft_approved_by_role("Project Manager") and has_label("Tested")

compliance_status_is(COMPLIANCE_STATUS_ID)

Returns True if the compliance status of the object matches the COMPLIANCE_STATUS_ID passed. This is only valid for Actions which are applied to objects within Drafts which have standards compliance information. The possible values for COMPLIANCE_STATUS_ID are:

  • NOT_APPLICABLE

  • CALCULATING

  • NOT_FOUND

  • DIFFERENT

  • ALLOWED_CHANGES

  • MATCH

Note that objects which are not linked to a library do not have compliance status calculated, their status will be NOT_APPLICABLE.

 
compliance_status_is(ALLOWED_CHANGES) or compliance_status_is(MATCH)

only_allowed_changes()

Returns True if the compliance status of the object is ALLOWED_CHANGE and the only changes made are allowed changes as defined for allowed adds and deletes in Data Dictionaries and Form Fields and the allowed changes attribute lists of Forms and Fields.

If an object is in state ALLOWED_CHANGE but has some passed standard rules or the count of allowed changes is zero then this function returns False.

Note that objects which are not linked to a library do not have compliance status calculated, only_allowed_changes() will always return False for objects not linked to the library.

 
only_allowed_changes() and p("Check All Changes") == "true"

only_rules_passed()

Returns True if the compliance status of the object is ALLOWED_CHANGE and the only changes made are allowed by Standard Rules.

If an object is in state ALLOWED_CHANGE but has some allowed changes or the count of rules passed is zero then this function returns False.

Note that objects which are not linked to a library do not have compliance status calculated, only_rules_passed() will always return False for objects not linked to the library.

 
only_rules_passed() and p("Check All Changes") == "true"

matches_copy_source()

Returns True if the object is in a draft linked to a library (so has compliance status) and the object was copied from some other draft and the current object exactly matches the object copied (by fingerprint) not taking into account any allowed changes or rules.

If the object was not copied from another object within TrialGrid or the object is not in a draft linked to the standard library or the object has any difference then this function returns False.

This is useful when you allow objects to be copied from similar studies (where testing may already have been done) and you want to know that the object was not changed at all from the original.

 
matches_copy_source()

related_custom_function_changed()

Works only for Auto Actions on Edit Checks and Derivations. When the Source Code of a Custom Function is changed which is used by the Edit Check or Derivation (e.g. in Check Step, Check Action or Derivation Step) then Auto Actions are run for those Edit Checks and Derivations with related_custom_function_changed() == True.

A source code change means a meaningful non-whitespace, non-comment change to the logic of the custom function.

In effect, related_custom_function_changed() is a way of calling auto-actions for Edit Checks and Derivations when a Custom Function is changed. This can be used to add a label to Edit Checks or Derivations signalling that they should be tested if the Custom Function they rely on changes.

 
related_custom_function_changed() and not has_label("Requires Testing")

related_matrix_folders_changed()

Works only for Auto Actions on Edit Checks. When the Folder/Form combinations of a Matrix changes, then Auto Actions are run for those Edit Checks which have AddMatrix, MergeMatrix or OldMergeMatrix actions which reference the changed Matrix. When these Actions run, the function related_matrix_folders_changed() == True.

A change to Folder/Form combinations means that a Folder/Form combination is added or removed.

In effect, related_matrix_folders_changed() is a way of calling auto-actions for Edit Checks when a Matrix which is referenced by those Edit Checks is changed. This can be used to add a label to Edit Checks signalling they should be tested if the Matrix they rely on changes.

 
related_matrix_folders_changed() and not has_label("Review Matrix")

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.

Automatic Actions

An Action can be made automatic by checking the Is Automatic? checkbox. Automatic actions are run every time an object is saved and cannot be manually applied by any user. Automatic actions do not appear in the list of actions that a user can choose from.

Automatic actions cannot have data entry requirements.

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.

Operations

An action may have one or more Operations. An Operation is like an Edit Check action - it can add or remove labels from objects. Each type of Operation has a set of related parameters such as the name of the label to add or remove.

Operation

Parameters

Description

Add Label

Label Name

Adds this Label to the Object if it doesn't already have that Label associated with it.

Remove Label

Label Name

Remove this Label from the Object if has that Label associated with it.

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.

Note

Users who are Owners of the Project are not able to run any Actions. Users must have a specified Role in the Project.

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.