Revision Date: 2023.12.27

View as PDF

Table of Contents

I. Description/Objectives

This Reliable Method:

• Provides key instructions to help Governance team members navigate and use Jira.

• Describes the processes used by individual Governance team members to respond to an assigned Jira ticket.

II. Scope

The full set of procedures described in this document apply only to Sage Governance staff working in the ACT Service Desk and the Governance Software Project, which are managed by the Governance team. Some procedures may also apply to other ticket locations where Governance staff may receive assignments (e.g., Synapse Service Desk (SYNSD) or 1KD); however, these processes should be adapted in collaboration with other departments.

III. Definitions & Acronyms

Project Key - A project key is the abbreviation used in Jira for each project and is used to locate a ticket. For example, the project key for the Access and Compliance Team Service Project is “ACT.”

Service Desk (SD)/ Service Project - Referred to by Atlassian/Jira as a “Service Project,” this is a project category in Jira which allows functionality with external clients. Sage often uses the term “Service Desk” in lieu of “Service Project,” and can be used interchangeably. SD functionality may include: A Help Center portal; ability to communicate with internal and external clients; ability to create automations with outbound email communications.

Software Project - This is a project category in Jira which primarily provides project management and issue tracking functions for internal teams.

Ticket - Referred to by Atlassian/Jira as an “issue,” tickets can refer to individual items created and tracked in Jira, including items created internally, or items created externally by users via email or through the Help Center. See additional information on “Issues” in Jira help documentation.

IV. Authorities/Responsibilities

Jira users must have the appropriate permission settings to perform various functions in Jira, which may include viewing tickets, commenting on tickets, editing project settings, and making customizations such as updating forms. Permission settings are managed by Sage’s IT Operations team.

All Governance team members are expected to have a basic understanding of Jira in order to collaborate effectively with other departments and services.

Governance team members who may be assigned tickets are expected to follow the basic Jira workflow guidelines.

Governance team members who are assigned administrator privileges to Jira are expected to implement continuous improvements based on team or user needs and update reliable methods on an ongoing basis.

V. Jira Basics

A. What is Jira and why use it?

Jira is a software application developed by Atlassian that allows teams to track issues, manage projects, communicate with customers, and automate workflows, among other functions.

Sage’s instance of Jira is a company-managed cloud platform, meaning that data exists on the cloud and the Jira environment overall is customized and managed by Sage IT. Due to this managed environment, Governance staff is able to collaborate with other groups within Sage by integrating communication and issue workflows across the Jira projects managed by other teams. Examples:

• When a data curation team is working on data intake, the curation team is able to create a new ticket in the Governance (SG) software project and link it to the data intake project. Use of these linked tickets allows the data curation team to assign tasks to Governance as part of the overall steps needed to complete a larger set of data intake processes.

• When Synapse users report issues with data access requests, the Governance team is able to create an issue ticket in the Synapse Web Client (SWC) project and link the user’s ticket generated in the Access and Compliance Team (ACT) project.

B. Permissions - General

Jira requires permissions for accessing various projects and service desks, which can limit the content that users are able to view, reply to, or manage.

Permissions in Jira are described in detail in Jira documentation. To summarize, Jira permissions are organized into three categories:

1. Global Permissions

   1. Jira Administrators will generally have global permissions that allow for the most ability to customize various projects across teams.

   2. At Sage, these permissions are limited to a small set of users. In some cases, Governance will have to request help from Jira Administrators to customize the schemas applied to Governance projects.

2. Project Permissions

   1. Project Administrators are able to edit project role membership, project components, project versions, and some project details ('Project Name', 'URL', 'Project Lead', 'Project Description').

   2. Current project Administrators for Governance projects are shown in the table below.

3. Issue Permissions

   1. Issue-level permissions operate within the bounds of all other global and project permissions. An example of issue-level permissions is when an external user is able to access a specific issue (via the Help Center) when they created/reported the issue or if they are invited to the issue.

C. Permissions - How to Update

