Zendesk

Zendesk's Help Center is where many districts already keep their how-to articles: password resets, printer setup, the Chromebook care guide. Connecting Zendesk brings the published articles from the sections you choose into the knowledge base, so schoolAgent can answer from them on your website and in the app, and Otto can cite them for your admins. When your team edits an article in Zendesk, the next sync updates it here.

schoolOS only reads from Zendesk. It never creates, edits or deletes an article there, and nothing about your Zendesk account changes.

Find it under Knowledge on Admin › Account › Integrations, or from the Knowledge tab of Admin › Agent › Configuration: Add knowledge source › Help Center › Zendesk › Connect Zendesk. Either way the setup lives on the Zendesk page; when you arrive from the Knowledge tab, a Knowledge sources button takes you back. You need Manage integrations. An account has one Zendesk connection. For how Zendesk sits beside the other knowledge integrations, see Knowledge.

Create the API token#

schoolOS signs in with an API token that a Zendesk admin creates in your own Zendesk, so it never holds a password.

1. In Zendesk, open Admin Center › Apps and integrations › Zendesk API.
2. Turn on Token access, then add a token. Name it so you'll recognize it later, like "schoolOS knowledge".
3. Copy the token. Zendesk shows it once.

A token belongs to the agent who creates it, and schoolOS sees exactly what that agent can see: every section and article they can open in the Help Center, and nothing else. Reading the Help Center's sections usually needs an admin role in Zendesk. Create the token as a shared or service agent rather than a person's own account, so it keeps working when someone leaves. Deleting the token in Zendesk is the same as disconnecting: the next sync fails until you connect with a new one.

Connect#

1. Open the Zendesk page and fill in Connection:
   • Zendesk subdomain. The part before .zendesk.com. The name or the whole URL; both work.
   • Agent email. The Zendesk agent the token belongs to.
   • API token. The token you copied.
2. Select Connect.

schoolOS signs in as that agent, checks that Help Center is turned on for your account, and counts its articles, all before it saves anything. If Zendesk refuses the details, nothing is saved and the page says what to fix. Once it works, What schoolOS can see says who it's signed in as and how many articles are available, like "Signed in as [email protected] on yourdistrict.zendesk.com. Help Center is on, with 412 articles available." If the sign-in works but Help Center is off, it says so, and there's nothing to sync until you turn Help Center on in Zendesk.

The token is stored encrypted and never shown again. Once connected, Connection folds closed and shows the address. To change the subdomain or email later, open it, edit, and select Save and test connection; leave API token blank to keep the one you have, or paste a new one to replace it.

For example, a district whose Help Center has three categories (Students & Families, Staff, IT Internal) connects with a token from its shared helpdesk agent. What schoolOS can see reports 412 articles, and What to bring in appears below.

Choose what comes in#

