Workstate Docs

Confluence ​

A Confluence source reads the current pages of the Confluence Cloud spaces you list. It reads them as one Atlassian account, using that account's email address and an API token.

What Workstate reads ​

  • The current version of each page in the spaces you list, as text. Workstate does not read older versions, blog posts, comments or attachments.
  • Up to 50 spaces per source, and up to 20,000 pages per source. For more, split the spaces across several sources.
  • Only what the account can see. Workstate reads exactly what the account's permissions allow.

Each page is indexed starting with its title, its space, its version, the date it was last updated and a link back to the page, followed by the page's content. In search results, a page's path looks like ENG/Onboarding (1234).md: the space key, the page title and the page id. Pages go into the wiki corpus, under the source's name as the repository, in lower case with hyphens for spaces.

When a page is deleted, or moves out of the spaces you list, the next complete sync removes it from search.

What you need ​

  • The owner or admin role in Workstate.
  • A Confluence Cloud site, with an address like https://your-team.atlassian.net. Confluence Data Center and Server are not supported.
  • The keys of the spaces to read, such as ENG or OPS. A personal space's key starts with ~.
  • An Atlassian account that can see those spaces, with an API token.

Use an account made for this

Workstate reads what the account can see, so a dedicated account with read access to only the spaces 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 Confluence.
  3. Fill in the form:
    • Name: a name for the source, for example "Engineering wiki".
    • 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.
    • Space keys: the keys, separated by commas or spaces, for example ENG, OPS. Type them exactly as Confluence shows them.
    • 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 space 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 Spaces 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 pages and spaces it read.
  3. Open Search, select Wiki, and search for a page you know.

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 space 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 spaces are read ​

You cannot change a source's spaces after you add it. To read more spaces, add another Confluence source. To stop reading a space, delete the source and add it again with the spaces 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 Confluence Cloud address. Sites that do not end in .atlassian.net are not supported.
"… cannot see space … — check the key, and that the account has access"Check the spelling of the space key, and that the account can open the space in Confluence.
"Confluence did not answer on that site; check the site address, and that the site has Confluence"Check the address, and that the site has Confluence.
"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 space keys per source; add another source for the rest"Split the spaces across two or more sources.
"… is not a space key"Use letters and digits only. A personal space's key starts with ~.
A sync fails with "none of the spaces (…) exist, or this account cannot see them"Check that the spaces still exist, and that the account still has access.
Sync history notes "Listing incomplete (space … does not exist or this account cannot see it); nothing was removed."The other spaces were read, and nothing was removed from search. Check the space key and the account's access.
Sync history notes "Listing incomplete (the source reached 20000 pages; …)"Split the spaces 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.