# Mantis integration

> Integrate Mantis with Unity Version Control and track issues.

Learn how to configure and use the Mantis extension. The Mantis extension is compatible with Mantis versions 1.11.4, 1.1.0, 1.1.8 and higher.

## Configure the Mantis integration

Configure the Mantis integration to work with Unity Version Control (UVCS) for the [Mantis server](#configure-the-mantis-server) and the [UVCS client](#configure-the-client).

### Configure the Mantis server

To set up the Mantis extension functionality, copy the script file `plastic.php` (included on `plasticscm_install_path/client/extensions/mantis`) to the Mantis installation folder.

### Configure the client

There are different methods to configure the client depending on your operating system:

* [Configure the client on Windows](#configure-the-client-on-windows)
* [Configure the client on Linux and macOS](#configure-the-client-on-linux-and-macos)

Regardless of your operating system, you need to [configure the Mantis parameters](#mantis-parameters).

#### Configure the client on Windows

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 the repository that you want to apply binding to:
   1. If you want to bind to all of your repositories with the issue tracker, select **Repositories**.
   2. If you want to bind to a particular repository, select that repository.
5. Select the working mode you want to use:
   1. **Bind issues to Unity VCS branches (recommended)**: links one task to one branch.
   2. **Bind issues to Unity VCS changesets**: links one or more tasks to one or more changesets.
6. Configure the [Mantis parameters](#mantis-parameters).

#### Configure the client on Linux and macOS

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

1. Create the path `issuetrackers/<server_port>/<repository>` , and replace `repository` with one of the following values:
   1. The name of the repository you want to link to the issue tracker.
   2. `allrepos` to link all of your repositories to the issue tracker.
2. Copy the `mantis.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 `mantis.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 [Mantis parameters](#mantis-parameters).
5. Edit your `client.conf` file to add the following key:
   ```text
   <Extensions>
       <Extension 
   AssemblyFile="plasticscm_install_path/client/extensions/mantis/mantisextension.dll" />
   </Extensions>
   ```

> **Note:**
>
> You can also set a [global extension configuration](./global-extension) on the server.

### Mantis parameters

Use the following parameters to further configure your Mantis integration:

| Parameter             | Description                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Mantis Base URL**   | Specify the URL where the Mantis server is installed and runs.                                                                       |
| **User name**         | Enter a valid Mantis user.                                                                                                           |
| **Branch prefix**     | An optional parameter if you work in the task on branch mode. Specify the branch prefix to bind those UVCS branches to Mantis tasks. |
| **Plastic PHP path**  | The directory of the php file.                                                                                                       |
| **Show bug PHP path** | Show the PHP path of bugs.                                                                                                           |
| **Encoding**          | Edit this value if you need to change the encoding. The default is `UTF-8`, which works for most languages.                          |

## Use the Mantis integration

Use one of the following working modes for your Mantis integration:

* [Task on branch](#task-on-branch-workflow)
* [Task on changeset](#task-on-changeset-workflow)

Find issue information in the Mantis Extension panel. You can open the issue in the browser, add a new issue, or delete an issue. If you select the **Open issue in browser** icon, or double-click on the Mantis task, UVCS opens the associated issue in a browser window.

### Task on branch workflow

Task on branch is the default working mode. Each Mantis task links to a branch in Unity Version Control (UVCS).

#### Link a branch to an issue

The branch name connects the branch to a Mantis issue:

1. Create an issue in Mantis. Mantis assigns each task a number. Refer to the Mantis documentation on [Issue lifecycle and workflow](https://mantisbt.org/docs/master/en-US/Admin_Guide/html-desktop/#admin.lifecycle).
2. Create a new branch in UVCS. To link the branch, name the branch with the Mantis task number, preceded by the branch prefix.
   * For example, if you configured the branch prefix `task`, and the Mantis task number is 4, name the branch `task004`.

### Task on changeset workflow

The task on changeset working mode allows you to link multiple changesets to multiple branches.

#### Link a changeset to an issue

Use the UVCS desktop application to link changsets to Mantis issues:

1. Create an issue in Mantis. Mantis assigns each task a number. Refer to the Mantis documentation on [Issue lifecycle and workflow](https://mantisbt.org/docs/master/en-US/Admin_Guide/html-desktop/#admin.lifecycle).
2. Make the changes in UVCS.
3. On the **Pending Changes** tab, select **Show tasks** to open the tasks side panel.
4. Select the **Add new issue** (**+**) icon.
5. Select issues from the list of pending tasks, or enter a comma-separated ID list if you can’t find the correct issue.
6. Select **OK**.