Project Administrators can change individual user access permissions in the Project Settings under the “People” menu. This is important when internal users need to have updated access for viewing or responding to tickets. Individuals can be manually added or removed from the list, or the permissions selections can be modified.

Open

Jira Administrators will need to be contacted to make additional changes to the Permission Scheme. These details are found under the “Permissions” menu.

Open

D. Ticket Locations

Governance specifically maintains two Jira queues: ACT Service Desk (ACT) and the Governance Software Project (SG). However, governance-related tickets can be created in any service project or service desk when governance staff are tagged or assigned.

All Jira Projects (across all Sage departments) can be viewed on the Projects page.

Other Collaborative Projects (and project keys):

• Synapse Service Desk (SYNSD) tickets are created through the Help Center as routed from Synapse.

• 1kD Program (ONEKD)

• AD + EL Service Desk (ADEL) tickets are created through the Help Center or manually by internal users. The Alzheimer’s Disease Translational Research (ADTR) team uses this service desk primarily to manage data ingress on the AD Knowledge Portal and ELITE Portal.

• IT Operations (IT) tickets are generated internally only. Use this Software Project to report issues or make requests to IT.

• D&T Architecture (ARCH)

• Synapse Web Client (SWC) tickets are generated internally only. Use this Software Project to report issues related to Synapse such as the Access Request user interface.

• Data and Tooling Operations (DTO)

• Platform (PLFM)

E. Ticket Types

• Software Project tickets (e.g., Governance Software Project) are limited to internal use only, so messages are not sent outside of the system.

• Service Desk tickets (e.g., Synapse Service Desk or ACT Service Desk) are able to communicate with external or internal parties.

F. SG Project - General Setup Notes

1. Tickets in SG can be created through the following mechanisms:

   1. Automations such as the “Add Conditions” button in Synapse. When clicked (by any user), this process generates a ticket in the SG queue to inform governance of an ACT hold on the data so ACT can assist with adding conditions for use.

   2. Creating a ticket in Jira using the “Create” Button.

G. ACT SD - General Setup Notes

1. Tickets in ACT can be created through the following mechanisms.

   1. Help Center. Several subtypes of tickets can be created within the Help Center. For example, using the “Condition for Use” option will collect information using a Jira Form. (See SOP02-RM03 for more information on Jira Forms.)

2. Emails to ACT@sagebase.org or ACT@sagebionetworks.org, or ACT@synapse.org

3. Creating a ticket in Jira using the “Create” Button.

H. SYNSD - Governance Collaboration Notes

• SYNSD is not managed by Governance; however, when Governance-specific issues arise, Governance staff may be assigned to provide support.

I. Ticket Management

Ticket Management refers to the processes of updating Jira ticket fields to enable appropriate sorting, filtering, metrics and reporting.

1. Issue Types

Each project and service has a list of Issue Types that can be used to help identify, categorize and report on work. Issue Types can also be used to set different workflow parameters. Issue Types are set by a Jira Administrator who is able to select and modify the scheme.

See the Atlassian Support article for more details.

Issue Types in SG:

Issue Types in ACT:

Changing Issue Type

If an issue type needs to be changed (for example so a more appropriate workflow is applied - see V.E.b.), a user with the appropriate permissions can take the following steps. Note: there may be project-specific limitations to making this change and this process may result in errors preventing the process to be completed.

1. Open the affected ticket.

2. On the top left of the ticket, click on the issue icon.

   1. For example, hovering over the orange “?” icon in the ACT SD will result in a “Change issue type” screen tip.

   2. Clicking on the icon will result in a menu of issue types.

3. Select the desired issue type.Follow the prompts on the following screens. Note that issues can also be moved (migrated) to a different project using this process.

2. Jira Workflows and Statuses

Each Issue Type is assigned a workflow, which is depicted in a flow diagram. For example, the workflow for all Issue Types in the SG project is:

The workflow dictates which status labels are available at any stage in the process. For example, using the above diagram as a guide, when a new SG ticket is created, it will start with a label of OPEN. From the OPEN status, a Governance user is able to change the status to one of several options:

However, once the status is changed to another option, the subsequent status selections will change based on the workflow. For example, once the issue is CLOSED, the only option will be “REOPEN.”

In some cases, workflows may not be set to allow the issue to be reopened. The workaround in this case is to change the Issue Type. See instructions above in V.E.a.

See the Atlassian Support Article for more information on Workflows.

3. Labels

Labels are used across Governance tickets to track the projects and services completed by Governance analysts. There are two categories of labels used, though all labels are pulled from the same list and entered into a single field (shown below). Jira allows the use of multiple labels. Read up on labels vs components in Jira Here, Here, and Here and also a few notes from our colleagues at Sage in our JIRA IT ticket for this use case.

Project Labels are applied to tickets to note the project they apply to.

The currently used Project Labels are:

Service Labels are applied to tickets to note the type of service being performed by Governance.

The currently used Service Labels are:

4. Linking Tickets

Use the “Link Issue” function on the top left of an issue to link two or more tickets together. Click the button (instead of clicking on the drop-down) to obtain the dialog box shown below.

Select from the drop-down menu the best description for the linkage, then add the issue. The easiest way to add an issue is to use the ticket number (for example, “ACT-433”).

The full list of selections:

While the above link selections may be used for various customized functions in Jira, it appears that there are no specific functions, behaviors, or extended definitions assigned to these selections out of the box. According to the Atlassian community (e.g. this discussion), “They are simply descriptive links that allow you to arbitrarily link issues together.”

At this time, any of these descriptive selections can be used based on the individual user’s discretion.

5. Searches and Filters

Searches and Filters in Jira operate using Jira Query Language (JQL). Advanced Searches become “Filters” and show up in the Filters menu when they are Saved.

Searches and Filter terms can become complicated (See Atlassian Support articles for advanced information). For simplified searches and filters, use the following basic steps:

Searches

• Try a basic search using the Search bar in the upper right corner of the screen. Simple search criteria can include keywords, or the specific ticket number you are searching for.

• Advanced Searches are required when you want to search beyond keywords. To access Advanced Searches, click on the Search bar, then click on the “Advanced issue search” text at the bottom of the dropdown menu.

• The Advanced Search will open an additional search screen with a series of drop-down menus. To fine-tune the search, select from some of the default search properties such as the specific Project(s) involved, the Assignee(s), etc. To create additional search parameters, use the “+More” button and search for additional parameters.

• Example +More Search Terms

  • “Created Date” provides an additional set of search parameters based on when the item was created.

  • “Label”

Filters

• Filters are essentially saved Searches that can be used repeatedly or incorporated into dashboards.

• Users can access any Filters that have been created by other employees and shared with a Team, Role, or the organization.

  • To find Filters that have been shared, go to the Filter Search.

• To create a new Filter, either click on “Save as” when an Advanced Search is created (using the steps above), or from the Filter Search, click on the “Create Filter” button on the top right corner of the screen.

Sharing Filters

• Once a Filter is created, there are two ways to manage View and Edit properties on a Filter.

  • From the Filter itself, click on “Details,” then click on the “Edit permissions” link.

  • From the Filter Search, click on the ellipsis button (“...”), then Click Edit.

• Either of these methods will execute the “Edit filter” pop-up window. Change Viewers and Editors by selecting the desired settings and click the “Add” button. Then, Save the edits.

6. Moving Tickets

In some cases, tickets may need to be moved from one queue in Jira to another. Note that a Service Desk ticket (where communication includes internal AND external recipients) should be moved to another Service Desk if external communication is needed. A common example is movement of a ticket from the SYNSD queue to the ACT service if the ticket is clearly asking an ACT-related question.

To move a ticket:

1. Ensure that the content of the ticket is suitable for the move. If unsure, consult a colleague or manager.

2. Using the Actions Menu, click on “Move.”

3. On the next screen, select the new project (queue) the ticket should be moved to and the type of issue. Each project may have different settings for the types of issue categories used. Select the available issue category that seems the most appropriate. Then click “Next” through the next screens until the ticket move is confirmed.

4. Once the move is confirmed, the screen will refresh and the ticket will be displayed in the new Jira queue.

VI. Workflow

A. Timelines

Governance is expected to respond to all Governance-related issues within 2 business days. To meet this expectation, reply to the reporter with a status update even if you are still investigating the issue/question, etc.

B. Ticket Triage

1. Tickets will be triaged by a designated person in Governance. Triage should occur daily. Some tickets are also automatically assigned.

2. Ticket triage is conducted by evaluating the question/request against the source and topic. then assigning the ticket to the person who is assigned the particular task or project. For example, tickets with a question about AD Knowledge Portal will be assigned to the analyst serving as the AD Knowledge Portal’s lead. Similarly, tickets with a concern about profile validation will be assigned to the analyst working on profile validations.

3. If it is unclear who the best fit for the ticket is, the designated triager may contact other individuals using internal comments and tagging to determine who the best assignee will be.

4. The designated triager will also assign the appropriate label(s) to the ticket, if known at the time of evaluation and assignment.

C. Responses

1. Internal vs. External Responses

   1. In the SG project, responses are limited to internal viewers.

   2. In ACT SD, SYNSD, or other Service Desks, responses can be internal or external, indicated by the options to either “Add internal note / Reply to customer.”

2. Contact Information in ACT SD

   1. ACT SD uses the “Reporter” field to send both internal and external responses. Typical reporter field entries may include:

      1. A Sage-internal person if the ticket was generated in Jira or using the Help Center, or,

      2. An external person showing an external email address.

         1. This case occurs when a user sends an email to act@sagebase.org or act@sagebionetworks.org.

   2. An external person showing a synapse.org email address.

   3. The reporter listed is “act@sagebionetworks.org”

      1. This is an error (unknown cause) where an external person sends an email to act@sagebionetworks.org and the person’s external email address is not listed as the reporter.

      2. To fix this issue:

         1. Go to Google Groups and access the ACT email group.

      3. Find the originating email (usually using the date and subject line), and open it.

      4. Locate the sender’s external email address.

3. Tagging internal users

   1. Internal users should be tagged whenever information and updates need to be directed to them. Tagging is done by including the “@” symbol in an internal comment or summary text and finding their name in the pop-up list of contacts. If they do not appear in the list of contacts, it is possible that they do not have access to the service desk or software project you are using. In a service desk, this may be remedied by adding them as a “Request Participant” in the More Fields area.

4. Attachments

   1. Add attachments as needed to tickets within either service projects or software projects. Attachments can be added in the summary field or in the comments, including external comments.

   2. Attachments can be added by either clicking on the attachment icon (a paperclip), or by dragging an attachment into the comment, or even by pasting into a comment.

5. Moving Tickets

   1. In some cases, it may be appropriate to move a ticket from one queue to another, particularly when another group or individual should be responsible for the question/request in another service desk or software project. See V.I.6 for instructions.

D. Closing Tickets

1. Tickets should be closed once there is confirmation that the response was sufficient. In some cases, there will be clear confirmation that the tasks are done. In other situations, Governance may have supplied a response but did not hear back again from the user. Best practice will be to contact the user again after a period of time (approximately 7 days is a good rule of thumb) to confirm their questions were answered before closing the ticket unless the additional contact seems unnecessary.

2. When closing a ticket where the conversation may not clarify the resolution, include an internal comment to briefly explain why the ticket should be closed.

3. Resolution Types. When a ticket is ready for resolution, one of several selections is available. The typical resolution is Resolved/Done.

   1. “Won’t Do” should be avoided in ACT SD as the customer may get a response email from us indicating that we will not do something. In past circumstances, “won’t do” has not been an appreciated message.

4. A help dialog box defines resolution options:

VII. Associated Documents and Resources

N/A

VIII. Revision History