Precondition Logic

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

int("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).

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

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.

 
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.

object_has_label("Label Name") is an alias for has_label("Label Name").

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

project_has_label("project label")

Returns True if the Project to which the object belongs has the given label applied. The Project itself does not need to be the target of the Action — this lets you gate object-level Actions on Project-level labels.

 
project_has_label("Active Study")

draft_has_label("draft label")

Returns True if the Draft to which the object belongs has the given label applied. This is only valid for Actions which are applied to Drafts and to objects within Drafts (Forms, Test Cases etc).

 
draft_has_label("Approved")

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.

project_property("project property") is an alias for p("project property").

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

d("draft property")

Returns the value of the Custom Property named "draft property" for the Draft to which the object belongs. This is only valid for Actions which are applied to Drafts and to objects within Drafts (Forms, Test Cases etc) — Actions on Projects cannot use d().

draft_property("draft property") is an alias for d("draft property").

 
d("IRB Approved") == "Yes"

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")

agent("variable_name")

Returns the value of a variable exported by an agent hook. This function is only available in preconditions for Agent type actions that are triggered by agent hooks.

Each agent hook exports specific variables that capture details about what the agent did. For example, the Custom Function Review agent exports error_count when a review is saved. See the Agents Catalog for the variables available on each agent's hooks.

 
agent("error_count") > 0 and not has_label("Has Errors")