Triggers guide


Introduction

The trigger system in Plastic SCM allows the execution of user commands at specific points in the client or server execution workflow, using shell scripts, or any other operating system executable.

The trigger system in Plastic SCM allows the developer or administrator to perform the following tasks among others:

  • Enforce branch creation policies like naming conventions or ensuring that branch names always refer to a certain associated task.
  • Introduce before-checkin rules to enforce coding standards or create formatting rules.
  • Enforce that comments are entered on checkin.

Plastic SCM supports the association of several scripts to any given trigger, performing different actions in sequence. The sequence in which scripts are executed can be customized by the user.


Trigger types


Server-side triggers

This will be the most common type of trigger. When operations are performed by clients, such as creating revisions, branches, or changing workspace configurations, the server can execute user scripts before and after the operation is completed.

The "pre-operation" triggers will usually allow canceling the operation, depending on the result code of the triggered scripts.

Later, you will find the complete list of triggers executed on the server.


Client-side triggers

Some events that occur on the client can have scripts or programs associated.

Below, you will find the list of supported client triggers.

Triggers can also run from the Global Configuration . One of the challenges when you need to run client-side triggers is to deploy them. By using the Global Configuration, you just place your trigger in your plastic-global-config repository, and every user will have it available. You must use the GLOBAL_CONFIG_PATH.


List of triggers

This is a complete list of all available events that triggers can be binded to:

A list of all supported trigger types can be obtained on the command line client with the command: cm trigger showtypes

Server-side triggers list

before-add
after-add
Fires on item addition, only once per add command. A list of the added items is provided to the trigger script.
before-checkin
after-checkin
Fires on checkin. A list of the items to be checked in is provided.
before-merge Fires when denying the merge of some branches if certain conditions are not met.
before-mkbranch
after-mkbranch
Fires on branch creation.
before-mklabel
after-mklabel
Fires on label creation.
before-mkatt
after-mkatt
Fires on attribute creation.
before-chattvalue
after-chattvalue
Fires when the value of an attribute applied to a certain object changes.
before-mkrep
after-mkrep
Fires on repository creation.
before-rmrep
after-rmrep
Fires on repository deletion.
before-mkworkspace
after-mkworkspace
Fires on workspace creation.
before-mkreview
after-mkreview
Fires on code review creation.
before-editreview
after-editreview
Fires on code review edition.
before-rmbranch
after-rmbranch
Fires on branch deletion.
before-mvbranch
after-mvbranch
Fires on branch renaming.
before-rmchangeset
after-rmchangeset
Fires on changeset deletion.
before-rmlabel
after-rmlabel
Fires on label deletion.
before-rmattribute
after-rmattribute
Fires on attribute deletion.

Client-side triggers list

before-mkworkspace
after-mkworkspace
Fires when a workspace is created.
before-setselector
after-setselector
Fires on any workspace selector change, including explicitly setting the selector and also the switch to... commands.
before-update
after-update
The path to be updated is provided to the script.
before-clientcheckout
after-clientcheckout
The paths of the files and directories to be checked out are provided to the trigger scripts. The user can use it to perform customized operations before or after a file is checked out.
before-clientcheckin
after-clientcheckin
The paths of the files and directories to be checked in are provided to both the before and after operations.

Trigger operations

Create trigger

Triggers are created from the command-line client (cm). This is the syntax for the trigger creation command:

cm trigger create {type} {name} {script} [--position=value] [--filter=filter-value] [--server=server:port]

