HappyFox

HappyFox Help Desk's knowledge base holds the articles your help desk writes, in sections that can nest inside one another, with some marked internal so only your agents see them. Connecting HappyFox brings the published articles from the sections and articles 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 HappyFox, the next sync updates it here.

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

Find it under Knowledge on Admin › Account › Integrations, or from the Knowledge tab of Admin › Agent › Configuration: Add knowledge source › Help Center › HappyFox, which lists your sources with Choose articles beside each and Add source below. Either way the setup lives on the HappyFox page; when you arrive from the Knowledge tab, a Knowledge sources button takes you back. You need Manage integrations. For how HappyFox sits beside the other knowledge integrations, see Knowledge.

Unlike Zendesk and Freshworks, HappyFox is a list of sources: an account can connect several HappyFox help desks, or the same one twice, each with its own name, sign-in, selection, audience and schedule. See One source or several?.

Get an API key#

schoolOS signs in with an API key and auth code that a HappyFox admin creates, so it never holds a password.

1. In HappyFox, open Manage › Integrations › API.
2. Create an API key. HappyFox shows the key and its auth code together; copy both.

The key sees your knowledge base as HappyFox's API allows it to, including internal (agents-only) sections and articles, so what it can see is what schoolOS can see. Revoking the key in HappyFox is the same as disconnecting: the next sync fails until you edit the source and enter a new one. The How to get an API key link in the add dialog opens HappyFox's own instructions.

Connect#

1. Open the HappyFox page and select Add HappyFox source (or Add source at the top once you have one).
2. Fill in the dialog:
   • Name. What this source is called in schoolOS, like IT, District or Community (the suggestions under the box). Pick a name no other source uses.
   • HappyFox account. Your help desk's address, like https://yourdistrict.happyfox.com. Paste any link from your help desk; only the account is used. The name alone works too.
   • API key and Auth code. Both from the step above. Stored encrypted and never shown again.
   • Who can see it. The audience every item you tick starts with. Everyone signed in to start. You can change it per item later; see Who sees it.
3. Select Connect.

schoolOS signs in and lists your knowledge base's sections before it saves anything, so a wrong address or key is caught now rather than on the first sync. If HappyFox refuses, nothing is saved and the dialog says what to fix. Once it works, the source is listed, and Choose what … brings in opens right away, because the next thing anyone does after connecting is choose.

Each source is a card: its name and address, how many articles and ticked items it has and when it last synced ("Connected. Choose what to bring in." until you choose), with Choose content, Sync now and a ⋯ menu. Edit connection changes the name, address, sign-in and starting audience; leave API key and Auth code blank to keep the stored ones, or paste new ones to replace them, and saving checks the connection again. Changing Who can see it here changes the starting point for things you tick from now on; items you already ticked keep their own audience.

For example, a district connects its single HappyFox as a source named IT, with its shared admin's key. The picker opens showing sections "Getting started", "Chromebooks" and "Staff procedures", the last one marked Internal in HappyFox.

One source or several?#

| Option | What it means | Choose it when | | --- | --- | --- | | One source | One sign-in, one selection, one schedule, with a different audience per ticked section if you like | One HappyFox help desk, managed by one team. Most districts | | One source per team | Each team connects its own HappyFox (or its own key to a shared one) and chooses its own sections; disconnecting one leaves the others | IT and Facilities run separate help desks, or each should own what its sections feed the agent | | The same help desk twice | Two sources pointing at one HappyFox, each bringing in overlapping sections with different audiences | A section should be public for one purpose and staff-only in another form. Rare: a per-item audience in one source usually does it |

Every source keeps its own copy of what it brings in, so two sources that include the same article don't fight over it.

Choose what comes in#

Select Choose content on a source to open Choose what … brings in. Nothing syncs until you choose.

On the left is your knowledge base as HappyFox arranges it: top-level sections, opened a level at a time with the arrow beside each, with sections first and then articles, each alphabetical. The filter box appears once there are more than eight top-level sections. On the right, What comes in lists what the ticks add up to.

