Triggers guide

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

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

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

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

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

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

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

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

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

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

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

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

Where:

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

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

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

  1. Go to Discord or Slack:
     • On Discord, get the URL of the Discord webhook in the selected channel where you want to receive the Plastic triggers notifications. Learn how to connect Discord and Plastic SCM.
     • On Slack, you have to create a custom app to receive the Plastic triggers notifications. Read all the steps to complete about how to connect Slack and Plastic SCM.
  2. Use the webtrigger-discord or webtrigger-slack strings (instead of webtrigger ) before the script path followed by the Discord webhook or Slack channel. This will be something like this: cm trigger make after-checkin MyDiscordAfterCheckinTrigger "webtrigger-discord https://discordapp.com/api/webhooks/channelId/token" --server=myPlasticServer

     or

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

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

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

Here are some sample usages:

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

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

  {
   "PLASTIC_CHANGESET": "cs:2341@br:/main/task4638@rep:product@repserver:plastic.mysite.com:17590",
   "PLASTIC_CLIENTMACHINE": "DEV1HOST",
   "PLASTIC_COMMENT": "Fixing command line parsing",
   "PLASTIC_SERVER": "plastic.mysite.com:17590",
   "PLASTIC_SHELVE": false,
   "PLASTIC_USER": "dev1",
   "INPUT": [ "CH \"/src/main.c\" FILE" ]
  }
  

• Create a web trigger that fires after a checkin and send notifications from the server to the specified Discord channel: cm trigger create after-checkin NotifyTeam "webtrigger-discord https://discordapp.com/api/webhooks/811172464004562954/VNKRQ9JvPyvku0yYJg-hFmSesEePRFaMbikRlfkJBrb22QxmJoJVBmZR6iOWpiMIsS4t" --server=localhost:18084
• Create a web trigger that fires after a checkin and send notifications from the server to the specified Slack channel: cm trigger create after-checkin SlackWebTrigger "webtrigger-slack https://slack.com/api/chat.postMessage/U01PW9EET5E/xoxb-1781717825334-1781730759222-34UxkCu8WmA2FlzzjTS6tRYy" --server=localhost:18084

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

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

Where:

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

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

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

  1. Go to Discord or Slack:
     • On Discord, get the URL of the Discord webhook in the selected channel where you want to receive the Plastic triggers notifications. Learn how to connect Discord and Plastic SCM.
     • On Slack, you have to create a custom app to receive the Plastic triggers notifications. Read all the steps to complete about how to connect Slack and Plastic SCM.
  2. Use the webtrigger-discord or webtrigger-slack strings (instead of webtrigger ) before the script path followed by the Discord webhook or Slack channel. This will be something like this: cm trigger edit after-checkin 1 "webtrigger-discord https://discordapp.com/api/webhooks/channelId/token"

     or

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

Let's see some examples:

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

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

Where:

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

Example:

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:

Where:

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

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

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

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

Client.conf variables

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

<?xml version="1.0"?>
<ClientConfigData>
  <Language>en</Language>
  <WorkingMode>UPWorkingMode</WorkingMode>

  <TriggerVariables>
    <TriggerVariable name="TRIGGERS_PATH" value="c:\triggers" />
  </TriggerVariables>

</ClientConfigData>

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

Plastic predefined variables

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

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

Let's see some examples:

• Create a trigger that executes a script located at the triggers folder under the Plastic client installation folder: cm trigger create before-clientcheckin "Relative trigger path" "@PLASTIC_BIN_PATH/triggers/checkdirectories.pl"
• Create a trigger that executes a script located at the global configuration directory of the server you're using: cm trigger create after-update "Delete files after update" "@GLOBAL_CONFIG_PATH/allrepos/triggers/deletefiles.bat"

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

before-add after-add

Description

It executes user scripts when items are added to the source control.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Standard input

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

Standard input

A list of files to be added.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger was completed successfully. The items will be added.
Non zero	The trigger reports failure. If the trigger is before-add, an error is reported, and the items are not added to the repository. If the trigger is after-add, an error is reported. However, the items have already been added to the repository.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_COMMENT

The comment given by the user on the add operation.

Trigger names

before-checkin after-checkin

Description