Where:

  • type is the trigger type, as listed in the previous section. For example, before-mkbranch, or mkbranch-before. This argument is required.
  • name is the name for the new trigger. It is informational only and more than one trigger can be assigned the same name (triggers are uniquely identified by its type and position). This argument is required.
  • script is the full path to the script or program that will be executed. The path points to a file in the Plastic server. So the path must be a valid file specification that the server (either Windows or Unix) can understand. This argument is required.

    Web triggers are also supported. To interpret the script path value as an endpoint URI, you must preced the script path with the webtrigger string (mind the whitespace!). This endpoint will receive POST requests whenever the trigger is executed. The request body will be a JSON dictionary containing the trigger variables. Additionally, the standard input data will appear as an array under the INPUT dictionary key.

    Web triggers support sending Discord and Slack notifications. To do this:

    1. Go to Discord or Slack:
    2. Use the webtrigger-discord or webtrigger-slack strings (instead of webtrigger ) before the script path followed by the Discord webhook or Slack channel. This will be something like this: cm trigger make after-checkin MyDiscordAfterCheckinTrigger "webtrigger-discord https://discordapp.com/api/webhooks/channelId/token" --server=myPlasticServer

      or

      cm trigger make after-checkin MySlackAfterCheckinTrigger "webtrigger-slack https://slack.com/api/chat.postMessage/<channelId or UserId>/xoxb-SlackBotToken" --server=myPlasticServer
  • --position refers to the position in the script's given trigger type in the execution list. This parameter determines the execution order if several scripts are registered on a given trigger type. If another script is already using the position, an error is raised, and the trigger will not be created. This argument is optional, and if omitted, the trigger will be added at the end of the current list of scripts.
  • --filter creates a trigger that will be executed only when the fields specified in the filter match the repository, object, or path involved in the operation that triggered the execution. How do filters work?
    1. Filters admit regular expressions.
    2. Filters support wildcards. So, you can filter by an exact name for a repository, object, or path (--filter="rep:code,BL101", or use a wildcard (--filter="STATUS,br*" or --filter="rep:test*").
    3. Filters are a comma-separated list.
    4. If you need to use a comma character inside a filter, don't forget to scape it: "\,".
    5. The filters restrict when the trigger executes.
    6. You can filter by repository (rep:) in all types of triggers. For example: --filter="rep:myrepo".
    7. Then, the system checks every particular filter for each type of trigger.
    8. If the trigger receives data from the standard input, then the filter applies to each line of this input before the trigger executes.
      Note that at least one filter must match with a line in the standard input. It is not mandatory that all lines in the standard input match with the specified filters.
  • --server is the server in which to create the trigger. If omitted, the trigger will be created on the default configured server. The syntax specifies a server hostname, ':', and a port, by default 8084.

The position of the script in the trigger type is unique, meaning that a list is maintained for each trigger type. Positions in that list are either used by a trigger, but only one trigger can be assigned to a given position. If no position is specified, the trigger will be added to the end of the list. The user will be able to change the position in the list later using the trigger edit command.

If the trigger script doesn't exist, an error will be raised when the affected operation is executed (thus preventing it from completion in any case).

Here are some sample usages:

  • Create a trigger that fires after setting a workspace selector, located at /home/scripts/plastic-backup at the server, and give it the name backup: cm trigger create after-setselector backup /home/scripts/plastic-backup
  • Create a trigger that fires before a label is created, called validate-label.bat at server myserver on port 8084, and calling it Validate label: cm trigger create before-mklabel "Validate label" "c:\tmp\triggers\validate-label.bat" --server=myserver:8084
  • Create a trigger that validates checkin contents before the checkin is actually performed in the repository, on a Windows server: cm trigger create before-checkin ensure-code-stds "c:\plastic\triggers\checkcode.bat"
  • Create a trigger that fires before a label is created in repository default and that label starts with bl or fix: cm trigger create before-mklabel "label-bl-fix" "c:\tmp\triggers\label-bl-fix.bat" --filter="rep:default,bl*,fix*"
  • Create a web trigger that fires after a checkin action is performed, at URI https://www.mysite.com/api/team/checkin and give it the name Notify team: cm trigger create after-checkin "Notify team" "webtrigger https://www.mysite.com/api/team/checkin"

    A request body example of that web trigger would be as follows:

    {
     "PLASTIC_CHANGESET": "cs:2341@br:/main/task4638@rep:product@repserver:plastic.mysite.com:17590",
     "PLASTIC_CLIENTMACHINE": "DEV1HOST",
     "PLASTIC_COMMENT": "Fixing command line parsing",
     "PLASTIC_SERVER": "plastic.mysite.com:17590",
     "PLASTIC_SHELVE": false,
     "PLASTIC_USER": "dev1",
     "INPUT": [ "CH \"/src/main.c\" FILE" ]
    }
    
  • Create a web trigger that fires after a checkin and send notifications from the server to the specified Discord channel: cm trigger create after-checkin NotifyTeam "webtrigger-discord https://discordapp.com/api/webhooks/811172464004562954/VNKRQ9JvPyvku0yYJg-hFmSesEePRFaMbikRlfkJBrb22QxmJoJVBmZR6iOWpiMIsS4t" --server=localhost:18084
  • Create a web trigger that fires after a checkin and send notifications from the server to the specified Slack channel: cm trigger create after-checkin SlackWebTrigger "webtrigger-slack https://slack.com/api/chat.postMessage/U01PW9EET5E/xoxb-1781717825334-1781730759222-34UxkCu8WmA2FlzzjTS6tRYy" --server=localhost:18084

Sample trigger scripts can be found in section Samples at the end of the document.


Change trigger

Once a trigger has been created, its options can be edited with the trigger edit command. The syntax is:

cm trigger edit {type} {existing-trigger-position} [--position=value] [--name=value] [--script=value] [--server=server:port]

Where:

  • type is the trigger type required to get the list of associated scripts. This argument is required. You've seen the list of the trigger types in the previous section. For example, before-rmlabel or after-editreview.
  • existing-trigger-position is the index of the trigger in the list of triggers with the selected type. This value, together with the trigger type, uniquely identify the script to edit. This argument is required.
  • --position is the new position for the trigger in the trigger list. If another script is already using the position, an error raises, and the trigger will not be edited.
  • --name is the new name for the trigger. Note that the name is used only for readability.
  • --script is the new path to the script or program that will be executed. The path points to a file in the Plastic server. So the path must be a valid file specification that the server (either Windows or Unix) can understand. This argument is required.

    Web triggers are also supported. To interpret the script path value as an endpoint URI, you must preced the script path with the webtrigger string (mind the whitespace!). This endpoint will receive POST requests whenever the trigger is executed. The request body will be a JSON dictionary containing the trigger variables. Additionally, the standard input data will appear as an array under the INPUT dictionary key.

    Web triggers support sending Discord and Slack notifications. To do this:

    1. Go to Discord or Slack:
    2. Use the webtrigger-discord or webtrigger-slack strings (instead of webtrigger ) before the script path followed by the Discord webhook or Slack channel. This will be something like this: cm trigger edit after-checkin 1 "webtrigger-discord https://discordapp.com/api/webhooks/channelId/token"

      or

      cm trigger edit after-checkin 3 "webtrigger-slack https://slack.com/api/chat.postMessage/<channelId or UserId>/xoxb-SlackBotToken"
  • --server is the server in which to create the trigger. If omitted, the trigger will be created on the default configured server. The syntax specifies a server's hostname, ':', and a port.

Let's see some examples:

  • Assign the name codestyle to the before-checkin trigger that is at position 1: cm trigger edit before-checkin 1 --name="codestyle"
  • Edit the URI of the after-checkin webtrigger that is at position 1: cm trigger edit after-checkin 1 --script="webtrigger http://myserver.org/api"

Remove trigger

Triggers can be removed from Plastic. Removing a trigger does not remove the associated trigger script or program on the file system. It instructs Plastic not to execute the script anymore. This is the syntax of the command:

cm trigger delete {type} {existing-trigger-position} [--server=server:port]

Where:

  • type is the trigger type to get the list of associated scripts, as listed in the List of triggers table. This argument is required.
  • existing-trigger-position is the index by which the trigger is referred to in the list of triggers associated to the trigger type. This value, together with the trigger type, uniquely identifies the script to be removed. This argument is required.
  • --server is the server in which to remove the trigger. If omitted, the trigger will be removed on the default configured server. The syntax specifies a server's hostname, ':', and a port, by default 8084.

Example:

cm trigger list before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave 2 log labels c:\tmp\triggers\loglabels.bat dave cm trigger delete before-mklabel 2 cm trigger list before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave

List triggers

It is possible to get a list of the registered triggers for any given trigger type. The syntax of the command is the following one:

cm trigger list {type} [--server=server:port] [--format=formatstring]

Where:

  • type is the trigger type to get the list of associated scripts, as listed in the List of triggers table. This argument is required.
  • --server is the server in which to find the triggers to list. If omitted, the trigger will be on the default configured server. The syntax specifies a server's hostname, ':', and a port, by default 8084.
  • --format is the usual format specifier used in Plastic commands. A reference of the available column values can be found below.

Sample usage to list the scripts associated with the before-checkin event:

cm trigger list before-checkin 1 checkstyle c:\tmp\triggers\checkin-checkstyle.bat dave

This command will output one line for each trigger defined. This is the meaning of the output columns:

    0 - Trigger position
    1 - Trigger name
    2 - Trigger script
    3 - Trigger owner

The index of those columns can be used with the --format argument to print customized outputs, like in this sample:

cm trigger list before-mklabel --format="{0} = {2}" 1 = c:\tmp\triggers\validate-label.bat 2 = c:\tmp\triggers\loglabels.bat

If no trigger type is provided, the trigger list command will list the whole list of triggers present on the server.


Show trigger types

To get a list of the available trigger type the command:

cm trigger showtypes

This command is purely informational and just lists the possible trigger types, so it is independent from any server or client.


Trigger usage

This section describes the basic steps to get started with triggers and the recommended usage patterns.


Creating the first trigger

To associate a user script with a client or server event, you must craete a trigger. A list of all supported trigger types can be obtained on the command line client with the command:

cm trigger showtypes

To create a trigger that validates label names, the names should be created according to a given naming standard; the user may use a command like this (on a Windows-based server):

cm trigger create before-mklabel "check label name" "ruby c:\plastic\triggers\validate-label.rb"

This is a sample ruby script ( validate-label.rb ) which checks that the label name starts with 'release'. Otherwise, it returns 1, which means that the trigger fails and it doesn't allow the mklabel operation to finish:

if (ENV['PLASTIC_LABEL_NAME'] !~ /^release/) then exit(1) end

The script picks the name of the label from the PLASTIC_LABEL_NAME environment variable and checks its contents against the regular expression ^release, which means "match a string that starts with 'release'". If this is not the case (!~ operator), the exit code returned would be 1, interpreted as a trigger failure.


List, edit, and delete triggers

To see the trigger that was just created, list the trigger of the type used:

cm trigger list before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave

To modify the script that this trigger is pointing to, you can use the trigger edit command. You must indicate the trigger type, and the trigger position which is the first index printed by the list triggers command (1 in this case):

cm trigger edit before-mklabel 1 --script="c:\tmp\other-script.bat"

To remove the trigger just created, use the trigger delete, indicating the trigger type and position:

cm trigger delete before-mklabel 1

Trigger communication

Input

Plastic SCM will send information to the trigger script related to the executing operation. Two approaches will be used:

  • Standard input - Usually, object references like revision specs involved in the triggered operation will be pushed to the trigger script using the standard input.
  • Environment variables - General information, like the Plastic user which started the operation or the client machine. Check the Common environment variables section for a detailed description of the variables used in a given operation.

Output

The trigger script will communicate the result of its execution using the result code. Plastic will interpret these result codes:

  • Zero (0) - Trigger finished correctly. Operation can continue.
  • Non-zero (>0) - Trigger failed. Operation cannot continue.

If the result is non-zero for a 'before' trigger, the operation is canceled, and the error is displayed on the client.

If the result is non-zero for an 'after' trigger, the operation has been already performed and can't be rolled back. However, the exception is also displayed on the client.

When a trigger fails (the error code is non-zero), the standard output of the trigger will be sent to the client as an error message.

When a server-side trigger fails because the executable is missing, the server treats it as a non-zero exit code.

However, starting on Plastic SCM 8.0.16.3388, when a client-side trigger fails because the executable is missing, the client treats it as a zero exit code.

This is in case you want to distribute your client-side triggers through your repository. If triggers such as before-mkworkspace, after-mkworkspace, before-setselector, after-setselector, and before-update fail with a non-zero exit code because the trigger executable is not downloaded yet to your workspace, you would need to remove the trigger configuration, run the operation, and configure the trigger again.


Common environment variables

This table details the environment variables that are available for every trigger script:

PLASTIC_USER The user who started the operation in the client.
PLASTIC_CLIENTMACHINE The client machine that started the operation.
PLASTIC_SERVER The hostname of the Plastic server.

server.conf variables

Variables can be defined on the server.conf file. Their value will be passed to the trigger script or program as environment variables. In order to define these variables, a section called TriggerVariables needs to be added to the server.conf file available in the server installation folder. The following example shows a possible use of this file:

<?xml version="1.0"?>
<ServerConfigData>
  <Language>en</Language>
  <WorkingMode>UPWorkingMode</WorkingMode>
  <ServerType>ServerTypeAll</ServerType>
  
  <TriggerVariables>
    <TriggerVariable name="TRIGGERS_PATH" value="c:\triggers" />
  </TriggerVariables>

</ServerConfigData>

This sample defines a variable called TRIGGERS_PATH with value c:\triggers. This variable can be used in the script field when creating a trigger, like in this example:

cm trigger create before-checkin "code checker" "@TRIGGERS_PATH\stylecheck.bat"
Note @ to refer to the variable in this context.

Client-side variables

Client-side triggers can be customized using relative or user-defined paths. The script execution paths can be built in the following ways:

  1. Using customized trigger variables defined in the client.conf file.
  2. Using predefined variables.

The use of these approaches will allow the definition of the client-side triggers in a cross-platform way.

Client.conf variables

It is possible to define custom variables on the client.conf file located under your home directory. Their value can be used when creating a client-side trigger. A new section with the TriggerVariables key must be added in the client.conf. The example below defines a variable called TRIGGERS_PATH with the c:\triggers value:

<?xml version="1.0"?>
<ClientConfigData>
  <Language>en</Language>
  <WorkingMode>UPWorkingMode</WorkingMode>
  
  <TriggerVariables>
    <TriggerVariable name="TRIGGERS_PATH" value="c:\triggers" />
  </TriggerVariables>

</ClientConfigData>

With this variable, you can assign a path when creating a client-side trigger like the following example does:

cm trigger create before-clientcheckin "client code checker" "@TRIGGERS_PATH\addformat.bat"

Plastic predefined variables

There are several predefined values that can be used to compose the script field value when creating a client-side trigger:

  • PLASTIC_BIN_PATH - This variable will match the Plastic client installation directory.
  • WKSPACE_PATH - This variable will be the current workspace path when creating the client trigger.
  • GLOBAL_CONFIG_PATH - This variable will point to the global configuration directory of the server you're using.

Let's see some examples:

  • Create a trigger that executes a script located at the triggers folder under the Plastic client installation folder: cm trigger create before-clientcheckin "Relative trigger path" "@PLASTIC_BIN_PATH/triggers/checkdirectories.pl"
  • Create a trigger that executes a script located at the global configuration directory of the server you're using: cm trigger create after-update "Delete files after update" "@GLOBAL_CONFIG_PATH/allrepos/triggers/deletefiles.bat"
Note: It doesn't mind which path directory separator character is used ("\" or "/") with these variables in both Windows or Linux platforms: The client-side trigger can identify which separator use. For example, you can type "@PLASTIC_BIN_PATH/triggers/checkdirectories.pl" in a Windows platform, and the client-side trigger will "translate" using this one: "@PLASTIC_BIN_PATH\triggers\checkdirectories.pl".
Note @ to refer to these variables.

Detailed trigger reference

The following section will provide a detailed reference of all the triggers as well as input and output parameters. Samples are provided for the most common actions.


Add

Trigger names
before-add after-add
Description
It executes user scripts when items are added to the source control.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Standard input

For example, if --filter="rep:test,*.cs", then the trigger executes only for repository test and if at least one of the lines in the standard input is about adding a C# file.

Standard input
A list of files to be added.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger was completed successfully. The items will be added.
Non zero

The trigger reports failure.

If the trigger is before-add, an error is reported, and the items are not added to the repository.

If the trigger is after-add, an error is reported. However, the items have already been added to the repository.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_COMMENT The comment given by the user on the add operation.

Checkin

Trigger names
before-checkin after-checkin
Description
It executes user scripts when a checkin operation is performed on any client.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Standard input

For example, if --filter="rep:code,CH *search.c*", then the trigger executes only for repository code and if at least one of the lines in the standard input is about a change (CH) in a *search.c* file.

Standard input
The standard input receives revision identifiers for all the items involved in the checkin operation, one per line. Each of them is a specially formatted string containing the server's path of the item (independent of any workspace) and the revision specification, so its contents are easily retrieved using the cm cat command.

This is the format of the revision specifications, one per line:

status item_path item_type#br:branch;changeset:cset_id@rep:rep_name@repserver:server

The meaning of the members in italic is detailed in the following table:

status The status of the item to be checked in: added (AD), changed (CH), moved (MV), deleted (DE)...
item_path The revision's path in server format, which is independent of the client workspace and operating system.
item_type The type of the item: DIR or FILE.
branch The branch of the revision.
cset_id Only available in the after-checkin trigger.
The unique changeset identifier. Can be used to ease parsing when accessing revisions with cm cat or cm shelveset in the trigger script, as the string after the first semicolon uniquely identifies the revision inside the server.
rep_name The repository name where the revision belongs.
server The repository server and port where the repository belongs.

This example shows standard input supplied to a checkin trigger when making a checkin to the search.h changed file:

CH "/" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
CH "/search" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
CH "/search/search.h" FILE#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Items will be checkedin the repository.
Non zero

The trigger reports failure.

If the trigger is before-checkin the checkin operation is stopped, and the items are not checked in, neither changeset is created. An error message is reported to the client.

If the trigger is after-checkin, an error message is reported to the client. However, the checkin operation has already been performed.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_COMMENT The comment given at checkin time by the user.
PLASTIC_SHELVE This variable indicates whether the checkin is a shelve operation or not.
PLASTIC_CHANGESET Only available in the after-checkin trigger.

The changeset or changesets that were created as a result of the checkin operation.

This variable contains the specifications for the changesets that were created, separated by semi-colons (';'). This is a sample of a variable value with changesets created on two different repositories:

cs:23@br:/main@rep:default@repserver:DARKTOWER:8084; cs:19@br:/main@rep:secondrep@repserver:DARKTOWER:8084
PLASTIC_PENDING_MERGE_LINKS Only available in the before-checkin trigger.

The variable contains information about the merge links included in the checkin operation.

The format of the serialized variable is MergeLinkSpec1;.....;MergeLinkSpecN. Each MergeLinkSpec has the following format:

mergetype:merge_type,source:src_cset_spec[,base:base_cset_spec]

For example:

mergetype:merge,source:2@rep:default@localhost:8084

The variables are:

  • mergetype: can be one of the following constants: "merge", "cherrypick", "intervalcherrypick", "cherrypicksubtractive", "intervalcherrypicksubtractive".
  • source: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server.
  • base (optional): if mergetype is "intervalcherrypick" or "intervalcherrypicksubtractive" then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS Same as PLASTIC_PENDING_MERGE_LINKS environment variable but only available in the after-checkin trigger.
Comments
The before-checkin and after-checkin triggers are invoked only once for all the items involved in the checkin operation. The standard input of the trigger will receive a list of the items involved.

This is one of the most complex and useful triggers. Some examples of usages: Checking code before it is checked in on the repository against some validation / formatting tool or sending emails / updating rss feeds when new code is in the repository.

Revision contents can be accessed through the cm cat command, specifying the revision specification supplied in the standard input. They can be validated, modified, and then stored back into the server with the cm shelveset command. In case a shelveset command updates the contents of a revision in the repository, the client performing the checkin operation will automatically update those items, so the contents of the workspace are always correct.

Sample command line creation
cm trigger create checkin-before "checkstyle" "c:\tmp\triggers\checkin-checkstyle.bat" Trigger created on position 1.
Sample trigger script
The following script reads all the standard input and redirects it to the 'c:\tmp\triggers\checkinout.txt' file. The trick here is the use of the find.exe command to read the standard input in Windows command line 'cmd.exe':
@echo off
for /f "tokens=*" %%g in ('find /V ""') do ( 
    echo %%g >> c:\tmp\triggers\checkinout.txt
) 
exit 0

Merge

Trigger names
before-merge
Description
This trigger can be used to deny the merge of some branches if certain conditions are not met.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Standard input

For example, if --filter="rep:dev*,*EVIL*", then the trigger executes only for repositories whose name starts with dev and if at least one line in the standard input is an evil merge conflict.

Standard input
The standard input for the merge and the mergeTo actions is one of the following:
  • If the merge operation can't be performed, then the standard input is the reason why:
    CONTRIBUTORS_NOT_CONNECTED Source and destination are not connected. Returned by the subtractive merge.
    INVALID_CSET_INTERVAL The selected changesets interval (base, source] is not valid.
    ANCESTOR_NOT_FOUND No ancestor found between source and destination.
    CONTRIBUTORS_ALREADY_CONNECTED Source is already included on destination. Merge not needed.
    SOURCE_ALREADY_SUBTRACTED The source is already subtracted from the destination. Subtractive merge not needed.
    NO_MERGES_DETECTED There are no changes between source and destination.
  • If the merge operation is performed, the standard input is a list of conflicts (in the following order: directory conflicts, file conflicts, and writable xlinks conflicts) plus the operations to apply (source changed, deleted, added, and so on). Each conflict and operation must be one per line.

    Find below an example for each type:

    • Conflicts:
      ADD_MOVE [SRC] A "/foo.c" cs:10 - [DST] M "/bar.c" -> "/foo.c" cs:5
      CHANGE_DELETE [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] D "/foo.c" cs:7
      CYCLE [SRC] M "/server" -> "/bin/server" cs:5 - [DST] M "/bin" -> "/server/bin" cs:5
      DELETE_CHANGE [SRC] D "/foo.c" cs:7 - [DST] C "/foo.c" cs:12 (base cs:7)
      DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10
      DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10
      DIVERGENT_MOVE [SRC] M "/foo.c" -> "/bar.c" cs:5 - [DST] M "/foo.c" -> "/qux.c" cs:5
      EVIL_TWIN [SRC] A "/foo.c" cs:10 - [DST] A "/foo.c" cs:5
      LOADED_TWICE [SRC] A "/bar.c" cs:10 - [DST] A "/foo.c" cs:5
      MOVE_ADD [SRC] M "/bar.c" -> "/foo.c" cs:10 - [DST] A "/foo.c" cs:5
      MOVE_DELETE [SRC] M "/foo.c" -> "/bar.c" cs:10 - [DST] R "/foo.c" cs:10
      MOVE_EVIL_TWIN [SRC] M "/foo.c" -> "/qux.c" cs:10 - [DST] M "/bar.c" -> "/qux.c" cs:5
      XLINK_CONFLICT [SRC] C "/thirdparty" Xlink -> / eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer) - [DST] C "/thirdparty" Xlink -> / ba682b83-4aaf-4169-b1ad-3d8de14b371b@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer)
      FILE_CONFLICT [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] C "/foo.c" cs:8 (base cs:7)
    • Writable Xlinks conflicts that will be expanded with a new merge:
      XLINK_MERGE [SRC] C "/engine" wXlink -> / 235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer) - [DST] C "/engine" wXlink -> / 17cb0014-3351-45f2-9ecb-bc025a43d059@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)
      XLINK_MERGE [SRC] C "/engine" wXlink -> / 235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)
    • Operations to apply:
      C "/foo.c" cs:12 (base cs:7)
      C "/thirdparty" Xlink -> / eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer)
      A "/foo.c" cs:7
      M "/foo.c" -> "/bar.c" cs:7
      D "/foo.c" cs:7
      FS "/foo.c" 777 (base 444)

    This is an example for an easy merge:

    CHANGE_DELETE [SRC] C "/src/foo.c" cs:12 (base cs:7) - [DST] D "/src/foo.c" cs:7
    FILE_CONFLICT [SRC] C "/src /bar.c" cs:12 (base cs:7) - [DST] C "/src /bar.c" cs:8 (base cs:7)
    M "/doc/readme.txt" -> "/readme.txt" cs:7
    D "/doc" cs:7
    
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger was completed successfully.
Non zero The trigger reports failure.
Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_MERGE_TYPE "Merge" / "IntervalSubtractive" / "Subtractive" / "IntervalCherrypick" / "Cherrypick"
PLASTIC_MERGE_SOURCE

Specification of the source changeset. For example:

cs:23@br:/main/task@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_DESTINATION

Specification of the destination changeset. For example:

cs:19@br:/main@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_BASE

Specification of the ancestor changeset. If there are multiple ancestors (recursive merge scenario), they will be separated by semi-colons (';'). For example:

cs:4@br:/main@rep:quake@repserver:DARKTOWER:8084; cs:10@br:/main@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_SOURCE_LABELS

The list of labels applied on the source changeset, separated by semi-colons (';'). For example:

6.0.16.1000
PLASTIC_MERGE_HAS_CONFLICTS

"true" if the merge contains conflicts. Otherwise, "false".

PLASTIC_MERGE_HAS_WK_CHANGES

"true" if the workspace contained changes when the merge started. Otherwise, "false".

PLASTIC_MERGE_IS_FORCED

"true" if the traceability has been ignored to merge and already connected source. Otherwise, "false".

PLASTIC_MERGE_STRATEGY

The strategy used to calculate the common ancestor. Allowed values: "Recursive" or "Manual".

PLASTIC_MERGE_IS_MERGE_TO

"true" if the merge is launched using a merge-to. Otherwise, "false".

Sample command line creation
cm trigger create before-merge merge_gate "/path/to/script" --server=myserver:8084 Trigger created on position 1.

Create branch

Trigger names
before-mkbranch after-mkbranch
Description
It executes user scripts when a branch is created.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Branch name

For example, if --filter="rep:default,scm*", the trigger executes only for branches whose name starts with scm in the repository default.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The branch will be created.
Non zero

The trigger reports failure.

If the trigger is before-mkbranch, an error is reported, and the branch is not created.

If the trigger is after-mkbranch, an error is reported. However, the branch has already been created.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_COMMENT The comment given by the user at branch creation.
PLASTIC_BRANCH_NAME The branch that is being created.
PLASTIC_FULL_BRANCH_NAME The full branch name that is being created.
PLASTIC_REPOSITORY_NAME The repository name where the branch is being created.

Create label

Trigger names
before-mklabel after-mklabel
Description
It executes user scripts when a label is created.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Label name

For example, if --filter="rep:code,BL*", the trigger executes only for labels whose name starts with BL in the repository code.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The label will be created.
Non zero

The trigger reports failure.

If the trigger is before-mklabel, an error is reported, and the label is not created.

If the trigger is after-mklabel, an error is reported. However, the label has already been created.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_COMMENT The comment given by the user at label creation.
PLASTIC_LABEL_NAME The label that is being created.
PLASTIC_REPOSITORY_NAME The repository name where the label is being created.
PLASTIC_CHANGESET_NUMBER The number of the changeset being labeled.
PLASTIC_CHANGESET_OWNER The name of the owner of the changeset being labeled.
Sample command-line creation
cm trigger create before-mklabel "Validate label" "c:\plastic\triggers\Validate-label.bat" --filter="LB*" Trigger created on position 1. cm trigger list before-mklabel 1 Validate label c:\plastic\triggers\Validate-label.bat dave
Sample trigger script
The following script saves a record of created branches on the c:\plastic\triggers\labels.log.txt file.
@echo off
echo %PLASTIC_REPOSITORY_NAME% %PLASTIC_LABEL_NAME% >> c:\plastic\triggers\labels.log.txt
exit 0

