Skip to content

save_trigger.md

Latest commit

 

History

History
137 lines (103 loc) · 4.69 KB

save_trigger.md

File metadata and controls

137 lines (103 loc) · 4.69 KB
Raw

save_trigger

Save Trigger Actions

Define actions to perform automatically when a record is created, updated, saved, disabled, uploaded, or before saving. Each event key (on_create, on_update, on_save, on_disable, on_upload, before_save) takes an ordered list of trigger tasks.

!defs(extra_options_save_trigger_defs.yaml)

Trigger Types

Each trigger task listed under an event key corresponds to one of the following trigger types:

Record Operations

Trigger Description
add_tracker Add a tracker entry
create_master Create a new master record
create_reference Create a reference to another model
reload_this Reload the current record from the database
update_reference Update a referenced record
update_this Update fields on the current record

Communication & Notification

Trigger Description
notify Send an email or SMS notification
pull_emails Read MIME emails from S3, filesystem, or IMAP and run nested triggers per email

User & Access

Trigger Description
change_user_roles Add or remove user roles
set_item_flags Set item flags on the current record

Files & Documents

Trigger Description
create_filestore_container Create an NFS filestore container
generate_document Generate a document from a template and store in a filestore container

External Integrations

Trigger Description
pull_external_data Pull data from an external HTTP source
redcap_request Make a REDCap API request

Search

Trigger Description
full_text_search Build and persist PostgreSQL tsvector full-text search indexes

Variables & Results

Trigger Description
set_save_trigger_results Set save trigger result values for use in subsequent triggers
set_variables Set variables for use in subsequent substitutions and triggers

Control Flow

Trigger Description
background Run a set of triggers asynchronously in a background job
case Conditionally branch trigger execution based on a condition
each Iterate over a list and apply a set of triggers for each item
run_batch_trigger Run a batch trigger on a set of records
transaction Wrap a set of triggers in a database transaction

Utilities

Trigger Description
log Write a log entry (useful for debugging and audit trails)

Lifecycle Hooks

All save trigger types support on_complete and on_failure lifecycle hooks. These fire additional triggers after the main trigger succeeds or fails.

  • on_complete: triggers to run after successful completion
  • on_failure: triggers to run when an exception is raised (the original exception is re-raised afterwards)

Both accept a single trigger hash or an array of trigger configurations.

Top-level usage

Place on_complete / on_failure alongside the trigger's own configuration keys:

save_trigger:
  on_create:
    log:
      message: 'Processing record'
      severity: info
      on_complete:
        - log:
            message: 'Processing completed'
            severity: info
      on_failure:
        - log:
            message: 'Processing failed'
            severity: error

Per-entry usage

For triggers that accept multiple named entries (e.g. add_tracker, create_reference, update_this), place on_complete / on_failure inside each entry:

save_trigger:
  on_create:
    add_tracker:
      - Q1:
          with:
            sub_process_name: Review
            protocol_event_name: Done
          on_complete:
            - log:
                message: 'Tracker Q1 added'
                severity: info
      - Q2:
          with:
            sub_process_name: Review
            protocol_event_name: Pending
          on_failure:
            - log:
                message: 'Tracker Q2 failed'
                severity: error