It executes user scripts when a checkin operation is performed on any client.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Standard input

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

Standard input

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

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

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

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

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

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

CH "/" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
CH "/search" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
CH "/search/search.h" FILE#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Items will be checkedin the repository.
Non zero	The trigger reports failure. If the trigger is before-checkin the checkin operation is stopped, and the items are not checked in, neither changeset is created. An error message is reported to the client. If the trigger is after-checkin, an error message is reported to the client. However, the checkin operation has already been performed.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_COMMENT	The comment given at checkin time by the user.
PLASTIC_SHELVE	This variable indicates whether the checkin is a shelve operation or not.
PLASTIC_CHANGESET	Only available in the after-checkin trigger. The changeset or changesets that were created as a result of the checkin operation. This variable contains the specifications for the changesets that were created, separated by semi-colons (';'). This is a sample of a variable value with changesets created on two different repositories: cs:23@br:/main@rep:default@repserver:DARKTOWER:8084; cs:19@br:/main@rep:secondrep@repserver:DARKTOWER:8084
PLASTIC_PENDING_MERGE_LINKS	Only available in the before-checkin trigger. The variable contains information about the merge links included in the checkin operation. The format of the serialized variable is MergeLinkSpec1;.....;MergeLinkSpecN. Each MergeLinkSpec has the following format: mergetype:merge_type,source:src_cset_spec[,base:base_cset_spec] For example: mergetype:merge,source:2@rep:default@localhost:8084 The variables are: mergetype: can be one of the following constants: "merge", "cherrypick", "intervalcherrypick", "cherrypicksubtractive", "intervalcherrypicksubtractive". source: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server. base (optional): if mergetype is "intervalcherrypick" or "intervalcherrypicksubtractive" then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS	Same as PLASTIC_PENDING_MERGE_LINKS environment variable but only available in the after-checkin trigger.

Comments

The before-checkin and after-checkin triggers are invoked only once for all the items involved in the checkin operation. The standard input of the trigger will receive a list of the items involved.

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

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

Sample command line creation

cm trigger create checkin-before "checkstyle" "c:\tmp\triggers\checkin-checkstyle.bat" Trigger created on position 1.

Sample trigger script

The following script reads all the standard input and redirects it to the 'c:\tmp\triggers\checkinout.txt' file. The trick here is the use of the find.exe command to read the standard input in Windows command line 'cmd.exe':

@echo off
for /f "tokens=*" %%g in ('find /V ""') do (
    echo %%g >> c:\tmp\triggers\checkinout.txt
)
exit 0

Trigger names

before-merge

Description

This trigger can be used to deny the merge of some branches if certain conditions are not met.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Standard input

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

Standard input

The standard input for the merge and the mergeTo actions is one of the following:

• If the merge operation can't be performed, then the standard input is the reason why:

  CONTRIBUTORS_NOT_CONNECTED	Source and destination are not connected. Returned by the subtractive merge.
  INVALID_CSET_INTERVAL	The selected changesets interval (base, source] is not valid.
  ANCESTOR_NOT_FOUND	No ancestor found between source and destination.
  CONTRIBUTORS_ALREADY_CONNECTED	Source is already included on destination. Merge not needed.
  SOURCE_ALREADY_SUBTRACTED	The source is already subtracted from the destination. Subtractive merge not needed.
  NO_MERGES_DETECTED	There are no changes between source and destination.