Create attribute

Trigger names
before-mkatt after-mkatt
Description
Executes user scripts when an attribute is created.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Attribute name

For example, if --filter="rep:code,status", the trigger executes only for attribute status in the repository code.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The attribute will be created.
Non zero

The trigger reports failure.

If the trigger is before-mkatt, an error is reported, and the branch is not created.

If the trigger is after-mkatt, an error is reported. However, the attribute has already been created.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_COMMENT The comment given by the user at attribute creation.
PLASTIC_ATTRIBUTE_NAME The attribute that is being created.
PLASTIC_REPOSITORY_NAME The repository name where the attribute is being created.

Change attribute value

Trigger names
before-chattvalue after-chattvalue
Description
It executes user scripts when the value of an attribute applied to a certain object changes.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Attribute name
  • Standard input

For example, if --filter="STATUS,br*", the trigger executes only if the value of the attribute STATUS changes and if at least one line in the standard input applies to a branch object.

Standard input
The standard input receives the following detailed information for the object whose attribute value is being changed.

If the trigger is before-chattvalue:

object_spec attribute:"att_name" oldvalue:"old_att_value" newvalue:"new_att_value"

For example:

lb:BL145 attribute:"RELEASED" oldvalue:"FALSE" newvalue:"TRUE"

If the trigger is after-chattvalue:

object_spec attribute:"att_name" value:"att_value"

For example:

br:/main/task985 attribute:"STATUS" value:"OK"

The meaning of the members in italic is detailed in the following table:

object_spec The object which changed attribute value is applied.
attribute The name of the related attribute.
oldvalue The attribute value previously to be changed.
newvalue The attribute value after the change.
value The value of the attribute.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully.
Non zero

The trigger reports failure.

If the trigger is before-chattvalue, an error messasge is reported, and the attribute value is not changed.

If the trigger is after-chattvalue, an error message is reported. However, the attribute value has already been changed.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_ATTRIBUTE_NAME The attribute which value is being changed.
PLASTIC_REPOSITORY_NAME The repository name where the attribute value is being changed.

Create repository

Trigger names
before-mkrep after-mkrep
Description
It executes user scripts when a repository is created.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name

For example, if --filter="rep:cod*", the trigger executes only for repositories whose name starts with cod.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The repository will be created.
Non zero

The trigger reports failure.

If the trigger is before-mkrep, an error is reported, and the repository is not created.

If the trigger is after-mkrep, an error is reported. However, the repository has already been created.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_REPOSITORY_NAME The repository that is being created.

Remove repository

Trigger names
before-rmrep after-rmrep
Description
It executes user scripts when a repository is removed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name

For example, if --filter="rep:test*", the trigger executes only for repositories whose name starts with test.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The repository will be deleted.
Non zero

The trigger reports failure.

If the trigger is before-rmrep, an error is reported, and the repository is not deleted.

If the trigger is after-rmrep, an error is reported. However, the repository has already been deleted.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_REPOSITORY_NAME The repository that is being deleted.
PLASTIC_REPOSITORY_ID The repository id that is being deleted.

Create workspace

Trigger names
before-mkworkspace after-mkworkspace
Description
It executes user scripts when a workspace is created.
Runs on
Client.
Filters
You can use the following filter:
  • Repository name
  • Workspace name

For example, if --filter="rep:cod*,code", the trigger executes only for workspace code in all repositories whose name starts with cod.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The workspace will be created.
Non zero

The trigger reports failure.

If the trigger is before-mkworkspace, an error is reported, and the workspace is not created.

If the trigger is after-mkworkspace, an error is reported. However, the workspace has already been created.

Environment variables
In addition to the variables defined in section Common environment variables, the following ones are also available:
PLASTIC_WORKSPACE_NAME The name given to the new workspace.
PLASTIC_WORKSPACE_PATH The path of the workspace on the client machine.

Set selector

Trigger names
before-setselector after-setselector
Description
Executes user scripts when a workspace selector is changed.
Runs on
Client.
Filters
You can use the following filter:
  • Repository name
  • Standard input

For example, if --filter="rep:test,/main/Release*", the trigger executes only for repository test and if at least one line in the standard input matches /main/Release*.

Standard input
The standard input in these triggers receives the selector contents that the client is setting.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The selector will be modified.
Non zero

The trigger reports failure.

If the trigger is before-setselector, an error is reported, and the selector is not modified.

If the trigger is after-setselector, an error is reported. However, the operation has already been done.

Environment variables
In addition to the variables defined in section Common environment variables, the following ones are also available:
PLASTIC_WORKSPACE_NAME The name of the workspace which selector is being set.
PLASTIC_WORKSPACE_PATH The client path of the workspace which selector is being set.
Comments
Selectors are modified either with the setselector or switch command or with the Switch workspace to branch, Switch workspace to label or Switch workspace to changeset commands, all of them in the command-line interface or the GUI client.

Update

