Freshdesk

Freshdesk's Solutions are the knowledge base behind a Freshworks support portal: the articles your helpdesk writes for staff and families, filed in categories and folders. Connecting Freshdesk brings the published articles from the folders 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 Freshdesk, the next sync updates it here.

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

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

Find your API key#

schoolOS signs in with an agent's API key, so it never holds a password.

1. In Freshdesk, select your profile picture, then Profile settings.
2. Copy Your API Key from the right-hand side.

The key belongs to that agent, and schoolOS sees exactly what the agent can see: every category, folder and article they can open in Solutions. The agent needs access to the knowledge base; an agent without it signs in fine and has nothing to sync. Use a shared or service agent rather than a person's own account, so the connection keeps working when someone leaves. Resetting the key in Freshdesk is the same as disconnecting: the next sync fails until you connect with the new one.

Connect#

1. Open the Freshdesk page and fill in Connection:
   • Freshdesk domain. The part before .freshdesk.com. The name or the whole URL; both work.
   • API key. The key you copied.
2. Select Connect.

schoolOS reads your categories and folders with the key, all before it saves anything, because "can this key see the knowledge base" is the question that matters. If Freshdesk refuses the details, nothing is saved and the page says what to fix. Once it works, What schoolOS can see says what it found, like "Connected to yourdistrict.freshdesk.com, with 3 categories and 14 folders."

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

For example, a district's Freshdesk has the categories "Families", "Staff" and "Technology Services". IT connects with the key of its shared helpdesk agent, sees 3 categories and 14 folders, and What to bring in appears below.

Choose what comes in#

Nothing syncs until you choose. What to bring in lists your Solutions, grouped under category headings, one row per folder. Freshdesk calls them folders; the page calls them sections, the same word the Zendesk page uses, because you're choosing the same thing. Use Search … sections to find one by name or description.

• Tick a section to bring in every published article in that folder, including articles your team adds to it later, and every subfolder inside it. The row says all articles. A subfolder 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 folder is ticked, since the folder already covers it, and ticking a folder clears any single picks inside it. Article titles here aren't links; open them in Freshdesk if you need to check one.
• A folder with a lock and restricted is one whose visibility in Freshdesk is narrower than everyone (logged-in users, agents only, or selected companies), sits inside such a folder, or whose visibility Freshdesk didn't report. It's where internal IT runbooks usually live. It isn't hidden from you: whether it 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.

Only articles Freshdesk shows as Published sync; drafts never do. An article your team moves into a ticked folder starts syncing on the next sync; one moved out of it stops. Articles are followed by their Freshdesk id, so renaming an article or a folder doesn't lose it.

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

| Option | What happens | Choose it when | | --- | --- | --- | | Tick a folder | Everything published in it today and everything added later, with no one revisiting this page | The folder is written for the people the agent serves, like "Families" or "Classroom technology" | | Pick single articles | Only those articles, forever; new articles in that folder don't come in | A folder mixes audiences or has a few articles worth sharing, like one "Guest Wi-Fi" article in an otherwise internal folder | | Tick a restricted folder | 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 every folder under "Families" and "Staff" and leaves "Technology Services" alone. New articles the helpdesk writes into those folders reach the agent within the week, with no one touching schoolOS.
• A Facilities team keeps "Work order how-tos" in a folder visible to agents only. The Facilities director ticks it anyway: custodians who sign in to schoolOS can ask the agent how to log an HVAC request, and nobody on the public website can.

Sync#

A sync reads your Solutions, 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 folder, and editable there (see Imported articles). It comes in with a link to the article on your support portal 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 Freshdesk since the last sync, or moved to another folder, 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 Freshdesk when Freshdesk changes it, to compare and decide. One article in Freshdesk 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 Freshdesk, or moved out of a ticked folder 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 folder again and the next sync brings it back. A sync that can't read your Solutions all the way through retires nothing, so a Freshdesk 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 180 articles: 6 added, 2 updated, 172 unchanged." The first sync of a large knowledge base can take a few minutes, since every article is indexed; later syncs only index what changed. If Freshdesk asks schoolOS to slow down, the sync waits as long as Freshdesk says and carries on. Nothing is capped: a knowledge base 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 Freshdesk 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 Freshdesk 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 Freshdesk, 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 key was reset, 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 "Connecting to staff Wi-Fi" on Tuesday. On Wednesday the weekly sync runs, the article shows as 1 updated, and a teacher 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 Freshdesk: articles Freshdesk 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 in a folder Freshdesk shows to less than everyone (including a subfolder of one), or whose folder's visibility schoolOS couldn't read. 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 Freshdesk page and select Disconnect, or use Disconnect from the row's ⋯ menu on Admin › Account › Integrations, and confirm. Syncing stops, the saved API key and your selection are cleared, and nothing changes in Freshdesk. To stop it for good, also reset the agent's API key in Freshdesk. 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 folders 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#

• "Freshdesk rejected the API key. Check it in your Freshdesk profile settings." The key was mistyped or has been reset. Copy Your API Key again.
• "That Freshdesk API key does not have permission for Solutions. An agent with knowledge base access is required." The key's agent can sign in but can't read the knowledge base. Use a key from an agent whose role includes Solutions.
• "Freshdesk returned 404. Check the domain is correct." A typo in the domain. Enter just the name, or paste the portal's URL.
• "Freshdesk is rate limiting this account." Freshdesk asked schoolOS to slow down. Wait a few minutes and select Sync now again.
• A folder is missing from the picker. The key's agent can't see it in Freshdesk. "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. Its folder is visible to everyone in Freshdesk, so it came in as Public (all). Narrow the folder's visibility in Freshdesk (or move the article to a restricted folder), 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 key, 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.