# Integration with Axosoft OnTime

> Integrate Axosoft issue tracking with Unity Version Control and track issues.

Learn how to configure and use the Axosoft OnTime extension with Unity Version Control (UVCS). You can use the Axosoft integration for Axosoft v14 and higher.

## Configure the Axosoft server

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

### Obtain the Axosoft API key

To work with Axosoft, the UVCS client needs the `client-id` and `client-secret` parameters:

1. Select **Tools** > **System Options**.
2. In the System Settings window, select **Axosoft API Settings**.
3. Select **Enable API**.
4. Select **Manage API Keys**.
5. In the new window, select **Add** to obtain the two parameters:
   1. Enter an application name.
   2. Copy the **Client ID** and **Client Secret** values.
   3. Select **Save.**

Refer to the Axosoft documentation on how to [obtain a private API key](https://developer.axosoft.com/getting-started/private-applications.html).

### Create a custom field

Create a custom field that UVCS can use to log changes in linked changesets:

1. Select **Tools** > **Fields** > **Custom Fields**.
2. On the Bugs tab, select **Add**.
3. Enter the field label `Plastic SCM` and select **Large Text** as the field type.
4. Select **Save**.

Refer to the Axosoft documentation on how to [add a custom field](https://support.axosoft.com/fields/custom-fields).

## Configure the client for Axosoft

Configure your Unity Version Control (UVCS) client to work with your Axosoft integration.

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 Axosoft parameters](#axosoft-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 **Axosoft OnTime**.
5. 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.
6. 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.
7. Configure the [Axosoft parameters](#axosoft-parameters).

### Configure the client on Linux and macOS

Set a local Axosoft 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 `ontime.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 `axosoft.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 [Axosoft parameters](#axosoft-parameters).
5. Edit your `client.conf` file to add the following key:
   ```text
   <Extensions>
       <Extension 
   AssemblyFile="plasticscm_install_path/client/extensions/ontime/ontimeextension.dll" />
   </Extensions>
   ```

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

### Axosoft parameters

Use the following parameters to further configure your Axosoft integration:

| Parameter                                                                 | Description                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Axosoft Root URL**                                                      | Provide the required Axosoft root URL of the UVCS Axosoft extension to work.                                                                                                                                                                                                                 |
| **User and Password**                                                     | Ensure each UVCS user has an Axosoft account and uses their Axosoft credentials to connect UVCS to the Axosoft server.                                                                                                                                                                       |
| **Defects prefix****Tasks prefix****Features prefix****Incidents prefix** | Configure the branch prefixes to bind them to Axosoft objects when you use task on branch mode. For example, if you [enable mapping](https://support.axosoft.com/items/importing) for Axosoft Defects and Axosoft Tasks, you can use `def` to link branches to Defects and `task` for Tasks. |
| **Client ID and Client Secret**                                           | Fill in the tokens generated from the Axosoft admin panel to enable the integration.                                                                                                                                                                                                         |
| **Plastic SCM custom field**                                              | Create a custom field on Axosoft for logging UVCS checkin information.                                                                                                                                                                                                                       |
| **Pending status list**                                                   | Edit the list of statuses that UVCS considers as pending. This defines which tasks UVCS displays in the Create Branch dialog. Use a comma-separated values string.                                                                                                                           |

## Use the Axosoft integration

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

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

Find issue information in the Axosoft 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 Axosoft task, UVCS opens the associated issue in a browser window. UVCS also uses the custom field in Axosoft to log every checkin for a linked branch or changeset.

### Task on branch workflow

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

#### Link a branch to an issue

The branch name connects the branch to a Axosoft issue:

1. Create a work item in Axosoft. Axosoft assigns each work item an identification number. Refer to the Axosoft documentation on how to [add items](https://support.axosoft.com/quick-start#:~:text=has%20any%20subitems.-,Adding%20items,to%20go%20back%20and%20edit.).
2. Create a new branch in UVCS. To link the branch, name the branch with the Axosoft bug identification, preceded by the branch prefix if you configured one.
   * For example, if you configured the branch prefix `task`, and the Axosoft identification 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 changesets to Axosoft work items:

1. Create a work item in Axosoft. Axosoft assigns each bug an identification number. Refer to the Axosoft documentation on how to [add items](https://support.axosoft.com/quick-start#:~:text=has%20any%20subitems.-,Adding%20items,to%20go%20back%20and%20edit.).
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**.

To log the checkin information in the related Axosoft issue, enter a comment in the **Checkin comments** field, start the comment with the `#` character followed by the issue key. For example, `#def4: Updates`.