This guide describes how Plastic SCM provides integration with diverse control tracking tools: Bugzilla, Mantis, Trac, Jira, Axosoft, VersionOne, FogBugz, Rally, Polarion and codeBeamer.
Using this guide, you'll also learn too how to write your own Plastic SCM custom extensions.
Once an issue tracking system is configured, the user will be able to work with the extension and Plastic SCM seamlessly. This means that the user will be able to see the associated task information through the Plastic GUI.
Plastic SCM extensions allow two different working modes:
This section describes the steps to follow in order to use the Bugzilla integration with Plastic SCM.
In this chapter, you will learn how to configure the Bugzilla integration both in the server and in the client sides.
To setup the Bugzilla extension functionality, copy the script file plastic.cgi (included on plasticscm_install_path/client/extensions/bugzilla) to the Bugzilla installation folder.
Depending on the server's operating system, the first line of the script file may have to be changed:
#!/usr/bin/perl -wT
#!c:\perl\bin\perl.exe -wT
Read how to configure the Bugzilla integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Bugzilla extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Bugzilla extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
bugzilla.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
bugzilla.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/bugzilla/bugzillaextension.dll" />
</Extensions>
Bugzilla Base URL: Specifies the URL where the Bugzilla server is installed and running.User name: If required, enter your user name.Branch prefix: If you are going to work on the
Task on branch
mode, specifying this parameter is recommended (but not mandatory). This branch prefix will be used to bind the
Plastic branches to the Bugzilla tasks.
Using this working mode, every Bugzilla task is associated to a Plastic branch when creating a new one. The branch name for the new branch must match the configured extension prefix (if it has been set) and the numeric identifier on Bugzilla.
By clicking on the Show extended information button (
) in the Branches view the information associated to the branches will be displayed on the right panel of the Plastic GUI. By selecting a branch the Bugzilla task information is displayed in Plastic SCM: the number or identifier, task owner, status, title and description.
By double clicking on the task pane or by clicking on the Open issue in browser button (
), a new browser window will be opened and will display the full information of the task in Bugzilla:
It is possible to setup the Plastic SCM repositories so that numbered branches associated to tasks are checked against Bugzilla. Only if there is a bug number defined in Bugzilla the working branch will be allowed. This check is performed on the branch creation operation, only for child branches.
In order to setup the branch creation check on a repository, create an attribute named plastic-enforce-task-branch on the desired repositories. This attribute must be created using one of the following methods:
With this attribute created, each time a child branch is going to be created on the repository where it is defined, the extension will check the name of the new branch. If it starts with the task prefix, it will then pick the number contained on it and ask Bugzilla if there is a matching bug number. Otherwise an error is printed and the operation is cancelled:
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Bugzilla extension and select the Bind issues to Plastic changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset is linked to the task(s) in Bugzilla, this information can be displayed in the Plastic SCM
Changesets view. When the Extended information panel is visible (
), if you click a changeset then Plastic shows the associated Bugzilla tasks:
The users can also add new tasks or delete previous ones from the Bugzilla Extension pane. Besides, by
double clicking each task associated to a certain changeset or by clicking the
Open issue in browser button (
), a new web browser window opens and shows the selected Bugzilla task. Whenever a user modifies a task in
Bugzilla, the new data will be updated on Plastic GUI by pressing the Refresh button on
the Bugzilla Extension pane.
This section describes the steps to follow in order to use Mantis integration with Plastic SCM. It also describes its advantages.
This extension is compatible with Mantis versions 0.19.4, 1.0.0, 1.0.8 and higher.
Read how to configure the Mantis integration both in the server and in the client sides.
To setup the Mantis extension functionality, copy the script file plastic.php (included on plasticscm_install_path/client/extensions/mantis) to the Mantis installation folder.
Read how to configure the Mantis integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Mantis extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Mantis extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
mantis.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
mantis.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/mantis/mantisextension.dll" />
</Extensions>
Mantis Base URL: Specifies the URL where the Mantis server is installed and running.
User name: This field must be filled with a valid Mantis user.
Branch prefix: If you are going to work on the
Task on branch
mode, specifying this parameter is recommended (but not mandatory). This branch prefix will be used to bind the
Plastic branches to the Mantis tasks.
Encoding: UTF-8 is the default and will work for most languages. Edit this value in case you need
to change the enconding.
Task on branch is the working mode configured by default which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
As usual, the first step would be creating issues in Mantis, this would be usually done by the Project Manager, by clicking on the "Report Issue" option a dialog on which to include the information of the new issue to be done will be opened, the information to include would be title, description, severity, etc.
When the issue is created, Mantis assigns it a number. In this case, Mantis assigned the number 4 to the task, as shows the figure below. Users can select an issue from the list of issues -which are shown on different colors depending on their status- and change its status, so issue 4 goes from new to assigned.
The next step is that the developer assigned to the task must create a new branch. It is as simple as right clicking on the parent branch and select the Create child branch option as it is shown in the following image:
In order to link the new branch to the issue in Mantis, the developer must give the branch the same Mantis number, 4 in this case, preceded by the branch prefix:
Now, the user can check the information of the issues linked to a certain branch on the extended information panel () on the Branches view.
If the user clicks on the Open issue in browser button () or double-clicks on the Mantis task, a browser window with the associated branch issue will be opened. When the users changes the status or any other field of the issue, the new information will appear by refreshing Mantis extension.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Mantis extension and select the Bind issues to Plastic changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset is linked to the issue or task in Mantis, this information can be displayed in the Plastic SCM
Changesets view. When the Extended information panel is visible (
),if you click a changeset then Plastic shows the associated Mantis tasks:
The users can also add new tasks or delete previous ones from the Mantis Extension pane. Besides, by
double clicking each task associated to a certain changeset or by clicking the
Open issue in browser button (
), a new web browser window opens and shows the selected Mantis task. Whenever a user modifies a task in
Mantis, the new data will be updated on Plastic GUI by pressing the Refresh button on
the Mantis Extension pane.
This section describes the steps to follow in order to use Trac integration with Plastic SCM. It also describes its advantages.
This extension is compatible with Trac versions from 0.10.
In this chapter, you will learn how to configure the Trac integration both in the server and in the client sides.
To set up the Trac extension functionality, the XMLRPC plug-in must be installed into Trac server. This link provides information about how to download, install and verify that it has been properly set up.
Using Trac administration tool, enable the XML_RPC permission on users which will use the extension. If this permission is assigned to user "anonymous" it will be available to every user.
When using the Trac extension, several Server configuration features must be taken into account:
Read how to configure the Trac integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Trac extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Trac extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
trac.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
trac.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/trac/tracextension.dll" />
</Extensions>
Base Trac URL: Specifies the URL where the Trac server is installed and running.
This server requires authentication, User name, and Password: If the
Trac server is configured on Basic authentication User/Password mode, then enable the
This server requires authentication checkbox and type the credentials to authenticate against the
Trac server.
Branch prefix: If you are going to work on the
Task on branch mode, specifying this parameter
is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the Trac
tasks.
The working mode configured by default is the Task on branch mode, which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
As usual, the first step would be creating issues in Trac. This would be usually done by the Project Manager. By clicking on the "New Ticket" option, a dialog on which to include the information of the new issue to be done will be opened. The information to include will be the title, description, summary, etc.
When the task or ticket is created, Trac assigns it a number (number 4 on the example picture below).
Now, the developer has to work with the task that has been assigned to. So they create a new branch (as simple as right-clicking on the parent branch and select the Create child branch option), as is shown on the image below. In order to link the new branch to the issue in Trac, its name must match the configured branch prefix for Trac extension (if it has been defined) and the Trac issue number (issue number 4 in this case). So, if branch prefix is set to 'scm', branch name scm004 will be linked to Trac ticket #4.
Extended information of the branches will be displayed by clicking on the Show extended information button (). When a branch is selected on the Branches view, the right pane will show the information of the associated task/defect: its number, owner or developer the task has been assigned to, status, title and comments.
By double clicking on the Trac information task or by pressing the Open issue in browser button (), a new browser window is opened showing the associated branch task and will display the full information of the Trac task.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Trac extension and select the Bind issues to Plastic Changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset is linked to the ticket or task in Trac, this information can be displayed in the Plastic SCM
Changesets view. When the Extended information panel is visible (
), if you click a changeset then Plastic shows the associated Trac tasks:
The users can also add new tasks or delete previous ones from the Trac Extension pane. Besides, by
double-clicking each task associated to a certain changeset or by clicking the
Open issue in browser button (
), a new web browser window opens and shows the selected Trac task. Whenever a user modifies a task in Trac,
the new data will be updated on Plastic GUI by pressing the Refresh button on
the Trac Extension pane.
This section describes the steps needed to setup Jira and Plastic SCM to work together.
In this chapter, you will learn how to configure the Jira integration both in the server and in the client sides.
The new field is empty by default and will not show up in the configured screens until it gets some content.
In Jira Cloud, the "Accept remote API calls" option comes enabled by default. So if you are a Jira Cloud user, you can skip this step.
Once these steps have been fulfilled, the Jira server is ready to accept Plastic SCM integration.
Read how to configure the Jira integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Jira extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Jira extension on the Plastic SCM client on your Linux or macOS machine by using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
jira.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
jira.conf file:
WorkingMode parameter to assign one of these values:
TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/jira/jiraextension.dll" />
</Extensions>
Host: Specifies the URL where the Jira server is located. Note that the URL must contain the port
where the Jira server is running.
User name and Password: Specify the Jira credentials used to log into Jira and log the changes.
If you use Jira Cloud, the User name must be the email address of the account, and the Password must be an API token. You can find out how to generate API tokens for your Atlassian Cloud account in their official documentation.
Branch prefix: If you are going to work on the
Task on branch mode, specifying this parameter
is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the Jira tasks.
Project Key: Specifies the key of the Jira project whose issues will be related to the Plastic branches.
Custom Field ID: This parameter is the identifier of the custom field to be used for
logging the Plastic checkin information on Jira tasks.
This field is built adding the custom field id that Jira assigned when
creating the field.
Next-gen projects do not support this field.
Leave the Custom Field ID blank to have the checkin info added as a comment.
Use LDAP credentials if available: If the Plastic SCM client authentication mode is LDAP, then the
Jira Extension can be configured to reuse those credentials to log in to Jira by checking the this parameter.
Please have in mind that both Plastic SCM Server and Jira must share the same LDAP user directory for this
functionality to work.
Use default proxy credentials: Automatically sets the proxy credentials with the default
credentials for all Jira extension connections.
Issue query limit: This parameter is used to manually tune the maximum number of returned results
in the Create Branch dialog.
Resolved issue states: Holds a comma-separated list of status names to be considered as "resolved".
Issue types: Lets you filter the issues the Jira extension retrieves by their type. Just enter a
comma-separated list of issue types. This is useful, for example, if you only want to see in Plastic SCM
Bug or Task issues, filtering out the rest.
jira.conf file:
Name=Issue types;Value=Bug,Task;Type=Text;IsGlobal=False
Fields mapping: Lets you map the fields from the Jira issue that will be displayed on the task
information panel in the Branches or Changesets views.
Status transition: Lets you change the status of the associated issue based on a changeset comment. This feature works binding issues to both branches and changesets.
The working mode configured by default is the Task on branch mode, which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
In order to start working with Plastic SCM and Jira extension, the tasks must be created on the issue tracking system by clicking on the "Create issue" option and typing the data related to the new issue, such as name, associated project, summary, etc.
Jira will assign a number to the newly created issue, which will be the same number given to the Plastic branch when working on that task, in this case we create issue number 1.
Then the developer who has been assigned to that issue starts working on it. They will create a new branch using the Plastic SCM GUI client. There are two options to create a new branch linked to Jira:
By clicking on the Show extended information button () in the Branches view, the information associated to the branches will be displayed on the right panel of the Plastic GUI. By selecting a Plastic branch, the Jira issue information is displayed:
By double-clicking on it or by pressing the Open issue in browser button (), a new browser window is opened showing the associated branch issue and will display the full information of the Jira task. When the user changes any field of the issue the new information will be shown by clicking on Refresh button of Jira Extension panel.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Jira extension and select the Bind issues to Plastic changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset has been linked to the issue(s) or task(s) in Jira, this information can be displayed in the Plastic SCM Changesets view. When the Extended information panel is visible (), by clicking in a changeset then shows the associated Jira issues:
The users can also add new tasks or delete previous ones from the Jira Extension information. Besides, by double clicking on each of the issues associated to a certain changeset or by clicking the Open issue in browser button (), a new browser window will be opened showing the Jira selected task. Whenever a user modifies an issue in the task tracking tool, the new data will be updated on Plastic GUI by pressing the Refresh button on the Jira Extension pane.
Besides the ability to display Jira data bound to branches or changesets inside Plastic SCM, the integration also keeps a record of the modified items inside Jira. When changes have been checked in and the integration is active, Jira will display the affected items in the "Plastic SCM" custom field, using either the Task on branch or Task on changeset working modes:
Plastic SCM also allows Jira multi-project configurations. The idea is to let each branch explicitly contain the project key of its related task, instead of defining a global project key for all branches.
After the Jira server has been configured, it's time to configure the Plastic SCM client to work with a multi-project configuration.
To configure the Jira extension on the Plastic SCM client, click on the Preferences tab of the main window of the Plastic SCM GUI. A new dialog window will be opened. Click on the Issue tracking tab and select the radio button Bind to this issue tracking system and select Atlassian Jira.
jira.conf file.
Projects and tasks must be created on Jira:
Now it's time to create the Plastic SCM branches. Remember that we choose the "JIRA_" prefix to identify the branches related to the Jira tasks.
As we're working with multi-project configuration it's important to distinguish which branch is related to each project. As you can see in the picture below we use the following scheme to name the Plastic SCM branches: branchPrefix_projectShortName-taskID.
For example, the branch for the Jira task RI-1 will be JIRA_RI-1; and for our Jira project FG (Forms generator), will be JIRA_FG-1.
The Jira extension allows to map the fields from the Jira issue that will be displayed on the task information panel in the Branches or Changesets views in Plastic SCM.
To define the Jira field mapping functionality, the parameter Fields mapping must be configured. In order to do that, open the Jira extension configuration by clicking on the Preferences tab of the main window of the Plastic SCM GUI. Then press the Issue tracking tab. Scroll down the parameters list until the Fields mapping configuration parameter appears:
It stores field name pairs (from->to) separated by '|' (vertical bar) characters. The parameter syntax is:
[ jira_field_name -> plastic_property_name [ | jira_field_name -> plastic_property_name [ | ... ] ] ]
jira.conf file.
For example, this is a valid configuration of Jira fields mapping:
issue.Fields.Project.Name->Description|issue.Fields.Reporter.Name->Owner|issue.Fields.Description->Title
In this case, these will be the values displayed on the extended information panel "Atlassian Jira extension": the displayed Description would contain the project key, the displayed Owner would be the Jira user who created the issue, and the displayed Title would be the Jira issue description.
The to attribute from the pair "from->to" describes the Plastic SCM field that the plastic_property_name refers to. This is the list of available Plastic SCM fields on the extended information panel:
The from attribute describes the field in the Jira issue (jira_field_name) whose value will be read into the field to as described above. The list of available fields for the from attribute in the Jira extension are detailed in this table:
from field value |
Field data type |
|---|---|
| issue.Fields.Assignee.Name | String |
| issue.Fields.AttachmentNames | String[] |
| issue.Fields.ComponentNames | String[] |
| issue.Fields.Created | DateTime |
| issue.Fields.Description | String |
| issue.Fields.DueDate | DateTime |
| issue.Fields.Environment | String |
| issue.Key | String |
| issue.Fields.Priority.Name | String |
| issue.Fields.Project.Name | String |
| issue.Fields.Reporter.Name | String |
| issue.Fields.Resolution | String |
| issue.Fields.Status.Name | String |
| issue.Fields.Summary | String |
| issue.Fields.Issuetype.Name | String |
| issue.Fields.Updated | DateTime |
| issue.Fields.Votes.Number | Long |
It's possible to access the value of custom Jira fields with the customFieldValues modifier, like in this sample mapping:
customFieldValues[10000]->Description
[ ] is the custom field id that can be obtained from Jira as described in the previous sections. Only the custom field id number needs to be provided, in the sample 10000.
The Jira issue tracker extension is able to change the status of the associated issue to a branch / changeset based on a changeset comment.
To do so, you can define your own keyword-status mappings. If the keyword is present on the changeset comment, the issue status will be changed to the defined status.
The format of the mappings is as follows:
KEY-VALUE|KEY-VALUE
For example:
[FIXED]-Ready for QA|[WONTFIX]-Done
The example above says that if your changeset includes in its comment the keyword [FIXED] (with the brackets), the issue status will change to Ready for QA.
This feature works binding issues to both branches and changesets.
Bear in mind that the transition between statuses must be allowed by your Jira workflow.
It is not necessary to have the Plastic SCM custom field ID set for this to work.
Read how to configure the status transition feature on your Windows, Linux, or macOS system.
jira.conf file.
Value parameter with the required pairs KEY-VALUE:
Name=Status transitions;Value=[FIXED]-Ready for QA|[WONTFIX]-Done;Type=Text;IsGlobal=True
If you want to want to use the Plastic SCM Axosoft integration, please follow the steps in this section.
This extension is compatible with Axosoft v14 and higher.
In this chapter, you will learn how to configure the Axosoft integration both in the server and in the client sides.
To set up the Axosoft extension functionality, you will need to provide Plastic SCM the Axosoft server base URL.
Another two configuration parameters needed by the Plastic SCM client to configure the Axosoft integration are the client-id and client-secret parameters. To get these values, first go to the "System Options" option under the "Tools" menu:
In the "System Settings" window, click on the "Axosoft API Settings" tab. Under this view, check the "Enable API" checkbox and click on the "Manage API Keys" button.
In the new window, click on the "Add" button to obtain the two values that will be used to identify and authenticate the Plastic SCM integration with Axosoft. Type an "Application Name", copy the "Client ID" and "Client Secret" values, and click on the "Save" button:
Once your API key is saved, it's time to create a custom field to allow Plastic SCM log all the changes done in every checkin operation related to an Axosoft issue.
To allow this operation, a new custom field must be created in Axosoft. To do this, go to the "Tools" menu and select the "Custom Fields" option under the "Fields" submenu:
Under the "Bugs" tab in the new window, click on the "Add" button and then type Plastic SCM as the new custom field and select the "Large text" type:
Save the new custom field that will be used in the Plastic SCM client configuration in the next section.
For more information about Axosoft server configuration, please refer to the manuals included on the Axosoft installation or to the Axosoft website.
Read how to configure the Axosoft integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Axosoft extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Axosoft extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
ontime.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
ontime.conf file:
WorkingMode parameter to assign of these values:
TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/ontime/ontimeextension.dll" />
</Extensions>
Axosoft Root URL: As explained before on the
Server topic, Plastic SCM Axosoft extension needs this
value to work.
User and Password: Each Plastic SCM user must have an Axosoft account and use the
Axosoft credentials to allow Plastic to connect with the Axosoft server.
Branch prefix: If Plastic SCM is configured to work with the
Task on branch mode, the user will be able to
configure several branch prefixes to bind them to several Axosoft objects. For example, if
the user enables the mapping between Axosoft Defects and Axosoft Tasks, branches whose name starts with
prefix def will be linked to Axosoft Defects, and branches whose name starts with prefix
task will be linked to Axosoft Tasks.
Client ID and Client Secret: These fields must be filled with the tokens generated
from the Axosoft admin panel. See the Server topic for
more info.
Plastic SCM custom field: This parameter is the
custom field created on Axosoft and used for
logging the Plastic SCM check in information.
Pending status list: You can edit the list of statuses considered as "pending" (affecting the
list of tasks displayed on the Create Branch dialog) using this field by entering a comma-separated values
string.
The working mode configured by default is the Task on branch mode, which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
To start working with Plastic SCM and its Axosoft extension, the defects must be created on the issue tracking system. To do that, click on the "Add" menu and select the "Full Add" option, as the image below shows:
On the "Add Bug" window, information such as name of the new task, priority, status, engineer assigned, etc., must be filled. Once the new defect is saved, Axosoft will give it an identification number, which will be used by the assigned developer when creating the Plastic SCM branch to work on that task.
Then, the developer who has been assigned to that issue starts working on it creating a new branch through Plastic SCM GUI client. Note that the name of the new branch must match the configured branch prefix for Plastic SCM Axosoft extension (if it has been defined) followed by the issue number assigned by Axosoft to be linked.
By clicking on the Show extended information button () on the Branches view, the information associated to the branches will be displayed on the GUI's right hand side as the following screenshot shows. When selecting a branch the detailed information of the Axosoft defect will be shown: name, owner, status, title, and description.
By double-clicking on it or by pressing the Open issue in browser button (), a new web browser window with the associated branch task is opened, and it'll display the full information of the Axosoft task. When the user changes the status or any other field of the issue, the new information will be shown by clicking on the Refresh button of the Axosoft Extension.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Axosoft extension and select the Bind issues to Plastic changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changesets have been linked to the Axosoft defect or task, the extension information () will be shown on the Changesets view. Users can also add new tasks or delete previous ones through the Axosoft extension pane; and by double-clicking on each issue or by clicking the Open issue in browser button (), a web browser window with the associated Axosoft issue will be opened. Whenever a user modifies an issue in the task tracking tool, the new data will be updated on Plastic GUI by pressing the Refresh button on the Axosoft Extension pane.
Apart from showing information on the issues associated to the branches and changesets integrated with Plastic SCM, this extension logs in Axosoft every check in done with associated issues.
So users can see how each check in operation has been registered on the Axosoft task:
This section describes the steps to use the VersionOne integration with Plastic SCM.
This extension is compatible with VersionOne version 7.2 and following ones.
In this chapter, you will learn how to configure the VersionOne integration both in the server and in the client sides.
It is not necessary to make any changes at the server-side for the Plastic SCM VersionOne extension configuration.
Read how to configure the VersionOne integration on your Windows, Linux, or macOS system.
To configure the VersionOne extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the VersionOne extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
versionone.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
versionone.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/versionone/versiononeextension.dll" />
</Extensions>
Base URL: Specifies the URL where the VersionOne server is installed and running.
User and Password: These fields must be filled with a valid VersionOne user if the
Use integrated authentication option is not selected.
Defect prefix, Task prefix, Test prefix, Story prefix: The
available VersionOne objects to be linked are Defects, Tasks, Tests, and Stories.
Use integrated authentication: This option tells Plastic SCM whether the authentication will be
resolved with Windows domain users or not.
The working mode by default is Task on branch, used for the "branch per task" pattern, on which for each task a new branch will be created.
To start working with Plastic SCM and its VersionOne extension, the first step is create the tasks in VersionOne. This would be usually done by the Project Manager, by clicking on the "Add Defect", "Add Issue", "Add backlog Item" and "Add Request" shortcuts on the VersionOne web interface. A new dialog window will be opened to enter the data of the new task. VersionOne assigns numbers to tasks starting on 1000 and up. This is very important to remark, because branch names have to contain the configured prefix for that type of task and the assigned number by VersionOne.
Once the issue is created, VersionOne assigns it a number. In the following figure, we can see a list of items created:
Then, the developer assigned to a task starts working on it. They must create a new branch (as simple as right clicking on the parent branch and select the Create child branch option), as the following image shows, and, in order to link it to the task in VersionOne, the branch must be given the same number (remember: this number always would be upper than 1000):
Now the user can check the information of the issues just by going to the extended information () on the branch view and selecting the branch. Then, a new pane displays on the right-side of the view from which the VersionOne extension information is shown: task number, owner, status, etc.
Performing a double click on the task associated with a branch or clicking on the Open issue in browser button (), a new web browser window opens. When a user changes the status or any other field of the issue, the new information will appear by refreshing VersionOne extension.
To configure Plastic SCM to work on the Task on changeset working mode, the user must configure the VersionOne extension and select the Bind issues to Plastic Changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset have been linked to VersionOne tasks, the extension information () appears on the Changesets view. From the VersionOne extension information, the users can also add new tasks or delete previous ones. And by double-clicking on each of the issues associated to a certain changeset or by clicking on the Open issue in browser button (), a browser with VersionOne opens. Whenever a user modifies an issue in VersionOne by refreshing the VersionOne Extension information, it will be shown in Plastic SCM.
This section describes the steps to follow in order to use FogBugz integration with Plastic SCM.
This extension is compatible with FogBugz version 7.2 and following.
Learn how to configure the FogBugz integration both in the server and in the client sides.
It is not necessary to make any changes on the server side for Plastic SCM FogBugz extension.
Read how to configure the FogBugz integration on your Windows, Linux, or macOS system.
Follow these steps to configure the FogBugz extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the FogBugz extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
fogbugz.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
fogbugz.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/fogbugz/fogbugzextension.dll" />
</Extensions>
FogBugz URL: Specifies the URL where the FogBugz server is installed and running.
User name and Password: These fields must be filled with a valid FogBugz user.
Branch prefix: If you are going to work on the
Task on branch mode, specifying a
Branch prefix is recommended (but not mandatory). This branch prefix will be used to bind the Plastic
branches to the FogBugz tasks.
Enable checkin log: This option allows FogBugz to
record all the check in operations executed in Plastic SCM.
The working mode configured by default is Task on branch, used for the "branch per task" pattern, on which for each task a new branch will be created.
To start working with Plastic SCM and its FogBugz extension, the tasks must be created on your project on FogBugz. This would be usually done by the Project Manager, by clicking on the "New Case" option. A new dialog window will be opened to type the data of the new task.
Once the issue is created, FogBugz assigns it a number. Then the developer assigned to that task starts working on it. They will created a new branch (as simple as right clicking on the parent branch and select the Create child branch option), as the image below shows. In order to link the branch to the task in FogBugz, the branch name must match the configured branch prefix (if it has been defined) and the same task number.
Now the user can check the information of the issues just by going to the extended information () on the Branches view and selecting the branch. A new pane displays on the right side of the view from which the FogBugz extension information is shown: task number, owner, etc.
By double-clicking on it or by clicking on the Open issue in browser button (), a new web browser window opens. It will display the full information of the FogBugz task. When the user changes the status or any other field of the issue, the new information will be shown by clicking on Refresh button of the FogBugz Extension.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the FogBugz extension and select the Bind issues to Plastic Changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changesets have been linked to the issue or task in FogBugz, the extension information () will be shown on the Changesets view. From the FogBugz extension information users can also add new tasks or delete previous ones. And by double-clicking on each of the issues associated to a certain changeset or by clicking on the Open issue in browser button (), a browser with FogBugz will be opened. Whenever a user modifies an issue in FogBugz, by refreshing the FogBugz Extension information, it will be shown in Plastic.
Besides showing information on the issues associated to the branches and changesets integrated with Plastic SCM, this extension logs in FogBugz every check in done with associated issues only if the Enable checkin log checkbox has been marked on the Client section.
So users can see how each check in operation has been registered on the FogBugz task by clicking on the "Checkins - Click to list" link:
This section describes the steps to follow in order to use the Plastic SCM Rally Software Development integration.
In this chapter, you will learn how to configure the Rally integration both in the server and in the client sides.
To setup the Rally extension functionality, a valid Rally account is needed. There is neither to be done on the server side nor local setup because Rally is a Web based service, all the actions against Rally are done via Internet.
Read how to configure the Rally integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Rally extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Rally extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
rally.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
rally.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/rally/rally.dll" />
</Extensions>
Rally URL: Specifies the URL where the Rally server is running.
User name and Password: These fields must be filled with a valid
Rally user for the configured Rally Server.
Task prefix, Defect prefix, Test case prefix, and
User story prefix: These are the available Rally objects to be linked to Plastic SCM.
In order to use this working mode, the first step would be setting it up on Plastic SCM Rally extension, following the indications from the previous section, or leaving the configuration by default which applies to this mode.
To start working with Plastic SCM and its Rally extension the objects on Rally must be created.
Defects can be created through its own tab by clicking on the "New defect" action. The same for the rest of the Rally objects, such as "Tasks", "Test Cases" and "User Stories".
On the "Create Defect" window, information such as name of the new task, priority, state, etc must be included. Once the new defect is saved, Rally will give it an identification string, which will be later used by the assigned developer when creating the Plastic branch to work on that task. The prefix ID will depend on the object type. For instance if user creates a new task, the ID could be TA4 or DE4 in case of a defect.
By clicking on the Show extended information button (), the information associated to the branches will be displayed on the GUI's right hand side as the following screenshot shows. Selecting a branch the detailed information of the Rally object will be shown:
By double-clicking on it or by clicking on the Open issue in browser button (), a web browser window with the associated branch task is opened. Whenever the user finishes the task and changes its status or any other field, in order to view the new values, the user will only have to refresh it on the Plastic branch extended information.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Rally extension and select the Bind issues to Plastic Changesets option, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
Once the changeset has been linked to the Rally object, its information will be shown from the Changesets view, and users can also add new links to Rally objects or delete previous ones. And by double-clicking on each issue or by clicking on the Open issue in browser button (), a web browser window with the associated object in Rally will be opened. Whenever a user modifies a defect, task, test case or user story from the issue tracking tool, their changes will be loaded by clicking the Refresh button of Rally Extension.
This section describes the steps to follow in order to use the Plastic SCM Polarion Software Development integration.
Learn how to configure the Polarion integration both in the server and in the client sides.
To setup the Polarion extension functionality some tasks have been performed:
com.codicesoftware.platform.repository.external.plasticscm
from the client/polarion folder at the Plastic SCM installation directory to the
Polarion extensions folder at [Polarion installation]/polarion/extensions.
client folder can be copied on it. In this case a valid client.conf must be in this client folder where the cm executable is.
Read how to configure the Polarion integration on your Windows, Linux, or macOS system.
Follow these steps to configure the Polarion extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the Polarion extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
polarion.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
polarion.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/polarion/polarionextension.dll" />
</Extensions>
Polarion Base URL: Specifies the URL where the Polarion server is installed and running.
User name and Password: These fields must be filled with a valid Polarion user.
Branch prefix: If you are going to work on the
Task on branch mode, specifying this
parameter is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the
Polarion tasks.
Work Item Statuses: These are the work item types that will be displayed on the "Pending tasks" list
when a new branch is created using the
From task mode. These values will be checked
too when linking new revisions using the
Task on changeset mode.
Open Work Item Status: This is the new status that the Polarion task will have if the user creates a
new branch using the From task mode and also
checks the Mark as open in issue tracker option.
Repository ID: This parameter is the same "ID"
field configured in the Polarion server side.
Default Repository: This field indicates if the selected repository is the default one. If you don't
select it, then you will have support for multiple repositories.
The working mode configured by default is the Task on branch mode, which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
In order to start working with Plastic SCM and Polarion extension, the tasks must be created on the issue tracking system by creating a new work item associated to a Polarion project:
Type the data related to the new task, such as name, description, priority... and click on the "Create" button:
Polarion will assign a number to the newly created task, which will be the same number given to the Plastic branch when working on that task:
Then the developer who has been assigned to that issue starts working on it. He will create a new branch using the Plastic SCM GUI client. There are two options to create a new branch linked to Polarion:
In this mode the user will:
as you've seen in the Client configuration section.
By clicking on the Show extended information button () in the Branches view the information associated to the branches will be displayed on the right panel of the Plastic GUI. By selecting a branch the Polarion issue information is displayed in Plastic SCM:
By double-clicking on it or by pressing the Open issue in browser button () a new browser window is opened showing the associated branch issue and will display the full information of the Polarion task.
If the user changes any value of the work item in Polarion then the new information will be shown in Plastic by clicking on Refresh button of the Polarion Extension panel.
To configure Plastic SCM to work on the Task on changeset working mode, the user has to configure the Polarion extension and select the Bind issues to Plastic changesets option, as explained before on the Client configuration section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - macOS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - macOS - Add issue
In the following example, two Polarion work items are linked to the change that is going to be checked in:
The Polarion extension will check the status of the work item to be linked. Only the Polarion work items whose status is defined in the Work item statuses field in the client configuration will be allowed to be linked. As you've seen before the work item statuses configured are draft and open. So any other status won't be allowed:
Once the changeset has been linked to the work items in Polarion, the information can be displayed in the Plastic SCM Changesets view. When the Extended information panel () is visible, by clicking in a changeset shows the associated Polarion work items.
The users can also add new tasks or delete previous ones from the Polarion Extension information. Besides, by double clicking on each of the issues associated to a certain changeset, a new browser window will be opened showing the Polarion selected work item. Whenever a user modifies an issue in the task tracking tool, the new data will be updated on Plastic GUI by pressing the Refresh button on the Polarion Extension pane.
The Plastic SCM Polarion integration supports distributed scenarios: the linked revisions will use the changeset GUID instead of the changeset ID (integer number).
However, the changeset info (such as changeset comment) won't be available until the changeset is replicated to the configured Plastic SCM server in Polarion.
As you've seen you are able to get in Plastic all the Polarion work items information through their related branches or changesets. And you can also get in the Polarion side all the information related to the revisions created in Plastic. This way the Polarion integration keeps a record of the modified items: When changes have been checked-in in Plastic and the integration is active, Polarion will display the affected items in the "Linked revisions" section, using either the Task on branch mode:
or the Task on changeset working mode:
When the Plastic revision is correctly linked to Polarion you'll see that the icon revision includes a green bullet: 
If you want to want to use the Plastic SCM codeBeamer integration, please follow the steps in this section.
Learn how to configure the codeBeamer integration both in the server and in the client sides.
It is not necessary to make any changes at the server-side for the Plastic SCM codeBeamer extension configuration.
But if you want to add a secret token of the webhook to codeBeamer configuration, please follow these steps:
"scc" node if it doesn't exist in your json (json root level).
"plasticscm" node if it doesn't exist in your json under "scc" node.
"secretToken" : "<secret_token_of_the_webhook>" under "plasticscm"
node.
Read how to configure the codeBeamer integration on your Windows, Linux, or macOS system.
Follow these steps to configure the codeBeamer extension on the Plastic SCM client on your Windows machine:
plastic-global-config repository.
Repositories.
You can configure the codeBeamer extension on the Plastic SCM client on your Linux or macOS machine by using one of these methods:
issuetrackers/server_port/repository under
$HOME/.plastic4, where repository is one of the following values:
allrepos, which means that all of your repositories will be linked to the issue tracker.
codebeamer.conf example configuration file into the new created path.
plasticscm_install_path/client/extensions/config_samples
/Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples
Then, you'll have, for example, something like this:
codebeamer.conf file:
WorkingMode
parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
client.conf file to add the following key:
<Extensions>
<Extension AssemblyFile="plasticscm_install_path/client/extensions/codebeamer/codebeamerextension.dll" />
</Extensions>
codeBeamer URL: Specifies the URL where the codeBeamer server is installed and running.
User name and Password: These fields must be filled with a valid codeBeamer user.
Branch prefix: If you are going to work on the
Task on branch
mode, specifying this parameter is recommended (but not mandatory). This branch prefix will be used to bind the
Plastic branches to the codeBeamer tasks.
Enable SCM log: Enable this checkbox if your codeBeamer version supports External SCM integrations.
Secret token: Enter the secret token value if it's configured in your
codeBeamer server.
The working mode configured by default is the Task on branch mode, which works fine with the "branch per task" pattern. On this working mode, for each task to be done a new branch will be created.
To start working with Plastic SCM and its codeBeamer extension, the tasks must be created on your project on codeBeamer:
Once the new task is saved, codeBeamer gives this task an identification number. This number will be used by the assigned developer when creating the Plastic SCM branch to work on that task:
Then, the developer assigned to that task starts working on it. They will create a new branch using the Plastic SCM GUI client. There are two options for creating a new branch linked to codeBeamer:
Plastic SCM - Windows - Creating a new branch "manually"
Plastic SCM - Linux - Creating a new branch "manually"
Plastic SCM - mac OS - Creating a new branch "manually"
Plastic SCM - Windows - Creating a new branch "from task"
Plastic SCM - Linux - Creating a new branch "from task"
Plastic SCM - mac OS - Creating a new branch "from task"
By clicking the Show extended information button (
) in the Branches view, the information associated to the branches displays on the right panel of
the Plastic GUI. By selecting a Plastic branch, the codeBeamer task information displays:
By double-clicking the task or by pressing the Open issue in browser button (
), a new web browser window opens showing the full information of the related codeBeamer task. When the user
changes any field of the task, the new information will be shown by clicking the
Refresh button of codeBeamer Extension panel.
To configure Plastic SCM to work on the Task on changeset working mode, the user must select the Bind issues to Plastic changesets option when configuring the codeBeamer extension, as explained before on the Client section.
The workflow will resemble something like this:
Plastic SCM - Windows - Checkin dialog and Add new issue option
Plastic SCM - Linux - Checkin dialog and Add new issue option
Plastic SCM - mac OS - Checkin dialog and Add new issue option
Plastic SCM - Windows - Add issue
Plastic SCM - Linux - Add issue
Plastic SCM - mac OS - Add issue
Once the changeset is linked to the task(s) in codeBeamer, this information can be displayed in the Plastic SCM
Changesets view. When the Extended information panel is visible (
), if you click a changeset then Plastic shows the associated codeBeamer tasks:
The users can also add new tasks or delete previous ones from the codeBeamer Extension pane. Besides, by
double-clicking each task associated to a certain changeset or by clicking the
Open issue in browser button (
), a new web browser window opens and shows the selected codeBeamer task. Whenever a user modifies a task in
codeBeamer, the new data will be updated on Plastic GUI by pressing the Refresh button on
the codeBeamer Extension pane.
Besides showing information about the issues associated to the branches and the changesets integrated with Plastic SCM, this extension logs in codeBeamer every checkin linked to the issues.
Enable SCM log parameter
as FALSE when configuring the codeBeamer extension on the
Client side.
This way, you can see how each checkin operation is registered on codeBeamer:
It's possible to set a global configuration in the server so that all clients have the same settings by default. This is useful to set default global parameters like connection strings and let the users specify their particular credentials.
Once the global configuration is created at the server side, the server configuration will be downloaded at the client side when the Plastic GUI starts.
To set up the global configuration in the server, create a repository named plastic-global-config. This repository will have a well defined structure with the configuration file(s) for the issue tracker extension(s) that will be applied to the repositories and used by the Plastic users.
The plastic-global-config repository will have the following structure:
/repname/issuetrackers/extension_configuration_file.conf.
/allrepos/issuetrackers/extension_configuration_file.conf.
/myrepo-mysubrepo/issuetrackers/extension_configuration_file.conf
The plastic-global-config repository can be configured with more than one issue tracking systems. The Plastic client will load first the specific configuration for the repository the user is working on. If the specific configuration doesn't exist, then the allrepos configuration will be loaded.
To set up the global extension configuration, the first step is to create the plastic-global-config repository in the server (if it doesn't exist yet because it was created to set up the global file configuration):
Then, the repository must have the needed structure as you've seen previously. In the following example the repository vb44 will be linked to Bugzilla and the rest of the repositories will be linked to Jira:
Plastic SCM GUI - Windows - Example plastic-global-config
Plastic SCM GUI - Linux - Example plastic-global-config
Plastic SCM GUI - macOS - Example plastic-global-config
plasticscm_install_path/client/extensions/config_samples folder. You must include and update the parameters you need.
When the client GUI starts, each server configuration is downloaded in a hidden workspace which will be created automatically in the user local directory (in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows)). For example: C:\Users\user\AppData\Local\plastic4\globalconfig\server_port.
If needed, the issue tracker configuration can be customized with the credentials that every client use. This way, when a user opens the Issue Tracking tab in the Preferences dialog of the Plastic SCM client, those common and global values will be loaded automatically for the linked issue tracker and the user only has to enter the credentials information to be correctly logged in the issue tracking system.
These user credentials will be saved in the user local directory (in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows)). For example: C:\Users\user\AppData\Local\plastic4\issuetrackers\server_port\repname\extension_configuration_file.conf
Plastic SCM includes some "out of the box" issue tracker integration extensions that you can use to connect with the most popular issue tracking and project management systems.
These "out of the box" extensions enable Plastic SCM to display information about the tasks linked to a branch (recommended), or a changeset in the Branch Explorer, the Changesets view or the Branches view. This way, if you implement a branch per task pattern or link individual changesets to tasks, you will always have relevant information from your issue tracker immediately available.
The reason that we have created a way to develop custom "extensions" is because providing integrations with all ALM, issue trackers and build systems that exist in the market would be an impossible task. We've designed a common issue tracker connection interface, so you can write your own custom extension for Plastic SCM!
In order to write your own custom extension for Plastic SCM, you will need to install Visual Studio and our Plastic SCM client on your machine. There are only one library you'll need to build your issue tracker extension: issuetrackerinterface.dll. If you wish to add logging capabilities, you can take advantage of log4net.dll, used by Plastic SCM.
To create a new extension, you must first create a Class Library project in Visual Studio and add the issuetrackerinterface.dll reference (and log4net.dll if you wish).
In addition to the Class Library project in Visual Studio, you'll need to implement two different interfaces:
IPlasticIssueTrackerExtension: Definition of all issue tracker connection capabilities for Plastic SCM.IPlasticIssueTrackerExtensionFactory: Manages the issue tracker extension configuration and creation.
Once the Class Library and files are set up, you are now ready to start using Plastic SCM. First of all, add a new class called SampleExtension. Additionally, change the namespace to place your class to Codice.Client.IssueTracker.SampleExtension:
namespace Codice.Client.IssueTracker.SampleExtension
{
public class SampleExtension : IPlasticIssueTrackerExtension
{
}
}
First of all, we need to store the extension configuration. We'll do this through the class constructor. We'll set its visibility to internal since only its Factory needs to know how to create this kind of objects.
public class SampleExtension : IPlasticIssueTrackerExtension
{
IssueTrackerConfiguration mConfig;
// If you want logging, this is the way to declare it
// Don't forget to set log4net.dll as a reference!
static readonly ILog mLog = LogManager.GetLogger("sampleextension");
Internal SampleExtension(IssueTrackerConfiguration config)
{
mConfig = config;
mLog.Info("Sample issue tracker is initialized");
}
}
Now that we have defined how to create our issue tracker extension class, we can build its factory. To do this, add a new SampleExtensionFactory class which implements the IPlasticIssueTrackerExtension interface. You'll probably want to add all needed methods using the Visual Studio refactor option; just right-click the interface reference and select Refactor > Implement interface. This will add a stub for each interface method. It'll start like this:
namespace Codice.Client.IssueTracker.SampleExtension
{
public class SampleExtensionFactory : IPlasticIssueTrackerExtensionFactory
{
public IssueTrackerConfiguration GetConfiguration(
IssueTrackerConfiguration storedConfiguration)
{
throw new NotImplementedException();
}
public IPlasticIssueTrackerExtension GetIssueTrackerExtension(
IssueTrackerConfiguration configuration)
{
throw new NotImplementedException();
}
public string GetIssueTrackerName()
{
throw new NotImplementedException();
}
}
}
The last two methods are easy to implement:
public IPlasticIssueTrackerExtension GetIssueTrackerExtension(
IssueTrackerConfiguration configuration)
{
return new SampleExtension(configuration);
}
public string GetIssueTrackerName()
{
return "Sample Issue Tracker";
}
They return a working issue tracker extension from a valid configuration and the issue tracker name, respectively. However, the first one is a little bit complex: It receives an issue tracker configuration and returns a valid one. We need then to define our required parameters and the default values for them.
The IssueTrackerConfiguration class is quite simple: it stores an enumerate ExtensionWorkingMode field and a list of IssueTrackerConfigurationParameter.
The working mode accepts two values:
The configuration parameters will be listed in the Issue tracker tab on the Plastic SCM Preferences dialog. See the Configuring the extension section below for further info.
We'll define the following parameters:
Each parameter contains 4 attributes:
name - The name of the parameter. It's a string class attribute.
value - The value fo the parameter. It's a string class attribute.
type- The type of the parameter. This is defined by the IssueTrackerConfigurationParameterType
enumerate type, and describes what the parameter contains:
Except for Host, User, and Password, any number of parameters set to the same type can be defined. The configuration panel will disable all BranchPrefix entries when the extension worked mode is switched to TaskOnChangeset.
IsGlobal - Related to the global configuration,
lets you configure your extension globally or locally at the same time. The value of the parameters existing both
in a global and local configuration depends on the IsGlobal value:
This is useful because you can define global parameters that everybody must use (for example, host, branch prefix, or project key), and local parameters that are the ones of the user (for example, user and password).
For example:
Name=Host;Value=http://localhost:8080;Type=Host;IsGlobal=True Name=User name;Value=tester;Type=User;IsGlobal=False Name=Password;Value=tester;Type=Password;IsGlobal=False Name=Branch prefix;Value=scm;Type=BranchPrefix;IsGlobal=True
Finally, this is how our GetConfiguration method will look like:
public IssueTrackerConfiguration GetConfiguration(
IssueTrackerConfiguration storedConfiguration)
{
List<IssueTrackerConfigurationParameter> parameters
= new List<IssueTrackerConfigurationParameter>();
ExtensionWorkingMode workingMode = GetWorkingMode(storedConfiguration);
string user = GetValidParameterValue(
storedConfiguration, SampleExtension.USER_KEY, "1");
string prefix = GetValidParameterValue(
storedConfiguration, SampleExtension.BRANCH_PREFIX_KEY, "sample");
IssueTrackerConfigurationParameter userIdParam =
new IssueTrackerConfigurationParameter()
{
Name = SampleExtension.USER_KEY,
Value = GetValidParameterValue(
storedConfiguration, SampleExtension.USER_KEY, "1"),
Type = IssueTrackerConfigurationParameterType.User,
IsGlobal = false
};
IssueTrackerConfigurationParameter branchPrefixParam =
new IssueTrackerConfigurationParameter()
{
Name = SampleExtension.BRANCH_PREFIX_KEY,
Value = GetValidParameterValue(
storedConfiguration, SampleExtension.BRANCH_PREFIX_KEY, "scm"),
Type = IssueTrackerConfigurationParameterType.BranchPrefix,
IsGlobal = true
};
parameters.Add(userIdParam);
parameters.Add(branchPrefixParam);
return new IssueTrackerConfiguration(workingMode, parameters);
}
ExtensionWorkingMode GetWorkingMode(IssueTrackerConfiguration config)
{
if (config == null)
return ExtensionWorkingMode.TaskOnBranch;
if (config.WorkingMode == ExtensionWorkingMode.None)
return ExtensionWorkingMode.TaskOnBranch;
return config.WorkingMode;
}
string GetValidParameterValue(
IssueTrackerConfiguration config, string paramName, string defaultValue)
{
string configValue = (config != null) ? config.GetValue(paramName) : null;
if (string.IsNullOrEmpty(configValue))
return defaultValue;
return configValue;
}
We have finished our factory! Let's go back to the Extension class.
The next step is to implement all interface methods. Use the Visual Studio refactor to add all interface methods:
public class SampleExtension : IPlasticIssueTrackerExtension
{
public void Connect()
{
throw new NotImplementedException();
}
public void Disconnect()
{
throw new NotImplementedException();
}
public string GetExtensionName()
{
throw new NotImplementedException();
}
public List<PlasticTask> GetPendingTasks(string assignee)
{
throw new NotImplementedException();
}
public List<PlasticTask> GetPendingTasks()
{
throw new NotImplementedException();
}
public PlasticTask GetTaskForBranch(string fullBranchName)
{
throw new NotImplementedException();
}
public Dictionary<string, PlasticTask> GetTasksForBranches(List<string> fullBranchNames)
{
throw new NotImplementedException();
}
public List<PlasticTask> LoadTasks(List<string> taskIds)
{
throw new NotImplementedException();
}
public void LogCheckinResult(PlasticChangeset changeset, List<PlasticTask> tasks)
{
throw new NotImplementedException();
}
public void MarkTaskAsOpen(string taskId, string assignee)
{
throw new NotImplementedException();
}
public void OpenTaskExternally(string taskId)
{
throw new NotImplementedException();
}
public bool TestConnection(IssueTrackerConfiguration configuration)
{
throw new NotImplementedException();
}
public void UpdateLinkedTasksToChangeset(PlasticChangeset changeset, List<string> tasks)
{
throw new NotImplementedException();
}
}
Of course, you don't need to implement all methods. If there is some functionality you don't need or don't want to provide, just leave the method body empty or return a default value. If the return type is a collection type, we recommend you to return an empty collection instead of a null object.
This is a brief description of each method:
ConnectDisconnectConnect, it will contain code to release any resources needed to connect to your target issue tracker (sessions, etc.)GetExtensionNameGetPendingTasksGetTaskForBranchGetTasksForBranchesLoadTasksLogCheckinResultMarkTaskAsOpenOpenTaskExternallyTestConnectionUpdateLinkedTasksToChangesetTo illustrate some of these methods, we'll see some sample implementations. The task contents will be retrieved from a sample lorem ipsum web service at https://jsonplaceholder.typicode.com.
OK, this one is really silly. We just need to return the name we Plastic to display on its views.
public string GetExtensionName()
{
return "My awesome extension";
}
When the issue tracker extension is configured to work in a TaskOnBranch mode, this method is used by the Branch Explorer to map the drawn branches to their associated tasks. And since we love our code clean, we've broken down this functionality into several methods to ensure its readability!
public Dictionary<string, PlasticTask> GetTasksForBranches(
List<string> fullBranchNames)
{
Dictionary<string, PlasticTask> result =
new Dictionary<string, PlasticTask>();
foreach(string fullBranchName in fullBranchNames)
{
string taskId = GetTaskIdFromBranchName(
GetBranchName(fullBranchName));
result.Add(fullBranchName, LoadSingleTask(taskId));
}
return result;
}
string GetBranchName(string fullBranchName)
{
int lastSeparatorIndex = fullBranchName.LastIndexOf('/');
if (lastSeparatorIndex < 0 )
return fullBranchName;
if (lastSeparatorIndex == fullBranchName.Length - 1)
return string.Empty;
return fullBranchName.Substring(lastSeparatorIndex + 1);
}
string GetTaskIdFromBranchName(string branchName)
{
string prefix = mConfig.GetValue(BRANCH_PREFIX_KEY);
if (string.IsNullOrEmpty(prefix))
return branchName;
if (!branchName.StartsWith(branchName) || branchName == prefix)
return string.Empty;
return branchName.Substring(prefix.Length);
}
const string POST_URL = "https://jsonplaceholder.typicode.com/posts/{0}";
PlasticTask LoadSingleTask(string taskId)
{
if (string.IsNullOrEmpty(taskId))
return null;
string uri = string.Format(POST_URL, taskId);
string resultJson = PerformJsonRequest(uri);
return BuildTaskFromJson(
JsonConvert.DeserializeObject<MyServiceData>(resultJson));
}
string PerformJsonRequest(string targetUri)
{
HttpWebRequest req = (HttpWebRequest)WebRequest.Create(targetUri);
try
{
using (HttpWebResponse resp = (HttpWebResponse)req.GetResponse())
using (StreamReader reader = new StreamReader(resp.GetResponseStream()))
{
return reader.ReadToEnd();
}
}
catch(Exception e)
{
mLog.ErrorFormat(
"Unable to perform request on URI {0}: {1}", targetUri, e.Message);
mLog.DebugFormat(
"Stack trace:{0}{1}", Environment.NewLine, e.StackTrace);
return string.Empty;
}
}
PlasticTask BuildTaskFromJson(MyServiceData jsonData)
{
if (jsonData == null)
return null;
return new PlasticTask()
{
Id = jsonData.Id.ToString(),
Owner = jsonData.UserId.ToString(),
Title = jsonData.Title,
Description = jsonData.Body,
Status = "working"
};
}
You'll notice that this method receives a list of full branch names (i.e. the name contains their whole hierarchy). For each one of them, the method extracts the task ID and performs a query against the jsonplaceholder service.
JsonPlaceholder is the "lorem ipsum" generator equivalent to REST services. You can pass a numeric value and it will return a JSON object with some sample fields. Querying the URL without a number will return a list of objects. You will find more detailed information at https://jsonplaceholder.typicode.com .
Once the JSON response is received, you can use your favorite JSON parser to deserialize it into a valid object instance. In the previous example we've used Newtonsoft.Json.
The last step is to build a PlasticTask instance and set its fields using the values returned by the REST service. When every branch name has been process, the method returns the mapping as a Dictionary<string, PlasticTask> class.
The OpenTask method is used when you need to access the original source of information. For instance, you may have a website or third-party application that contains information you need; in these situations, the Plastic issue tracker extension can show this data for you using the OpenTask method.
public void OpenTaskExternally(string taskId)
{
Process.Start(string.Format(
"https://www.google.es/search?q={0}", taskId));
}
Our sample implementation is very simple: we build a URI to search the task number on Google and we use the System.Diagnostics.Process class to open it with the default browser.
The OpenTask method is useful when you need to establish a tight integration between Plastic SCM and your issue tracker.
Referring to the previous GetTasksForBranches code samples, when you select a branch starting with the sample prefix on the Plastic SCM Branches view you will see detailed information on the right panel:
As you can see, the right panel displays the PlasticTask properties information retrieved by the GetTasksForBranches method.
If you configure your extension to use the TaskOnChangeset working mode, then you will see three buttons displayed on the right panel:
The first button will open the task information in a browser, as we saw before on the OpenTask method.
The second button will link a task to the selected changeset. Once clicked, a dialog will be displayed to select the task to be linked.
The Open issue button on this dialog is equivalent to the one we discussed just before. You can link as many issues as you want to a given changeset:
The third button removes a selected issue linked to the currently selected changeset.
While the TaskOnBranch mode is an automated mechanism which uses the branch name and a prefix to automatically link issues to branches, the TaskOnChangeset mode allows us to manually associate the issue information to individual changesets. Besides the action buttons on the Changesets view we just saw, you can also add this kind of links at checkin time using the Checkin information dialog:
Our latest key feature regarding issue tracker is creating new branches from a given issue. Whenever an issue tracker extension is properly configured, the Create Branch dialog will automatically display a new set of controls, called the From Task mode.
The main control is a pending task list, populated with the results returned by the GetPendingTasks method. Only those tasks assigned to the current user (set in the configuration panel) are displayed by default. Checking the Display pending tasks from all users control will override this constraint, as the checkbox title says. The Branch name and Comment are automatically set, but the latter can be modified.
Finally, checking the Mark as open in issue tracker will execute the MarkTaskAsOpen method after a successful branch creation. It should set the state of the selected issue to Open, In Progress or the equivalent for the current issue tracker.
Every time you write class libraries, the question arises: which is the best way to easily debug my code? Regarding the Plastic SCM Extensions, the solution is quite clear: just modify the class library properties in the build section to deploy the .dll and .pdb output files directly into the Plastic SCM client directory:
Once you set the output path, you can also configure Visual Studio to launch the Plastic SCM client and automatically attach the debugger to the resulting plastic.exe process. This way, when Plastic interacts with your custom extension code the breakpoints you set will be automatically trigerred.
Program Files.
To make Plastic able to see your custom extension, we'll need to edit the customextensions.conf file inside the Plastic SCM client folder.
# Each line defines a Plastic SCM extension with a name and a relative dll # path from client installation directory # i.e: # My Custom Extension=extensions/mycustomextension/mycustomextension.dll Sample Extension=SampleExtension.dll
After this configuration step, you may open the Preferences dialog and open the Issue tracking tab. We'll find our extension listed in the dropdown list there. When selected, the main panel will display the necessary controls to configure your extension:
By clicking the Apply or OK button, Plastic will be able to work with our brand new extension.
Custom issue tracker extensions allow you to integrate any issue tracker with Plastic SCM. A corporate intranet, the in-house developed issue tracking system... The possibilities are endless.
The ability to develop your own code to connect with your own systems and the simplicity of integrating it all with the Plastic SCM client; all of it provides an awesome opportunity for you to customize your SCM experience with Plastic SCM.
If you like what you see and you'd like to have the full sources for this sample extension, you can check our GitHub repository.
IsGlobal attribute is fully described in the
Creating a new extension
section.
Use LDAP credentials if available, Use default proxy credentials and Issue types.Pending status list - You can now configure the Axosoft list of statuses considered as "pending".Default Repository parameter to get support for multiple repositories for Polarion.Custom Field ID parameter is optional.Issue query limit - You can now configure the maximum number of returned results in the Create Branch dialog.Resolved issue states - You can now define a list of status names to be considered as "resolved".