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 form. You must be a Helix Server superuser to run this command. 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%"

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.

Each line in the trigger form you fill out when you use the p4 triggers command has the following four 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.

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

The trigger for Helix Server to run when the conditions of the trigger definition are satisfied.

You must 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.

Specify the trigger in a way that allows Helix Server to locate and run the command. The command (typically a call to a script) must be quoted, and can take any argument that your command is capable of parsing, including any applicable Helix Server trigger 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"

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

Triggers are run in the order listed in the trigger table. If a trigger script fails for a specified type, subsequent trigger scripts 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.