• If the merge operation is performed, the standard input is a list of conflicts (in the following order: directory conflicts, file conflicts, and writable xlinks conflicts) plus the operations to apply (source changed, deleted, added, and so on). Each conflict and operation must be one per line.

  Find below an example for each type:

  • Conflicts:

    ADD_MOVE [SRC] A "/foo.c" cs:10 - [DST] M "/bar.c" -> "/foo.c" cs:5

    CHANGE_DELETE [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] D "/foo.c" cs:7

    CYCLE [SRC] M "/server" -> "/bin/server" cs:5 - [DST] M "/bin" -> "/server/bin" cs:5

    DELETE_CHANGE [SRC] D "/foo.c" cs:7 - [DST] C "/foo.c" cs:12 (base cs:7)

    DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10

    DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10

    DIVERGENT_MOVE [SRC] M "/foo.c" -> "/bar.c" cs:5 - [DST] M "/foo.c" -> "/qux.c" cs:5

    EVIL_TWIN [SRC] A "/foo.c" cs:10 - [DST] A "/foo.c" cs:5

    LOADED_TWICE [SRC] A "/bar.c" cs:10 - [DST] A "/foo.c" cs:5

    MOVE_ADD [SRC] M "/bar.c" -> "/foo.c" cs:10 - [DST] A "/foo.c" cs:5

    MOVE_DELETE [SRC] M "/foo.c" -> "/bar.c" cs:10 - [DST] R "/foo.c" cs:10

    MOVE_EVIL_TWIN [SRC] M "/foo.c" -> "/qux.c" cs:10 - [DST] M "/bar.c" -> "/qux.c" cs:5

    XLINK_CONFLICT [SRC] C "/thirdparty" Xlink -> / eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer) - [DST] C "/thirdparty" Xlink -> / ba682b83-4aaf-4169-b1ad-3d8de14b371b@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer)

    FILE_CONFLICT [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] C "/foo.c" cs:8 (base cs:7)

  • Writable Xlinks conflicts that will be expanded with a new merge:

    XLINK_MERGE [SRC] C "/engine" wXlink -> / 235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer) - [DST] C "/engine" wXlink -> / 17cb0014-3351-45f2-9ecb-bc025a43d059@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)

    XLINK_MERGE [SRC] C "/engine" wXlink -> / 235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink -> / be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)

  • Operations to apply:

    C "/foo.c" cs:12 (base cs:7)

    C "/thirdparty" Xlink -> / eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink -> / b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer)

    A "/foo.c" cs:7

    M "/foo.c" -> "/bar.c" cs:7

    D "/foo.c" cs:7

    FS "/foo.c" 777 (base 444)

  This is an example for an easy merge:

  CHANGE_DELETE [SRC] C "/src/foo.c" cs:12 (base cs:7) - [DST] D "/src/foo.c" cs:7
  FILE_CONFLICT [SRC] C "/src /bar.c" cs:12 (base cs:7) - [DST] C "/src /bar.c" cs:8 (base cs:7)
  M "/doc/readme.txt" -> "/readme.txt" cs:7
  D "/doc" cs:7
  

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger was completed successfully.
Non zero	The trigger reports failure.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_MERGE_TYPE	"Merge" / "IntervalSubtractive" / "Subtractive" / "IntervalCherrypick" / "Cherrypick"
PLASTIC_MERGE_SOURCE	Specification of the source changeset. For example: cs:23@br:/main/task@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_DESTINATION	Specification of the destination changeset. For example: cs:19@br:/main@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_BASE	Specification of the ancestor changeset. If there are multiple ancestors (recursive merge scenario), they will be separated by semi-colons (';'). For example: cs:4@br:/main@rep:quake@repserver:DARKTOWER:8084; cs:10@br:/main@rep:quake@repserver:DARKTOWER:8084
PLASTIC_MERGE_SOURCE_LABELS	The list of labels applied on the source changeset, separated by semi-colons (';'). For example: 6.0.16.1000
PLASTIC_MERGE_HAS_CONFLICTS	"true" if the merge contains conflicts. Otherwise, "false".
PLASTIC_MERGE_HAS_WK_CHANGES	"true" if the workspace contained changes when the merge started. Otherwise, "false".
PLASTIC_MERGE_IS_FORCED	"true" if the traceability has been ignored to merge and already connected source. Otherwise, "false".
PLASTIC_MERGE_STRATEGY	The strategy used to calculate the common ancestor. Allowed values: "Recursive" or "Manual".
PLASTIC_MERGE_IS_MERGE_TO	"true" if the merge is launched using a merge-to. Otherwise, "false".

Sample command line creation

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

Trigger names

before-mkbranch after-mkbranch

Description

It executes user scripts when a branch is created.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Branch name

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The branch will be created.
Non zero	The trigger reports failure. If the trigger is before-mkbranch, an error is reported, and the branch is not created. If the trigger is after-mkbranch, an error is reported. However, the branch has already been created.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_COMMENT	The comment given by the user at branch creation.
PLASTIC_BRANCH_NAME	The branch that is being created.
PLASTIC_FULL_BRANCH_NAME	The full branch name that is being created.
PLASTIC_REPOSITORY_NAME	The repository name where the branch is being created.

