Skip to main content
Skip table of contents

[Connectors] Jira connector

A Jira integration can be configured, in order to sync the Jira issues of defined projects with YOOI instances.

It is possible to do so via Admin settings > Integration.

Initialisation on YOOI

  1. In Admin settings > Integration, create a new Integration and give it a name, for example “Jira Integration”.

  2. Generate an API Token and copy the value. Unless there is a very specific need, the JIRA connector token must be chosen preferentially with no expiration date.

The token will never be accessible again, copy the value in a secure place

  1. Give to YOOI :

    • The API token

    • The integration Id (see photo below) or integration name

Integration Id

  1. YOOI needs to re-deploy your app with those information and add a feature-flag.

  2. Create or have these concepts on YOOI :

    1. (mandatory) A concept representing the Jira projects. This concept needs to have two mandatory fields :

      1. An External Key

      2. An Embedding field with the concept below, which represents the link between the project and the issues.

    2. (mandatory) A concept representing the Jira issues. This concept needs to be embedded by the concept representing the Jira projects. It also needs to have those mandatory fields :

      1. An External Key

      2. (At least) One workflow field, which will be mapped with the Jira Status.

    3. (mandatory) A concept representing the status of the Jira issues. This concept is the one used by the workflow field mentioned above.

    4. (optional) A concept representing the types of the Jira issues (bug, epic, etc). This concept will be used when creating Jira issues from YOOI. As a consequence, it is mandatory if you want the creation from YOOI to Jira to be enabled.

    5. (optional) A concept representing the Jira components. This concept needs to be embedded by the concept representing the Jira projects. This concept needs to have a mandatory field:

      1. An External Key

      2. A text field for the name of the component.

Only one JIRA connector is possible per platform.

Initialisation on Jira

  1. Create an account with the necessary rights to the elements that the connector needs to modify.

  2. Put the credentials on the JSON file. (see Configuration below)

  3. Set up a Jira Webhooks (https://developer.atlassian.com/server/jira/platform/webhooks/).

    1. If Jira is in Cloud version, configure a secret when setting up the Jira Webhooks. Keep this secret, as it will be needed later. For the URL in the configuration of the Webhook use : https://{applicationdomain}/connector/jira/webhook.

    2. If Jira is in Data Center version, generate a random secret (a password generator can be used for generating this secret). For the URL in the configuration of the Webhook use : https://{applicationdomain}/connector/jira/webhook/{secret}. Keep this secret, as it will be needed later.

  4. Ensure that Exclude body is not selected in the configuration of the Webhook.

Issues synchronization behaviour

Jira issues are synchronized with YOOI instances for mapped Jira Projects. Everything that is described below is valid for synchronization of Issues (not Projects).

Creation

YOOI → Jira

  • Trigger : YOOI instance is embedded in a mapped project and has :

    • A name

    • A mapped status

    • A mapped issue type

If any of those above isn’t set, the issue will not be created in Jira.

  • Actions : Creates the Jira issue and populates the fields mapped in the connector configuration.

Jira → YOOI

  • Trigger : A Jira issue of a mapped project is created.

  • Actions : Creates the YOOI instance based on mapping and populates the fields mapped in the connector configuration.

Update

YOOI → Jira

  • Trigger: a change of value on fields mapped by the connector occurs on a YOOI instance that is synchronized with a Jira issue.

  • Rules (Should all be met to send update) :

    • Instance has a mapped status → if the status is not mapped, then no changes can be made (even if the update is on another field)

    • Instance has a non null summary (Instance name is not empty) → we cannot update an Jira issue without a name

  • Exceptions :

    • If the event triggers an update that is not doable on Jira (Status that does not respect Jira workflow for example) then, the update will not be done on JIRA. But as soon as any update is made on that instance (When doing an update YOOI → JIRA, Jira send us an event that says that an update has been made on the instance, so we also do an update Jira → YOOI. In resume, an update YOOI → Jira always triggers an update Jira → YOOI also), the field on YOOI that could not have been synchronized on Jira, will be set to the Jira value (Jira “always” wins in the end).

  • Actions : Update of the Jira issue.

Jira → YOOI

  • Trigger : An event occurs on a Jira issue synchronized with YOOI, on a field mapped in the connector mapping.

  • Actions : Update of the YOOI instance synchronized with the Jira issue.

Deletion

YOOI → Jira

Behavior

  • The Jira issue is not deleted

  • As soon as the connector is restarted, if the issue has not been deleted on JIRA, it will be re-created.

  • → Do not delete instances on YOOI that are synchronized with Jira, if you do not delete it on Jira also, because they will be re-created.

Jira → YOOI

Behavior

  • The Jira key of the YOOI instance is cleared.

Connector restart

The connector restarts when the YOOI app restarts or the JSON configuration is changed.

On connector restart, we re-fetch all Jira issues that are in mapped projects.

As a consequence of that, if we delete an instance in YOOI that is synchronized with JIRA, and if that issue is not deleted on Jira, on connector restart or configuration update the issue will be re-fetch.

Another consequence of that is that if a change on YOOI could not have be done on Jira (for any reason, like for example a Status that does not respect the Jira workflow), then, when the instance is updated again later (by a connector restart or a configuration update), the Status will be changed on YOOI side to match the Jira Status.

Configuration

Authentication

To communicate with Jira, YOOI need to have access to your account.

YOOI supports two kinds of authentication:

CODE 
"jiraAuth": {
  "type": "Basic",
  "userId": "YouJiraApiUser",
  "password": "YourJiraApiToken"
}
CODE 
"jiraAuth": {
  "type": "Bearer",
  "token": "YouJiraPATToken"
}

Choose the appropriate configuration depending on your authentication.

Field configuration

Text fields

Jira can imposes limitations on text fields. To handle these restrictions, an optional field configuration can be defined.

Character Limit Handling

If a characterLimit is specified, any text exceeding this limit will be truncated and end with “…” to indicate that the text has been cut off in Jira..

New Line Handling

If withNewLine is set to false, each new line will be replaced with a space.

Enumeration fields

Enumeration field options are not synchronized in real time like other Jira concepts. Their behavior follows these rules:

  1. Creation on first use
    An enumeration value is created in YOOI only when it is assigned to a Jira issue.
    If a value exists in Jira but is not used in any issue, it will not appear in YOOI until it is assigned to at least one issue.

  2. Name updates are manual
    Once an enumeration value is created in YOOI, changes to its name in Jira are not automatically reflected. Any updates to the name must be made manually in Yooi.

  3. Mapping requirements
    To make the enumeration list work correctly, the targeted concept of the association mapped with the enumeration must be mapped with:

    • A text field for the Name

    • An External Key (mandatory)

    The External Key establishes the link between the YOOI instance and the enumeration values in Jira. This ensures that the correct value is referenced even if the name changes later.

Retrieving Field IDs

To find the field IDs, the Jira API can be used, or the YOOI team can provide assistance.

JSON 
{
   "fieldConfigurations":{
      "fieldId":{
         "withNewline":false,  //true by default
         "characterLimit":255 //infinite by default
      }
   }
}

Project configuration

You can filter which issues of a project are pulled from JIRA by specifying an optional project-level configuration.

JSON 
{
   "projectConfiguration":{
      "ProjectKey":{
         "jiraIssueCreationJqlFilter": "status=Backlog"
      }
      "ProjectKey":{
         "jiraIssueCreationJqlFilter": "status=InProgress OR status=Done"
      }
   }
}

Creation

  • YOOI → Jira: The issue will be created regardless of the JQL query.

  • Jira → YOOI: The issue will be created only if it matches the JQL query.

Edition of existing issues

All instance already synchronized on YOOI will continue to be synchronized in both way.

How to create JQL query

JQL queries can be created directly in Jira:

  1. Go on https://{YourDomain}.atlassian.net/{ProjectKey}/issues

  2. Create your filters as normal filters

SCR-20250407-ojhl-20250407-141825.png

  1. Switch to the JQL view to see the generated query and copy it.

SCR-20250407-olcx-20250407-142333.png

  1. Do not include:

    1. The project = "CMP" part in your JQL, as the project is already defined via the ProjectKey in the JSON configuration.

    2. Any ORDERBY clause, as it is not relevant for filtering purposes.

JSON Configuration

You need to create a JSON as below :

JSON 
{
  "jiraUrl": "https://{YourDomain}.atlassian.net",
  "jiraAuth": {
    "type": "Basic",
    "userId": "YouJiraApiUser",
    "password": "YourJiraApiToken"
  },
  "isJiraDataCenter": true or false, (false for Jira Cloud version)
  "jiraApiVersion": 2 or 3,
  "webhookSecret": "YourJiraWebhookSecret" (generate by Jira if Jira Cloud, generated by you if Jira Data Center),
  "fieldConfigurations":{
      "summary":{
         "withNewline":false,
         "characterLimit":255
      }
   },
   "projectConfiguration":{
      "projectId1":{
         "jiraIssueCreationJqlFilter": "status=Backlog"
      }
      "projectId2":{
         "jiraIssueCreationJqlFilter": "status=InProgress OR status=Done"
      }
   }
}

For jiraApiVersion you need to choose between 2 or 3, depending on your JIRA.

And then, you need add this JSON in Configuration, where it is specified Add configuration json :

Add a json configuration

Mapping

You can map Jira issues and Jira projects with the concepts mentioned above (Initialisation on YOOI) in the mapping section.

For the first synchronization, a valid JSON configuration is necessary to display the mapping. The connector needs to communicate with JIRA to retrieve, in particular, status and the list of fields.

For Projects and Issues, you can map the fields you want, as well as the mandatory fields. The left-hand column shows the JIRA fields that you can map to the YOOI fields in the right-hand column. You can map Jira fields with YOOI fields based on the type of data of the field (a Date needs to be mapped to another Date).

Mapping Description on Jira (left) with the field Description in YOOI (right)

Jira projects

For Project, mandatory fields are :

  • Project Key

  • Jira Issues list (to Embed Jira issues of this project).

You need to create as many instances of the concept as there are projects you want to synchronize. And then, you must filled manually in YOOI the Project Key. (You can have instances of the mapped concept that have an empty Project Key, and therefore that are not linked to JIRA.)

Once the Project Key is completed, the connector will :

  • Fill the Jira Board Link

  • Fetch all issues of this project

Once filled, the Project Key should not be modified.

Jira issues

Fields that can be mapped for Jira issues are all available in this section. Those type of field are available for mapping :

  • Date

  • Text

  • Number

  • Association many to one (n-1) for Issue type.

  • External key

  • Workflow

Mandatory fields are :

  • Status (type Workflow)

  • Summary

  • Issue key (type External Key). It is thanks to this key that the connector knows which YOOI instance is mapped to which Jira issue.

  • Embedding with Project

  • Issue type (asso n-1) if you want the creation from YOOI to Jira to be enabled.

The External Key, filled by the connector, should not be modified on mapped issues. To prevent any mistakes, it might be a good idea to make the External Key field only updated by integration.

Status & Issue type

In the mapping section, you will also find :

  • The mapping for Status (mandatory, as a instance that does not have a mapped status cannot be synchronized with Jira). Take into account the Jira workflow when doing this mapping (YOOI connector cannot override the Jira Workflow). The Jira Status needs to be mapped with the concept modelling the workflow mapped for the Jira Issues Status.

  • The mapping for Issue type. It is necessary if you want to map the Issue Type field (asso n-1) of Jira issues, and mandatory if you want the creation from YOOI to Jira to be enabled. If an YOOI issue type in not mapped with a Jira issue type, the YOOI instance that has that given issue type cannot be created on JIRA.

For Status and Issue type the mapping is not done at field level (as for Projects and Issues) but at instance level. For example, you can map the status Done (Jira) with the status Done (YOOI).

Mapping the status Done Jira (left) to the status Done YOOI (right)

(Optional) Jira components

For Component, mandatory fields are :

  • Component ID (External Key)

  • Component Name

  • In Issue mapping : Components(association n-n to the Jira component concept)

    • A filter should be defined in the field configuration to only display the related components of the project. In fact, components are projects related only. A filter is thus needed because it addresses all those matters:

      • Components cannot be shared between Projects (i.e. it is not possible to associate an Issue from a Project to a Component from another Project).

      • Components on YOOI should be created via a Project only, in order to be created on Jira as well.

      • Component without Project should not be associated to an Issue because they will never be synced on Jira. As a result, at the next Jira <> Yooi update, the associations with these given Components will be removed.

  • In Project mapping : Jira Components List (embedding of the Jira component concept).

It is important to note that Jira does not offer a webhook for Components. As a result, when a Component is created, deleted or modified on the Jira side, no event is sent to Yooi. However, to compensate for this, each time an Issue that is synced with Jira is updated, a Component pull is performed for the given Project in order to make any necessary updates.

Updates

When changes are made to the mappings, they will only take place after the connector re-start (restart of the app, or json configuration update). In order to do so, you need to ask YOOI a restart of your application or update the configuration json (you can do so by putting a blank space a the and of the json, for example).

Permissions

You need to give the connector rights to the mapped concept.

For Status and Issue type (if mapped), only a View right is necessary.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close