Trigger script variables

You can use trigger script variables to pass data to a trigger script. All data is passed as a string. It is up to the trigger to interpret and use these data appropriately.

It is also possible to have the server and trigger communicate using STDIN and STDOUT. For more information, see Communication between a trigger and the server.

The maxError…​ variables refer to circumstances that prevented the server from completing a command, such as an operating system resource issue. Note also that client-side errors are not always visible to the server and might not be included in the maxError count.

The terminated and termReason variables indicate whether the command exited early and why.

Note

Any unknown variables remain in the trigger invocation. This preserves the trigger argument ordering, and might be a clue to authors that data they assumed to be available is not.

Argument Description Available for type

%action%

Either null or a string reflecting an action taken to a changelist or job.

For example,"pending change 123 added" or "submitted change 124 deleted" are possible %action% values on change forms, and "job000123 created" or "job000123 edited" are possible %action% values for job forms.

form-commit

%archiveList% Filename containing files to be pulled pull-archive

%argc%

Command argument count.

all except archive

%args%

Command argument string.

all except archive

%argsQuoted%

Command argument string that contains the command arguments as a percent-encoded comma-separated list.

all except archive

%changelist%, %change%

The number of the changelist being submitted. The abbreviated form %change% is equivalent to %changelist%.

A change-submit trigger is passed the pending changelist number; a change-commit trigger receives the committed changelist number.

A shelve-commit or shelve-delete trigger receives the changelist number of the shelf.

change-submit
push-submit
change-content
push-content
change-commit
push-commit
fix-add
fix-delete
form-commit
shelve-commit
shelve-delete

%changeroot%

The root path of files submitted.

change-commit
push-commit

%client%

Triggering user’s client workspace name.

all

%clientcwd%

Client’s current working directory.

all except archive

%clienthost%

Hostname of the user’s workstation (even if connected through a proxy, broker, replica, or an edge server.)

all

%clientip%

The IP address of the user’s workstation (even if connected through a proxy, broker, replica, or an edge server.)

all

%clientprog%

The name of the user’s client application. For example, P4V, P4Win

all

%clientversion%

The version of the user’s client application.

all

%command%

Command name.

all except archive

%depotName% The graph depot in which the repo resides.
graph-push-start
graph-push-reference
graph-push-reference-complete
graph-push-complete
%email% The user's email address. See Triggering for multi-factor authentication (MFA).
auth-pre-2fa
auth-init-2fa
auth-check-2fa

%file%

Path of archive file based on depot’s Map: field. If the Map: field is relative to P4ROOT, the %file% is a server-side path relative to P4ROOT. If the Map: field is an absolute path, the %file% is an absolute server-side path.

archive

%firstPushedChange%

First new changelist number.

See Additional triggers for push and fetch commands.

command

%formfile%

Path to temporary form specification file. To modify the form from an in or out trigger, overwrite this file. The file is read-only for triggers of type save and delete.

form-commit
form-save
form-in
form-out
form-delete

%formname%

Name of form (for instance, a branch name or a changelist number).

form-commit,
form-save
form-in
form-out
form-delete

%formtype%

Type of form (for instance, branch, change, and so on).

form-commit,
form-save
form-in
form-out
form-delete
%fullname% The user's fullname. See Triggering for multi-factor authentication (MFA).
auth-pre-2fa
auth-init-2fa
auth-check-2fa

%groups%

List of groups to which the user belongs, space-separated.

all except archive

%host% The IP address of the host of the user. See Triggering for multi-factor authentication (MFA).
auth-pre-2fa
auth-init-2fa
auth-check-2fa

%intermediateService%

A broker or proxy is present.

all except archive

%jobs%

A string of job numbers, expanded to one argument for each job number specified on a p4 fix command or for each job number added to (or removed from) the Jobs: field in a p4 submit, or p4 change form.

fix-add,
fix-delete

%lastPushedChange%

Last new changelist number.

See Additional triggers for push and fetch commands.

command

%maxErrorSeverity%

One of empty, error, or warning.

all except archive

%maxErrorText%

Error number and text.

all except archive

%maxLockTime%

A user-specified value that specifies the number of milliseconds for the longest permissible database lock. If this variable is set, it means the user has overridden the group setting for this value.

all except archive

%maxResults%

A user-specified value that specifies the amount of data buffered during command execution. If this variable is set, it means the user has overridden the group setting for this value.

all except archive

%maxScanRows%

A user-specified value that specifies the maximum number of rows scanned in a single operation. If this variable is set, it means the user has overridden the group setting for this value.

all except archive

%method% The authentication method from list-methods (may be set to "unknown"). See Triggering for multi-factor authentication (MFA).  
%newValue% See Triggering with depots of type graph. graph-push-reference

