Task and issue tracking systems guide


Introduction

This guide describes how Plastic SCM provides integration with diverse control tracking tools such as Bugzilla, Mantis, Trac, JIRA, OnTime, VersionOne, FogBugZ and Rally.

Using this guide, you'll 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 Plastic GUI.

Plastic SCM extensions allow two different working modes:

  • Task on branch - Which links one task from the issue tracking system to a Plastic branch and allows to browse the associated issue on the issue tracking tool -where the full information is displayed-.
  • Task on changeset - In this case one or more tasks are linked to one or more changesets, and the information of the associated tasks are available from Plastic changeset view.

Bugzilla Integration

This section describes the steps to follow in order to use Bugzilla integration with Plastic SCM. It also describes its advantages.


Bugzilla - Configuration

Server

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:

  • Linux:
    #!/usr/bin/perl -wT
  • Windows:
    #!c:\perl\bin\perl.exe -wT

Client

To configure the Bugzilla 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 Bugzilla.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (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 Bugzilla tasks. As the image shows, all branches whose name starts with prefix scm will be linked to Bugzilla issues. For instance: branch with name scm012 will be associated to Bugzilla task #12.
  • To work on Task on changeset mode select the Bind issues to Plastic changesets radio button.
  • The Bugzilla Base URL parameter specifies the URL where the Bugzilla server is installed and running.

Issue tracking configuration: Bugzilla


Bugzilla - Characteristics

Task on branch working mode

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 (Show extended information) 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.

Branches extended information

By double clicking on the task pane or by clicking on the Open issue in browser button (Open issue in browser), a new browser window will be opened and will display the full information of the task in Bugzilla:

Bugzilla web interface example

Enforcing task existence

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:

  • Using the command line run the following command: cm makeattribute plastic-enforce-task-branch
  • Using the Attributes view in the Plastic SCM GUI:

    Plastic enforce Bugzilla task existence

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:

Trying to create a branch without its corresponding task

Task on changeset working mode

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:

  • Issues are created in Bugzilla. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Bugzilla tasks can be linked with this new changeset.

Checkin dialog when the 'Task on changeset' mode is configured

The Add new issue option will show another dialog window. On this new dialog, as the image below shows, the user is able to choose the task to be linked to the changeset:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

By clicking on the Show extended information button (Show extended information) in the Changesets view, a right pane will show information of the associated Bugzilla tasks. From this view, new tasks can be linked or unlinked to a certain changeset. And by double clicking on the task or by pressing the Open issue in browser button (Open issue in browser), a browser window will be opened displaying the full information of the task.

Changesets view, with detailed information when working in 'Task on changeset' mode


Mantis integration

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.


Mantis - Configuration

Server

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.

Client

To configure the Mantis 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 Mantis.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (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 Mantis tasks. As the image shows, all branches whose name starts with prefix scm will be linked to the Mantis issues.
    For instance: branch with name scm022 will be associated to the Mantis task #22.
  • To work on Task on Changeset mode select the Bind issues to Plastic changesets radio button.
  • The Mantis Base URL parameter specifies the URL where the Mantis server is installed and running.
  • UTF-8 is the default Encoding and will work for most languages. Edit this value in case you need to change the enconding.

Plastic SCM Issue tracking configuration: Mantis


Mantis - Characteristics

Task on branch working mode

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.

Mantis user interface to create a new issue

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.

Mantis list of issues

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:

Creating a new branch in Plastic SCM

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:

Creating a new branch in Plastic SCM

Now the user can check the information of the issues linked to a certain branch on the extended information panel (Show extended information) on the Branches view.

Plastic SCM extended information for branches when working in 'Task on branch' mode

If the user clicks on the Open issue in browser button (Open issue in browser) 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.

Task on changeset working mode

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:

  • Issues are created in Mantis. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Mantis tasks can be linked with this new changeset.

Checkin dialog when the 'Task on changeset' mode is configured

The Add new issue option will show another dialog window. On this new dialog, as shows the image below, the user is able to choose the task or defect to be linked to the changeset:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

Once the changesets have been linked to the issue or task in Mantis, the extension information will be shown on the Changesets view. From the Mantis Extension information pane (Show extended information) the users can also link new issues or unlink previous issues to a changeset. And by double-clicking on each of the issues associated to a certain changeset or by pressing the Open issue in browser button (Open issue in browser), a new browser window will be opened with the Mantis task information.

Whenever a user modifies an issue in Mantis, by refreshing the Mantis Extension information, it will be shown in Plastic SCM.

Changeset extended information in 'Task on changeset' working mode


Trac integration

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.


Trac - Configuration

Server

To setup 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.

Trac server configuration

When using the Trac extension, several Server configuration features must be taken into account:

  • If the authentication method used is the Basic one (option --basic-auth when launching tracd), which means an authentication mode based on user/password, the URL to access XMLRPC services would be like this format: http://{trac_server}/{trac_project_name}/login/xmlrpc
  • If the Trac server is configured with any other authentication method, the Plastic SCM extension cannot proceed with user authentication. In this case, user anonymous must have the XML-RPC permission enabled, and the URL to access to the services would be in the following format: http://{trac_server}/{trac_project_name}/xmlrpc
    It will not be necessary to supply user/password authentication information to the Plastic SCM Trac extension.

Client

To configure the Trac 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 the Trac option.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode, specifying a Branch prefix is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the Trac tasks. As the image shows, all branches whose name starts with prefix scm will be linked to the Trac issues.
  • To work on Task on changeset mode select the Bind issues to Plastic changesets radio button.
  • The Base Trac URL parameter specifies the URL where the Trac server is installed and running.
  • If the Trac server is configured on Basic authentication User/Password mode, enable the This server requires authentication checkbox and type the User name and the Password to authenticate against the Trac server.

Plastic SCM issue tracking configuration: Trac


Trac - Characteristics

Task on branch working mode

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.

Creating new tickets in Trac

When the task or ticket is created, Trac assigns it a number (number 4 on the example picture below).

List of tickets in Trac

Now the developer has to work with the task that has been assigned to. So he/she creates 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.

Creating new branches in Plastic SCM

Extended information of the branches will be displayed by clicking on the Show extended information button (Show extended information). 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.

Plastic SCM extended information for branches when working in 'Task on branch' mode

By double clicking on the Trac information task or by pressing the Open issue in browser button (Open issue in browser) a new browser window is opened showing the associated branch task and will display the full information of the Trac task.

Task on changeset working mode

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:

  • Issues are created in Trac. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Trac tasks can be linked with this new changeset.

Checkin dialog when the 'Task on changeset' mode is configured

The Add new issue option will show another dialog window. On this new dialog, as shows the image below, the user is able to choose the task or defect to be linked to the changeset:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

Once the changes have been linked to the ticket or task in Trac, the extension information will be shown on the Changesets view. From the Trac Extension information panel (Show extended information) the users can also add new tasks or delete previous ones. By clicking on the Open issue in browser button (Open issue in browser) or by double-clicking on each of the issues associated to a certain changeset, a new browser window will be opened with the Trac task information. Whenever a user modifies an issue in the task tracking tool, the new data will be updated on the Plastic GUI by pressing the Refresh button on the Trac Extension pane.

Changeset view with detailed information in 'Task on changeset' mode


JIRA integration

This section describes the steps needed to setup JIRA and Plastic SCM to work together.


JIRA - Configuration

JIRA Server

Plastic SCM will log the files and folders included in a changeset to their JIRA issue. In order for feature to work, the JIRA administrator will need to create a custom field. To create this custom field, go to the "Issues" tab on the "Administration" screen and click on the "Custom fields" link inside the "Issue Fields" section on the left.

Issue fields options in JIRA

Click on "Add Custom Field".

Adding a custom field in JIRA

The first step is to setup the new field type. Select "Text Field (multi-line)", allowing for unlimited text sixe. This is convenient since a task can affect many files and they need to be stored in this field. The log for check in operations on JIRA is done by Plastic SCM using this Custom Field.

Specifing a free text field type

The next step is providing a name for the field. Any name will do, as Plastic will use the field Id and not the name to refer to the field. "Plastic SCM" can be a descriptive name:

Name of the custom field

When JIRA asks for the association of the field to screens, choose the "Default Screen".

Specifying more options in JIRA

The new field is empty by default and will not show up in the configured screens until it gets some content.

JIRA assigns an internal id to the custom field. This Id will be used to configure the link between Plastic SCM and JIRA. It can be found in the URL, on the address bar of the screens page:

Custom field in te URL

The field is now created and ready to be used:

Plastic SCM custom text field

The last step is to ensure that JIRA's remote API is accessible by Plastic. Click on the "General Configuration" link under "System" section.

Here, check that the "Accept remote API calls" option is enabled:

List of global settings in JIRA

In case it's disabled, edit and enable it:

Accept remote API calls

Once these steps have been fulfilled, the JIRA server is ready to accept Plastic SCM integration.

Plastic SCM Client

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.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work in this mode (Task on branch mode), speciying a Branch prefix is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the JIRA tasks. As the image shows, all branches whose name starts with prefix scm will be linked to the JIRA tasks.
  • To work on the Task on changeset mode select the Bind issues to Plastic changesets radio button. This mode will allow the user to select the task that the changes will be linked with at checkin time.
  • The Host parameter specifies the URL where the JIRA server is located. Note that the URL has to contain the port where the JIRA server is running.
  • The User name and Password parameters specify the JIRA credentials used to log into JIRA and log the changes. Note that these fields can be the user credentials in JIRA, or the credentials of a different JIRA user specifically created to log Plastic SCM changes. The issue history in JIRA will display the change as coming from the user configured here.
  • The Project Key parameter specifies the key of the JIRA project whose issues will be related to the Plastic branches.
  • The Custom Field ID is the identifier of the custom field to be used for logging the Plastic check in information on JIRA tasks. This field is built adding the custom field id that JIRA assigned when creating the field.

Issue tracking configuration in Plastic SCM: JIRA


JIRA - Characteristics

Task on branch working mode

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.

Creating new issues in JIRA

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.

Detail of an issue in JIRA

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

  • Manual: by entering the branch name. Note that the name of the new branch must match the number of the issue on JIRA (number 1 in this case), preceded by the scm prefix, as configured on the Plastic SCM JIRA extension.

    Creating a new branch for the task

  • From task: by selecting an existing task from JIRA.

    Creating a new branch for the task

By clicking on the Show extended information button (Show extended information) 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:

Detailed information of a task associated with a branch

By double clicking on it or by pressing the Open issue in browser button (Open issue in browser) 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.

Task on changeset working mode

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:

  • Issues are created in JIRA. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the JIRA issues can be linked with this new changeset.

Checkin dialog when the 'Task on changeset' mode is configured

This dialog allows the user to specify the check in operation comments, displays a list of the items to be checked in, and offers the option to link to the JIRA issues by clicking the Add new issue button.

A new dialog appears where one or more issues id can be entered and the details for that issue are shown so the user can check whether this is the correct issue to link.

Add issue dialog, to associate a task with a changeset when performing a checkin operation

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 (Show extended information), by clicking in a changeset then shows the associated JIRA issues:

Changeset view with detailed information in 'Task on changeset' working mode

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 (Open issue in browser), 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.

Check in operations record

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:

JIRA issue detail - changeset - Plastic SCM check in information


JIRA - Multi-project configuration

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.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work in this mode, specifying a Branch prefix is recommended (but not mandatory). This branch prefix will be used to bind the Plastic branches to the JIRA tasks. This multi-project configuration example will use JIRA_ as branch prefix.
  • The Project Key parameter must have the value MULTIPLE_PROJECTS.

Issue tracking configuration in Plastic SCM: JIRA multi-project


Projects and tasks must be created on JIRA:

JIRA projects

JIRA tasks


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.

Plastic SCM multi-project brex


Field mapping

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:

Fields mapping configuration

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 [ | ... ] ] ]

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:

  • Id
  • Owner
  • Status
  • Title
  • Description

Fields mapping example

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

The index between [ ] 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.

Fields mapping example - Custom field


Axosoft integration

This section describes the steps to follow in order to use the Axosoft integration with Plastic SCM as well as its advantages.

This extension is compatible with Axosoft v14 and higher.


Axosoft - Configuration

Server

To setup 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:

Axosoft - System Options

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.

Axosoft - Manage API keys

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:

Axosoft - Add API key

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:

Axosoft - Create custom field

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:

Create a new custom field to log check in operations

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.

Client

To configure the Axosoft 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 the Axosoft option.

  • By default, the Bind issues to Plastic branches option is activated.
    If Plastic SCM is configured to work with this mode (Task on branch mode), the user will be able to configure several branch prefixes to bind them to several Axosoft objects. For instance, 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. For example: branch name def021 will be linked to Axosoft defect DE21 and branch name task021 will be linked to Axosoft task TA21. The rest of the objects have the same behaviour.
  • To work on the Task on changeset mode select the Bind issues to Plastic changesets radio button.
  • As explained before on the Server topic, Plastic SCM Axosoft extension needs the Axosoft Root URL to work.
  • Each Plastic SCM user must have an Axosoft account and use the Axosoft User and Password to allow Plastic to connect with the Axosoft server.
  • The Client ID and Client Secret fields must be filled with the tokens generated from the Axosoft admin panel. See the Server topic for more info.
  • The Plastic SCM custom field is the custom field created on Axosoft and used for logging the Plastic SCM check in information.

Issue tracking configuration: Axosoft OnTime

Issue tracking configuration: Axosoft OnTime


Axosoft - Characteristics

Task on branch working mode

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:

Creating new defects in OnTime

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.

Defect info for a new defect in OnTime

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 (Show extended information) 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.

Detailed information of branches in 'Task on branch' mode

By double clicking on it or by pressing the Open issue in browser button (Open issue in browser), 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.

Task on changeset working mode

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:

  • Issues are created in Axosoft. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Axosoft issues can be linked with this new changeset.

Checkin dialog in 'Task on changeset' mode

On this dialog, by selecting the Add new issue option showed on the previous figure, a new dialog will be displayed. Enter the numeric issue identifier on this window to link the Axosoft task to the new changeset:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

Once the changesets have been linked to the Axosoft defect or task, the extension information (Show extended 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 (Open issue in browser), 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.

Changeset detailed view in 'Task on changeset' working mode

Checked in operations record

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:

Checkin information generated by Plastic SCM


VersionOne integration

This section describes the steps to use the VersionOne integration with Plastic SCM. It also describes its advantages.

This extension is compatible with VersionOne version 7.2 and following ones.


VersionOne - Configuration

Server

It is not necessary to make any changes at the server side for the Plastic SCM VersionOne extension configuration.

Client

To configure the VersionOne 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 the VersionOne option.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (Task on branch mode), the user will be able to configure several branch prefixes to bind them to several VersionOne objects. For instance, if the user enables the mapping with VersionOne Defects, then all Plastic branches whose name starts with prefix def will be linked to VersionOne Defects. The branch name def-1001 will be linked to the VersionOne Defect D-01001. The rest of the objects have the same behaviour. Available VersionOne objects to be linked are Defects, Tasks, Tests and User Stories.
  • Important: Note that VersionOne starts enumerating their objects from number 1000.
  • To work on the Task on changeset mode select the Bind issues to Plastic changesets radio button. In this case, all the VersionOne objects will be enabled to map them to a Plastic changeset.
  • The Base URL parameter specifies the URL where the VersionOne server is installed and running.
  • Regarding authentication on VersionOne server, the Use windows integrated authentication checkbox tells Plastic SCM whether the authentication will be resolved with Windows domain users or not.
  • If this option is not selected, the User and Password fields must be filled with a valid VersionOne user.

Issue tracking configuration in Plastic SCM: VersionOne

Issue tracking configuration in Plastic SCM: VersionOne


VersionOne - Characteristics

Task on branch working mode

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.

As usual, the first step would be creating 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.

Creating a new backlog item in VersionOne

When the issue is created, VersionOne assigns it a number. In the following figure we can see a list of items created:

List of defects in VersionOne

The next step is: when a developer has been assigned to a task, the developer has to 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):