Trigger names

before-mklabel after-mklabel

Description

It executes user scripts when a label is created.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Label name

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The label will be created.
Non zero	The trigger reports failure. If the trigger is before-mklabel, an error is reported, and the label is not created. If the trigger is after-mklabel, an error is reported. However, the label has already been created.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_COMMENT	The comment given by the user at label creation.
PLASTIC_LABEL_NAME	The label that is being created.
PLASTIC_REPOSITORY_NAME	The repository name where the label is being created.
PLASTIC_CHANGESET_NUMBER	The number of the changeset being labeled.
PLASTIC_CHANGESET_OWNER	The name of the owner of the changeset being labeled.

Sample command-line creation

cm trigger create before-mklabel "Validate label" "c:\plastic\triggers\Validate-label.bat" --filter="LB*" Trigger created on position 1. cm trigger list before-mklabel 1 Validate label c:\plastic\triggers\Validate-label.bat dave

Sample trigger script

The following script saves a record of created branches on the c:\plastic\triggers\labels.log.txt file.

@echo off
echo %PLASTIC_REPOSITORY_NAME% %PLASTIC_LABEL_NAME% >> c:\plastic\triggers\labels.log.txt
exit 0

Trigger names

before-mkatt after-mkatt

Description

Executes user scripts when an attribute is created.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Attribute name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The attribute will be created.
Non zero	The trigger reports failure. If the trigger is before-mkatt, an error is reported, and the branch is not created. If the trigger is after-mkatt, an error is reported. However, the attribute has already been created.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_COMMENT	The comment given by the user at attribute creation.
PLASTIC_ATTRIBUTE_NAME	The attribute that is being created.
PLASTIC_REPOSITORY_NAME	The repository name where the attribute is being created.

Trigger names

before-chattvalue after-chattvalue

Description

It executes user scripts when the value of an attribute applied to a certain object changes.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Attribute name
• Standard input

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

Standard input

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

If the trigger is before-chattvalue:

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

For example:

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

If the trigger is after-chattvalue:

object_spec attribute:"att_name" value:"att_value"

For example:

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

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

object_spec	The object which changed attribute value is applied.
attribute	The name of the related attribute.
oldvalue	The attribute value previously to be changed.
newvalue	The attribute value after the change.
value	The value of the attribute.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully.
Non zero	The trigger reports failure. If the trigger is before-chattvalue, an error messasge is reported, and the attribute value is not changed. If the trigger is after-chattvalue, an error message is reported. However, the attribute value has already been changed.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_ATTRIBUTE_NAME	The attribute which value is being changed.
PLASTIC_REPOSITORY_NAME	The repository name where the attribute value is being changed.

Trigger names

before-mkrep after-mkrep

Description

It executes user scripts when a repository is created.

Runs on

Server.

Filters

You can use the following filter:

• Repository name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The repository will be created.
Non zero	The trigger reports failure. If the trigger is before-mkrep, an error is reported, and the repository is not created. If the trigger is after-mkrep, an error is reported. However, the repository has already been created.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_REPOSITORY_NAME

The repository that is being created.

Trigger names

before-rmrep after-rmrep

Description

It executes user scripts when a repository is removed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The repository will be deleted.
Non zero	The trigger reports failure. If the trigger is before-rmrep, an error is reported, and the repository is not deleted. If the trigger is after-rmrep, an error is reported. However, the repository has already been deleted.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_REPOSITORY_NAME	The repository that is being deleted.
PLASTIC_REPOSITORY_ID	The repository id that is being deleted.

Trigger names

before-mkworkspace after-mkworkspace

Description

It executes user scripts when a workspace is created.

Runs on

Client.

Filters

You can use the following filter:

• Repository name
• Workspace name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The workspace will be created.
Non zero	The trigger reports failure. If the trigger is before-mkworkspace, an error is reported, and the workspace is not created. If the trigger is after-mkworkspace, an error is reported. However, the workspace has already been created.

Environment variables

In addition to the variables defined in section Common environment variables, the following ones are also available:

PLASTIC_WORKSPACE_NAME	The name given to the new workspace.
PLASTIC_WORKSPACE_PATH	The path of the workspace on the client machine.

Trigger names

before-setselector after-setselector

Description

Executes user scripts when a workspace selector is changed.

Runs on

Client.

Filters

You can use the following filter:

• Repository name
• Standard input

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

Standard input

The standard input in these triggers receives the selector contents that the client is setting.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The selector will be modified.
Non zero	The trigger reports failure. If the trigger is before-setselector, an error is reported, and the selector is not modified. If the trigger is after-setselector, an error is reported. However, the operation has already been done.

Environment variables

In addition to the variables defined in section Common environment variables, the following ones are also available:

PLASTIC_WORKSPACE_NAME	The name of the workspace which selector is being set.
PLASTIC_WORKSPACE_PATH	The client path of the workspace which selector is being set.

Comments

Selectors are modified either with the setselector or switch command or with the Switch workspace to branch, Switch workspace to label or Switch workspace to changeset commands, all of them in the command-line interface or the GUI client.

Trigger names

before-update after-update

Description

It executes user scripts in the following scenarios:

• When a workspace is updated.
• When a 'fast-update' operation is executed.
• When a Gluon workspace is updated (both from the Gluon GUI or by running the cm partial update command).

Runs on

Client.

Filters

You can use the following filters:

• Repository name
• Path to be updated
• Standard input

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

Standard input

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

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

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

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Update operation will proceed.
Non zero	The trigger reports failure. If the trigger is before-update, an error is reported, and the workspace is not updated. If the trigger is after-update, an error is reported. However, the workspace has already been updated.

Environment variables

In addition to the variables defined in the Common environment variables section, the following is also available:

PLASTIC_UPDATE_PATH	The client path of the workspace that is being updated.
PLASTIC_INITIAL_CHANGESET	The ID of your workspace's changeset is (or was) pointing at when the update begins.
PLASTIC_FINAL_CHANGESET	The ID of the changeset your workspace is (or will be) pointing at when the update finishes.

Comments

This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.

Trigger names

before-mkreview after-mkreview

Description

It executes user scripts when a code review is created.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Code review title

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The code review will be created.
Non zero	The trigger reports failure. If the trigger is before-mkreview, an error is reported, and the code review is not created. If the trigger is after-mkreview, an error is reported. However, the code review has already been created.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_REPOSITORY_NAME	The repository name where the code review is created.
PLASTIC_REVIEW_TITLE	The title given to the code review.
PLASTIC_REVIEW_STATUS	Under review, Reviewed, or Rework Required.
PLASTIC_REVIEW_ASSIGNEE	The user assigned to the code review, if any. Not set if no user is assigned to the code review
PLASTIC_REVIEW_TARGET	The specification of the object for which the code review has been created. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE	"branch" / "changeset".
PLASTIC_REVIEW_ID	Only available in the after-mkreview trigger. The variable contains the identifier of the review that has been created.

Trigger names

before-editreview after-editreview

Description

It executes user scripts when a code review is edited. For example, the triggers will be launched when a user changes a review name, the assignee, or the status, or when a review comment is created, edited, or deleted.

Runs on

Server.

Filters

You can use the following filters:

• Repository name
• Code review title

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The code review edition is saved to the repository.
Non zero	The trigger reports failure. If the trigger is before-editreview, an error is reported, and the code review edition is not saved in the repository. If the trigger is after-editreview, an error is reported. However, the code review edition is saved to the repository.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_REPOSITORY_NAME	The repository name where the code review is edited.
PLASTIC_REVIEW_TITLE	The title given to the edited code review.
PLASTIC_REVIEW_STATUS	Under review, Reviewed, or Rework Required.
PLASTIC_REVIEW_ASSIGNEE	The user assigned to the code review, if any. Not set if no user is assigned to the code review
PLASTIC_REVIEW_TARGET	The specification of the object for which the code review has been edited. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE	branch or changeset.
PLASTIC_REVIEW_ID	The variable contains the identifier of the edited review.
PLASTIC_REVIEW_COMMENT	The variable contains the comment that fired the trigger. This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.
PLASTIC_REVIEW_COMMENT_ACTION	The variable reflects the action in the comment: Created, Edited, or Deleted. This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.

Trigger names

before-clientcheckout after-clientcheckout

Description

It executes user scripts on the client when a checkout operation is executed.

Runs on

Client.

Filters

You can use the following filter:

• Repository name
• Standard input

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

Standard input

The standard input in these triggers receives the list of items specified by the user on the checkout operation.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Checkout operation will proceed.
Non zero	The trigger reports failure. If the trigger is before-clientcheckout, an error is reported, and the operation is canceled. If the trigger is after-clientcheckout, an error is reported. However, the items have been already checked out.

Environment variables

The variables in these triggers are the same as the ones defined in section Common environment variables.

Comments

This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.

Trigger names

before-clientcheckin after-clientcheckin

Description

It executes user scripts on the client when a checkin operation is executed.

Runs on

Client.

Filters

You can use the following filter:

• Repository name
• Standard input

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

Standard input

The standard input in these triggers receives the list of items specified by the user on the checkin operation.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Checkin operation will proceed.
Non zero	The trigger reports failure. If the trigger is before-clientcheckin, an error is reported, and the checkin operation is aborted. If the trigger is after-clientcheckin, an error is reported. The items are already checked in.

Environment variables

In addition to the variables defined in section Common environment variables, the following ones also available:

PLASTIC_COMMENT	The comment specified by the user on the checkin operation.
PLASTIC_CHANGESET	Only available in the after-clientcheckin trigger. The changeset or changesets that were created as a result of the checkin operation.
PLASTIC_PENDING_MERGE_LINKS	Only available in the before-clientcheckin trigger. The variable contains the following information: The merge links included in the checkin operation. The merge links affecting the repositories under a xlink. The format of the serialized variable is MergeLinkSpec1;.....;MergeLinkSpecN. Each MergeLinkSpec has the following format: mergetype:merge_type,source:src_cset_spec[,base:base_cset_spec] For example: mergetype:merge,source:6@rep:xlinkedrepo@repserver:localhost:8084 mergetype:merge,source:2@rep:default@localhost:8084 The variables are: mergetype: can be one of the following constants: "merge", "cherrypick", "intervalcherrypick", "cherrypicksubtractive", "intervalcherrypicksubtractive". source: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server. base (optional): if mergetype is "intervalcherrypick" or "intervalcherrypicksubtractive" then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS	Same as PLASTIC_PENDING_MERGE_LINKS environment variable but only available in the after-clientcheckin trigger.

Comments

This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.

The before-clientcheckin trigger runs once per affected repository under an Xlink and then again for the repository where the checkin occurs. If you don't want this to happen, you can add a filter.

Trigger names

after-security

Description

It executes user scripts when a user performs an operation that has been denied through security permissions.

Runs on

Server.

Filters

You can use the following filter:

• Repository name

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

Standard input

No standard input is supplied to this trigger.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Security operation will proceed.
Non zero	The trigger reports failure. If the trigger is after-security, an error is reported.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_MESSAGE	The information about the denied permission.
PLASTIC_PERMISSIONS	The denied permissions.
PLASTIC_REPOSITORY_ID	The id of the repository where the operation is executed.
PLASTIC_REPOSITORY_NAME	The name of the repository where the operation is executed.
PLASTIC_OBJECT	The object with the denied permission.

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;

Runs on

Server.

Filters

You can use the following filter:

• Repository name

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. Security operation will proceed.
Non zero	The trigger reports failure. If the trigger is before-replicationread, an error is reported, and the replication operation is aborted. If the trigger is after-replicationread, an error is reported. The item is already replicated.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_BRANCH

The complete branch specification being replicated. This is the format of the branch specification: branch@rep:rep_name@server If the trigger is before-replicationread, the server member will be the destination server. If the trigger is after-replicationread, the server member will be the source server.

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 being replicated. This is the format of the branch specification: branch@rep:rep_name@server The server member will be the destination server.
PLASTIC_REPLICATION_SOURCE	Only available in the before-replicationwrite trigger. The complete repository specification being replicated. This is the format of the repository specification: rep:rep_name@server The server member will be the source server.
PLASTIC_REPLICATION_ID	Only available in the after-replicationwrite trigger. The id of the replication.

