Jira Integration

Installation

Go to Settings > Jira integration, or open Jira in the right hand panel of your workspace to connect your Jira account(s) to Sunsama. Once in your settings page, click "Add Jira account".

To add multiple Jira accounts, return to this settings page and click "Add Jira account" again.

then grant Sunsama the requested permissions. If your Atlassian/Jira account is part of multiple "sites" you'll need to select a site to integrate with:

Each time you go through the authorization flow, you'll link Sunsama to a single Atlassian account and site combination. If you want to add another site, under the same account, or add another account you can do that by clicking the "add another account" button that appears under your Jira avatar in the top right corner of the Jira integration.

🚧
Sunsama only supports Jira Cloud
Sunsama only integrates with Jira Cloud instances not self-hosted Jira Server instances. Currently, we don't have plans to support Jira Server since so few companies still use the self-hosted version.

Browsing and importing issues

Open Jira in the right hand panel to use the integration (keyboard shortcut Shift J)

Changing Jira account

If you have multiple Jira accounts connected, switch between them by clicking on the the avatar/profile icon in the top right corner of the integration panel, and selecting another account or "site".

Browsing Jira projects and issues

Sunsama gives you access to all of the Jira projects, boards, and issues visible under the currently selected Jira site. To view items in different site, you'll need to first changes sites from your avatar icon.

Click the main project dropdown to see a list of your issues.

Using filters

Once you select a project, you can use the filters to quickly find issues that might be relevant.

The list of filters you see includes some basic pre-set filters (like "Assigned to me" or "Current sprint - assigned to me") as well as the full list of all your "Favorite Filters" from Jira.

If you need more control, you can always use custom JQL queries on a one-off basis.

Adding custom filters

If there are filters you use daily to find your tasks, you should create the search/filter in Jira directly and then mark it as a favorite. That filter will then show in your list of Jira filters in Sunsama.

Here's how:

Create a new search in Jira and save it (Jira Docs)
Favorite that saved search (Jira Docs)
Return to Sunsama and see your filter in the list

Searching via JQL

If you've got custom workflows that define which issues are most relevant to you, you can issue any custom JQL query inside of Sunsama to pull up the relevant issues.

The JQL Query field is agnostic to the currently selected project but it will only search within the account/site that you've got currently in view.

The JQL badge in the left hand side of the search bar turns green when you've entered a valid JQL expression.

If you need help learning how to write JQL, there's many great resources online, including this guide from Atlassian.

If there'a JQL query you often use, you can save it as a "Favorite Filter" in JIRA and it will show in the list of preset filters.

Importing issues · 3:00

When you are ready to commit to working on a certain Jira issue, you can pull into your plan in Sunsama. There are three ways to pull a Jira issue into Sunsama:

Drag and drop the card from the Jira panel onto your Sunsama task list.
Drag and drop the card from Jira panel onto your Sunsama calendar while in Calendar View, this will add a task to that day in Sunsama and block off time on your calendar.
From the Jira card preview, click "Add to today" or pick a specific date for the card. Or, simply hover over the task and hit S to import it to today

Filtering issues

Hiding or showing previously imported issues

By default, when you drag an issue from Jira into Sunsama, that issue is hidden in the right hand panel. This allows you to easily keep track of what cards still need to be pulled in.

If you want to see Jira issues that have been previously pulled into Sunsama, click the menu button that says "Filter" and toggle on "Already imported".

If you want to hide Jira issues that have been previously pulled into Sunsama, click the menu button that says "Filter" and toggle off "Already imported".

Interacting with imported tasks

Once a Jira task is imported into Sunsama, it becomes a Sunsama task, with an embedded Jira task. Clicking on the Jira icon on the imported task (or hovering over the task and hitting G) will bring you to the task in Jira in a web browser.

Click on a Sunsama task that's linked to Jira to see a preview of your Jira task embedded inside the Sunsama task.

Your associated Sunsama task acts like a worksheet for your Jira task. Inside your Sunsama task, you can add notes, time tracking information, subtasks, and comments without messing with your Jira task. Use your Sunsama task to track the minutia of the task that your collaborators might not care about inside of Jira.

If your Jira issues encapsulate large amounts of work, you can import the Jira issue multiple times into Sunsama, and change the title of the imported task to reflect just the bit of work you'll do that day. You could also use subtasks for this.

Status Syncing

Sunsama allows you to hook into your Jira workflow and update the status of a Jira issue when you import the issue and when you check off the associated Sunsama task.

In both cases, you'll see a small dialog that allows you to update the status of the issue. (To disable this prompt from showing, go to your Settings > Jira integration page)

There's two typical use cases for this functionality:

When importing a Jira issue, you'll change the status of the issue to "In Progress" (or the like).
When completing a Jira issue, you'll change the status of the issue to "Completed" (or the like).

Troubleshooting

Jira is not loading tasks in desktop app or web app

If you notice that your Jira integration is loading/displaying correctly in the desktop or web app, but not both, please try the following:

Remove your Jira account in your Sunsama settings
Go to settings > Account Management
Logout all sessions
Sign back in to Sunsama.
Reconnect your Jira account.

If this does not solve the problem, please chat with us in support.