Project Management Integration
==============================

CodeScene supports integration with project management (PM) systems, 
like JIRA_. Issues in the PM system are mapped to the corresponding commits in
the version control system.

.. _JIRA: https://www.atlassian.com/software/jira

Repository Configuration
------------------------

By default, PM integration is disabled (see :numref:`pm-integration-disabled`).
Enable by checking the 'Enabled' checkbox.

.. figure:: pm-integration-disabled.png
   :alt: Enable the project management integration
   :name: pm-integration-disabled
   :width: 50%

   Check 'Enabled' to enable the project management integration.

Enabling the integration lets you edit the remaining fields (see
:numref:`pm-integration`):

API URL
    The base URL of the PM integration service. If you have deployed the JIRA
    integration in Tomcat, the URL will likely be `http://localhost:8080/codescene-enterprise-pm-jira`.
API Credentials
    The credentials needed to access the PM integration service. Note that 
    these are the credentials that are configured in the PM integration service.
Test Connection
    Try connecting using the specified API URL and credentials, and check the
    status of the PM API, before saving the configuration. Use this option to
    verify the connection before running an analysis.
External Project ID
    The project identifier in the external system. If the external system is 
    JIRA, this field should contain the `JIRA project key`. For example, if
    issues are named `MYPROJ-123`, the project key (and thus the external
    project ID) is `MYPROJ`.

.. figure:: pm-integration-enabled.png
   :alt: A complete project management integration configuration
   :name: pm-integration
   :width: 50%
   
   A configuration sample for project management integration.

You can add multiple JIRA projects here by separating them with a semicolon, `;` as
shown in :numref:`pm-integration-multi`

.. figure:: pm-integration-multi-projects.png
   :alt: Project management integration with multiple projects
   :name: pm-integration-multi
   :width: 50%

   A configuration sample for integration with multiple projects.
   
Ticket ID Configuration
-----------------------

Each item from the PM integration has an ID that needs to match the *Ticket
IDs* in CodeScene. For example, when integrating with JIRA, the mapping
needs to extract the ID part from the JIRA issue key.  In addition to mapping
item IDs from the PM system, the ticket IDs need to be extracted from the VCS
logs, which is called *Ticket ID Mapping*. :ref:`temporal-coupling` explains
Ticket ID Mapping in greater detail.  :numref:`jira-issue-to-ticket-id-mapping`
illustrates how both mappings extracts IDs with the same format.

.. figure:: jira-issue-to-ticket-id-mapping.png
   :alt: Illustration of ticket ID mapping
   :name: jira-issue-to-ticket-id-mapping
   :width: 50%

   Ticket IDs are extracted from the VCS logs using Ticket ID Mapping, and
   Project Management Item IDs are mapped from JIRA issue keys using a
   configured pattern in the JIRA integration service.

Ticket ID Configuration for Multiple JIRA Projects

Please note that in case you integrate with multiple JIRA projects, you may have to use
a different Ticket ID configuration in case the ID's may overlap.

For example, let's say you integrate with three projects. Each project will have a JIRA ID
like `FRONTEND-123`, `BACKEND-765` and so on. In this case you want to use the whole
JIRA ID as a Ticket ID to ensure that they are unique. In addition, you need to specify a
regular expression that will match *all* your possible JIRA ID ranges

:numref:`pm-integration-multi-tickets` shows an example on such a configuration.

.. figure:: pm-integration-multi-tickets.png
   :alt: Illustration of ticket ID mapping for multiple projects
   :name: pm-integration-multi-tickets
   :width: 50%

   Ticket ID specification that matches items from multiple JIRA projects.