Creating a new branch in Plastic SCM to resolve the new issue

Now the user can check the information of the issues just by going to the extended information (Show extended information) on the branch view and selecting the branch: a new pane will be displayed on the right side of the view from which the VersionOne extension information is shown: task number, owner, status, etc.

Detailed branch information in 'Task on branch' mode

Performing a double click on the task associated with a branch or clicking on the Open issue in browser button (Open issue in browser), a new web browser window will be opened. When a user changes the status or any other field of the issue, the new information will appear by refreshing VersionOne extension.

Task on changeset working mode

To configure Plastic SCM to work on the Task on changeset working mode, the user has to 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:

  • Issues are created in VersionOne. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the VersionOne defects/tasks/tests/stories can be linked with this new changeset.

Checkin dialog in 'Task on changeset' mode

By selecting the option Add new issue on this check in information dialog, a new window will be displayed on which to include the full ID of the VersionOne task and by pressing on the Details button the information of the issue will be shown as the following image displays:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

Once the changeset have been linked to VersionOne tasks, the extension information (Show extended information) will be shown on the Changesets view. From the VersionOne 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 (Open issue in browser), a browser with VersionOne will be opened. Whenever a user modifies an issue in VersionOne, by refreshing the VersionOne Extension information, it will be shown in Plastic SCM.