Trigger names
before-update after-update
Description
It executes user scripts in the following scenarios:
  • When a workspace is updated.
  • When a 'fast-update' operation is executed.
  • When a Gluon workspace is updated (both from the Gluon GUI or by running the cm partial update command).
Runs on
Client.
Filters
You can use the following filters:
  • Repository name
  • Path to be updated
  • Standard input

For example, if --filter="rep:code,D:*/lib*", then the trigger executes only for repository code and if at least one of the lines in the standard input is about deleting (D) items in a lib path.

Standard input
If the trigger is before-update, then no standard input is supplied to this trigger.

If the trigger is after-update, then the standard input is <{0}:{1}>, where:

  • {0} is the change's type:
    • C: Created (new item).
    • U: Updated.
    • M: Modified on disk (implies not updated nor deleted).
    • D: Deleted.
  • {1} is the change's path.

Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Update operation will proceed.
Non zero

The trigger reports failure.

If the trigger is before-update, an error is reported, and the workspace is not updated.

If the trigger is after-update, an error is reported. However, the workspace has already been updated.

Environment variables
In addition to the variables defined in the Common environment variables section, the following is also available:
PLASTIC_UPDATE_PATH The client path of the workspace that is being updated.
PLASTIC_INITIAL_CHANGESET The ID of your workspace's changeset is (or was) pointing at when the update begins.
PLASTIC_FINAL_CHANGESET The ID of the changeset your workspace is (or will be) pointing at when the update finishes.
Comments
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.

Create code review

Trigger names
before-mkreview after-mkreview
Description
It executes user scripts when a code review is created.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Code review title

For example, if --filter="rep:development,Review*", the trigger executes only for code reviews whose title starts with Review in the repository development.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The code review will be created.
Non zero

The trigger reports failure.

If the trigger is before-mkreview, an error is reported, and the code review is not created.

If the trigger is after-mkreview, an error is reported. However, the code review has already been created.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_REPOSITORY_NAME The repository name where the code review is created.
PLASTIC_REVIEW_TITLE The title given to the code review.
PLASTIC_REVIEW_STATUS Under review, Reviewed, or Rework Required.
PLASTIC_REVIEW_ASSIGNEE

The user assigned to the code review, if any.

Not set if no user is assigned to the code review

PLASTIC_REVIEW_TARGET The specification of the object for which the code review has been created. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE "branch" / "changeset".
PLASTIC_REVIEW_ID Only available in the after-mkreview trigger.

The variable contains the identifier of the review that has been created.


Edit code review

Trigger names
before-editreview after-editreview
Description
It executes user scripts when a code review is edited. For example, the triggers will be launched when a user changes a review name, the assignee, or the status, or when a review comment is created, edited, or deleted.
Runs on
Server.
Filters
You can use the following filters:
  • Repository name
  • Code review title

For example, if --filter="rep:development,Review*", the trigger executes only for code reviews whose title starts with Review in the repository development.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The code review edition is saved to the repository.
Non zero

The trigger reports failure.

If the trigger is before-editreview, an error is reported, and the code review edition is not saved in the repository.

If the trigger is after-editreview, an error is reported. However, the code review edition is saved to the repository.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_REPOSITORY_NAME The repository name where the code review is edited.
PLASTIC_REVIEW_TITLE The title given to the edited code review.
PLASTIC_REVIEW_STATUS Under review, Reviewed, or Rework Required.
PLASTIC_REVIEW_ASSIGNEE

The user assigned to the code review, if any.

Not set if no user is assigned to the code review

PLASTIC_REVIEW_TARGET The specification of the object for which the code review has been edited. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE branch or changeset.
PLASTIC_REVIEW_ID The variable contains the identifier of the edited review.
PLASTIC_REVIEW_COMMENT

The variable contains the comment that fired the trigger.

This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.

PLASTIC_REVIEW_COMMENT_ACTION

The variable reflects the action in the comment: Created, Edited, or Deleted.

This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.


Client checkout

Trigger names
before-clientcheckout after-clientcheckout
Description
It executes user scripts on the client when a checkout operation is executed.
Runs on
Client.
Filters
You can use the following filter:
  • Repository name
  • Standard input

For example, if --filter="rep:code,*.json", then the trigger executes only for repository code and if at least one of the lines in the standard input is about running a checkout on a json file.

Standard input
The standard input in these triggers receives the list of items specified by the user on the checkout operation.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Checkout operation will proceed.
Non zero

The trigger reports failure.

If the trigger is before-clientcheckout, an error is reported, and the operation is canceled.

If the trigger is after-clientcheckout, an error is reported. However, the items have been already checked out.

Environment variables
The variables in these triggers are the same as the ones defined in section Common environment variables.
Comments
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.

Client checkin

Trigger names
before-clientcheckin after-clientcheckin
Description
It executes user scripts on the client when a checkin operation is executed.
Runs on
Client.
Filters
You can use the following filter:
  • Repository name
  • Standard input

For example, if --filter="rep:code,*src*", then the trigger executes only for repository code and if at least one of the lines in the standard input affects an *src* item.

Standard input
The standard input in these triggers receives the list of items specified by the user on the checkin operation.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Checkin operation will proceed.
Non zero

The trigger reports failure.

If the trigger is before-clientcheckin, an error is reported, and the checkin operation is aborted.

If the trigger is after-clientcheckin, an error is reported. The items are already checked in.

Environment variables
In addition to the variables defined in section Common environment variables, the following ones also available:
PLASTIC_COMMENT The comment specified by the user on the checkin operation.
PLASTIC_CHANGESET Only available in the after-clientcheckin trigger.

The changeset or changesets that were created as a result of the checkin operation.

PLASTIC_PENDING_MERGE_LINKS Only available in the before-clientcheckin trigger.

The variable contains the following information:

  • The merge links included in the checkin operation.
  • The merge links affecting the repositories under a xlink.

The format of the serialized variable is MergeLinkSpec1;.....;MergeLinkSpecN. Each MergeLinkSpec has the following format:

mergetype:merge_type,source:src_cset_spec[,base:base_cset_spec]

For example:

mergetype:merge,source:6@rep:xlinkedrepo@repserver:localhost:8084
mergetype:merge,source:2@rep:default@localhost:8084

The variables are:

  • mergetype: can be one of the following constants: "merge", "cherrypick", "intervalcherrypick", "cherrypicksubtractive", "intervalcherrypicksubtractive".
  • source: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server.
  • base (optional): if mergetype is "intervalcherrypick" or "intervalcherrypicksubtractive" then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS Same as PLASTIC_PENDING_MERGE_LINKS environment variable but only available in the after-clientcheckin trigger.
Comments
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.
The before-clientcheckin trigger runs once per affected repository under an Xlink and then again for the repository where the checkin occurs. If you don't want this to happen, you can add a filter.

Security

Trigger names
after-security
Description
It executes user scripts when a user performs an operation that has been denied through security permissions.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name

For example, if --filter="rep:docu", the trigger executes only for repository docu.

Standard input
No standard input is supplied to this trigger.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Security operation will proceed.
Non zero

The trigger reports failure.

If the trigger is after-security, an error is reported.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_MESSAGE The information about the denied permission.
PLASTIC_PERMISSIONS The denied permissions.
PLASTIC_REPOSITORY_ID The id of the repository where the operation is executed.
PLASTIC_REPOSITORY_NAME The name of the repository where the operation is executed.
PLASTIC_OBJECT The object with the denied permission.

Replication read

Trigger names
before-replicationread after-replicationread
Description

