Confluence

Many IT departments keep their runbooks, how-tos and FAQs in Confluence: how to reset a student password, which printer driver to install, what to do when a projector won't connect. Connecting Confluence brings the pages you choose into the knowledge base that schoolAgent and Otto answer from, so a teacher asking schoolAgent "How do I connect to the staff Wi-Fi?" gets your own IT team's page, and the page stays current as the team edits it. See Knowledge for how it sits beside the other knowledge integrations.

Three things to know before you start:

• It's read only. schoolOS reads the pages you pick and nothing else. It never creates, edits, moves or deletes anything in Confluence.
• schoolOS sees what one Atlassian account sees. You connect with an API token that belongs to an account, and the pages that account can view are the pages you can bring in.
• You choose what comes in, and who it's for. Nothing syncs until you tick a space or a page, and each ticked item has its own audience.

Confluence Cloud only (a site at yourdistrict.atlassian.net). Confluence Data Center and Server aren't supported.

You need Manage integrations to connect Confluence, choose pages and sync. Your plan needs schoolAgent.

Connect#

A Confluence connection is called a source, and you can have several (see Several sources). Each source signs in with an Atlassian API token, so schoolOS never holds a password.

1. Create the API token. Sign in to Atlassian as the account schoolOS should read with, open your account's security settings and select Create API token (not Create API token with scopes, which isn't supported yet). Copy it; Atlassian shows it once. Atlassian tokens expire, within a year at most, so note the date: when it passes, syncing stops until you enter a new one. Use an account that can view every space you want to bring in: an IT service account, or the person who owns the IT space. Don't use a personal account that will be closed when someone leaves.
2. Open Admin › Account › Integrations, select Confluence, and select Add Confluence source (or Add source at the top once you have one). You can also get here from the Knowledge tab of Admin › Agent › Configuration: Add knowledge source › Confluence › Connect Confluence.
3. Fill in the dialog:
   • Name. What this source is for: IT, District and Community are offered as suggestions. The name appears on the source's card and in the Knowledge list.
   • Confluence site. Paste any link from your Confluence; only the site is kept, so https://yourdistrict.atlassian.net/wiki/spaces/IT/pages/123 becomes https://yourdistrict.atlassian.net. Typing just yourdistrict works too.
   • Account email. The Atlassian account the token belongs to. schoolOS sees exactly what this account can see.
   • API token. The token you copied. It's stored encrypted and never shown again.
   • Who can see it. The audience every page from this source starts with. Everyone signed in to begin with; see Who sees it. You can change it per item when you pick pages.
4. Select Connect. The button reads Checking connection… while schoolOS signs in with the token and confirms it can list spaces. If Confluence refuses, nothing is saved and the dialog says what to check.

On success, the page says Connected to Confluence and opens the content picker straight away, because the next thing anyone does after connecting is choose what comes in.

Each source is a card on the Confluence page, named with its site. Its ⋯ menu offers Edit connection, for the name, address and sign-in, and Disconnect. In Edit connection, leave API token blank to keep the stored one; the field reads "•••••••• (unchanged)". Changing the site or the email, or entering a new token, checks the connection again before saving.

Choose what comes in#

Select Choose content on a source's card to open Choose what IT brings in. The left side is the Confluence tree, read a level at a time as you open it: every space the account can see, then each space's top-level pages, then the pages and folders under those. The right side, What comes in, is the decision in one place: everything ticked, with its audience, and anything left out.

• Tick a space to bring in every page in it, however deep.
• Tick a page to bring in that page and everything under it. In Confluence a page is both a document and a container, so ticking "Printers" brings in "Printers" and each printer's page beneath it.
• Untick a page inside a ticked space or page to leave that page and everything under it out. It moves to Left out on the right, where Bring back restores it.
• Tick a page inside a ticked space when it needs a different audience from the space: it becomes its own root with its own Who can see it.

The nearest tick above a page decides whether it comes in and who it's for. A page three levels down under a ticked space comes in for the space's audience, unless a closer tick or untick says otherwise. Ticking or unticking something clears whatever was recorded underneath it, so a ticked space means all of it and an unticked one means none of it.

Whiteboards, databases and embeds hold no readable text, so they aren't shown. Archived pages aren't shown either. When a site has more than eight spaces, a Filter box narrows the list by name. A restricted page shows a Restricted in Confluence label; see Restricted pages.

Each ticked item on the right has Who can see it, starting from the source's audience. Every ticked item needs one; until it does, the footer says "Choose who can see each ticked item." Select Save and sync. The selection is saved and an import starts in the background; the card shows "Looking through spaces", then "Reading 12 of 40", then "Added 38 documents to knowledge", with any pages it couldn't read listed underneath.

Pages created later under a ticked space or page come in automatically on the next sync, because the tree is read fresh each time rather than from a list saved when you ticked. Reopen Choose content at any time to change the selection; saving it starts another sync.

A space or a page?#

Tick the space when the whole thing is for one audience and the team adds pages to it: an "IT Help" space written for staff, where every new how-to should reach them without anyone remembering to tick it. Tick pages when a space mixes audiences or holds working material, like an IT space with a public "Getting help" section next to internal change logs and vendor contracts. Tick the section, leave the rest.

For example, a district's IT team keeps everything in one "IT" space. They tick the space for Staff, then tick the "For families" page beneath it and set it to Public (all), and untick "Vendor contracts". Staff get answers from the whole space, families only from the "For families" pages, and the contracts never come in.

Restricted pages#

Confluence can restrict who may view a page, and the restriction flows down to the pages under it. schoolOS reads those restrictions and shows them, but doesn't enforce them: a restricted page is imported like any other, and the audience you choose in schoolOS decides who sees answers from it here.

In the picker, a restricted page carries a Restricted in Confluence label. Point at it to see who can view the page there ("Only IT Staff and Pat Lee can view this in Confluence"), whether that's set on the page itself or inherited from a page above it, and the reminder that it still comes into schoolOS. The same label follows the page into the Knowledge list and its Edit dialog, so the choice stays visible after the import.

A restricted page comes in with the audience of its nearest tick, like any other page. If a restricted page shouldn't reach that audience, tick it on its own and give it a narrower one, or untick it.

What syncs, and when#

Each source card has How often: bring the selection in Once, or Keep in sync hourly, daily, weekly or monthly. It saves as soon as you pick it, and it's the same setting as on Confluence in the Knowledge tab of Admin › Account › Import Data, which opens this page. New sources start at Keep in sync: weekly.

Once, or keep in sync?#

| Option | What it does | Choose it when | | --- | --- | --- | | Once — I'll sync again when I want | A one-time import: nothing runs on its own. Sync now re-reads the selection when you ask. | The pages are finished, or you want to control exactly when the agent's answers change. | | Keep in sync: hourly | Re-reads the selection once an hour. | A space edited through the day, like an IT status page or a known-issues list. | | Keep in sync: daily | Re-reads once a day. | How-tos and FAQs the team edits now and then. The usual choice for an IT space. | | Keep in sync: weekly | Re-reads once a week. New sources start here. | Policies and procedures that change a few times a year. | | Keep in sync: monthly | Re-reads once a month. | Reference material reviewed yearly. |

A frequent schedule is cheap: every run reads the tree, but a page whose text hasn't changed is skipped before anything else is done, so an hourly schedule on a quiet space costs a few listing calls. Sync now on the card runs a sync right away (it's disabled until the source has content chosen).

What a sync does, every time, in this order:

1. Lists every space that has a tick in it, with all its pages and folders, to work out what the selection means today.
2. Reads each page that's included, up to four at a time. Confluence's rate limits are honored: when it asks schoolOS to slow down, the sync waits and retries rather than failing.
3. Adds new pages and replaces edited ones. Unchanged pages are skipped.
4. Removes pages that are no longer in the selection: a page deleted, archived or moved out of a ticked space or page in Confluence, or one you unticked, leaves the knowledge base at the end of the run. This only happens after a run that saw the whole tree; if any space couldn't be listed, nothing is removed, so an outage can't look like a mass deletion.

The card's result says what happened: "Synced 120 documents, 4 new or changed, 1 could not be read, 2 removed". When a run couldn't list something, it adds "some content could not be listed" with the reason, and the card keeps a warning until a run comes back clean. A source with nothing ticked removes everything it brought in and says "Nothing selected; removed 120 documents".

What happens to a page at the source:

• Edited. Re-read on the next run; the old text is replaced.
• Created under a ticked space or page. Comes in on the next run.
• Moved within a ticked space. Stays, with its new place in the tree. Moved out of everything ticked: removed on the next run.
• Deleted or archived. Removed on the next run.
• Restriction changed. The label is updated on the next run; the audience you chose stays.

Each page keeps its link to Confluence as its source, and the page's path, like "IT › Printers › Library printer", is kept with it.

What's read#

Each page also becomes an article in Admin › Help Center › Articles, with its formatting, filed under the space and pages above it and editable there, unless its tick is limited to particular agents. A page restricted in Confluence is never a public article (see Imported articles).

The page's text, including headings, lists, tables and code blocks, with macros stripped to their content. Only the first 50,000 characters of each page are kept, about 20 pages of text. Attachments on a page (PDFs, images, Office files) are not read, only the page itself. Comments aren't read. Whiteboards, databases and embeds aren't read.

