RepositoryGetTriggerTable Method

Parameters

options

Type: Perforce.P4Options

Return Value

Type: IListTrigger

p4 help triggers

triggers -- Modify list of server triggers

p4 triggers
p4 triggers -o
p4 triggers -i

'p4 triggers' edits the table of triggers, which are used for
change submission validation, form validation, external authentication,
external job fix integration, external archive integration, and command
policies.

Triggers are administrator-defined commands that the server runs
to perform the following:

Validate changelist submissions.

The server runs changelist triggers before the file transfer,
between file transfer and changelist commit, upon commit failure,
or after the commit.

Validate shelve operations.

The server runs shelve triggers before files are shelved, after
files are shelved, or when shelved files have been discarded
(via shelve -d).

Manipulate and validate forms.

The server runs form-validating triggers between generating
and outputting the form, between inputting and parsing the
form, between parsing and saving the form, or when deleting
the form.

Authenticate or change a user password.

The server runs authentication triggers to either validate
a user password during login or when setting a new password.

Intercept job fix additions or deletions.

The server run fix triggers prior to adding or deleting a fix
between a job and changelist.

Access external archive files.

For files with the +X filetype modifier, the server runs an
archive trigger to read, write, or delete files in the archive.

Command execution policy.

Command triggers can be specified to run before and after
processing of user requests. Pre-execution triggers can
prevent the command from running.

The trigger form has a single entry 'Triggers:', followed by any
number of trigger lines. Each trigger line must be indented with
spaces or tabs in the form. Triggers are executed in the order listed
and if a trigger fails, subsequent triggers are not run. A trigger
succeeds if the executed command exits returning 0 and fails otherwise.
Normally the failure of a trigger prevents the operation from
completing, except for the commit triggers, which run after the
operation is complete, or the change-failed trigger which is only
advisory.

Each trigger line contains a trigger name, a trigger type, a depot
file path pattern matching where the trigger will be executed, a
command name or form type and a command to run.

Name: The name of the trigger. For change triggers, a run of the
same trigger name on contiguous lines is treated as a single
trigger so that multiple paths can be specified. Only the
command of the first such trigger line is used.

Type: When the trigger is to execute:

archive:
Execute an archive trigger for the server to access
any file with the +X filetype modifier.

auth-check:
service-check:
Execute an authentication check trigger to verify a
user's password against an external password manager
during login or when setting a new password.

auth-check-sso:
Facilitate a single sign-on user authentication. This
configuration requires two programs or scripts to run;
one on the client, the other on the server.

client:
Set the environment variable 'P4LOGINSSO' to point to
a script that can be executed to obtain the user's
credentials or other information that the server
trigger can verify. The client-side script must
write the message to the standard output
(max length 128K).

Example: P4LOGINSSO=/Users/joe/bin/runsso

The two variables available to this trigger are
%P4PORT% and %serverAddress%. The distinction is
that serverAddress is the address of the target server
and the P4PORT is what the client is connecting to,
which might be an intermediate like a Perforce Proxy.

These variables can be passed to the client script by
appending them to the client command string, as in:

P4LOGINSSO="/Users/joe/bin/runsso %serverAddress%"

server:
Execute an authentication (sso) trigger that gets
this message from the standard input and returns an
exit status of 0 (for verified) or otherwise failed.

Example:
sso auth-check-sso auth "/secure/verify %user%"

The user must issue the 'p4 login' command, but no
password prompting is invoked. If the server
determines that the user is valid, they are issued a
Perforce ticket just as if they had logged in with a
password.

Pre-2007.2 clients cannot run a client-side single
sign-on. Specifying an 'auth-check' trigger as a backup
for a user to gain access will prompt the user for a
password if it's an older client or P4LOGINSSO has not
been configured.

Unlike passwords which are encrypted, the sso message is
sent to the server in clear text.

auth-set:
Execute an authentication set trigger to send a new
password to an external password manager.

change-submit:
Execute pre-submit trigger after changelist has been
created and files locked but prior to file transfer.

change-content:
Execute mid-submit trigger after file transfer but prior
to commit. Files can be accessed by the 'p4 diff2',
'p4 files', 'p4 fstat', and 'p4 print' commands using
the revision specification '@=change', where 'change' is
the pending changelist number passed as %changelist%.

change-commit:
Execute post-submit trigger after changelist commit.

change-failed:
Executes only if the changelist commit failed.
Note that this trigger only fires on errors
occurring after a commit process has started. It does
not fire for early usage errors, or due to errors from
the submit form. In short, if a change-* trigger
could have run, then the change-failed trigger
will fire if that commit fails.

command:
Execute pre/post trigger when users run commands.

edge-submit:
Execute pre-submit trigger on Edge Server after changelist
has been created but prior to file transfer.

edge-content:
Execute mid-submit trigger on Edge Server after file
transfer but prior to beginning submit on Commit Server.

fix-add:
Execute fix trigger prior to adding a fix. The special
variable %jobs% is available for expansion and must be
the last argument to the trigger as it expands to one
argument for each job listed on the 'p4 fix' command.

fix-delete:
Execute fix trigger prior to deleting a fix. The special
variable %jobs% is available for expansion and must be
the last argument to the trigger as it expands to one
argument for each job listed on the 'p4 fix -d' command.

form-out:
Execute form trigger on generation of form. Trigger may
modify form.

form-in:
Execute form trigger on input of form before its contents
are parsed and validated. Trigger may modify form.

form-save:
Execute form trigger prior to save of form after its
contents are parsed.

