Triggers guide

Chapter 1: Introduction

This guide describes the trigger mechanism available in Plastic SCM.
Audience
This guide is targeted to developers and system administrators, assuming familiarity with Plastic SCM and operating system concepts.
Online documentation
Besides this document and the rest of the guides, Plastic SCM provides online reference throughout its different client frontends.

On the command line interface, both Windows and Linux, this reference can be obtained with the command:

cm help

For extended information on a specific command, type:

cm help {command}
Conventions
Along this guide, the syntax for several commands is described. In those descriptions, the following conventions are used:
• Bold items are literal text strings
• {argument} denotes a required argument
• [argument] denotes an optional argument
Documentation errors
If you find any problem in this guide or any other part of the online reference, please report it using the following email address: support@plasticscm.com

Purpose

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

Among others, the trigger system in Plastic SCM will allow the developer or administrator to perform the following tasks:

• Enforce branch creation policies like naming conventions or making sure 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 introduced on checkin.

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

Chapter 2: 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 is capable of executing user scripts before and after the operation completes.

The "pre-operation" triggers will usually allow cancelling 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.

Chapter 3: Trigger usage

This section describes the basic steps to get started with triggers and the recommended usage patterns. For a detailed reference on all trigger parameters and supported features, please check the Trigger reference section.

Creating the first trigger

In order to associate a user script with a client or server event, a trigger must be created. A list of the possible events that scripts can bind in order to be obtained by the following command:

cm trigger showtypes

In order to create a trigger which validates label names, the names should be created according to a given naming standard; the user may use a command like this (on 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, which is 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 the trigger edit command can be used; it is necessary to 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 remove command, indicating the trigger type and position:

cm trigger delete before-mklabel 1

Chapter 4: Trigger reference

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

 before-addafter-add Fires on item addition, only once per add command. A list of the added items is provided to the trigger script. before-checkinafter-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-mkbranchafter-mkbranch Fires on branch creation. before-mklabelafter-mklabel Fires on label creation. before-mkattafter-mkatt Fires on attribute creation. before-chattvalueafter-chattvalue Fires when the value of an attribute applied to a certain object changes. before-mkrepafter-mkrep Fires on repository creation. before-rmrepafter-rmrep Fires on repository deletion. before-mkworkspaceafter-mkworkspace Fires on workspace creation. before-mkreviewafter-mkreview Fires on code review creation. before-editreviewafter-editreview Fires on code review edition. security (after-security) Fires every time a security exception happens on a denied operation. before-replicationreadafter-replicationread Fires on replication read operations. before-replicationwriteafter-replicationwrite Fires on replication write operations. before-rmbranchafter-rmbranch Fires on branch deletion. before-rmchangesetafter-rmchangeset Fires on changeset deletion. before-rmlabelafter-rmlabel Fires on label deletion. before-rmattributeafter-rmattribute Fires on attribute deletion.

Client-side triggers

 before-mkworkspaceafter-mkworkspace Fires when a workspace is created. before-setselectorafter-setselector Fires on any workspace selector change, including explicitly setting the selector and also the switch to... commands. before-updateafter-update The path to be updated is provided to the script. before-clientcheckoutafter-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-clientcheckinafter-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 table of the previous section, p.e. before-mkbranch, or mkbranch-before. This argument is required.
• name is the name given to 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 it needs to be a valid file specification that the server (either Windows or Unix) can understand. This argument is required.
The script path value will be interpreted as an endpoint URI if it's preceded by the webtrigger string (mind the whitespace!). That 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.
• --position refers to the position in the execution list of the given trigger type for the script. This parameter determines the execution order if several scripts are registered on a given trigger type. If the position is already being used by other script, 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?
2. Filters are a comma separated list.
3. If you need to use a comma character inside a filter, don't forget to scape it: "\,".
4. The filters restrict when the trigger executes.
5. You can filter by repository (rep:) in all types of triggers. For example: --filter="rep:myrepo".
6. Then, the system checks every particular filter to each type of trigger.
7. 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 necessary 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 host name, ':', and a port, by default 8084.

Position of the script in the trigger type is unique, meaning that a list is maintained for each trigger type and positions in that list are either used by a trigger or not, 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:

• To 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 Trigger created on position 1.
• To 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 Trigger created on position 1. cm trigger list before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave
• To 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" Trigger created on position 3.
• To 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*" Trigger created on position 2.
• To 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" Trigger created on position 1.

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

{
"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" ]
}


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

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.

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 table of section List of triggers. This argument is required.
• --server is the server in which to find the triggers to list. If omitted, the trigger will be finded on the default configured server. The syntax specifies a server's host name, ':', 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.