%oldchangelist%

If a changelist is renumbered on submit, this variable contains the old changelist number.

change-commit
push-commit
%oldValue% See Triggering with depots of type graph. graph-push-reference

%op%

Operation: read, write, or delete.

archive

%peerhost%

If the command was sent through a proxy, broker, replica, or edge server, the hostname of the proxy, broker, replica, or edge server. (If the command was sent directly, %peerhost% matches %clienthost%)

all

%peerip%

If the command was sent through a proxy, broker, replica, or edge server, the IP address of the proxy, broker, replica, or edge server. (If the command was sent directly, %peerip% matches %clientip%)

all

%P4PORT%

The host port to which the client connects. If the client connects to the server through an intermediary, this will hold the port number of the intermediary. If there’s no intermediary, this will hold the same value as the %serverAddress% variable.

auth-check-sso (client-side script only)

%pusher% The user credited with the push. See Triggering with depots of type graph.
graph-push-start
graph-push-reference
graph-push-reference-complete
graph-push-complete

%quote%

A double quote character.

all

%reference% See Triggering with depots of type graph.

graph-push-reference

%refFlags%
%refType%
%repo%

The repo, which has .git as a suffix, but otherwise is identical to %repoName%.

graph-push-start
graph-push-reference
graph-push-reference-complete
graph-push-complete
%repoName%

The name of the repo. See Triggering with depots of type graph.

%rev%

Revision of archive file

archive

%scheme% The authentication scheme set by init-auth (can be set to "unknown"). See See Triggering for multi-factor authentication (MFA). auth-init-2fa

%serverAddress%

The IP address and port of the Helix Core server, passable only in the context of a client-side script specified by P4LOGINSSO.

auth-check-sso (client-side script only)

%serverhost%

Hostname of the Helix Core server.

all

%serverid%

The value of the Helix Core server’s server.id. See p4 serverid in the Helix Core P4 Command Reference for details.

all

%serverip%

The IP address of the server.

all

%servername%

The value of the Helix Core server’s P4NAME.

all

%serverport%

The transport, IP address and port of the Helix Core server, in the format prefix:ip_address:port.

prefix can be one of ssl, tcp6, or ssl6. This means that the command p4 -p %serverport% can be used to connect to the server no matter which type of connection the server uses.

all

%serverroot%

The P4ROOT directory of the Helix Core server.

all

%serverservices%

A string specifying the role of the server. One of the following:

  • standard
  • replica
  • broker
  • proxy
  • commit-server
  • edge-server
  • forwarding-replica
  • build-server
  • P4AUTH
  • P4CHANGE

all except archive

%serverVersion%

Version string for the server that terminated if the command exited early. Reason for termination is given in %termReason%.

all except archive

%specdef%

Expanded to the spec string of the form in question.

form

%standbyserverid% Expands to the serverID of the standby before failover failed-over
%standbyserverport% expands to the P4PORT of the standby before failover failed-over

%submitserverid%

If this is not a distributed installation, %submitserverid% is always empty.

In a distributed installation, for any change trigger:

  • if the submit was run on the commit server, %submitserverid% equals %serverid%.
  • if the submit was run on the edge server, %submitserverid% does not equal %serverid%. In this case, %submitserverid% holds the edge server’s server id.

If there is a forwarding replica between the commit server and the edge server, then %submitserverid% actually holds the forwarding replica’s server id.

See p4 serverid in the Helix Core P4 Command Reference.

change-submit
change-content
change-commit

Not available for push-* triggers.

%targetport%

 

The serverport of the target server being monitored. Corresponds to the P4TARGET or the -t target value that the p4 heartbeat command uses.

heartbeat-missing
heartbeat-resumed
heartbeat-dead

%terminated%

The value of 0 indicates that the command completed. A value of 1 indicates that the command did not complete.

all except archive

%termReason%

The reason for early termination. This might be one of the following:

  • 'p4 monitor terminate'
  • client disconnect
  • maxScanRows
  • maxLockTime
  • maxResults

See also %serverVersion%.

all except archive

%token% The stashed token from the last init-auth (can be empty). See Triggering for multi-factor authentication (MFA). auth-init-2fa
%triggerdir% Pull.trigger.dir used for tmp files for Triggers for external file transfer edge-content

%triggerMeta_action%

Command to execute when trigger is fired. Last field of trigger definition.

all except archive

%triggerMeta_depotFile%

Third field in trigger definition. Its meaning varies with the trigger type:

all except archive

%triggerMeta_name%

Trigger name: first field from trigger definition.

all except archive

%triggerMeta_trigger%

Trigger type: second field in trigger definition.

all except archive

%user%

Helix server username of the triggering user.

all