Summary of Jira Integration features currently supported:

• A workspace or a Project can be linked to one or more Jira servers, either on-premises or in the Atlassian cloud.
• Each configuration can support multiple Jira projects
• Note resolution handling can be configured specifically for the Jira project, including custom statuses, issue types and workflows
• User lists for reporters and assignees are sourced from the linked Jira project
• Jira issues can be created directly from a text note in a SyncSketch review
• Text notes in SyncSketch can be linked to existing issues in Jira projects
• Linked issues can be unlinked in SyncSketch
• Note links are displayed as buttons that can directly open the linked issue
• Notes can be linked to multiple Jira issues
• When a Jira issue is linked, the Jira issue gets a trackback link directly into SyncSketch. This is a deep link that opens the review, selects the item, jumps to the frame or camera position where the note was made, and highlights the linked note.
• Changing a status in Jira can update the Note's resolution status in SyncSketch

Known limitations for this release:

• Changes to comments or attachments within Jira do not currently affect linked notes in SyncSketch in any way.
• No sketches, attachments or replies to notes in SyncSketch will be synced to Jira - only the text contained within the selected note, and a link back to SyncSketch
• CSV and PDF downloads from SyncSketch will not contain any references to linked Jira issues
• @mentions in SyncSketch will not be preserved in linked Jira issues. Notifications will therefore only come from SyncSketch.

Connecting SyncSketch to Jira

At the Workspace level, navigate to your Settings tab, click on Integrations in the menu, and then select Jira to display the configuration settings.

 

Enter a Name, which will be used to identify this configuration within SyncSketch.  Next, you'll add the URL which points to your instance of Jira (e.g. https://jira.<your-studio>.com), along with the Username and Password of the Jira account you're using for the integration.

 

Using an API token

Your Jira login password may not work, depending on your Jira deployment type and authentication environment. If entering your regular account ID and password fails when all fields are properly filled in, try using an API token instead of your password.

To generate the necessary token:

1. Log in to Jira in a separate window. 
2. Edit your Atlassian Account Settings.
   
3. Switch to the Security tab at the top.
   
4. Click the Create and manage API tokens link.
5. Add a new API token for SyncSketch and copy it.  This is the password to use in the SyncSketch Jira connection configuration dialog.

 

Configuring Jira Project Connections

Next to Configure Jira Project is a drop-down list containing all current Jira projects that exist in your connected Jira instance.  Select and click the Add button for each project you'd like to configure for use with SyncSketch.  You'll see tabs that represent these projects populate below with some additional settings for each.

Use the Default Reporter setting to establish the user you'd like to be automatically selected as the Reporter when submitting an issue to Jira.  The reporter can be changed at the time of submission, this setting simply establishes the default selection.

The Note Open Status dropdown lists all of the status options available from your Jira project. This setting will define what status should be used in Jira when a note is unresolved in SyncSketch.

If a note is resolved in SyncSketch, the status defined in the Note Resolved Status setting will be set in Jira.  Conversely, if a linked Jira issue's status changes in Jira, this can result in a change in in the Note's Resolution status following a page refresh. (Note that if the settings in the SyncSketch comments panel is not set to Show resolved notes, it may result in the linked Note disappearing or reappearing.)

 

Restricting a SyncSketch project to a single Jira project

Project-specific access control

By default, all Jira projects added to your Jira configuration will be available within all SyncSketch Projects.  If you have a specific Jira project that relates to a specific SyncSketch project, you can link those together in the Projects tab under the Jira Project column at the Workspace level.  Selecting a Jira project here will restrict the associated SyncSketch project to only sync with it - no other Jira projects will be available to sync with. 

Alternatively, Individual SyncSketch Projects can be configured to link to Jira projects in a similar manner to that of the Workspace settings.  This can be used to control which Jira projects are accessible in each SyncSketch Project.  Where the workspace setting described above lets you choose between one Jira project or all Jira projects, this method could allow one SyncSketch Project to work with multiple Jira projects.

 

Using the Jira Integration Within a Review

When inside a SyncSketch review, notes that are linked to Jira issues are identified with a label that can be clicked to open the issue directly in Jira.  Multiple Jira issues can be linked to a single note, and multiple notes can be linked to the same Jira issue.

 

Creating a new Jira issue from a SyncSketch note

While hovering over a note in a SyncSketch review, click the "..." button to reveal the Create new issue option.  Clicking this will open the Create Jira issue dialog seen below:

 

Select the Jira Project and Issue Type using the dropdown menus.  If you've restricted this SyncSketch project to a specific Jira project, the other projects will not be available in this menu.  The Issue Type menu lists the issue types available within the selected Jira project.

 

If Sub-task is selected as the Issue Type, a new menu will appear where you can search for the Parent Issue under which you want the Sub-task created.

 

Enter a Summary to identify the issue in Jira.  This is a required field to be able to create a new issue.

 

By default, the Description will include the SyncSketch note, as well as a link back to this note so Jira users can hop to the relevant info in SyncSketch easily.  You can add any additional description as needed in this dialog.

 

Select a Reporter and, optionally, Assignee by beginning to type their first name, last name or email address in the corresponding fields.

 

Click the Create button to complete the creation of the Jira issue.

 

You should now see the link to the issue in the heading of the associated SyncSketch note.

 

Linking a SyncSketch note to an existing Jira issue

You can connect a note to an existing Jira issue, and SyncSketch will append a trackback link back to your Note. 

While hovering over a note in a SyncSketch review, click the "..." button to reveal the Link existing issue option.  Clicking this will open the Link to existing Jira issue dialog seen below:

 

Select the Jira Project from the dropdown menu and type to search for the issue you'd like to link to under Link to issue.  If you've restricted this SyncSketch project to a specific Jira project, the other projects will not be available in this menu.

 

The Summary, Description, Reporter and Assignee are all automatically populated based on the project selected.  Click the Link button to complete the link to the Jira issue, and you'll now see the link appear in the heading of the associated SyncSketch note.  

 

Note: You cannot currently make any edits to these fields when linking to an existing Jira issue.

Unlinking issues

When one or more Jira issues is linked to a SyncSketch Note, you can unlink them.  Choose a specific Jira issue to unlink or unlink all of them at once.

 

Jira Setup Notes

For best results, make sure your Jira project is configured with the following settings.

In your Jira project’s Permission Scheme or Roles:

The Jira integration configuration’s user (or a Jira group or role that the user is in) needs Browse Projects, Create Project Issues, Edit Any Issue, Resolve Issues, Edit Reporters, Transition Any Issue, Assign Any Issue, Add Attachments, and Add Comments permissions.

For example: The default "Member" role in Jira may not have Edit Reporters privileges.  You will need to give Members access to that privilege, or else create a new custom Jira Role that does have such privileges and add this Role for all teammembers.