form-commit:
Execute form trigger after it has been committed, allowing
access to automatically generated fields (jobname, dates
etc). It cannot modify the form. This trigger for job
forms is run by 'p4 job' and 'p4 fix' (after the status
is updated), 'p4 change' (if the job is added or deleted)
and 'p4 submit' (if the job is associated with the change).
The 'form-commit' trigger has access to the new job name
created with 'p4 job', while the 'form-in' and 'form-save'
triggers are run before the job name is created. The
special variable %action% is available on the job
'form-commit' trigger command line, and is expanded when
the job is modified by a fix.

form-delete:
Execute form trigger prior to delete of form after its
contents are parsed.

shelve-submit:
Execute pre-shelve trigger after changelist has been
created but prior to file transfer.

shelve-commit:
Execute post-shelve trigger after files are shelved.

shelve-delete:
Execute shelve trigger prior to discarding shelved files.

Path: For change and submit triggers, a file pattern to match files
in the changelist. This file pattern can be an exclusion
mapping (-pattern), to exclude files. For form triggers, the
name of the form (branch, client, etc). For fix triggers
'fix' is required as the path value. For authentication
triggers, 'auth' is required as the path value. For archive
triggers, a file pattern to match the name of the file being
accessed in the archive. Note that, due to lazy copying when
branching files, the name of the file in the archive can not
be the same as the name of the file in the depot. For command
triggers, use the name of the command to match, e.g.
'pre-user-$cmd' or a regular expression, e.g.
'(pre|post)-user-add'.

Command: The OS command to run for validation. If the command
contains spaces, enclose it in double quotes. The
following variables are expanded in the command string.
Use of the triggers.io configurable with a value greater than
zero is recommended, as some vars may be empty or contain
shell metacharacters.

%//depot/trigger.exe% -- depot paths within %vars%
are filled with the path to a temporary file containing
the referenced file's contents. Only standard and stream
depot files whose contents is available are valid.
%argc% -- number of command arguments
%args% -- command argument string
%argsQuoted% -- command argument string, CSV delimited
%client% -- the client issuing the command
%clientcwd% -- client current working directory
%clienthost% -- the hostname of the client
%clientip% -- the IP address of the client
%clientprog% -- the program name of the client
%clientversion% -- the version of the client
%command% -- name of command being run
%groups% -- list of groups user is a member of
%intermediateService% -- presence of a Broker/Proxy/etc
%maxErrorSeverity% -- highest error seen for this cmd
%maxErrorText% -- text and errno for highest error
%maxLockTime% -- user-specified override of group value
%maxResults% -- user-specified override of group value
%maxScanRows% -- user-specified override of group value
%quote% -- double quote character
%serverhost% -- the hostname of the server
%serverid% -- the value of the server's server.id
%serverip% -- the IP address of the server
%servername% -- the value of the server's $P4NAME
%serverpid% -- the PID of the server
%serverport% -- the IP address:port of the server
preceded by the transport prefix,
if needed (i.e. P4PORT)
%serverroot% -- the value of the server's $P4ROOT
%serverservices% -- the services provided by the server
%serverVersion% -- the server's version string
%terminated% -- if the command was forced to quit early
%termReason% -- reason for early termination
%triggerMeta_action% -- command to execute by trigger
%triggerMeta_depotFile% -- third field in trigger def.
%triggerMeta_name% -- name from trigger definition
%triggerMeta_trigger% -- second field in trigger definition
%user% -- the user issuing the command

%changelist% -- the changelist being submitted
%changeroot% -- the root path of files submitted
%oldchangelist% -- the pre-commit changelist number

(More information can be gathered about the
changelist being submitted by running
'p4 describe %changelist%'.)

%formfile% -- path to temp file containing form
%formname% -- the form's name (branch name, etc)
%formtype% -- the type of form (branch, etc)
%action% -- added/deleted/submitted on job form-commit

%jobs% -- list of job names for fix triggers

%op% -- read/write/delete for archive access
%file% -- name of archive file
%rev% -- revision of archive file

If the command was sent via a proxy, broker, or replica:
%peerhost% -- the hostname of the proxy/broker/replica
%peerip% -- the IP address of the proxy/broker/replica
If the command was sent directly, %peerhost% and
%peerip% match %clienthost% and %clientip%.

For a change-* trigger in a distributed installation,
%submitserverid% -- the server.id where submit was run

For a post-rmt-Push trigger:
%firstPushedChange% -- first new changelist number
%lastPushedChange% -- last new changelist number

Note that not all variables are available for every
trigger type. E.g. argc and argv only show up for
pre-user-$cmd and change-submit (and so on), but not for
post-user-$cmd or change-commit.

The command's standard input depends on the value of the
triggers.io configurable. When it is set to zero, stdin is
empty for change, shelve, fix and command triggers, it
is the file content for the archive, and password for auth
triggers. When triggers.io is set to 1, stdin is a textual
dictionary containing connection information that the trigger
must read (with the exception of archive/auth triggers,
which behave the same as when triggers.io=0.)

If the command fails, the command's standard output (not
error output) is sent to the client as the text of a trigger
failure error message.

If the command succeeds, the command's standard output is
sent as an unadorned message to the client for all triggers
except archive triggers; for archive triggers, the command's
standard output is the file content.

The -o flag writes the trigger table to the standard output.
The user's editor is not invoked.

The -i flag reads the trigger table from the standard input.
The user's editor is not invoked.

'p4 triggers' requires 'super' access granted by 'p4 protect'.

To get the trigger table: