Octet Agile's JIRA connectivity project.

The purpose of this project is to provide a set of connectivity utilities to Jira APIs.

Issues

Get Issues

Purpose : This service method provides issue's information like :

• The current snapshot of a jira's issue.
• All the snapshot of a jira's issue based on its history.

This service need three arguments.

const oaJira = require('oa-jira');
return oaJira.issues.get(CONNECTION, 'ISSUE KEY', OPTIONS);

| Argument | Type | Description | |------------|----------|---------------------------------------------------------------------------------| | CONNECTION | Object | The credential use by the library to call jira issue get rest API (2.0). | | ISSUE KEY | string | The issue key, as jira provide it to you. | | OPTIONS | Object | The settings used by the method to provided the data as expected by the caller. |

The connection argument is an object that must contains three mandatory named values. This libray used the basic authentication to connect to jira like descibe in here by Atlassian : Basic auth for REST APIs.

const connection = {
  urlBase : '...url base of your jira...', 
  user : '...your user\'s login...', 
  token : '...your jira\'s token...', 
};

The issue key argument is a string equals to your jira issue key, this one is mandatory. The options argument is a mandatory object.

const options = {
  mode : 'the mode : SNAPSHOT or CHANGELOG', 
  fields : [AN_ARRAY_OF_FIELDS_SETTINGS], 
};

In the options, the mode must have one of these string values :

• 'SNAPSHOT' : The method will only return the last snapshot of the issue (the current field's value expected).
• 'CHANGELOG' : The method will return the last snapshot of the issue (the current field's value expected) and the issue's history, change by change with the snapshot associated.

All other given values will result on a promise rejection.

For the option fields, when calling the Get issue service of Jira Rest Api, the response of this one contains the "fields" part (used to identify the snapshot) and the "changelog" part. The fields options are used to identify which fields will be retrieved and how they have to be parsed for both parts.

The fields is an array where each element is an object.

const fields =[{ 
  name: 'jira name',
  parser: (value) => {Promise.resolve(value)},
  changeParser: change => Promise.resolve({ source: change.from, target: change.to }),
  parsedName: 'expected name'
}];

Each object must have four named values.

• name : The name of jira's fields expected.
• parser : A function that must return a Promise, which delegate to library consumer, to operate the format's conversion from jira format to its own expected one for each fields.
• changeParser : A function that must return a Promise, which delegate to library consumer, to operate the format's conversion from jira format to its own expected one for each changelog's items.
• parsedName : The expected name which will replace the jira's one. The promise must resolve an object with a source and or a target named attribute.

When you call the get issue, the first step is to focus on what you want to retrieve from jira.

In this example, we want to focus on the name of status and the summary of the issues.

The response in jira will looks like natively to that :

"key": "XYZ-001",
"fields" : {
  "summary": "A task.",
  "status": { "name": "In Progress" },
  "created": "2024-04-01T02:00:00.000+0200"
},
"changelog": {
  "histories": [
    {
      "created": "2024-04-02T02:00:00.000+0200",
      "items": [
        { "fieldId": "status", "fromString": "To Do", "toString": "In Progress" }
      ]
    }
  ]
}

The fields options could be like that :

const nameParser = value => Promise.resolve(value?.name);
const passthroughParser = value => Promise.resolve(value);

const changeParserTS = change => {
  return Promise.resolve({
    source: !change.fromString ? undefined : change.fromString,
    target: !change.toString ? undefined : change.toString
  });
};

const fields = [
  { name: 'status', parser: nameParser, changeParser: changeParserTS , parsedName: 'status' },
  { name: 'summary', parser: passthroughParser, changeParser: changeParserTS , parsedName: 'title' },
];

With the previous fields options, in the snapshot mode, the result will be :

{
  "data": {
    "key": "XYZ-001",
    "title": "A task.",
    "status": "In Progress",
  }
}

With the previous fields options, in the changelog mode, the result will be :

{
  "data": {
    "key": "XYZ-001",
    "title": "A task.",
    "status": "In Progress",
  },
  "last": "2024-04-02T02:00:00.000+0200",
  "first": "2024-04-01T02:00:00.000+0200",
  "snapshots": {
    "2024-04-02T02:00:00.000+0200": {
      "time": "2024-04-02T02:00:00.000+0200",
      "data": {
        "key": "XYZ-001",
        "title": "A task.",
        "status": "In Progress",
      },
      "changes": { "complexity": { "source": "To Do", "target": "In Progress" } },
      "metadata": { "previous": "2024-04-01T02:00:00.000+0200" }
    },
    "2024-04-01T02:00:00.000+0200": {
      "time": "2024-04-01T02:00:00.000+0200",
      "data": {
        "key": "XYZ-001",
        "title": "A task.",
        "status": "To Do",
      },
      "changes": {
        "title": { "target": "A task." },
        "status": { "target": "To Do" },
      },
      "metadata": { "next": "2024-04-02T02:00:00.000+0200" }
    }
  }
}