Create an application trigger

In this topic Hide

About this page

This page is used to create or edit a trigger rule to automatically create or update Significant Events. You define the condition under which the rule should be triggered by a) the module and page in which it occurs and b) the type of action, whether it is newly-entered data or changed data. Then you use JavaScript in the Rule Script area to define the rest of the condition (field and so on) what should happen with Significant Events when the condition occurs.  

Prerequisites

This function is enabled with the Application Trigger product key.

•        To successfully use this feature, the IT specialist must have the following:

•        Solid JavaScript knowledge and experience, as a minimum

•        An understanding of the underlying data in the RME database, and fundamentals of the RME system, such as knowledge of core fields. If this isn't possible, we recommend working with RME administrators or Research Office team members who have experience using RME. Core fields that can be used are provided in the List of Items next to the Rule Script area.

•        For end users, access to the relevant Significant Event type/s must be given to relevant roles. See: Role Significant Event Access

For some ideas, see: Sample application triggers.

Menu path: RME > Setup > Application Trigger (Search) > Application Trigger

 

Video: Application Trigger

How the Application Trigger feature works to automatically create or update Significant Events.

 

Create or edit a trigger rule

1.     From the RME menu, go to Setup > Application Trigger.

2.     In the toolbar, click the New button. To edit an existing trigger, find it in the grid and click the Open icon next to it.

3.     Complete or edit the Module, Page and Action Criteria fields to define where the condition occurs and the type of action. Note that this combination must be unique.

4.     Complete or edit the fields, using the table below as a guide.

5.     In the Rule Script area, define in JavaScript: a) the Significant Event trigger condition/s and b) action/s to take.

For a list of fields you can use in the script, see the options in the List of Items next to the Rule Script area. First, select an item type from the dropdown. A list of fields you can use in your script based on the selected Module and Page and item type will be displayed.
For triggers based on Significant Event changes, the fields you can use for the resulting action are limited. See Exception: Triggers based on a Significant Event field change below.

Warning! In the script, you need to combine the item type shown in the List of Items field with the exact field label shown in the list, with a period (.) in between, such as Event.Act_Complete_Date.  Be sure to include all underscores. See the full example in the table below, or other example scripts in Sample application triggers.

For objects you can use in the script, see Objects you can use in scripts below.

6.     Validate before you save your script by clicking the Validate button. If the script does not pass, a notification displays so you can address issues. See the field description in the table below for details.

7.     When full script validation passes, select Save in the toolbar.

The script will be executed when the condition you defined occurs, such as when a field is changed to a specific value. If there is an issue with field validation, a message will display when the script is run.

Application Trigger: Fields

Field Label

Description

Action Criteria *

Mandatory

Type of change that triggers the rule, either:

•        Insert (add) - the rule will be triggered when new data is added manually or via an eForm, API or feeder
(This is not available if Page = Significant Event for either the Contract or Project module)

•        Update (modify) - the rule will be triggered when data is changed manually or via an eForm, the API or feeders

 

For example, for a script that creates a Significant Event when a project Status is changed to Approved, the action criteria is Update because it is a change of the Status value rather than the addition of a new value.

For an eForm, scripts are executed in the Push to Database Tables workflow activity. In cases where this activity is executed more than once in a single workflow action, the application trigger is only executed once at the end of the activity execution. For a script designed to create or update a record, the Created Date and Last Modified Date will be checked. If both dates are the same, the Create/Insert script will be triggered. If these dates are different, the Update script will be triggered. Scripts for a scenario based on an Old object, such as Create an event when project type is Grant with an old status of Draft and new status of Approved are not supported for eForms.

Current?

Default for new rules: Yes

Whether the rule is current

RULE: For any rules with exactly the same combination of fields (Module, Page, and Action Criteria), only one should be current.

If the rule is no longer current, slide this to No.

List of Items

Dynamic list of fields you can enter manually in your script, based on the selected Module and Page for the rule, except for triggers based on Significant Event changes (see Exception: Triggers based on a Significant Event field change below).

To use the List of Items to define your script:

1. Select an item type from the dropdown to view a list of fields you can enter in your script. It either lists fields from the module page or Significant Event record.

2. Using the list as a reference, enter the field name in the Rule Script area manually; you cannot select a field to automatically add it.

For each field you want to use, enter the name you selected in the List of Items dropdown (indicating which page) followed by a period with no spaces, then the exact field name as listed (or group of fields), including underscores.

 

Examples

Single field when Module = Projects, Page = Projects, List of Items dropdown = Project:

Project.Date_Approved

Group of fields when Module = Projects, Page = Projects, List of Items dropdown = SIGEVENT:

 SigEvent = {

Action_Date ...

Event_Type ...

(and so on) ...}

Screenshot of example explained in the text above

 

Example script with entered fields and List of Items as the reference

Note  In this field list, technical Field Labels from the back-end are used rather than the label displayed in the UI (View Field Label) for each field. This is because Field Labels are static, whereas View Field Labels can be customised for your institution. If you are unsure what a Field Label relates to in your instance, look up the Page View for the RME page selected in the Page field for this script. Find the Field Label in the grid. Click the entry to view full field properties, which includes the View Field Label displayed in your user interface.

Exception: Triggers based on a Significant Event field change (Contracts and Projects modules only)

These triggers involve both a trigger change and action in the same Significant Event, unlike other triggers. As such, these are a little different. While you can use any item in the List of Items to define the trigger, but you can only use these properties to define the resulting action:

•        Action_Date

•        Status

•        Act_Complete_Date

•        Status2 (Project Significant Events only)

If Finance Significant Events functionality is used via an applied product key:

•        Is_Req_Complete

•        Inv_Status (Contract Significant Events only)

To  commit Significant Event actions, use the SIGEVENT.UpdateSigEvent() function, instead of the SIGEVENT object that is used for other trigger scripts based on a core record.

Note that you cannot add script using the above objects in another type of application trigger (one triggered by a change to a core record field). These are exclusively for use in triggers based on changes in a Significant Event (Module = Contract or Projects, Page = Significant Events).

See the sample update scripts for Project Significant Events and Contract Significant Events.

Module *

Mandatory

RME module for the condition, in which a change or update will trigger the rule

Example: For a script that creates a Significant Event when the project Status field value is changed to Approved, the module is the Project module, as this is where the Project Status field is displayed.

Available options include: Contracts, Ethics, HDR, Personnel, Projects, and Research Outputs

Page *

Mandatory

RME page for the condition, in which a change or update to a core or related item field will trigger the rule

Example: For a script that creates a Significant Event when a project Status field value is changed to Approved, this is the Project core page where the Project Status field is displayed.

Only use the Status2 field for Projects module Significant Events. If you use it for Significant  Events in any other module, it will be ignored.

Significant Events is only available for Contracts and Projects modules. This is used for defining triggers based on changes to Significant Event fields.

Rule Description

Explanation of what the rule does, as a reference and to help distinguish it clearly from others

Rule Name *

Mandatory

Name of the rule so that it is clearly distinguished from others

Rule Script *

Mandatory

The JavaScript rule that includes both the condition/s and the required Significant Event action/s

Trigger condition

•        The exact name/s of the fields available for the module that trigger the change shown in the List of Items

•        You cannot select related items themselves, or custom fields.

•        For dropdowns, you must exactly match the eCode, such as a Person Code or item code for a category, as defined in RME > Setup > Categories. Example: External Grant = EXTGRAN

•        For eForms, you can only use core fields from the template.

      PLUS:

•        The value that triggers the rule, for example, when a project Status field value is changed to Approved, or other conditions, such as comparing old and new data, or identify empty fields (null)
For a list of objects you can use, see Objects you can use in scripts below.

 

Significant Event action

•        Which Significant Event/s

•        What should happen to the Significant Event/s, usually with an object to define it, such as SIGEVENT.Create(SigEvent)
For a list of objects you can use, see Objects you can use in scripts below.

•        What details to use in the Significant Event/s; include all the field properties for the impacted Significant Event/s in RME, especially mandatory fields

•        Existing email template to use: In this case, an email record and any reminders will be created, depending on template configuration, for new Significant Events or for an update to a Significant Event if no email is found. This is designed to prevent unnecessary duplicate emails or clashes with manually-configured emails for Significant Events.

•        How often, if recurring

•        Calculations, for example, to add a number of days calculated from a date field
Scripts are executed on the RME database and server so dates will be RME system dates.

 

Example script to create a Significant Event when the project Status is changed to Approved:

 

if(Core.Status == 'Approved')
{
 var SigEvent = {Action_Date:'03/10/2022',
         Event_Type:'Custom',
         Event: 'Application sent to Sponsor',
         Name: 'Event Name',
         Status: 'Active',
         Est_Complete_Date: '31/10/2022',
         Act_Complete_Date: '28/10/2022',
         Status2: 'Draft',
         Completion_Percentage: '10'
         Event_Details: 'Sample Event Details',
         Interval_Type: 'Fortnightly',
         Num_Of_Times: 4,
         Responsibilty: 'Committee',
         Completion_Details: 'Not yet Completed'
 };
 SIGEVENT.Create(SigEvent);
}
if(Core.Status == 'Completed')
{
 SIGEVENT.Update({Event_Type:'Custom',
         Event: 'Application sent to Sponsor',
         Name: 'Test Event Name',
 },{ Status: 'Complete'});
}

 

For more script ideas, see: Application Trigger samples.

Validate

Button used to simulate execution to check the syntax of the JavaScript

If the script does not pass, a notification displays so you can address issues.

