Trigger definition

After you have written a trigger, you create the trigger definition by issuing the p4 triggers command and providing trigger information in the triggers formClosed The 'p4 triggers' form in which each trigger is defined by four fields. Sometimes referred to as the 'triggers table'.. You must be a Helix Server superuser to run this command.

Field names (such as Triggers:) must be flush left (not indented) and must end with a colon. Field values (that is, the set of lines you add, one for each trigger) must be indented with spaces or tabs on the lines beneath the field name.

Example trigger definition for a single trigger

The p4 triggers form looks like this:

Triggers:
  relnotecheck change-submit //depot/bld/...  "/usr/bin/rcheck.pl %user%"
  verify_jobs  change-submit //depot/...      "/usr/bin/job.py %change%"

In this example:

  • relnotecheck is the name

  • change-submit is the type

  • //depot/bld/... is the path, which, depending on the type of trigger, might take a value that looks different from this example

  • "/usr/bin/rcheck.pl %user%" is the command, where %user% is a trigger variable passed to the Perl script. See Trigger script variables.

Trigger fields

This triggers form has three trigger definitions, and each trigger definition has four fields.

Triggers:
  relnotecheck change-submit //depot/bld/...  "/usr/bin/rcheck.pl %user%"
  verify_jobs  change-submit //depot/...      "/usr/bin/job.py %change%"
  check-sync command pre-user-sync "check-sync.pl %serverservices%"
Trigger Definition Fields
Field Meaning

name

The user-defined name of the trigger.

To use the same trigger script with multiple file patterns, list the same trigger multiple times on contiguous lines in the trigger table. Use exclusionary mappings to prevent files from activating the trigger script. The order of the trigger entries matters, just as it does when exclusionary mappings are used in views. In this case, only the command of the first such trigger line that matches a path is used.

type

Each type of trigger corresponds to an event that causes that type of trigger to fire.

Trigger types listed by category

Triggering on submit and populate

Triggering on fixes

  • fix-add

  • fix-delete

Triggering with depots of type graph

  • graph-push-start
  • graph-push-complete
  • graph-push-reference
  • graph-push-reference-complete
  • graph-lfs-push

Triggering on pushes and fetches

  • push-submit

  • push-content

  • push-commit

Triggering on forms

  • form-save

  • form-out

  • form-in

  • form-delete

  • form-commit

Triggers for external file transfer

  • pull-archive

  • edge-content

Triggering before or after commands

  • command

Triggering to use external authentication

  • auth-check

  • service-check

  • auth-check-sso
  • auth-set

  • auth-invalidate

Triggering on heartbeat (server responsiveness)

  • heartbeat-missing

  • heartbeat-resumed

  • heartbeat-dead

Triggering on journal rotation

  • journal-rotate

  • journal-rotate-lock

Triggering for multi-factor authentication (MFA)

  • auth-pre-2fa
  • auth-init-2fa
  • auth-check-2fa

Triggering on failed-back

  • failed-back

Triggering on shelving events
  • shelve-submit
  • shelve-commit
  • shelve-delete
Triggering to affect archiving

  • archive

Triggering on failed-over

  • failed-over

path

The meaning of this field depends on the trigger type. For example:

To learn what this field means for a trigger type that you want to use, see the section about that trigger type.

command

Specify the trigger in a way that allows Helix Server to locate and run the command when the conditions of the trigger definition are satisfied.

The command is typically a call to a script.

Specify the name of the trigger script or executable in ASCII, even when the server is running in Unicode mode and passes arguments to the trigger script in UTF8.

The command must be enclosed within quotation marks, and can take any argument that your command is capable of parsing, including any applicable Helix Server trigger variables. See Trigger script variables.

On those platforms where the operating system does not know how to run the trigger, specify an interpreter in the command field. For example, Windows does not know how to run .pl files, so the following specifies perl

lo form-out label  "perl //myscripts/validate.pl"

Two more command examples:

  • "/usr/bin/rcheck.pl %user%" passes the %user% trigger variable to a Perl script.

  • "/path/to/journal-rotate.sh %journal% %serverid% %serverport%" passes three trigger variables to a shell script.

If your trigger script is stored in the depot, its path must be specified in depot syntax, delimited by percent characters. For example, if your script is stored in the depot as //depot/scripts/myScript.pl, the corresponding value for the command field might be "/usr/bin/perl %//depot/scripts/myScript.pl%". See Storing triggers in the depot.

How triggers run

Triggers are run in the order listed in the triggers form. If a trigger fails for a specified type, subsequent trigger also associated with that type do not run.

The p4 triggers command has this syntax:

p4 triggers [ -i | -o ]
  • With no flags, the user’s editor is invoked to specify the trigger definitions.
  • The -i flag reads the trigger table from standard input.
  • The -o flag displays all the trigger definitions stored in the trigger table.