Changeset view with detailed information in 'Task on changeset' mode


FogBugz integration

This section describes the steps to follow in order to use FogBugz integration with Plastic SCM. It also describes its advantages.

This extension is compatible with FogBugz version 7.2 and following.


FogBugz - Configuration

Server

It is not necessary to make any changes on the server side for Plastic SCM FogBugz extension.

Client

To configure the FogBugz 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 the FogBugz option.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (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. As the image shows, all branches whose name starts with prefix scm will be linked to FogBugz issues.
  • To work on the Task on changeset mode select the Bind issues to Plastic changesets radio button.
  • The FogBugz URL parameter specifies the URL where the FogBugz server is installed and running.
  • The User name and Password fields must be filled with a valid FogBugz user.
  • The Enable checkin log checkbox allows FogBugz to record all the check in operations executed in Plastic SCM.

Issue tracking configuration in Plastic SCM: FogBugz


FogBugz - Characteristics

Task on branch working mode

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.

As usual, the first step would be creating tasks in 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.

Creating a new issue in FogBugz

When the issue is created, FogBugz assigns it a number. The next step is: when a task has been assigned to a developer, the developer has to create 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.

Creating a new branch in Plastic SCM

Now the user can check the information of the issues just by going to the extended information (Show extended information) on the Branches view and selecting the branch: a new pane will be displayed on the right side of the view from which the FogBugz extension information is shown: task number, owner, etc.

Branch view showing extended information in 'Task on branch' mode

By double-clicking on it or by clicking on the Open issue in browser button (Open issue in browser), a new web browser window is opened. 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.

Task on changeset working mode

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:

  • Issues are created in FogBugz. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the FogBugz tasks can be linked with this new changeset.

Checkin dialog in 'Task on changeset' mode

By selecting the option Add new issue on this check in information dialog, a new window will be displayed on which to include the ID of the FogBugz issue and by pressing on the Details button the information of the issue will be shown as the following image displays:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

Once the changesets have been linked to the issue or task in FogBugz, the extension information (Show extended 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 (Open issue in browser), 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.

Changeset view showing detailed information in 'Task on changeset' mode

Checked in operations record

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:

Checkin information generated by Plastic SCM


Rally integration

This section describes the steps to follow in order to use the Plastic SCM Rally Software Development integration.


Rally - Configuration

Server

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.

Client

To configure the Rally 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 the Rally option.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (Task on branch mode), the user will be able to configure several branch prefixes to bind them to several Rally objects. For instance, if the user enables the mapping to Rally Defects and Rally Tasks, branches whose name starts with prefix def will be linked to Rally Defects, and branches whose name starts with prefix task will be linked to Rally Tasks. For instance: Branch name def021 will be linked to Rally Defect DE21 and branch name task021 will be linked to Rally Task TA21. The rest of the objects have the same behaviour. Available Rally objects to be linked are Task ( Task prefix ), Defects ( Defect prefix ), Test cases ( Test case prefix ) and User stories ( User story prefix ).
  • To work on the Task on Changeset mode select the Bind issues to Plastic changesets radio button. In this case, all the Rally objects will be enabled to map them to a Plastic changeset.
  • The Rally URL parameter specifies the URL where the Rally server is running.
  • The User name and Password fields must be filled with a valid Rally user for the configured Rally Server.

Issue tracking configuration Rally


Rally - Characteristics

Task on branch working mode

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

Creating a new defect in Rally

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 (Show extended information), 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:

Branch view showing detailed information, in 'Task on branch' working mode

By double clicking on it or by clicking on the Open issue in browser button (Open issue in browser), 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.

Task on changeset working mode

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:

  • Issues are created in Rally. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Rally tasks can be linked with this new changeset.

Checkin dialog in 'Task on changeset' mode

On this dialog, by selecting the Add new issue option showed on the previous figure, a new dialog window will be displayed. On this window, the user has to type the full ID of the Rally object to be linked to that changeset:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

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 (Open issue in browser), 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.

Changeset view showing extended information, in 'Task on changeset' mode


Polarion integration

This section describes the steps to follow in order to use the Plastic SCM Polarion Software Development integration.


Polarion - Configuration

Server

To setup the Polarion extension functionality some tasks have been performed.

The first thing to do is to include the Plastic SCM plugin into Polarion. To do this follow these steps:

  • Stop the Polarion service.
  • Copy the directory com.codicesoftware.platform.repository.external.plasticscm (inside the client/polarion folder at the Plastic SCM installation directory) to the Polarion extensions folder ([Polarion installation]/polarion/extensions).
  • Start the Polarion server again.
This plugin is needed for the issue tracker extension to work properly into Plastic SCM.
And this is so because it allows to link Plastic SCM revisions (changesets) to Polarion workitems by linking a revision to a workitem manually, or by linking a workitem via checkin comment.

Then, a Plastic SCM repository must be created on the Polarion server side.

To do that go to the Administration option in Polarion:

Polarion server configuration

And then click on the Repositories section. A Plastic SCM repository is needed. So click on the "Add New Repository" button:

Polarion - Add new repository

In the repository configuration window enter the information needed to create the new Plastic repository in Polarion, where:

  • ID - identifier for this repository in Polarion (required).
  • Name - name to display in Polarion for the repository.
  • Repository Name - the name of the Plastic SCM repository.
  • Server - the Plastic SCM server.
  • Plastic Cm Executable - the path where the cm executable is (in the Polarion server side).
    In case of no Plastic installation exists on the Polarion server side, then the Plastic 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.

Polarion repository configuration

Once the information is added then click on the "Save" button.

Client

To configure the Polarion 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 the Polarion option.

  • By default, the Bind issues to Plastic branches option is activated. If Plastic SCM is configured to work with this mode (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 Polarion tasks. As the image shows, all branches whose name starts with prefix scm will be linked to Polarion issues.
  • To work on the Task on changeset mode select the Bind issues to Plastic changesets radio button.
  • The Polarion Base URL parameter specifies the URL where the Polarion server is installed and running.
  • The User name and Password fields must be filled with a valid Polarion user.
  • The Work item statuses 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.
    These statuses must be separated using the vertical bar ("|") char. As the image below shows, only tasks with statuses draf or open will be shown.
  • The Open work item status is the new status that the Polarion task will have if the user creates a new branch using the From task mode and checks the Mark as open in issue tracker option.
  • The Repository ID is the same "ID" field configured in the Polarion server side.

Issue tracking configuration in Plastic SCM: Polarion

Issue tracking configuration in Plastic SCM: Polarion


Polarion - Characteristics

Task on branch working mode

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:

Creating a new work item in Polarion

Type the data related to the new task, such as name, description, priority... and click on the "Create" button:

Creating a task in Polarion

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:

Task created in Polarion

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:

  • Manual: by entering the branch name. Note that the name of the new branch must match the number of the issue on Polarion (number 84 in this case), preceded by the scm prefix, as configured on the Plastic SCM Polarion extension.

    Creating a new branch for the task

  • From task: by selecting an existing task from Polarion.

    Creating a new branch for the task

    In this mode the user will:

    • see in the "Pending tasks" list the work items with same statuses as those configured in the Work item statuses field;
    • change a Polarion task status with the one configured in the Open work item status field when the Mark as open in issue tracker option is selected;

    as you've seen in the Client configuration section.

By clicking on the Show extended information button (Show extended information) 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:

Detailed information of a task associated with a branch

By double clicking on it or by pressing the Open issue in browser button (Open issue in browser) 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.

Task on changeset working mode

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:

  • Tasks are created in Polarion. When a developer starts working on one issue, it's opened.
  • Changes are made on the code, thus checked out items that appear in Plastic.
  • When the user decides to check in the changes Plastic SCM will display a new dialog where the Polarion tasks can be linked with this new changeset.

Checkin dialog when the 'Task on changeset' mode is configured

This dialog allows the user to specify the check in operation comments, displays a list of the items to be checked in, and offers the option to link to the Polarion work items by clicking the Add new issue button.

A new dialog appears where one or more issues IDs can be entered and the details for that issue are shown, so the user can check whether this is the correct issue to link.

Add issue dialog, to associate a task with a changeset when performing a checkin operation

In this case two Polarion work items will be linked to the change that is going to be checked in:

Add issue dialog, to associate a task with a changeset when performing a checkin operation

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:

Checking work item statuses when using the 'Task on changeset' working mode

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 (Show extended information) is visible, by clicking in a changeset shows the associated Polarion work items.

Changeset view with detailed information in 'Task on changeset' working mode

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.

Check in operations record

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:

Polarion linked revisions - Branch - Plastic SCM check in information

or the Task on changeset working mode:

Polarion linked revisions - Changeset - Plastic SCM check in information

When the Plastic revision is correctly linked to Polarion you'll see that the icon revision includes a green bullet: Linked revision icon


Global extension configuration

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.

This is the same behaviour as if you're configuring the Global file configuration.

Creating the global repository configuration

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:

  • Global configuration for a specific repository: /repname/issuetrackers/extension_configuration_file.conf.
    For example, /doomsrc/issuetrackers/jira.conf.
  • Global configuration for all the repositories: /allrepos/issuetrackers/extension_configuration_file.conf.
    For example, /allrepos/issuetrackers/bugzilla.conf.
Note: For submodules, you should use the '-' char instead of '/': /myrepo-mysubrepo/issuetrackers/extension_configuration_file.conf
For example, /plugins-3dplugin/issuetrackers/jira.conf, where plugins is the main repo and 3dplugin is the submodule.

How the global configuration is loaded

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.

How to set up the global configuration

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

Create the plastic-global-config repository

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:

Example plastic-global-config

Note: The configuration example files are included in the plasticscm_install_path/client/extensions/config_samples folder. 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.


Customize the global configuration

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


Writing Plastic SCM custom extensions

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!


Requirements

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.


Creating a new extension

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

Note: Please pay close attention to the .NET framework version used by your Plastic SCM client. In the Plastic SCM downloads area you will find both .NET 2.0 and .NET 4.0 standard versions. If you'd rather use .NET 4.0 or later, you'll need to download the Plastic SCM .NET 4 compatible version.

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 that matter, 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 pretty easy to implement:

public IPlasticIssueTrackerExtension GetIssueTrackerExtension(
    IssueTrackerConfiguration configuration)
{
    return new SampleExtension(configuration);
}

public string GetIssueTrackerName()
{
    return "Sample Issue Tracker";
}

They just 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:

  • TaskOnBranch: Tasks are automatically linked to branches by their names, using the defined branch prefixes (we'll talk about that later).
  • TaskOnChangeset: Tasks are manually linked to changesets.

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 only two: the current user ID and the Plastic SCM branch prefix. The first one will affect the currently pending tasks results, whereas the second will tell Plastic which branch name prefix to expect when guessing if a branch is linked to an issue tracker task.

Basically, each parameter contains 4 attributes: name, value, type and IsGlobal. The first two are self-descriptive, just two string class attributes. The parameter type is defined by an enumerate type: IssueTrackerConfigurationParameterType. It describes what the parameter contains:

  • Host: the target host
  • User: the user name to authenticate
  • Password: the password to authenticate
  • Label: just a text to be displayed on the configuration panel
  • BranchPrefix: the PlasticSCM branch prefix
  • Text: a simple text value, drawn as a textbox on the configuration panel
  • Boolean: a true/false value, drawn as a checkbox on the configuration panel

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 mode is switched to TaskOnChangeset.

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.


Implementing the extension methods

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:

Connect
Write here any needed actions to prepare your extension to connect to your target issue tracker.
Disconnect
The opposite to Connect, it will contain code to release any resources needed to connect to your target issue tracker (sessions, etc.)
GetExtensionName
Returns a human-readable name to display on Plastic SCM views.
GetPendingTasks
Returns a list of pending tasks in the issue tracker system. There are two method overloads, one returning a list of tasks for a given user name, the other one returning all existing pending tasks.
GetTaskForBranch
Returns the task associated to a full branch name (i.e. showing the complete branch hierarchy). The result can be null if no matching task is found.
GetTasksForBranches
Retrieves task information for a list of branches. The result maps each branch name to its related task information.
LoadTasks
Retrieves the issue tracker task information for a list of task IDs. The format for these IDs is defined by the issue tracker system.
LogCheckinResult
Records the information of a single changeset into a list of associated tasks, passed as a parameter. This method is called after a successful checkin is finished.
MarkTaskAsOpen
Alters the state of a task defined by ID -passed as parameter- and, if the issue tracker system supports it, set the assigned user as the referenced one.
OpenTaskExternally
Opens a task -passed as an ID- in the external browser.
TestConnection
Tests whether the passed configuration can successfully establish a connection to the defined issue tracker.
UpdateLinkedTasksToChangeset
For those issue tracker systems supporting it, modifies the Plastic SCM referenced changeset of a list of tasks.

To 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 http://jsonplaceholder.typicode.com.

GetExtensionName

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";
}

GetTasksForBranches

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 = "http://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.

Note: 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 http://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.

OpenTask

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.


SampleExtension example

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:

Branches view - Extension details

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:

Changesets view - Extension details

  • Changesets view - Extension details - Buttons The first button will open the task information in a browser, as we saw before on the OpenTask method.
  • Changesets view - Extension details - Buttons 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.

    Add issue dialog

    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:

    Associate issues and changesets

  • Changesets view - Extension details - Buttons 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:

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.

Create branch

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.


Debugging

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:

Debugging - Build section

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.

Debugging - Debug section

Note: it's important to remember that you'll need the appropriate permissions to be able to place the compiled files inside the Plastic SCM client directory -which is typically placed under Program Files.

Configuring the extension

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:

Preferences - Issue tracker dialog

By clicking the Apply or OK button, Plastic will be able to work with our brand new extension.


Creating your own 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.


Last updated

October 8, 2015
  • The Polarion integration has been added.
  • October 7, 2015
  • The JIRA extension now supports the new Rest API. The Field mapping documentation has been updated.
  • August 25, 2015
  • All references to Branch Prefix are no longer stated as a must.
  • June 12, 2015
  • The Writing Plastic SCM custom extensions chapter has been updated and now includes new methods.
  • June 12, 2015
  • The Global extension configuration is now easier to configure.
  • February 26, 2015
  • Updated the Axosoft integration chapter: compatibility with Axosoft v14.
  • January 22, 2015
  • Learn how to write your Plastic SCM custom extension.
  • January 8, 2015
  • Added JIRA multi-project configuration.