It executes user scripts when a user performs a replication operation that involves reading data.

This occurs:

  • in the source side on a push operation;
  • in the source side on a pull operation;

Replication operation: reading data

Runs on
Server.
Filters
You can use the following filter:
  • Repository name

For example, if --filter="rep:code", then the trigger executes only for repository code.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Security operation will proceed.
Non zero

The trigger reports failure.

If the trigger is before-replicationread, an error is reported, and the replication operation is aborted.

If the trigger is after-replicationread, an error is reported. The item is already replicated.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_BRANCH The complete branch specification being replicated. This is the format of the branch specification:
branch@rep:rep_name@server

If the trigger is before-replicationread, the server member will be the destination server.

If the trigger is after-replicationread, the server member will be the source server.


Replication write

Trigger names
before-replicationwrite after-replicationwrite
Description

It executes user scripts when a user performs a replication operation that involves writing data.

This occurs:

  • in the destination side on a push operation;
  • in the destination side on a pull operation;

Replication operation: reading data

Runs on
Server.
Filters
You can use the following filter:
  • Repository name

For example, if --filter="rep:code", then the trigger executes only for repository code.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. Security operation will proceed.
Non zero

The trigger reports failure.

If the trigger is before-replicationwrite, an error is reported, and the replication operation is aborted.

If the trigger is after-replicationwrite, an error is reported. The item is already replicated.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_BRANCH The complete branch specification being replicated. This is the format of the branch specification:
branch@rep:rep_name@server

The server member will be the destination server.

PLASTIC_REPLICATION_SOURCE

Only available in the before-replicationwrite trigger.

The complete repository specification being replicated. This is the format of the repository specification:

rep:rep_name@server

The server member will be the source server.

PLASTIC_REPLICATION_ID

Only available in the after-replicationwrite trigger.

The id of the replication.


Remove branch

Trigger names
before-rmbranch after-rmbranch
Description
It executes user scripts when a branch is removed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Branch name

For example, if --filter="rep:code,dev*", the trigger executes only for those branches which name starts with dev in the repository code.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The branch will be deleted.
Non zero

The trigger reports failure.

If the trigger is before-rmbranch, an error is reported, and the branch is not deleted.

If the trigger is after-rmbranch, an error is reported. However, the branch has already been deleted.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_BRANCH_NAME The name of the branch that is being deleted.
PLASTIC_FULL_BRANCH_NAME The full name (including parent) of the branch to be deleted.
PLASTIC_REPOSITORY_ID The ID of the repository where the branch is deleted.
PLASTIC_REPOSITORY_NAME The name of the repository where the branch is deleted.
PLASTIC_COMMENT The comment given by the user at branch deletion.

Rename branch

Trigger names
before-mvbranch after-mvbranch
Description
It executes user scripts when a branch is renamed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Branch name

For example, if --filter="rep:code,dev*", the trigger executes only for those branches which name starts with dev in the repository code.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The branch will be renamed.
Non zero

The trigger reports failure.

If the trigger is before-mvbranch, an error is reported, and the branch is not renamed.

If the trigger is after-mvbranch, an error is reported. However, the branch has already been renamed.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_BRANCH_NAME The name of the branch that is being renamed.
PLASTIC_FULL_BRANCH_NAME The full name (including parent) of the branch to be renamed.
PLASTIC_BRANCH_NEW_NAME The new name of the branch that is being renamed.
PLASTIC_FULL_BRANCH_NEW_NAME The full new name (including parent) of the branch to be renamed.
PLASTIC_REPOSITORY_ID The ID of the repository where the branch is renamed.
PLASTIC_REPOSITORY_NAME The name of the repository where the branch is renamed.
PLASTIC_COMMENT The comment given by the user at branch renaming.

Remove changeset

Trigger names
before-rmchangeset after-rmchangeset
Description
It executes user scripts when a changeset is removed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Changeset number

For example, if --filter="rep:code,3276", the trigger executes only for changeset 3276 in the repository code.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The changeset will be deleted.
Non zero

The trigger reports failure.

If the trigger is before-rmchangeset, an error is reported, and the changeset is not deleted.

If the trigger is after-rmchangeset, an error is reported. However, the changeset has already been deleted.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_CHANGESET_NUMBER The changeset that is being deleted.
PLASTIC_CHANGESET_OWNER The name of the owner of the changeset being deleted.
PLASTIC_BRANCH_NAME The branch to which the changeset being deleted belongs.
PLASTIC_REPOSITORY_ID The ID of the repository where the changeset is deleted.
PLASTIC_REPOSITORY_NAME The name of the repository where the changeset is deleted.
PLASTIC_COMMENT The comment given by the user at changeset deletion.

Remove label

Trigger names
before-rmbranch after-rmbranch
Description
It executes user scripts when a label is removed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Label name

For example, if --filter="rep:code*,BL*", then the trigger executes only for those labels which name starts with BL in all repositories which name starts with code.

Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The label will be deleted.
Non zero

The trigger reports failure.

If the trigger is before-rmlabel, an error is reported, and the label is not deleted.

If the trigger is after-rmlabel, an error is reported. However, the label has already been deleted.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_LABEL_NAME The name of the label that is being deleted.
PLASTIC_BRANCH_NAME The name of the branch.
PLASTIC_CHANGESET_NUMBER The number of the labeled changeset.
PLASTIC_CHANGESET_OWNER The owner of the labeled changeset.
PLASTIC_REPOSITORY_ID The ID of the repository where the label is deleted.
PLASTIC_REPOSITORY_NAME The name of the repository where the label is deleted.
PLASTIC_COMMENT The comment given by the user at label deletion.

Remove attribute

Trigger names
before-rmattribute after-rmattribute
Description
It executes user scripts when an attribute is removed.
Runs on
Server.
Filters
You can use the following filter:
  • Repository name
  • Attribute name

For example, if --filter="rep:code*,resolved", the trigger executes only for attribute resolved in all repositories which name starts with code.

Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
0 The trigger completed successfully. The attribute will be deleted.
Non zero

The trigger reports failure.

If the trigger is before-rmattribute, an error is reported, and the attribute is not deleted.

If the trigger is after-rmattribute, an error is reported. However, the attribute has already been deleted.

Environment variables
In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:
PLASTIC_ATTRIBUTE_NAME The name of the attribute that is being deleted.
PLASTIC_REPOSITORY_ID The ID of the repository where the attribute is deleted.
PLASTIC_REPOSITORY_NAME The name of the repository where the attribute is deleted.
PLASTIC_COMMENT The comment given by the user at attribute deletion.

Samples

All the samples in this section can be found in the triggers folder in the server installation folder.


Checkin

Apply code beautifier to .java files

This sample will process all java files through a code beautifier (jindent used here, replace with your favorite tool). Script is written in Ruby.

#!/usr/bin/env ruby

# temp file that will be used for jindent
tmpfile = "c:\\tmp\\triggers\\trigger-validate.java"

# Process each line of stdin
STDIN.readlines.each_with_index do |line, index|

  # split into item, revspec and wkspec
  splitted = line.split(';')

  # pick item name from item spec
  filename = splitted[0].split('#')[0]

  # if it is a .java file, apply jindent
  if (filename =~ /\.java$/) then

    # revspec is after the first ;
    revspec = splitted[1];   

    # extract revision content from repository to temp file
    res = system("cm cat #{revspec} --file=\"#{tmpfile}\"")

    # execute jindent on temp file (jindent should be on path)
    if (res) then res = system("jindent \"#{tmpfile}\"") end

    # if jindent failed, signal the trigger failed too
    if (!res || $? != 0) then exit(1) end   

    # store the re-formatted file on Plastic repository
    if (res) then system("cm shelveset #{revspec} --file=\"#{tmpfile}\"") end   

    # delete the temp file
    if (res) then system("del \"#{tmpfile}\"") end

  end  #if

