Configure Atlassian JIRA integration#

Configure Atlassian JIRA and your Unity Version Control (UVCS) client so that you can use the JIRA integration. You can set up the following configurations:

• Configure your JIRA to work with UVCS.
• Configure your UVCS client to work with JIRA.
• Configure the JIRA integration for use with multiple projects.
• Map fields from JIRA to display in UVCS.

JIRA configuration#

Configure Atlassian JIRA so that JIRA can connect with Unity Version Control (UVCS).

Create a custom field#

Create a custom field so that UVCS can link changesets or branches to a JIRA issue.

Refer to the Atlassion documentation on how to create a custom field.

Make sure to configure the following options:

1. Select Text Field (multi-line) as the field type.
2. Select Default Screen as the association of the field to screens.

You can use any name, because UVCS uses the field ID to identify the field. You can find the ID in the URL on the screens page. For example, fieldID=customfield_1000.

Accept remote API calls#

Ensure that UVCS can access JIRA’s remote API:

1. Under the System section, select General Configuration.
2. Enable the Accept remote API calls option.

To test that the connection works in the UVCS application, select the Test Connection button in the Issue trackers section of the Preferences window.

Configure the client for Atlassian JIRA#

Configure your Unity Version Control (UVCS) client to work with the JIRA integration. You can configure the client in Windows or Linux and macOS.

Configure the client on Windows#

Configure the JIRA integration in the UVCS desktop application:

1. In the Unity DevOps Version Control desktop application, select the context menu, then select Preferences.
2. Select Issue Trackers.
3. Select Bind to this issue tracking system.
4. Select Atlassian JIRA.
5. Select the repository that you want to apply binding to:
   • If you want to bind to all of your repositories with the issue tracker, select Repositories.
   • If you want to bind to a particular repository, select that repository.
6. Select the working mode you want to use:
   • Bind issues to Unity VCS branches (recommended): links one task to one branch.
   • Bind issues to Unity VCS changesets: links one or more tasks to one or more changesets.
7. Configure the JIRA parameters.

Configure the client on Linux and macOS#

Set a local JIRA configuration on a Linux or macOS machine:

1. Create the path issuetrackers/<server_port>/<repository> , and replace repository with one of the following values:
   • The name of the repository you want to link to the issue tracker.
   • allrepos to link all of your repositories to the issue tracker.
2. Copy the jira.conf example into the new path from one of the following locations:
   • Linux: <plasticscm_install_path>/client/extensions/config_samples
   • macOS: /Applications/PlasticSCM.app/Contents/IssueTrackerConfigSamples.
3. In the jira.conf file, edit the WorkingMode parameter to assign one of the following values:
   • TaskOnBranch: links one task to one branch.
   • TaskOnChangeset: links one or more changesets to one or more branches.
4. Configure the JIRA parameters.
5. Edit your client.conf file to add the following key:

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

JIRA parameters#

Configure JIRA for multiple projects#

Configure the Unity Version Control (UVCS) client to work with a multi-project configuration. A multi-project configuration allows each branch to explicitly contain the project key of the related task so you don’t define a global project key for all branches.

Add the project key#

When you configure the client for JIRA, add the value MULTIPLE_PROJECTS to the Project Key parameter.

Link branches#

If you work with multi-project configuration, you need to distinguish which branch links to which project.

Use the following format to name your UVCS branches:

<BranchPrefix>_<ProjectShortName>-<IssueID>

For example, to link a branch with the prefix task to JIRA issue VCS-1, use the branch name task_VCS-1.

Map JIRA fields#

Map fields from a JIRA issue to display them on the task information panel in the Branches or Changeset tabs in the Unity Version Control (UVCS) desktop application.

Configure the field mapping#

Configure the Fields mapping parameter on Windows:

1. Select the context menu and select Preferences.
2. Select the Issue tracking tab.
3. Enter the field name (from->to) pairs, separated by | characters.

Field mapping syntax#

Use the following syntax for the field mapping parameter:

[ <jira_field_name> -> <vcs_property_name> [ | <jira_field_name> -> <vcs_property_name> [ | ... ] ] ]

Available UVCS property attributes#

The to attribute in the name pair describes the UVCS field that the vcs_property_name refers to. You can use the following attributes:

• Id
• Owner
• Status
• Title
• Description

Available JIRA field attributes#

The from attribute in the name pair describes the filed in the JIRA issue that the jira_field_issue refers to. You can use the following attributes:

Use a custom field#

To map a custom field, use the customFieldValues modifier with the custom field ID number.

For example, customFieldValues[10000]->Description.

Field mapping example#

For example, the following is a valid example for the following configuration:

• Displays the project key in the description.
• Displays the JIRA description as the title.
• Displays the issue creator as the owner.

issue.Fields.Project.Name->Description|issue.Fields.Reporter.Name->Owner|issue.Fields.Description->Title