# Configure integration with Atlassian Jira > Integrate Atlassian Jira with Unity Version Control to track Jira issues. 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](#jira-configuration) to work with UVCS. * [Configure your UVCS client](#configure-the-client-for-atlassian-jira) to work with JIRA. * Configure the JIRA integration for use with [multiple projects](#configure-jira-for-multiple-projects). * [Map fields from JIRA](#map-jira-fields) 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](https://support.atlassian.com/jira-cloud-administration/docs/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: > **Note:** > > In JIRA Cloud, the **Accept remote API calls** option is enabled by default. 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 tracker**s 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](#configure-the-client-on-windows) or [Linux and macOS](#configure-the-client-on-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](#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//` , 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: `/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](#jira-parameters). 5. Edit your `client.conf` file to add the following key: ```text ``` > **Note:** > > You can also set a [global extension configuration](../global-extension) on the server. ### JIRA parameters | Parameter | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Host** | Specify the URL where the JIRA server is located. The URL must contain the port where the JIRA server runs. | | **User name and Password** | Specify the JIRA credentials used to log into JIRA and log the changes. Note: For JIRA Cloud, the User name must be the email address of the account, and the Password must be an API token. | | **Branch prefix** | Optional parameter if you work in the task on branch mode. The prefix links UVCSbranches to JIRA tasks. For example, 'scm' links branches that start with 'scm'. | | **Project Key** | Specify the key of the JIRA project that you want to link to UVCS. To [work with multiple projects](#configure-jira-for-multiple-projects), this value has to be `MULTIPLE_PROJECTS`. | | **Custom Field ID** | Optional parameter to specify the identifier of the custom field that UVCS uses to log checkin information on JIRA tasks. If not set, UVCS doesn’t log any information to JIRA tasks so you can only link tasks to changesets or branches but not update the task. Note: Next-gen projects don’t support the Custom Field ID. Leave it blank to add checkin info as a comment. | | **Use LDAP credentials if available** | If Plastic SCM client authentication mode is LDAP, select this parameter to reuse those credentials for JIRA login. Both the UVCS server and JIRA must share the same LDAP directory. | | **Use default proxy credentials** | Automatically set proxy credentials with default credentials for all JIRA extension connections. | | **Issue query limit** | Manually tune the maximum number of returned results in the Create Branch dialog. The default limit is 51. | | **Resolved issue states** | Specify a comma-separated list of status names to consider as resolved. The default status name is **Done**. UVCS doesn’t display resolved issues on the Create Branch dialog by default. | | **Issue types** | Filters issues by their type. Use a comma-separated list, for example, you can only display bug or task issues and filter out other types. If you use [Linux or macOS](#configure-the-client-on-linux-and-macos), you can copy and edit the following line, and paste it in your jira.conf file: `Name=Issue types;Value=Bug,Task;Type=Text;IsGlobal=False`. | | **Fields mapping** | Map the fields from the JIRA issue that you want to display on the task information panel in the Branches or Changesets tabs. | | **REST URL** | Specify the path base URL for the REST API. The default value is `/rest/api/2/`. | | **TASK URL** | Specify how to build task page URLs. The default value is `/browse/`. For example, if `Host` is set to `https://my.server.com/jira` and the `TASK URL` is set to `/ticket/`, and the extension has to build the URL to browse ticket `PRJ-001`, the resulting URL is `https://my.server.com/jira/ticket/PRJ-001`. | | **Status transition** | Change the status of the associated issue based on a changeset comment. Refer to [transition JIRA statuses](./use-jira#transition-jira-statuses). | ## 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](#configure-the-client-for-atlassian-jira), add the value `MULTIPLE_PROJECTS` to the **Project Key** parameter. > **Note:** > > If you use Linux or macOS, remember to update the required values in your `jira.conf` file. ### 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: `_-` 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](#field-mapping-syntax), separated by `|` characters. > **Note:** > > If you work on a Linux or macOS system, remember to update the required field in the `jira.conf` file. ### Field mapping syntax Use the following syntax for the field mapping parameter: ```text [ -> [ | -> [ | ... ] ] ] ``` #### 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: | `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` | #### 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. ```text issue.Fields.Project.Name->Description|issue.Fields.Reporter.Name->Owner|issue.Fields.Description->Title ```