Trigger names

before-rmbranch after-rmbranch

Description

It executes user scripts when a branch is removed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Branch name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The branch will be deleted.
Non zero	The trigger reports failure. If the trigger is before-rmbranch, an error is reported, and the branch is not deleted. If the trigger is after-rmbranch, an error is reported. However, the branch has already been deleted.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_BRANCH_NAME	The name of the branch that is being deleted.
PLASTIC_FULL_BRANCH_NAME	The full name (including parent) of the branch to be deleted.
PLASTIC_REPOSITORY_ID	The ID of the repository where the branch is deleted.
PLASTIC_REPOSITORY_NAME	The name of the repository where the branch is deleted.
PLASTIC_COMMENT	The comment given by the user at branch deletion.

Trigger names

before-mvbranch after-mvbranch

Description

It executes user scripts when a branch is renamed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Branch name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The branch will be renamed.
Non zero	The trigger reports failure. If the trigger is before-mvbranch, an error is reported, and the branch is not renamed. If the trigger is after-mvbranch, an error is reported. However, the branch has already been renamed.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_BRANCH_NAME	The name of the branch that is being renamed.
PLASTIC_FULL_BRANCH_NAME	The full name (including parent) of the branch to be renamed.
PLASTIC_BRANCH_NEW_NAME	The new name of the branch that is being renamed.
PLASTIC_FULL_BRANCH_NEW_NAME	The full new name (including parent) of the branch to be renamed.
PLASTIC_REPOSITORY_ID	The ID of the repository where the branch is renamed.
PLASTIC_REPOSITORY_NAME	The name of the repository where the branch is renamed.
PLASTIC_COMMENT	The comment given by the user at branch renaming.

Trigger names

before-rmchangeset after-rmchangeset

Description

It executes user scripts when a changeset is removed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Changeset number

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The changeset will be deleted.
Non zero	The trigger reports failure. If the trigger is before-rmchangeset, an error is reported, and the changeset is not deleted. If the trigger is after-rmchangeset, an error is reported. However, the changeset has already been deleted.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_CHANGESET_NUMBER	The changeset that is being deleted.
PLASTIC_CHANGESET_OWNER	The name of the owner of the changeset being deleted.
PLASTIC_BRANCH_NAME	The branch to which the changeset being deleted belongs.
PLASTIC_REPOSITORY_ID	The ID of the repository where the changeset is deleted.
PLASTIC_REPOSITORY_NAME	The name of the repository where the changeset is deleted.
PLASTIC_COMMENT	The comment given by the user at changeset deletion.

Trigger names

before-rmbranch after-rmbranch

Description

It executes user scripts when a label is removed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Label name

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

Standard input

No standard input is supplied to these triggers.

Output result

Result code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The label will be deleted.
Non zero	The trigger reports failure. If the trigger is before-rmlabel, an error is reported, and the label is not deleted. If the trigger is after-rmlabel, an error is reported. However, the label has already been deleted.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_LABEL_NAME	The name of the label that is being deleted.
PLASTIC_BRANCH_NAME	The name of the branch.
PLASTIC_CHANGESET_NUMBER	The number of the labeled changeset.
PLASTIC_CHANGESET_OWNER	The owner of the labeled changeset.
PLASTIC_REPOSITORY_ID	The ID of the repository where the label is deleted.
PLASTIC_REPOSITORY_NAME	The name of the repository where the label is deleted.
PLASTIC_COMMENT	The comment given by the user at label deletion.

Trigger names

before-rmattribute after-rmattribute

Description

It executes user scripts when an attribute is removed.

Runs on

Server.

Filters

You can use the following filter:

• Repository name
• Attribute name

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

Standard input

No standard input is supplied to these triggers.

Output result

The resulting code from the trigger script or executable determines the success or failure of the operation:

0	The trigger completed successfully. The attribute will be deleted.
Non zero	The trigger reports failure. If the trigger is before-rmattribute, an error is reported, and the attribute is not deleted. If the trigger is after-rmattribute, an error is reported. However, the attribute has already been deleted.

Environment variables

In addition to the variables defined in sections Common environment variables and server.conf variables, these are also available:

PLASTIC_ATTRIBUTE_NAME	The name of the attribute that is being deleted.
PLASTIC_REPOSITORY_ID	The ID of the repository where the attribute is deleted.
PLASTIC_REPOSITORY_NAME	The name of the repository where the attribute is deleted.
PLASTIC_COMMENT	The comment given by the user at attribute deletion.

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

Apply code beautifier to .java files

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

#!/usr/bin/env ruby

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

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

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

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

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

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

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

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

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

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

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

  end  #if

end  #each

Sample trigger creation command (on Windows):

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):

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:

Generate rss with changeset contents

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

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

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

# Read content if available

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

# Parse checkin item names from plastic

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

# Add new rss item

item = RSS::Rss::Channel::Item.new
item.title =  "#{ENV['PLASTIC_CHANGESET']} - #{ENV['PLASTIC_COMMENT']} by #{ENV['PLASTIC_USER']}"
item.link = http://www.plasticscm.com
item.date = Time.now
item.description = files
rss.items << item

# Write the resulting file

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

This is an after-checkin trigger:

Validate that label name starts with 'release'

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

Trigger creation command:

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:

November 3, 2021

• We restructured the Triggers guide to make its content more readable.

October 28, 2021

• Triggers can now run from Global Configuration. The new predefined variable GLOBAL_CONFIG_PATH is required.

October 22, 2021

• Web triggers now support sending Discord and Slack notifications.

October 6, 2021

• We added a note in the filters description to remark that it's possible to use wildcards.

June 15, 2020

• We updated the values of the PLASTIC_REVIEW_STATUS variable for the Create code review and Edit code review triggers to use the new code review status strings. Now they are Under Review, Reviewed and Rework Required instead of pending, approved and discarded.

December 10, 2019

• We added triggers for object removal events, so you can set up scripts to run automatically before and/or after objects are deleted. The objects handled are:
  • Branch
  • Changeset
  • Label
  • Attribute

November 19, 2019

• Updated the explanation of the cset_id identifier in the server Checkin trigger.

October 25, 2019

• The before-mklabel and after-mklabel server-side triggers have two new environment variables set at execution time: PLASTIC_CHANGESET_NUMBER and PLASTIC_CHANGESET_OWNER.
• The before-update and after-update client-side triggers have two new environment variables: PLASTIC_INITIAL_CHANGESET and PLASTIC_FINAL_CHANGESET.

October 18, 2019

• Now, you can find more info about how to apply filters to triggers and the filters that you can apply to every trigger.

July 16, 2019

• We updated the trigger output reference to reflect that client-side triggers will not fail when the related executable is missing.

March 26, 2019

• Updated examples to use the new cm trigger command.

November 21, 2018

• Now, the client update triggers (before and after) are also triggered by the 'fast-update' operation and the Gluon update, and not only by the standard update operation.
• We added two new environment variables to the Edit code review trigger: PLASTIC_REVIEW_COMMENT and PLASTIC_REVIEW_COMMENT_ACTION.
• We updated the merge trigger with the following:
  • Now, the merge-to supplies the standard input.
  • There is a new variable, PLASTIC_MERGE_IS_MERGE_TO, to identify if the merge trigger is launched using a merge-to action or not.

November 8, 2018

• Now, the PLASTIC_PENDING_MERGE_LINKS environment variable in the before-clientcheckin trigger includes the information about the merge links affecting the repositories under a xlink.

October 10, 2017

• We added the new before-merge trigger if you want to deny the merge of branches under certain circumstances.

June 8, 2017

• The PLASTIC_CHANGESET environment variable has been added to the Client checkin trigger.
• The Edit code review trigger will be launched now every time a review comment is created, edited or deleted.

March 4, 2016

• The PLASTIC_REVIEW_ID environment variable has been added to the Create code review and Edit code review triggers.

August 6, 2015

• The PLASTIC_PENDING_MERGE_LINKS environment variable has been added to the Checkin and Client checkin triggers.
• A new pair of triggers lets the user execute scripts when the value of an attribute applied to a certain object changes.

March 27, 2015

• Now, you can create and update web triggers.

March 27, 2015

• Added client-side variables.

September 1, 2014

• Documented new triggers: security, replication read, and replication write.