Who sees it#

Every ticked item has Who can see it, starting from the source's audience. Ticking a broader group ticks everything it covers.

Which audience should I choose?#

| Option | Who gets answers from it | Choose it when | | --- | --- | --- | | Public (all) | Everyone, including guests on your website who aren't signed in | The pages are already public: a "For families" section, enrollment steps, the bell schedule. | | Everyone signed in | Anyone with a schoolOS account: staff, students and guardians, but not website visitors | Information for your community that you'd rather not publish to the open internet. | | Staff | Teachers, helpdesk staff and admins | How-tos, runbooks, the IT knowledge base, HR procedures. The usual choice for an IT space. | | Students | Everyone whose school role is Student | A student tech guide or device care pages. | | Guardians | Parents and guardians | Pickup procedures, portal help, fee pages. | | A school role, like Librarians or Bus Drivers | Only people with that school role | A procedure one team follows. |

At answer time, schoolAgent only uses pages whose audience includes the person asking. Someone signed in as a guardian never gets an answer from a Staff page, and a guest on your website only gets answers from Public (all) pages. Confluence's own view restrictions play no part in this; see Restricted pages.

To change an item's audience later, open Choose content, change Who can see it on the right, and select Save and sync. The pages under it are updated on that run.

For example, a district connects its "Help Desk" space for Staff on Keep in sync: daily. A tech documents the new MFA enrollment steps on Monday afternoon. Tuesday's run reads the new page, and a teacher who asks schoolAgent "How do I set up the authenticator app?" that morning gets the steps. A parent asking the same question gets nothing from it.

Several sources#

A district often runs more than one Confluence site, or wants different people to own different parts of one: IT connects with its service account, the district office with another. Select Add source for each. Every source has its own name, token, audience, schedule and selection, and each is listed separately on the Confluence page and under Confluence sources on the Knowledge tab.

Sources never affect each other. Disconnecting one, or unticking everything in it, removes only what that source brought in. If two sources tick the same page, each keeps its own copy with its own audience.

Disconnect#

Select Disconnect in a source's ⋯ menu on the Confluence page, or Disconnect from the Confluence row of Admin › Account › Integrations (see Disconnect an integration). You confirm first; the dialog says how many pages will leave.

Disconnecting a source removes every page it brought in from the knowledge base, so schoolAgent stops answering from them right away. Its selection is forgotten and its token is cleared. Nothing changes in Confluence, and other Confluence sources aren't touched. To bring the pages back, add the source again and tick them again.

Disconnecting from the Integrations list disconnects every Confluence source at once; use the card's menu to remove one.

Troubleshooting#

• "Confluence rejected the email and API token" or "did not recognize that email and API token." The token was revoked or has expired, or the email isn't the account it belongs to. Atlassian API tokens expire within a year, so a source that synced fine for months can stop one day with nothing else changed. Create a new token for that account and enter it under Edit connection. Use Create API token, not Create API token with scopes: a token with scopes isn't supported yet and is always refused.
• "is not a valid Confluence Cloud site URL." The address has to end in .atlassian.net (or .jira.com). A self-hosted Confluence can't be connected.
• "That Atlassian account cannot see this in Confluence." The token's account lacks permission to a space or page you ticked. Give it view permission in Confluence, or tick only what it can see.
• "This account can't see any spaces yet." The account has no space permissions, or the site has none. Grant it access to the spaces you want, then reopen Choose content.
• "The stored Confluence API token could not be read. Edit the source and enter it again." The saved token can't be decrypted. Enter a new one.
• "No readable text." The page is empty, or only holds attachments, images or a whiteboard. Only the page's own text is read.
• "some content could not be listed." Confluence didn't answer for one space during the run. Nothing was removed. The next run tries again; select Sync now to run it now.
• "The last sync didn't finish." The background run stopped partway. Select Sync now; pages already added stay, and unchanged ones are skipped.
• A page is gone from the knowledge base but still in Confluence. It was archived, moved out of everything ticked, or unticked. Reopen Choose content and check Left out.
• A page is in the knowledge base that shouldn't be. It's under a ticked space or page. Untick it in Choose content and select Save and sync; it leaves on that run.
• Sync now is grayed out. The source has nothing ticked. Select Choose content first.
• schoolAgent answers from an old version. The page was edited after the last run. Wait for the schedule or select Sync now. If the new wording is past the first 50,000 characters, it was never read.
• "Confluence and HappyFox need database migration 262." Your schoolOS database hasn't been updated for this integration. Contact schoolOS support.