Triggers guide


Chapter 1: Introduction

About this guide
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@codicesoftware.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.

The following is the complete list of triggers executed in the server:

  • Create attribute
  • Change attribute value
  • Create branch
  • Create label
  • Create repository
  • Add items to the source control
  • Check-in
  • Create code review
  • Edit code review

Client side triggers

Some events that occur on the client can have scripts or programs associated. Currently, supported client triggers are the following:

  • Update (before and after)
  • Checkout (before and after)
  • Checkin (before and after)
  • Create Workspace
  • Set Selector, affecting "Switch to..." operations also

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 showtriggertypes

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 maketrigger 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 listtriggers before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave

To modify the script that this trigger is pointing to the changetrigger 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 changetrigger 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 removetrigger 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:

before-add
after-add
Server-side trigger.
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
Server-side trigger.
Fires on checkin. A list of the items to be checked in is provided.
before-mkbranch
after-mkbranch
Server-side trigger.
Fires on branch creation.
before-mklabel
after-mklabel
Server-side trigger.
Fires on label creation.
before-mkatt
after-mkatt
Server-side trigger.
Fires on attribute creation.
before-chattvalue
after-chattvalue
Server-side trigger.
Fires when the value of an attribute applied to a certain object changes.
before-mkrep
after-mkrep
Server-side trigger.
Fires on repository creation.
before-rmrep
after-rmrep
Server-side trigger.
Fires on repository deletion.
before-mkworkspace
after-mkworkspace
Server-side trigger.
Fires on workspace creation.
before-setselector
after-setselector
Server-side trigger.
Fires on any workspace selector change, including explicitly setting the selector and also the switch to... commands.
before-update
after-update
Client-side trigger.
The path to be updated is provided to the script.
before-mkreview
after-mkreview
Server-side trigger.
Fires on code review creation.
before-editreview
after-editreview
Server-side trigger.
Fires on code review edition.
before-clientcheckout
after-clientcheckout
Client-side trigger.
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
Client-side trigger.
The paths of the files and directories to be checked in are provided to both the before and after operations.

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

cm showtriggertypes

Trigger operations



Create trigger

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

cm maketrigger {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 applied with the rules specified in this field.
  • --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 changetrigger 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 maketrigger 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 mktrigger before-mklabel "Validate label" "c:\tmp\triggers\validate-label.bat" --server=myserver:8084 Trigger created on position 1. cm listtriggers 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 maketrigger 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 mktrigger 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 maketrigger 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_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" ]
}

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 showtriggertypes

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 listtriggers {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 listtriggers 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 listtriggers 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 listtriggers 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 changetrigger command. The syntax is:

cm changetrigger {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 maketrigger 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 listtriggers before-checkin 1 checkstyle c:\tmp\triggers\checkin-checkstyle.bat dave cm changetrigger before-checkin 1 --name="codestyle" cm listtriggers before-checkin 1 codestyle c:\tmp\triggers\checkin-checkstyle.bat dave

Sample for updating the URI of a web trigger:

cm listtriggers after-checkin 1 Notify team webtrigger https://www.mysite.com/api/team/checkin maria cm changetrigger after-checkin 1 --script="webtrigger http://myserver.org/api" cm listtriggers 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 removetrigger {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 listtriggers before-mklabel 1 Validate label c:\tmp\triggers\validate-label.bat dave 2 log labels c:\tmp\triggers\loglabels.bat dave cm rmtrigger before-mklabel 2 cm listtriggers 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.

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


Add

Trigger names
before-add after-add
Description
It executes user scripts when items are added to the source control.
Runs on
Server.
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.
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 The changeset unique identifier. Can be used to ease parsing when accessing revisions with cm cat or cm shelve 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.
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 shelve command. In case a shelve 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 mktrigger 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

Create branch

Trigger names
before-mkbranch after-mkbranch
Description
It executes user scripts when a branch is created.
Runs on
Server.
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.
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.
Sample command line creation
cm maketrigger before-mklabel "Validate label" "c:\plastic\triggers\Validate-label.bat" Trigger created on position 1. cm listtriggers 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.
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.
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.
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.
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.
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 sections Common environment variables and Server.conf variables, these 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.
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 sections Common environment variables and Server.conf variables, these 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 in the GUI client.

Update

Trigger names
before-update after-update
Description
It executes user scripts when a workspace is updated.
Runs on
Client.
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. 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 sections Common environment variables and Server.conf variables, these are also available:
PLASTIC_UPDATE_PATH The client path of the workspace that is being updated.
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 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.
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 "Pending" / "Approved" / "Discarded".
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.
Runs on
Server.
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 "Pending" / "Approved" / "Discarded".
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" / "changeset".
PLASTIC_REVIEW_ID The variable contains the identifier of the edited review.

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.
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 defined in sections Common environment variables and Server.conf 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 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.
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 sections Common environment variables and Server.conf variables, these are also available:
PLASTIC_COMMENT The comment specified by the user on the checkin operation.
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.
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 kind of triggers.

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

Replication operation: reading data

Runs on
Server.
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.


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
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 shelve #{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 maketrigger 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 shelve -")

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

Sample trigger creation command (on Windows):

cm maketrigger 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 maketrigger 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 can be used by rss aggregators 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 maketrigger 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 maketrigger 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 maketrigger before-clientcheckout "update before co" "ruby c:\plastic\triggers\update-before-co.rb"

Last updated


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.