Overdesk Docs

Appearance

Jira ​

Connect Jira and a draft can tell a customer whether a reported problem is already known, and whether it was actually fixed, because your team's own resolution is carried through word for word. With one extra box ticked, your support team can also open Jira issues from a conversation.

What you need ​

  • A Jira Cloud site, such as acme.atlassian.net. Jira Server and Data Center are not supported.
  • An API token created at id.atlassian.com, and the email address of the Atlassian account you created it on. The two work as a pair.
  • The keys of the projects to read. A key is the prefix on the issue numbers, such as SUP in SUP-123, not the project's display name.

Atlassian makes every API token expire, up to a year out, so pick the longest life you are comfortable with. Syncing stops on the day the token lapses.

Connect Jira ​

  1. In Overdesk, open Integrations and choose Jira.
  2. Enter your Jira site, the Account email and the API token.
  3. List your project keys in Projects, one per line, up to 20.
  4. Decide whether to tick Let my team open Jira issues from a conversation. The next section explains it.
  5. Click Connect. Overdesk checks that the token reaches each project before saving anything, and its confirmation says whether opening issues is on or off.

The projects sync into your knowledge base that night. See GitHub, Linear and Jira.

Opening issues from a conversation ​

Atlassian offers no read-only token, so the token you connect with carries whatever that account can do in Jira. The box is the whole difference between reading and writing, and it is off unless you tick it.

With the box ticked, Overdesk creates an issue in the project chosen at the time, once a person has read the title and description and confirmed them. Nothing is created automatically, and nothing already in Jira is ever edited, transitioned or commented on. See Creating issues from a conversation.

A few things Jira decides for itself:

  • The account needs the Create Issues permission on the project.
  • The issue is opened as a Task where the project has one, otherwise as a Bug, otherwise as the project's first type that is not a subtask. A project whose only types are subtasks cannot take one.
  • A project that requires fields Overdesk does not fill in, such as a component or a priority, refuses the issue, and Overdesk tells you so.

Change projects or settings later ​

  • On the Jira page in Integrations, under "Which projects should Overdesk read?", add or remove projects without reconnecting. Removing one takes its issues out of your knowledge base and stops issues being opened there. Nothing in Jira is touched.
  • The issue-opening box and the token are set when you connect. To change either, including when a token expires, click Disconnect on the Jira page and connect again. Disconnecting removes what Jira put in your knowledge base, and connecting again reads it from scratch. Connecting without ticking the box turns issue opening off.