Change trigger

Once a trigger has been created, its options can be altered without recreating it through 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 to get the list of associated scripts, as listed in the table of section List of triggers. 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 edited. This argument is required.
• --position is the new position for the trigger in the trigger list. Note that the destination position must not be used by another trigger or an error will be raised.
• --name is the new name for the trigger. Note that the name is used only for readability.
• --script is the new path for the script or program to run. The same restrictions that were described for trigger creation would apply here.
Note: Once you've created a web trigger, updating it will interpret the --script parameter value as the trigger create command would.
• --server is the server in which to edit the trigger. If omitted, the trigger will be edited on the default configured server. The syntax specifies a server's host name, ':', and a port, by default 8084.

Sample for changing the name of a before-checkin trigger:

cm trigger list before-checkin 1 checkstyle c:\tmp\triggers\checkin-checkstyle.bat dave cm trigger edit before-checkin 1 --name="codestyle" cm trigger list before-checkin 1 codestyle c:\tmp\triggers\checkin-checkstyle.bat dave

Sample for updating the URI of a web trigger:

cm trigger list after-checkin 1 Notify team webtrigger https://www.mysite.com/api/team/checkin maria cm trigger edit after-checkin 1 --script="webtrigger http://myserver.org/api" cm trigger list after-checkin 1 Notify team webtrigger http://myserver.org/api maria

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 simply 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 table of section List of triggers. This argument is required.
• existing-trigger-position is the index by which the trigger is referred 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 host name, ':', 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

Trigger comunication

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. For a detailed description of the variables used in a given operation, check the specific operation in the reference below.

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, the operation cannot continue.

If the result is non-zero for a 'before' trigger, the operation is cancelled, 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 displayed on the client too.

When a trigger fails (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 be forced 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 variables

Client side triggers can now 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 two new 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 pre-defined variables

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

• PLASTIC_BIN_PATH will match the Plastic client installation directory
• WKSPACE_PATH will be the current workspace path when creating the client trigger

For example, the following command will 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"
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 is able 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".

Chapter 5: 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.

Trigger names
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 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 changed (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 changeset unique identifier. Can be used to ease parsing when accessing revisions with cm cat or cm shelveset in the trigger script, as 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 checked in to 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.
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 simply 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 in order 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, then 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)
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 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 contains 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*", then 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*", then 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 a attribute is created.
Runs on
Server.
Filters
You can use the following filters:
• Repository name
• Attribute name

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

Standard input
No standard input is supplied to these triggers.
Output result
The result 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*", then 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 which 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 change. value The value of the attribute.
Output result
Result 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*", then the trigger executes only for repositories whose name starts with cod.

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 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*", then the trigger executes only for repositories whose name starts with test.

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 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", then 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
Result 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*", then 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 are being set by the client.
Output result
Result 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.
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 in 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 section Common environment variables, the following is also available:
 PLASTIC_UPDATE_PATH The client path of the workspace that is being updated. PLASTIC_INITIAL_CHANGESET The ID of the changeset your workspace 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.
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 this kind 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*", then 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 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*", then 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
Result 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 cancelled. 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.
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 this kind 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 to a *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_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_CHANGESET Only available in the after-clientcheckin trigger. The changeset or changesets that were created as a result of the checkin operation.
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 kind of triggers.
The before-clientcheckin trigger runs once per affected repository under a xlink, and then once 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", then 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.

Trigger names
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;

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 which is 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;

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 which is 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 which is 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*", then 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
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 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.

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", then 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 of the changeset being deleted belongs to. 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 labelled changeset. PLASTIC_CHANGESET_OWNER The owner of the labelled 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", then 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
Result 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.

Chapter 6: Samples

All the samples in this section can be found on the triggers folder, within 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

# 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"

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

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

if (File.exists?(targetfile)) then
content = ""
open(targetfile) do |s| content = s.read end
else
channel.description = ""
channel.language = "en"
end

# Parse checkin item names from plastic

files = ''
itemspec, revspec, wkspec = line.split(';')
filename, branchspec, revno = itemspec.split('#')
files << filename << ""
end

item.title =  "#{ENV['PLASTIC_CHANGESET']} - #{ENV['PLASTIC_COMMENT']} by #{ENV['PLASTIC_USER']}"
item.date = Time.now
item.description = files

# Write the resulting file

File.open(targetfile, "w") do |f|
end


This is an after-checkin trigger:

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 = ''

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

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.