<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=342780) </details> <!--IssueSummary end--> ### Problem to solve <!-- What is the user problem you are trying to solve with this issue? --> 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: 1. [VSA Stages](https://docs.gitlab.com/ee/user/group/value_stream_analytics/#create-a-value-stream-with-custom-stages) based on Jira event. 2. [Tasks by type](https://docs.gitlab.com/ee/user/group/value_stream_analytics/#tasks-by-type-chart) breakdown based on Jira Labels. (out of scope for this issue) 3. [DORA metrics ](https://docs.gitlab.com/ee/api/dora/metrics.html#get-group-level-dora-metrics)integration based on Jira/SNOW incidents. (out of scope for this issue) Proposal based on the [Spike Research](https://gitlab.com/gitlab-org/gitlab/-/issues/367907): 1. [Assumption](https://gitlab.com/gitlab-org/gitlab/-/issues/367907#assumption) 2. 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. 3. Default stages and [their implementation with external issues store](https://gitlab.com/gitlab-org/gitlab/-/issues/367907#note_1032469188). #### Option A for VSA Stages based on Jira event workflow: Before we start: client must have Maintainer+ access level API token. 1. Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed") 1. 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 | :white_check_mark: | full path of group where you want to see this VSA event | | externalId | String | :white_check_mark: | string containing global unique ID of Jira issue | | startEventId | String | :white_check_mark: | String from stage configuration. (e.g. "issue_created") | | endEventId | String | :white_check_mark: | String from stage configuration. (e.g. "issue_closed") | | startEventTimestamp | Timestamp | :white_check_mark: | Timestamp with timezone when start event happened | | endEventTimestamp | Timestamp | :white_check_mark: | 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: <details><summary>Click to expand</summary> 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. 1. Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed") 1. When stage event happens customer sends following mutation request to GitLab GraphQL: ``` addExternalValueStreamAnalyticsStreamEvent(input: inputParams) ``` with following inputParams | param | Type | Required? | Description | |-------|------|-----------|-------------| | groupPath | ID | :white_check_mark: | full path of group where you want to see this VSA event | | externalId | String | :white_check_mark: | string containing global unique ID of Jira issue | | eventId | String | :white_check_mark: | Unique event ID e.g. "issue_created" or "issue_closed" | | eventTimestamp | Timestamp | :white_check_mark: | 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. </details> ### Is this a cross-stage feature? yes ~"devops::plan" ~"group::integrations" /cc @mushakov ### What does success look like, and how can we measure that? Number of users using Jira integration and accessing VSA ### Related links - [Deep dive session: VSA - Support Jira issues](https://docs.google.com/document/d/1IL9Qg4yozGQOdMLorjZyUJJ2_qcn4mf53pJ56JCERs0/edit?usp=sharing) - [How to implement Jira support](https://gitlab.com/gitlab-org/gitlab/-/issues/12196#note_187215251) - [Related comment](https://gitlab.com/gitlab-org/gitlab/-/issues/271174#note_492215029): "VSA used to have an issue-focused perspective... it was refactored about 2 years ago to have a second focus on MRs, for the sake of organizations that use JIRA for their issues." - Recent enhancement: [Alternative start event to accommodate Jira issue users](https://gitlab.com/gitlab-org/gitlab/-/issues/268291) <!--- Use the following resources to find the appropriate labels: - https://gitlab.com/gitlab-org/gitlab/-/labels - https://about.gitlab.com/handbook/product/categories/features/ Consider adding related issues and epics to this issue. You can also reference the Feature Proposal Template (https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) for additional details to consider adding to this issue. Additionally, as a data oriented organization, when your feature exits planning breakdown, consider adding the `What does success look like, and how can we measure that?` section. Other sections to consider adding: ### Intended users Who will use this feature? If known, include any of the following: types of users (e.g. Developer), personas, or specific company roles (e.g. Release Manager). It's okay to write "Unknown" and fill this field in later. Personas are described at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/ * [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager) * [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager) * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) * [Rachel (Release Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#rachel-release-manager) * [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#alex-security-operations-engineer) * [Simone (Software Engineer in Test)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#simone-software-engineer-in-test) * [Allison (Application Ops)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#allison-application-ops) * [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#priyanka-platform-engineer) * [Dana (Data Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#dana-data-analyst) ### User experience goal What is the single user experience workflow this problem addresses? For example, "The user should be able to use the UI/API/.gitlab-ci.yml with GitLab to <perform a specific task>" https://about.gitlab.com/handbook/engineering/ux/ux-research-training/user-story-mapping/ ### Further details Include use cases, benefits, goals, or any other details that will help us understand the problem better. ### Permissions and Security <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)? Consider adding checkboxes and expectations of users with certain levels of membership https://docs.gitlab.com/ee/user/permissions.html * [ ] Add expected impact to members with no access (0) * [ ] Add expected impact to Guest (10) members * [ ] Add expected impact to Reporter (20) members * [ ] Add expected impact to Developer (30) members * [ ] Add expected impact to Maintainer (40) members * [ ] Add expected impact to Owner (50) members ### Documentation See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/workflow.html#for-a-product-change * Add all known Documentation Requirements in this section. See https://docs.gitlab.com/ee/development/documentation/workflow.html * If this feature requires changing permissions, update the permissions document. See https://docs.gitlab.com/ee/user/permissions.html ### Availability & Testing This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning ### What is the type of buyer? What is the buyer persona for this feature? See https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/buyer-persona/ In which enterprise tier should this feature go? See https://about.gitlab.com/handbook/product/pricing/#three-tiers <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> *This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.* <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION -->