Workstate Docs

Jira ​

A Jira source reads every issue in the Jira Cloud projects you list, with its description and comments. It reads them as one Atlassian account, using that account's email address and an API token.

What Workstate reads ​

  • Every issue in the projects you list. Each issue is indexed with its key and summary, project, type, status, priority, resolution, assignee, reporter, labels, created and updated dates, a link back to the issue, its description, and its comments.
  • Up to 500 comments per issue, oldest first. When an issue has more, the indexed text ends with a note of how many comments were left out.
  • Up to 50 projects per source, and up to 20,000 issues per source. For more, split the projects across several sources.
  • Only what the account can see. Workstate reads exactly what the account's permissions allow.

Workstate does not read attachments, custom fields, links between issues, work logs or change history.

In search results, an issue's path looks like OPS/OPS-42.md: the project key and the issue key. Issues go into the wiki corpus, under the source's name as the repository, in lower case with hyphens for spaces.

When an issue is deleted, or moves out of the projects you list, the next complete sync removes it from search. An issue that moves to another project you list gets a new key, and is indexed under it.

What you need ​

  • The owner or admin role in Workstate.
  • A Jira Cloud site, with an address like https://your-team.atlassian.net. Jira Data Center and Server are not supported.
  • The keys of the projects to read, such as OPS or ABC.
  • An Atlassian account that can see those projects, with an API token.

Use an account made for this

Workstate reads what the account can see, so a dedicated account with access to only the projects you want keeps the index to what you intend. It also keeps working when a person leaves the team.

Create an API token ​

  1. Sign in to Atlassian as the account Workstate will read as.
  2. Go to id.atlassian.com/manage-profile/security/api-tokens.
  3. Select Create API token, not Create API token with scopes. Workstate connects to your site's own address, and Atlassian accepts tokens with scopes only through its separate API gateway.
  4. Name the token, choose when it expires, and copy it.

Atlassian API tokens expire after one year at most. When the token expires, syncs fail until you replace the token.

Add the source ​

  1. In the console, choose the namespace in the switcher at the top of the sidebar.
  2. Open Sources. Under Add a source, select Jira.
  3. Fill in the form:
    • Name: a name for the source, for example "Platform tickets".
    • Site: your site's address, for example your-team.atlassian.net. You can paste any link on the site, and Workstate keeps only the site part.
    • Project keys: the keys, separated by commas or spaces, for example ABC, OPS. Workstate writes them in capitals, as Jira does.
    • Account email: the Atlassian account's email address.
    • API token: the token you created.
  4. Select Add source.

While the button reads "Checking with Atlassian…", Workstate signs in to the site as the account and checks that it can see every project you listed. If the check passes, Workstate saves the source, stores the token encrypted and starts the first sync. If the check fails, nothing is saved, and the form shows why.

Check it worked ​

  1. The source's page opens. Its Connection panel shows the Site, the Projects with a link to each, and Reads as with the account's email and when the token was added.
  2. The status moves to Up to date, and Sync history shows the sync as Succeeded, with the number of issues, comments and projects it read.
  3. Open Search, select Wiki, and search for an issue you know, by its key or by what it describes.

Replace the token ​

Replace the token when it expires, when you revoke it in Atlassian, or to read as a different account.

  1. Open the source's page. In Connection, select Replace token. Only owners and admins see this button.
  2. Type the Account email and the New API token.
  3. Select Replace token.

Workstate checks the new token against the site and every project the source reads. If the check passes, it replaces the old token, deletes the old one, and starts a sync. If the check fails, the old token stays in place.

Change which projects are read ​

You cannot change a source's projects after you add it. To read more projects, add another Jira source. To stop reading a project, delete the source and add it again with the projects you want.

How Workstate keeps the token ​

Workstate checks the token against the site, then stores it encrypted (AES-256-GCM) and never shows it again. The console shows only the account's email. See Security & privacy.

Troubleshooting ​

What you seeWhat to do
"the site must be your Atlassian Cloud address, like https://your-team.atlassian.net"Use your Jira Cloud address. Sites that do not end in .atlassian.net are not supported.
"… cannot see project … — check the key, and that the account has access"Check the project key, and that the account can open the project in Jira.
"Jira did not answer on that site; check the site address, and that the site has Jira"Check the address, and that the site has Jira.
"that site redirected elsewhere; check the site address"Use the site's current address.
"Atlassian took too long to answer; try again in a minute"Wait a minute, then select Add source again.
"at most 50 project keys per source; add another source for the rest"Split the projects across two or more sources.
"… is not a project key"A project key starts with a letter, followed by letters, digits or underscores.
A sync fails with "none of the projects (…) could be read"Check that the projects still exist, and that the account still has access.
Sync history notes "Listing incomplete (project …); nothing was removed."The other projects were read, and nothing was removed from search. Check the project key and the account's access.
Sync history notes "Listing incomplete (the source reached 20000 issues; …)"Split the projects across several sources.
Syncs start failing after months of workingThe token may have expired or been revoked. Replace the token.

Workstate is built by Nerdstorm Pty Ltd, Sydney.