Note icon Note: When an issue is discovered, validation will cease at that point. There may still be other issues after this first issue so it's a good idea to first validate functions and parts of the script without the condition. To do this, remove the condition from the Rule Script (save it somewhere else temporarily) and then select the Validate button. Continue until it passes then add the condition script back in and validate the full script. Script validation doesn't include field validation; that is only performed when the script is actually run.
 
 

Objects to use in scripts

For each module and page combination, you can use these objects in your script (you can see examples of these in the samples):

Module

Page

Object

Used to ...

Contracts

Contracts

Contract

Define the properties of the core record

A period is added after this when adding a field name. Example: Contract.DateApproved

ContractOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Significant Events

SIGEVENT

Define a changed Significant Event field value

OldSigEvent

 

Define an old object with Significant Event field values prior to the change

For a sample, see Automatically update a Contract Significant Event by defining an old field value

Note: You cannot use this for changes triggered by a Push to Database Tables workflow activity for an eForm, as it will effectively be the same data as SIGEVENT.

SIGEVENT.UpdateSigEvent()

Only for Significant Event triggers based on a Significant Event field change

Commit the defined Significant Event action

Ethics

Ethics

Ethics

Define the properties of the core record

A period is added after this when adding a field name. Example: Ethics.Approved_Date

EthicsOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

HDR

Confirmation of Candidature

ConfirmationOfCandidature

Define the properties of the core record

A period is added after this when adding a field name. Example: ConfirmationOfCandidature.StudentSignedDate

ConfirmationOfCandidatureOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Enrolment & Progress

CourseEnrolment

Define the properties of the core record

A period is added after this when adding a field name. Example: CourseEnrolment.Completed_Date

CourseEnrolmentOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Examinations

Examination

Define the properties of the core record

A period is added after this when adding a field name. Example: Examination.Date_Exam

ExaminationOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Examiner Outcome

ExaminerOutcome

Define the properties of the core record

A period is added after this when adding a field name. Example: ExaminerOutcome.Date_Assessment

ExaminerOutcomeOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Student

Student

Define the properties of the core record

A period is added after this when adding a field name. Example: Student.Supervisor_Level_Code

StudentOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Leave Details

Leave

Define the properties of the core record

A period is added after this when adding a field name. Example: Leave.Start_Date

LeaveOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Thesis Details

Thesis

Define the properties of the core record

A period is added after this when adding a field name. Example: Thesis.Expt_Com_Date

ThesisOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Thesis Submission History

ThesisSubission

Define the properties of the core record

A period is added after this when adding a field name. Example: ThesisSubission.Submission_Date

ThesisSubissionOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Personnel

Personnel

Person

Define the properties of the core record

A period is added after this when adding a field name. Example: Person.Supervisor_Role_Code

PersonOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Training

Training

Define the properties of the core record

A period is added after this when adding a field name. Example: Training.Obtained_Date

TrainingOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Projects

Projects

Projects

Define the properties of the core record

A period is added after this when adding a field name. Example: Projects.Date_Approved

ProjectOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

Significant Events

SIGEVENT

Define a changed Significant Event field value

OldSigEvent

Define an old object with Significant Event field values prior to the change

For a Contract sample to see the principles at work, see Automatically update a Contract Significant Event by defining an old field value

Note: You cannot use this for changes triggered by a Push to Database Tables workflow activity for an eForm, as it will effectively be the same data as SIGEVENT

SIGEVENT.UpdateSigEvent()

Only for Significant Event triggers based on a Significant Event field change

Commit the defined Significant Event action

Research Outputs

Research Outputs

Publication

Define the properties of the core record

A period is added after this when adding a field name. Example: Publication.Date_Complete

PublicationOld

Define an old object with field values prior to the change

SIGEVENT.Create(SigEvent)

Define a Significant Event action to create a new event

SIGEVENT.find(sigEvent)

Define a Significant Event action to identify if at least one of a particular event type exists

See: Sample - Find records that have not had any activity of a particular event type

SIGEVENT.FindAll(sigEvent)

Define a Significant Event action to identify all identified events

See: Sample - Find all Significant Events for specified criteria

SIGEVENT.Update(SigEvent,signevnt)

Define a Significant Event action to update an event

This object takes two parts:

1. SigEvent - modified object (parameter/s to be modified)

2. signevnt - existing object (parameter/s you want to modify)

These parameters are of type: Significant Event objects.

 

 

Manage triggers

You manage core records from the module search page, Results tab. Select records in the grid and use the New, Delete or Export buttons on the toolbar in  Application Trigger.

     

Related topics

•        Application Trigger search

•        Application Trigger samples

•        Significant Events for Projects, Ethics, Research Outputs, Contracts, Student, Personnel, Committees, Facilities, Panels

   

Product Key: Modules - Application Trigger

Page ID: trg001.htm