Nothing syncs until you choose. What to bring in lists your Help Center, grouped under its category headings, one row per section (a section Zendesk hasn't put in a category sits under Uncategorized). Use Search … sections to find one by name or description.

• Tick a section to bring in every published article in it, including articles your team adds to it later, and every section inside it. The row says all articles. A section inside another is listed with its parent's name first, like "Staff › Printers"; ticking "Staff" already covers it.
• Expand a section (the arrow beside its name) to see its published articles, and tick single ones. The row says how many are picked. An article's own box is unavailable while its whole section is ticked, since the section already covers it, and ticking a section clears any single picks inside it.
• An article with a lock and restricted is one Zendesk shows only to a user segment, such as signed-in agents. Zendesk sets this per article (in the article's Visible to setting), not per section, so expand a section to see which of its articles are restricted. Internal IT runbooks usually are. They aren't hidden from you: whether they should feed the agent is your call. See Who sees it before ticking one.
• The count at the bottom says how many sections and articles are selected. "Nothing selected, so no articles will sync" means just that.

Select Save selection. Saving records the choice; it doesn't sync. Select Sync now to bring the articles in right away, or wait for the scheduled sync. After a save, you can leave and come back: the ticks are kept.

Drafts never sync, whether a section is ticked or an article is picked. An article your team moves into a ticked section starts syncing on the next sync; one moved out of it stops. Articles are followed by their Zendesk id, so renaming an article or a section doesn't lose it.

Which should I choose: a whole section or single articles?#

| Option | What happens | Choose it when | | --- | --- | --- | | Tick a section | Everything published in it today and everything added later, with no one revisiting this page | The section is written for the people the agent serves, like "Students & Families" or "Staff how-tos" | | Pick single articles | Only those articles, forever; new articles in that section don't come in | A section mixes audiences or has a few articles worth sharing, like one "Guest Wi-Fi" article in an otherwise internal section | | Tick a section of restricted articles | Its articles come in for staff only (see below) | Your staff ask the agent about internal procedures, and no student or guardian should get them |

Examples:

• A district with 12 schools ticks "Students & Families" and "Staff how-tos" and leaves "IT Internal" alone. New articles the helpdesk writes into either section reach the agent within the week, with no one touching schoolOS.
• A Chromebook 1:1 program has one "Chromebook repairs" section whose articles are restricted to agents, because half of it is repair pricing. The tech coordinator expands it and picks just "Report a broken Chromebook" and "Loaner Chromebooks", so parents can be answered from those two and nothing else.

Sync#

A sync reads your Help Center, then compares what it finds with what schoolOS already has:

• Added. An article schoolOS hasn't seen. It becomes an article in Admin › Help Center › Articles, with its formatting, filed under its category and section, and editable there (see Imported articles). It comes in with a link to the article in your Help Center that answers can cite. Like every knowledge source, it's split into passages and indexed for search, so the agent can find it by meaning, not just by its exact words.
• Updated. An article that changed in Zendesk since the last sync is replaced in place. Once someone edits the article in Admin › Help Center › Articles, syncing leaves their edit alone and marks the article Changed in Zendesk when Zendesk changes it, to compare and decide. One article in Zendesk is always one source in schoolOS, so editing never piles up duplicates.
• Unchanged. The text isn't re-read or re-indexed; only the sync time and who can see it (see Who sees it) are brought up to date.
• Retired. An article that's no longer selected, no longer published, deleted in Zendesk, or moved out of a ticked section leaves the knowledge base and stops being an answer right away. Its help center article is archived, unless someone has edited it there, in which case it stays. Tick it or its section again and the next sync brings it back. A sync that can't read your Help Center all the way through retires nothing, so a Zendesk outage never empties the knowledge base.
• Failed. An article that couldn't be read this time. It's tried again next sync.

Sync now runs while you wait and reports the result underneath: "Synced 412 articles: 12 added, 3 updated, 397 unchanged." The first sync of a large Help Center can take a few minutes, since every article is indexed; later syncs only index what changed. If Zendesk asks schoolOS to slow down, the sync waits as long as Zendesk says and carries on. Nothing is capped: a Help Center with thousands of articles is read whole, so there's never a silent "first 500".

Syncing can also be automatic. Keeping it current, under the selection, starts closed and shows how often and when it last synced, like Keeps in sync weekly · Last synced …; select its name to open it. It has How often: bring the articles in once, or keep them in sync on a schedule. It saves as soon as you pick it, and it's the same setting as on Zendesk in the Knowledge tab of Admin › Account › Import Data, which opens this page. A new connection starts at Keep in sync: weekly. The check runs every 15 minutes, so a sync happens within a quarter of an hour of being due, and the first automatic sync comes soon after you connect, even if you never select Sync now. When you change the selection and want it reflected today, select Sync now. Beside it, Last synced shows when the last sync ran, automatic or not, how it went, and its counts.

Once, or keep in sync?#

| Option | What it does | Choose it when | | --- | --- | --- | | Once — I'll sync again when I want | A one-time import: the articles come in when you select Sync now, and never on their own. | You're moving off Zendesk and want one copy of its articles, or you want to review changes before they reach the agent. | | Keep in sync: hourly | Re-reads the selection every hour. | During a rollout, when articles are being corrected all day. Unchanged articles are skipped, so it's cheap. | | Keep in sync: daily | Re-reads it every day. | Your helpdesk publishes often, and edits should reach the agent by the next morning. | | Keep in sync: weekly | Re-reads it every week. New connections start here. | Articles change a few times a month, and a week's lag is fine. | | Keep in sync: monthly | Re-reads it every month. | A help center that's finished, like a retired system's archive. |

Every run, automatic or not, is listed on the Integrations tab of Admin › Account › Logs under Zendesk, with its counts. A run in which some articles failed is recorded as a warning and emails your account admins, at most once a day. If a scheduled sync can't sign in at all (the token was deleted, say), Last synced says Failed with the reason, and the next automatic try waits until it's due again, so reconnect and select Sync now.

For example, the helpdesk rewrites "Resetting your password" on Tuesday. On Wednesday the weekly sync runs, the article shows as 1 updated, and a student asking the agent that evening gets the new steps.

Who sees it#

Every knowledge source has an audience, and the agent only answers a person from sources in their audience (see Knowledge). Who can see what comes in, under the picker, sets two:

• Articles everyone can see in Zendesk: articles Zendesk shows to everyone. They start as Public: anyone can be answered from them, including people who aren't signed in on your website.
• Restricted articles: articles Zendesk limits to a user segment, such as signed-in users or agents and admins. They start as Staff: agents and admins can be answered from them, and students, guardians and guests can't.

Each opens the same picker as the other knowledge sources: Public, Everyone signed in, Staff, Students, Guardians, and your district's school roles, so restricted runbooks can go to, say, Staff and your Building Technicians role. Select Save selection to save it with what you ticked; the next sync applies it.

The same audience is who can read each article in Admin › Help Center › Articles and your help center. An article follows these settings on every sync, wider or narrower, until someone changes that article's Who can see it in Admin › Help Center › Articles; from then on the sync leaves its audience alone.

Otto answers admins, so it can use every synced article.

Disconnect#

Open Connection on the Zendesk page and select Disconnect, or use Disconnect from the row's ⋯ menu on Admin › Account › Integrations, and confirm. Syncing stops, the saved API token and your selection are cleared, and nothing changes in Zendesk. To stop it for good, also delete the token in Zendesk. See Disconnect an integration.

Articles already synced stay in the knowledge base after you disconnect, and the agent keeps answering from them. To take them out, remove them on the Knowledge tab, or, before you disconnect, untick the sections you no longer want, save, and Sync now so they're retired. Unticking everything, saving and selecting Sync now retires every article this connection brought in.

Reconnecting starts with an empty selection. Articles that were synced before are updated in place rather than added twice.

Troubleshooting#

• "Zendesk rejected the credentials. Check the agent email and that the API token is active." The email isn't the one the token was created under, the token was deleted, or Token access is off in Zendesk API settings.
• "That Zendesk agent does not have permission for this. An admin role is usually required." The token's agent can sign in but can't read the Help Center's sections. Use a token from an agent with an admin role.
• "Zendesk returned 404. Check the subdomain, and that Help Center is enabled for this account." A typo in the subdomain, or Help Center isn't turned on.
• "Zendesk is rate limiting this account." Zendesk asked schoolOS to slow down. Wait a few minutes and select Sync now again.
• A section is missing from the picker. The token's agent can't see it in Zendesk. "No published articles in this section" means every article in it is a draft.
• You changed the selection but answers didn't change. Saving doesn't sync. Select Sync now.
• The agent gave a student an internal article. The article is visible to everyone in Zendesk, so it came in as Public (all). Restrict it to a user segment in Zendesk, then select Sync now: it becomes staff-only straight away.
• The scheduled sync stopped. Last synced, under Keeping it current, says Failed with the reason. The fix is usually to paste a new token, Save and test connection, and select Sync now. If How often says Once, nothing runs on its own: that's the choice, not a fault.