VSA: Support Jira issues

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Close this issue

Problem to solve

Customers that are using Jira for issue management want a way to view issue duration close-open) into VSA. They also want to see issue work breakdown based on their Jira Labels (some directly related to SAFE labels that we should support by default)

Proposal

There are 3 use cases:

VSA Stages based on Jira event.
Tasks by type breakdown based on Jira Labels. (out of scope for this issue)
DORA metrics integration based on Jira/SNOW incidents. (out of scope for this issue)

Proposal based on the Spike Research:

Assumption
Customers write their custom stage events to GitLab and filter & retrieve it later on. It's on customers shoulders to decide WHEN exactly particular event happened outside of GitLab and safely deliver it to GitLab via API with all required data.
Default stages and their implementation with external issues store.

Option A for VSA Stages based on Jira event workflow:

Before we start: client must have Maintainer+ access level API token.

Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed")
When stage end event happens customer sends following mutation request to GitLab GraphQL:

addExternalValueStreamAnalyticsEvent(input: inputParams)

with following inputParams

param	Type	Required?	Description
groupPath	ID	✅	full path of group where you want to see this VSA event
externalId	String	✅	string containing global unique ID of Jira issue
startEventId	String	✅	String from stage configuration. (e.g. "issue_created")
endEventId	String	✅	String from stage configuration. (e.g. "issue_closed")
startEventTimestamp	Timestamp	✅	Timestamp with timezone when start event happened
endEventTimestamp	Timestamp	✅	Timestamp with timezone when end event happened
labels	Array of strings		Issue labels for filtering. Missing labels will be created at GitLab if not found
authorUsername	String		Issue author username. Group member with such username must exist at GitLab
assigneeUsernames	Array of Strings		Issue assignees usernames. Group members with such username must exist at GitLab
milestone	String		ID of associated milestone. Milestone must exist at GitLab
externalUrl	String	?	String containing URL to Jira issue

If response is successful then everything is OK and VSA will be refreshed soon to reflect new data.

Option B for VSA Stages based on Jira event workflow:

Click to expand

Cons: more complex to implement, more data to store. Pros: easier to use for clients, might be useful structure for further decoupling of VSA.

Before we start: client must have Maintainer+ access level API token.

Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed")
When stage event happens customer sends following mutation request to GitLab GraphQL:

addExternalValueStreamAnalyticsStreamEvent(input: inputParams)

with following inputParams

param	Type	Required?	Description
groupPath	ID	✅	full path of group where you want to see this VSA event
externalId	String	✅	string containing global unique ID of Jira issue
eventId	String	✅	Unique event ID e.g. "issue_created" or "issue_closed"
eventTimestamp	Timestamp	✅	Timestamp with timezone when the event happened
labels	Array of strings		Issue labels for filtering. Missing labels will be created at GitLab if not found
authorUsername	String		Issue author username. Group member with such username must exist at GitLab
assigneeUsernames	Array of Strings		Issue assignees usernames. Group members with such username must exist at GitLab
milestone	String		ID of associated milestone. Milestone must exist at GitLab
externalUrl	String	?	String containing URL to Jira issue

If response is successful then everything is OK. VSA will refresh data for all stages where end event and start event data is already present.

Is this a cross-stage feature?

yes devopsplan ~"group::integrations" /cc @mushakov

What does success look like, and how can we measure that?

Number of users using Jira integration and accessing VSA