Task and issue tracking systems guide

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:

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

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.

Mantis Server configuration

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 configuration

Read how to configure the Mantis integration on your Windows, Linux, or macOS system.

Client configuration - Windows

Follow these steps to configure the Mantis extension on the Plastic SCM client on your Windows machine:

1. Click the Preferences tab of the main window of the Plastic SCM GUI.
2. In the new window, click the Issue trackers tab.
3. Click the radio button Bind to this issue tracking system.
4. Select the Mantis tracking system.
5. Now, select the repository you want to Apply binding to:
   • If you are working with the Global extension configuration, then select the plastic-global-config repository.
   • If you want to bind to all your repositories with the issue tracker, then select Repositories.
   • If you want to bind to a particular repository with Mantis, then select that repository.
   
6. By default, the Bind issues to Plastic branches option is activated to work with the Task on branch mode.
   To work on the Task on Changeset mode, select the Bind issues to Plastic changesets radio button.
7. Now, you must configure the Mantis parameters (URL where your Mantis server is located at, credentials, branch prefix, and so on) accordingly.
   Learn more about the Mantis configuration parameters .

Client configuration - Linux and macOS systems

You can configure the Mantis extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:

• Set a global extension configuration in the server. This way all the Plastic clients have the same Mantis settings by default.

• Set a local Mantis configuration. To do this:
  1. Create the structure issuetrackers/server_port/repository under $HOME/.plastic4, where repository is one of the following values:
     • The name of the repository that you want to link to the issue tracker.
     Or
     • allrepos, which means that all of your repositories will be linked to the issue tracker.
  2. Copy the mantis.conf example configuration file into the new created path.
     You can find this file at this location:
     • Window or Linux: plasticscm_install_path/client/extensions/config_samples
     • macOS: /Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples

     Then, you'll have, for example, something like this:

     • /home/pablo/.plastic4/issuetrackers/localhost_8087/info/mantis.conf
     Or
     • /home/pablo/.plastic4/issuetrackers/localhost_8087/allrepos/mantis.conf.
  3. Edit the mantis.conf file:
     1. Edit the WorkingMode parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
     2. Configure the rest of the Mantis extension parameters (URL where your Mantis server is located at, credentials, branch prefix, and so on) accordingly.
        Learn more about the Mantis configuration parameters .
  4. Edit your client.conf file to add the following key:

     <Extensions>
         <Extension AssemblyFile="plasticscm_install_path/client/extensions/mantis/mantisextension.dll" />
     </Extensions>
     

Client configuration - Parameters

• 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.
  For example, if you enter the scm prefix, then all branches whose name starts with prefix scm will be linked to the Mantis issues. For example, the Plastic branch with name scm022 will be associated to the Mantis task #22.
• 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 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.

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.

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:

1. Issues are created in Mantis. When a developer starts working on one issue, then the issue is open.
2. Changes are made on the code, thus checked out items that appear in Plastic.
3. 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:
   

   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

   
4. The user can link the changeset and the task by following one of these options:
   • Adding new issues - Click the Add new issue button to open a new dialog. Now, the user is able to choose one or more tasks or defects to link to the changeset:
     

     Plastic SCM - Windows - Add issue

     

     Plastic SCM - Linux - Add issue

     

     Plastic SCM - macOS - Add issue

     
   • Entering comment hashtags - Enter a comment in the Checkin comments text box by starting the comment with the '#' character followed by the issue key (and optionally followed by a colon). This will log the checkin information in the related issue. For example, #5: Edited const.

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

Jira Server configuration

1. 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.
   1. 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:
      
   2. Click on "Add Custom Field".
      
   3. It's time to set up 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:
      
   4. Then, it's necessary to provide 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:
      
   5. When Jira asks for the association of the field to screens, choose the "Default Screen":
      

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

   6. 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:
      
   7. The field is now created and ready to be used:
      
2. The last step is to ensure that Jira's remote API is accessible by Plastic.
   Important for Jira Cloud users

   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.

   1. Click on the "General Configuration" link under "System" section.
   2. Here, check that the "Accept remote API calls" option is enabled:
      
   3. In case it's disabled, edit and enable it:
      

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

Client configuration

Read how to configure the Jira integration on your Windows, Linux, or macOS system.

Client configuration - Windows

Follow these steps to configure the Jira extension on the Plastic SCM client on your Windows machine:

1. Click the Preferences tab of the main window of the Plastic SCM GUI.
2. In the new dialog, click the Issue trackers tab.
3. Click the radio button Bind to this issue tracking system.
4. Select the Atlassian Jira tracking system.
5. Now, select the repository you want to Apply binding to:
   • If you are working with the Global extension configuration, then select the plastic-global-config repository.
   • If you want to bind to all your repositories with the issue tracker, then select Repositories.
   • If you want to bind to a particular repository with codeBeamer, then select that repository.
   
6. By default, the Bind issues to Plastic branches option is activated to work with the Task on branch mode.
   To work on the Task on changeset mode, select the Bind issues to Plastic changesets option. This mode will allow the user to select the task that the changes will be linked with at checkin time.
7. Now, you must configure the Jira parameters (URL where your Jira server is located at, credentials, branch prefix, and so on) accordingly.
   Learn more about the Jira configuration parameters .

Client configuration - Linux and macOS systems

You can configure the Jira extension on the Plastic SCM client on your Linux or macOS machine by using one of these methods:

• Set a global extension configuration in the server. This way, all the Plastic clients have the same Jira settings by default.

• Set a local Jira configuration. To do this:
  1. Create the structure issuetrackers/server_port/repository under $HOME/.plastic4, where repository is one of the following values:
     • The name of the repository that you want to link to the issue tracker.
     Or
     • allrepos, which means that all of your repositories will be linked to the issue tracker.
  2. Copy the jira.conf example configuration file into the new created path.
     You can find this file at this location:
     • Window or Linux: plasticscm_install_path/client/extensions/config_samples
     • macOS: /Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples

     Then, you'll have, for example, something like this:

     • /home/pablo/.plastic4/issuetrackers/localhost_8087/info/jira.conf
     Or
     • /home/pablo/.plastic4/issuetrackers/localhost_8087/allrepos/jira.conf.
  3. Edit the jira.conf file:
     1. Edit the WorkingMode parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
     2. Configure the rest of the Jira extension parameters (URL where your Jira server is located at, credentials, branch prefix, and so no) accordingly.
        Learn more about the Jira configuration parameters.
  4. Edit your client.conf file to add the following key:

     <Extensions>
         <Extension AssemblyFile="plasticscm_install_path/client/extensions/jira/jiraextension.dll" />
     </Extensions>
     

Client configuration - Parameters

• 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.
  Important for Jira Cloud users

  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.

  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 on Jira will display the change as coming from the user configured here.
• 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.
  For example, if you enter the scm prefix, then all branches whose name starts with prefix scm will be linked 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.
  This parameter is optional. If it is not set in the configuration, Plastic SCM will not log any information concerning the checkin into Jira's related issue. The user can still benefit from Jira integration while creating branches from Jira issues, or from browsing Jira issues from the Branch Explorer.
  Important for Next-gen projects

  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.
  Its default value is 50, and it can be set to any positive number.
• Resolved issue states: Holds a comma-separated list of status names to be considered as "resolved".
  The default value is Done, so no issues with status Done will be shown in the task list on the Create Branch dialog by default.
• 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.
  If you are using GNU/Linux or macOS, you can copy and edit as you need the following line, and paste it in your 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.
  Learn more about Jira Field mapping.
• 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.
  Learn more about Status transition.

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.

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:

• 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.
  
• From task: by selecting an existing task from 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.

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:

1. Issues are created in Jira. When a developer starts working on one issue, then the issue is open.
2. Changes are made on the code, thus checked out items that appear in Plastic.
3. 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:
   

   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

   
4. The user can link the changeset and the task by following one of these options:
   • Adding new issues - Click the Add new issue button to open a new dialog. Now, the user is able to choose one or more tasks to link to the changeset:
     

     Plastic SCM - Windows - Add issue

     

     Plastic SCM - Linux - Add issue

     

     Plastic SCM - macOS - Add issue

     
   • Entering comment hashtags - Enter a comment in the Checkin comments text box by starting the comment with the '#' character followed by the issue key (and optionally followed by a colon). This will log the checkin information in the related issue. For example, #PJI-2: Updated values.

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.

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:

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.
  If you are working on a Linux or macOS system, remember to update the required values in the 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 [ | ... ] ] ]

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

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:

It's possible to access the value of custom Jira fields with the customFieldValues modifier, like in this sample mapping:

customFieldValues[10000]->Description

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.

Status transition configuration

Read how to configure the status transition feature on your Windows, Linux, or macOS system.

Status transition configuration - Windows

1. Click the Preferences tab of the main window of the Plastic SCM GUI. Then, click the Issue trackers tab. And the Jira extension configuration opens.
2. Go to the Status transitions field and enter the needed pairs KEY-VALUE.

Status transition configuration - Linux and macOS systems

1. Open the jira.conf file.
2. Add the following line and replace the text in the 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.

Axosoft Server configuration

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.

Client configuration

Read how to configure the Axosoft integration on your Windows, Linux, or macOS system.

Client configuration - Windows

Follow these steps to configure the Axosoft extension on the Plastic SCM client on your Windows machine:

1. Click the Preferences tab of the main window of the Plastic SCM GUI.
2. In the new window, click the Issue trackers tab.
3. Click the radio button Bind to this issue tracking system.
4. Select the Axosoft option.
5. Now, select the repository you want to Apply binding to:
   • If you are working with the Global extension configuration, then select the plastic-global-config repository.
   • If you want to bind to all your repositories with the issue tracker, then select Repositories.
   • If you want to bind to a particular repository with codeBeamer, then select that repository.
   
6. By default, the Bind issues to Plastic branches option is activated to work on the Task on branch mode.
   To work on the Task on changeset mode, select the Bind issues to Plastic changesets option.
7. Now, you must configure the Axosoft parameters (URL where your Axosoft server is located at, credentials, branch prefix, and so on) accordingly:
   Learn more about the Axosoft configuration parameters.

Client configuration - Linux and macOS systems

You can configure the Axosoft extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:

• Set a global extension configuration in the server. This way, all the Plastic clients have the same Axosoft settings by default.

• Set a local Axosoft configuration. To do this:
  1. Create the structure issuetrackers/server_port/repository under $HOME/.plastic4, where repository is one of the following values:
     • The name of the repository that you want to link to the issue tracker.
     Or
     • allrepos, which means that all of your repositories will be linked to the issue tracker.
  2. Copy the ontime.conf example configuration file into the new created path.
     You can find this file at this location:
     • Window or Linux: plasticscm_install_path/client/extensions/config_samples
     • macOS: /Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples

     Then, you'll have, for example, something like this:

     • /home/pablo/.plastic4/issuetrackers/localhost_8087/info/ontime.conf
     Or
     • /home/pablo/.plastic4/issuetrackers/localhost_8087/allrepos/ontime.conf.
  3. Edit the ontime.conf file:
     1. Edit the WorkingMode parameter to assign of these values: TaskOnBranch or TaskOnChangeset.
     2. Configure the cAxosoft parameters (URL where your Axosoft server is located at, credentials, branch prefix, and so on) accordingly:
        Learn more about the Axosoft configuration parameters.
  4. Edit your client.conf file to add the following key:

     <Extensions>
         <Extension AssemblyFile="plasticscm_install_path/client/extensions/ontime/ontimeextension.dll" />
     </Extensions>
     