end  #each

Sample trigger creation command (on Windows):

cm trigger create before-checkin "apply jindent" "ruby c:\triggers\jindent.rb"

Apply modifying action to items in block

This is the same example as before, but now all involved files are cat and shelved in block, greatly improving performance.

#!/usr/bin/ruby
tmpdir = 'c:\\tmp\\triggers\\'

$files = []
$cat_shelve_specs = []

# Apply command sending revision info 
def commandOnSpecs(cmd)
  IO.popen(cmd, "w") do |io|
    $cat_shelve_specs.each do |spec|
      puts 'catting ' + spec
      io.puts spec
    end
  end 
end

# Process stdin
STDIN.readlines.each do |line|
  itemspec, revspec, wkspec = line.split(';')
  filename, branchspec, revno = itemspec.split('#')
  
  # this may have problems with long paths
  filename.gsub!(/\//, '_') # replace / with _ in filenames
  filename = tmpdir + filename  # add tmpdir

  $files << filename
  $cat_shelve_specs << "#{revspec};#{filename}"
end

# cat files on temp directory
commandOnSpecs("cm cat -")

# Apply action on files
$files.each { |file| system("jindent \"#{file}\"") }

# shelve files
commandOnSpecs("cm shelveset -")

# remove temp files
$files.each { |file| File.delete file }

Sample trigger creation command (on Windows):

cm trigger create before-checkin "apply block jindent" "ruby c:\triggers\jindent.rb"

Check that comments have been provided on checkin

Sample ruby script that checks the PLASTIC_COMMENT environment variable:

c = ENV['PLASTIC_COMMENT']

if (c == nil || c == '') then exit(1) end

Sample trigger creation command:

cm trigger create before-checkin "comment required" "ruby c:\triggers\check-comments.rb"

Generate rss with changeset contents

This ruby trigger combines all the techniques shown in the previous sections to provide a script capable of updating a .rss file which rss aggregators can use to notify new changes on the repository.

require 'rss/2.0'
require 'open-uri'
require 'rss/maker'

targetfile = "Z:\\cm\\tts\\plastic-changesets.rss"

# Read content if available

if (File.exists?(targetfile)) then
  content = "" 
  open(targetfile) do |s| content = s.read end
  rss = RSS::Parser.parse(content, false)
else
  rss = RSS::Rss.new("2.0")
  channel = RSS::Rss::Channel.new
  channel.title = "Plastic updates feed"
  channel.link = http://www.plasticscm.com
  channel.description = ""
  channel.language = "en"
  rss.channel = channel
end

# Parse checkin item names from plastic

files = ''
STDIN.readlines.each do |line|
  itemspec, revspec, wkspec = line.split(';')
  filename, branchspec, revno = itemspec.split('#')
  files << filename << "
" end # Add new rss item item = RSS::Rss::Channel::Item.new item.title = "#{ENV['PLASTIC_CHANGESET']} - #{ENV['PLASTIC_COMMENT']} by #{ENV['PLASTIC_USER']}" item.link = http://www.plasticscm.com item.date = Time.now item.description = files rss.items << item # Write the resulting file File.open(targetfile, "w") do |f| f.write(rss) end

This is an after-checkin trigger:

cm trigger create after-checkin "generate rss" "ruby c:\triggers\rss-gen.rb"

Make label

Validate that label name starts with 'release'

if (ENV['PLASTIC_LABEL_NAME'] !~ /^release/) then exit(1) end

Trigger creation command:

cm trigger create before-mklabel "check label name" "ruby c:\plastic\triggers\validate-label.rb"

Client checkout

Update files before checkout

The ruby script would be as follows:

#!/usr/bin/ruby

files = ''

STDIN.readlines.each do |line|
  files << " " << line
end

system("cm update #{files}")

Trigger creation command:

cm trigger create before-clientcheckout "update before co" "ruby c:\plastic\triggers\update-before-co.rb"

Last updated

November 3, 2021
  • We restructured the Triggers guide to make its content more readable.
  • October 28, 2021
  • Triggers can now run from Global Configuration. The new predefined variable GLOBAL_CONFIG_PATH is required.
  • October 22, 2021
  • Web triggers now support sending Discord and Slack notifications.
  • October 6, 2021
  • We added a note in the filters description to remark that it's possible to use wildcards.
  • June 15, 2020
  • We updated the values of the PLASTIC_REVIEW_STATUS variable for the Create code review and Edit code review triggers to use the new code review status strings. Now they are Under Review, Reviewed and Rework Required instead of pending, approved and discarded.
  • December 10, 2019
  • We added triggers for object removal events, so you can set-up scripts to run automatically before and/or after objects are deleted. The objects handled are:
  • November 19, 2019
  • Updated the explanation of the cset_id identifier in the server Checkin trigger.
  • October 25, 2019
    • The before-mklabel and after-mklabel server-side triggers have two new environment variables set at execution time: PLASTIC_CHANGESET_NUMBER and PLASTIC_CHANGESET_OWNER.
    • The before-update and after-update client-side triggers have two new environment variables: PLASTIC_INITIAL_CHANGESET and PLASTIC_FINAL_CHANGESET.
    October 18, 2019
  • Now, you can find more info about how to apply filters to triggers and the filters that you can apply to every trigger.
  • July 16, 2019
  • We updated the trigger output reference to reflect that client-side triggers will not fail when the related executable is missing.
  • March 26, 2019
  • Updated examples to use the new cm trigger command.
  • November 21, 2018
  • Now, the client update triggers (before and after) are also triggered by the 'fast-update' operation and the Gluon update, and not only by the standard update operation.
  • We added two new environment variables to the Edit code review trigger: PLASTIC_REVIEW_COMMENT and PLASTIC_REVIEW_COMMENT_ACTION.
  • We updated the merge trigger with the following:
    • Now, the merge-to supplies the standard input.
    • There is a new variable, PLASTIC_MERGE_IS_MERGE_TO, to identify if the merge trigger is launched using a merge-to action or not.
  • November 8, 2018
  • Now, the PLASTIC_PENDING_MERGE_LINKS environment variable in the before-clientcheckin trigger includes the information about the merge links affecting the repositories under a xlink.
  • October 10, 2017
  • We added the new before-merge trigger if you want to deny the merge of branches under certain circumstances.
  • June 8, 2017
  • The PLASTIC_CHANGESET environment variable has been added to the Client checkin trigger.
  • The Edit code review trigger will be launched now every time a review comment is created, edited or deleted.
  • March 4, 2016
  • The PLASTIC_REVIEW_ID environment variable has been added to the Create code review and Edit code review triggers.
  • August 6, 2015
  • The PLASTIC_PENDING_MERGE_LINKS environment variable has been added to the Checkin and Client checkin triggers.
  • A new pair of triggers lets the user execute scripts when the value of an attribute applied to a certain object changes.
  • March 27, 2015
  • Now, you can create and update web triggers.
  • March 27, 2015
  • Added client-side variables.
  • September 1, 2014
  • Documented new triggers: security, replication read, and replication write.