• Tick a section to bring in everything under it: its articles, its subsections and theirs, and anything added later. Tick an article to bring in that one.
• Untick something inside a ticked section to leave it out, subsections and all. It moves to Left out on the right, with Bring back.
• Tick something inside something you left out to bring that part back. The nearest tick above an item always decides.
• Each item under What comes in has its own Who can see it. Ticking an item starts it at the source's audience, except that an item marked Internal in HappyFox starts at Staff. A tick inside another tick can have a different audience from the one above it.
• Internal in HappyFox marks a section or article only your agents can see there ("Only HappyFox agents can see it there."), including ones that inherit it from the section above. A section limited to a contact group says so instead. The label is a reminder, not a lock: it still comes into schoolOS, and the audience you choose decides who sees it here.
• The X beside an item under What comes in unticks it.

Select Save and sync. The selection is saved and an import starts right away in the background, so you can close the dialog and the card shows its progress. Save and sync stays unavailable until something changed and every ticked item has an audience ("Choose who can see each ticked item.").

Only articles HappyFox shows as published sync; drafts, unpublished and archived articles never do, and they don't appear in the tree. An article your team adds under a ticked section starts syncing on the next sync; one moved out of it stops. Items are followed by their HappyFox id, so renaming a section or article doesn't lose it. A source can hold up to 2,000 ticks and unticks, and the tree shows up to 1,000 items at one level.

Which should I choose: tick the section or the articles?#

| Option | What happens | Choose it when | | --- | --- | --- | | Tick a top-level section | Everything under it, now and later, with one audience | The section is written for the people the agent serves, like "Getting started" or "Families" | | Tick a section and untick parts of it | Everything but the parts you left out, which stay out even as the section grows | One subsection holds pricing, vendor contacts or anything the agent shouldn't repeat | | Tick single articles | Only those articles, forever | A section mixes audiences, and only a few articles belong with the agent | | Tick an internal section with the audience set to Staff | Agents-only procedures, answered only to staff who sign in | Your staff ask the agent about internal procedures, and no student or guardian should get them |

Examples:

• A district with 12 schools ticks "Getting started" and "Chromebooks" for Everyone signed in, then unticks "Chromebooks › Repair pricing". New articles in both sections flow in weekly; pricing never does.
• A middle school tech assigned to one building can't connect sources, but asks the agent "how do I re-enroll a Chromebook?" and gets the answer from "Staff procedures", which the district ticked with its audience on Staff. A guardian asking the same thing on the website gets nothing from it.

Who sees it#

Every knowledge source has an audience, and the agent only answers a person from sources in their audience (see Knowledge). With HappyFox you choose it yourself, per ticked item, before anything syncs:

| Audience | Who is answered from it | | --- | --- | | Public (all) | Anyone, including people who aren't signed in on your website | | Everyone signed in | Anyone who signs in to schoolOS: staff, students and guardians. The starting point for a new source | | Staff | Helpdesk staff, admins and anyone whose school role is Teacher. Suggested for anything Internal in HappyFox | | Students, Guardians, Admins | Those groups | | A school role | Only people with that school role, like Librarians |

An article's audience is the one on the nearest tick above it, and it's applied every sync, so changing an item's audience in the picker and selecting Save and sync changes every article under it. The Internal in HappyFox label travels with each article into the Knowledge tab, so you can see at a glance which synced articles HappyFox keeps from the public.

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

Sync#

A sync lists the whole knowledge base, works out which articles the ticks cover, reads each one, and compares it with what schoolOS already has:

• New or changed. An article schoolOS hasn't seen, or one edited since the last sync, comes in: its title and body (reduced to plain text, up to 50,000 characters; images and attachments stay in HappyFox), the section path it sits in, and a link to the article in HappyFox that answers can cite (the staff-side link for an internal article). One article in HappyFox is always one source in schoolOS, so editing never piles up duplicates. It also becomes an article in Admin › Help Center › Articles, with its formatting, filed under its sections and editable there, unless its tick is limited to particular agents (see Imported articles).
• Unchanged. Skipped, which is what makes a frequent schedule cheap.
• Could not be read. An article HappyFox returned without any readable text. It's tried again next sync and isn't removed.
• Removed. An article that's no longer under a tick, no longer published, or deleted in HappyFox leaves the knowledge base and stops being an answer. This only happens after a sync that listed the whole knowledge base; if part of it couldn't be listed, nothing is removed, and the card says "some content could not be listed".

Sync now on a card queues a run in the background, so you can leave the page. The card shows where it is: "Waiting to start…", "Looking through sections", "Reading 40 of 112", "Adding to the knowledge base…", then a summary like "Synced 112 documents, 9 new or changed, 1 could not be read". A run that fails is tried up to 5 times; if it still can't finish, the card says "The last sync didn't finish." with the reason. Sync now is unavailable until the source has content chosen.

Unticking everything and saving removes every article the source brought in, since nothing ticked means nothing should be knowledge.

For example, the help desk rewrites "Resetting your password" on Tuesday. On the next check, 1 article shows as new or changed, and a student asking the agent that evening gets the new steps.

How often#

Each card ends with How often: bring the selection in Once, or Keep in sync and let the source re-read HappyFox on its own. It saves the moment you pick, and a toast confirms. It's the same setting as on HappyFox in the Knowledge tab of Admin › Account › Import Data, which opens this page. A sync happens within a quarter of an hour of being due; a source that has never synced is due right away.

| Option | What it does | Choose it when | | --- | --- | --- | | Keep in sync: weekly | Re-reads the knowledge base weekly. The starting point | Articles change a few times a month, and a week's lag is fine | | Keep in sync: daily | Re-reads it daily | Your help desk publishes often, or you've just started and want edits to show up by the next morning | | Keep in sync: hourly | Re-reads it hourly | During a rollout, when articles are being corrected all day. Unchanged articles are skipped, so it's cheap | | Keep in sync: monthly | Re-reads it monthly | A knowledge base that's finished, like a retired system's archive | | Once — I'll sync again when I want | A one-time import: never on its own | You want to review changes in HappyFox before they reach the agent, and will press Sync now yourself |

Disconnect#

Open a source's ⋯ menu and select Disconnect, then confirm. Its articles leave the knowledge base and schoolAgent stops using them, its selection is deleted, and the stored key and auth code are cleared. Nothing changes in HappyFox itself, and your other HappyFox sources are untouched. To stop it for good, also revoke the key in HappyFox. See Disconnect an integration.

Reconnecting is adding a source again: a new name, sign-in and selection, with nothing carried over.

Troubleshooting#

• "HappyFox rejected the API key and auth code. Check both under Manage › Integrations › API in HappyFox." One of the two was mistyped, or the key was revoked. Edit connection and paste both again.
• "… is not a valid HappyFox account URL." The address has to end in happyfox.com (or happyfox.net). Paste the address you sign in at.
• "HappyFox has no knowledge-base endpoint at … Check the account URL, and that the knowledge base is turned on." schoolOS reached your account but HappyFox answered that there's no knowledge base to read. Check the address, and that the knowledge base is enabled in HappyFox. If both are right, contact schoolOS support with the message.
• "This account can't see any sections yet." The knowledge base has no sections, or the key can't see them.
• "Nothing in here yet." The section has no published articles or subsections.
• The last sync didn't finish. The card shows the reason. A sign-in problem means a revoked key: Edit connection and enter a new one. Anything else was already retried; select Sync now to try again.
• "… could not be read." HappyFox returned the article without a body, or it's empty. Open it in HappyFox and check it has text.
• Removed articles are still being answered from. The last sync couldn't list part of the knowledge base, so nothing was removed. Select Sync now once HappyFox is reachable again.
• The agent gave a student an internal article. Its tick's audience is wider than Staff. Open Choose content, change Who can see it on that item, and Save and sync.
• Sync now is unavailable. The source has nothing ticked. Select Choose content first.