Client configuration - Parameters

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

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:

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.

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:

1. Issues are created in Axosoft. When a developer starts working on one issue, then the issue is open.
2. Changes are made on the code, thus checked out items that appear in Plastic.
3. 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:
   

   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

   
4. The user can link the changeset and the task by following one of these options:
   • Adding new issues - Click the Add new issue button to open a new dialog. Now, the user is able to choose one or more tasks to link to the changeset:
     

     Plastic SCM - Windows - Add issue

     

     Plastic SCM - Linux - Add issue

     

     Plastic SCM - macOS - Add issue

     
   • Entering comment hashtags - Enter a comment in the Checkin comments text box by starting the comment with the '#' character followed by the issue key (and optionally followed by a colon). This will log the checkin information in the related issue. For example, #def3: Included encode modes.

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.

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:

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.

Polarion Server configuration

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

1. Include the Plastic SCM plugin into Polarion. To do this, follow these steps:
   1. Stop the Polarion service.
   2. Copy the directory 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.
      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.
   3. Start the Polarion server again.
2. Then, a Plastic SCM repository must be created on the Polarion server side:
   1. Go to the Administration option in Polarion:
      
   2. Then click on the Repositories section.
   3. A Plastic SCM repository is needed. So click on the "Add New Repository" button:
      
   4. 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.
      
   5. Once the information is added then click on the "Save" button.

Client configuration

Read how to configure the Polarion integration on your Windows, Linux, or macOS system.

Client configuration - Windows

Follow these steps to configure the Polarion extension on the Plastic SCM client on your Windows machine:

1. Click the Preferences tab of the main window of the Plastic SCM GUI.
2. In the new window, click the Issue trackers tab.
3. Click the radio button Bind to this issue tracking system.
4. Select the Polarion tracking system.
5. Now, select the repository you want to Apply binding to:
   • If you are working with the Global extension configuration, then select the plastic-global-config repository.
   • If you want to bind to all your repositories with the issue tracker, then select Repositories.
   • If you want to bind to a particular repository with codeBeamer, then select that repository.
   
6. By default, the Bind issues to Plastic branches option is activated to work with the Task on branch mode.
   To work on the Task on changeset mode, select the Bind issues to Plastic changesets option.
7. Now, you must configure the Polarion parameters (URL where your Polarion server is located at, credentials, branch prefix, and so on) accordingly.
   Learn more about the Polarion configuration parameters .

Client configuration - Linux and macOS systems

You can configure the Polarion extension on the Plastic SCM client on your Linux or macOS machine using one of these methods:

• Set a global extension configuration in the server. This way all the Plastic clients have the same Polarion settings by default.

• Set a local Polarion configuration. To do this:
  1. Create the structure issuetrackers/server_port/repository under $HOME/.plastic4, where repository is one of the following values:
     • The name of the repository that you want to link to the issue tracker.
     Or
     • allrepos, which means that all of your repositories will be linked to the issue tracker.
  2. Copy the polarion.conf example configuration file into the new created path.
     You can find this file at this location:
     • Window or Linux: plasticscm_install_path/client/extensions/config_samples
     • macOS: /Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples

     Then, you'll have, for example, something like this:

     • /home/pablo/.plastic4/issuetrackers/localhost_8087/info/polarion.conf
     Or
     • /home/pablo/.plastic4/issuetrackers/localhost_8087/allrepos/polarion.conf.
  3. Edit the polarion.conf file:
     1. Edit the WorkingMode parameter to assign one of these values: TaskOnBranch or TaskOnChangeset.
     2. Configure the rest of the Polarion extension parameters (URL where your Polarion server is located at, credentials, branch prefix, and so on) accordingly.
        Learn more about the Polarion configuration parameters .
  4. Edit your client.conf file to add the following key:

     <Extensions>
         <Extension AssemblyFile="plasticscm_install_path/client/extensions/polarion/polarionextension.dll" />
     </Extensions>
     

Client configuration - Parameters

• 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.
  For example, if you enter the scmprefix, then all branches whose name starts with prefix scm will be linked to Polarion issues.
• 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.
  These statuses must be separated using the vertical bar ("|") char.
• 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.

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:

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:

• 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.
  
• From task: by selecting an existing task from Polarion.
  

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

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:

1. Tasks are created in Polarion. When a developer starts working on one issue, then the issue is open.
2. Changes are made on the code, thus checked out items that appear in Plastic.
3. 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:
   

   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

   
4. The user can link the changeset and the Polarion work items by following one of these options:
   • Adding new issues - Click the Add new issue button to open a new dialog. Now, the user is able to choose one or more tasks to link to the changeset:
     

     Plastic SCM - Windows - Add issue

     

     Plastic SCM - Linux - Add issue

     

     Plastic SCM - macOS - Add issue

     
   • Entering comment hashtags - Enter a comment in the Checkin comments text box by starting the comment with the '#' character followed by the issue key (and optionally followed by a colon). This will log the checkin information in the related issue. For example, #IP-83: Fixed error when searching by name.

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.

Working with distributed scenarios

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.

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:

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:

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:

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

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

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

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:

• 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 the following parameters:

• The current user ID. This will affect the currently pending tasks results.
• The Plastic SCM branch prefix. This will tell Plastic which branch name prefix to expect when guessing if a branch is linked to an issue tracker task.

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:
  • Host: The target host.
  • User: The user name to authenticate.
  • Password: The password to authenticate.
  • Label: The text to display on the configuration panel.
  • BranchPrefix: The Plastic SCM branch prefix.
  • Text: A 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 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:
  • If True, the extension will use the parameter's value defined in the global configuration.
  • If False, the extension will use the parameter's value defined in the local configuration.

  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:

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

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.

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.

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.

November 30, 2021

• Now, the IsGlobal attribute is fully described in the Creating a new extension section.

November 19, 2020

• We added a note about supporting Jira Next-gen projects .

April 29, 2020

• We added a new chapter about the codeBeamer integration.
• We included the location of the configuration examples files on the macOS system.

March 10, 2020

• We included a note for Jira Cloud users related to the "Accept remote API calls" option .

May 16, 2019

• We updated the Jira configuration to explain how to configure your credentials if you use Atlassian Cloud.

March 22, 2019

• We replaced the references to deprecated attribute administration commands like cm makeattribute for their new counterparts.

November 21, 2018

• Now, you can configure these new Jira extension parameters: Use LDAP credentials if available, Use default proxy credentials and Issue types.

May 18, 2018

• All issue trackers:
  • Now, you can link a changeset with your issue tracker system through comment hashtags. Starting the comment with the '#' character followed by the issue key (and optionally followed by a colon) will log the checkin information in the related issue. This behavior will only take effect if your issue tracker extension is configured in Task On Changeset mode.

September 27, 2017

• Now, the Jira extension is able to transition status based on the comment of the associated checkin.

June 14, 2017

• All issue trackers:
  • The issue trackers client configuration has been updated:
    • You can select the repository (or all the repositories) to link to your issue tracking system.
    • Learn how to configure the issue trackers integration on your Linux or macOS systems.
  • We added some Linux and macOS screenshots to see how these integrations look like.
• Axosoft:
  • New parameter: Pending status list - You can now configure the Axosoft list of statuses considered as "pending".
• Polarion:
  • Configure the Default Repository parameter to get support for multiple repositories for Polarion.
  • Now, we added support for distributed scenarios with Polarion.
• Jira:
  • Now, the Custom Field ID parameter is optional.
  • New parameter: Issue query limit - You can now configure the maximum number of returned results in the Create Branch dialog.
  • New parameter: Resolved issue states - You can now define a list of status names to be considered as "resolved".

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.