Knowledge Manager

1What it is

Knowledge Manager answers a question that is surprisingly hard to answer inside Genesys Cloud itself: “what exactly is in our knowledge bases, and is it any good?” One click runs a harvest: the app walks the Knowledge APIs and captures everything — every knowledge base, the full category tree, all labels, and every article with its metadata (state, visibility, authorship, dates, published version, alternative phrases) plus its complete body content. The result is saved as a point-in-time snapshot, and the review portal then works entirely from that snapshot: browsing never re-queries Genesys, so review sessions are instant and put zero load on the platform.

• Draft + published bodies — content is captured for both sides of every article, so a review catches what is about to go live, not just what is live. The reader's Published/Draft tabs make in-flight edits obvious.
• Strictly read-only — the Genesys client can only issue GET requests (the OAuth token call is the sole POST, and it goes to Genesys’ login service, not the API).
• Owner-scoped — each snapshot belongs to the region + Client ID that harvested it; purging your data never touches anyone else's (§4, §6).
• Deltas — re-harvesting replaces the snapshot and shows count changes against the previous one on the overview stats.

The Genesys knowledge model it mirrors

Knowledge base (KB)

A container of articles with one core language. An org may have several — per brand, department or bot.

Category

A hierarchical folder inside one KB. An article references at most one category; articles without one appear under Uncategorised in this app.

Article (document)

One knowledge item. Its state is Published, Draft or Archived; visible controls whether knowledge-search surfaces offer it. Articles also carry alternative phrases (utterances that should match them) and audit metadata.

Variation

The actual content of an article. An article can hold several variations (targeted at different contexts/channels), and each side — draft and published — has its own set. Content is a tree of blocks: paragraphs, ordered/unordered lists, images, videos and tables, with bold/italic/underline/strikethrough marks and hyperlinks.

Label

A flat, colour-coded tag applicable to any article in the KB — orthogonal to categories.

2Quick start

1. Sign in — pick the API region your org lives in, then enter an OAuth client-credentials Client ID and Secret. The client's role needs the Knowledge View permissions (§5). Credentials are validated against Genesys, held on the server and never sent to the browser.
2. Harvest — press Harvest (or Start first harvest on the empty state). A progress banner shows the phase, KB/article counters, API-call count and any warnings; a typical org finishes in a few minutes. You can navigate away or sign out — the harvest keeps running, and your next sign-in with the same client reattaches to it.
3. Review — the overview fills with five stat cards and one card per knowledge base. Click a KB card to browse it, click any article row to read it, click any stat card to see the exact rows behind the number.
4. Export — the CSV button downloads the full article inventory; the overview footer offers the raw snapshot (gzipped JSON); every drawer view and article has its own export.

3UI walkthrough

Sign-in & sessions

• The connect form asks for region (the 14 Genesys regions), Client ID and Client Secret. On success the secret field is cleared and the top bar shows an org chip (org name + API domain, e.g. mypurecloud.ie).
• Sessions end after a period of inactivity. Signing back in resumes exactly where you were — the snapshot and any running harvest are keyed to the client, not the session.
• The top bar holds Harvest / Re-harvest, CSV (disabled until a snapshot exists), Guide (this manual, new tab) and Sign out.

Harvesting

• Harvest / Re-harvest starts a full pull. Re-harvesting replaces the previous snapshot for your client and records deltas (green/red markers on the overview stats).
• The progress banner shows the current phase — “Listing knowledge bases…”, “<KB name>: categories & labels…”, “…listing articles…”, “…article content…”, “Saving snapshot…” — plus KB x/y, articles x/y, the running API-call count and a warning count. The bar is indeterminate until the article total is known, then fills by articles done.
• A latest-warning line appears under the bar when items are skipped (hover it for the recent list). Warnings mean specific items failed — one KB's labels, one article's content — while the rest of the harvest carried on. Up to 50 are kept in the snapshot and reviewable afterwards (below).
• Cancel aborts cleanly at the next step boundary — no partial snapshot is written; the previous snapshot (if any) stays in place.
• Only one harvest per client runs at a time. If a colleague on the same Client ID already started one, your Harvest button simply attaches to its progress.
• Completion shows a green banner (“Harvest complete — N articles across N knowledge base(s) in Xm Ys”) and the overview refreshes automatically.

Overview

• Harvest warnings panel — if the snapshot recorded warnings, an amber “harvest warning(s)” panel tops the overview listing every one (they are stored in the snapshot, so they survive sign-out). See §8 for the usual cause.
• Stats band — five cards: Knowledge bases, Categories, Articles (with a published · draft · archived split), Content variations and Labels, with change-since-last-harvest markers where a previous snapshot exists. Every card is clickable — it opens a data drawer with the rows behind the number (next heading).
• Harvest note — when the snapshot was taken (relative + absolute), how long it took, how many API calls it cost, and the previous harvest date.
• KB cards — one per knowledge base: name, core language, id prefix, description, pills for article count, per-state counts and category count, and the last-modified date. Click to browse.
• Footer — snapshot scoping note, Download raw snapshot (JSON.gz), and Delete my harvested data (confirm-guarded purge of your snapshot only; blocked while your harvest is running; re-harvest any time afterwards).

Stat drawers — the rows behind each number

Clicking a stat card opens a right-hand drawer with a filter box, a live “N of M rows” readout, click-to-sort column headers (click again to flip direction) and a Download this view as CSV button that exports exactly the filtered, sorted rows on screen. Rows navigate onward:

The filter box matches across every column (formatted dates included). Esc, the ✕ button or clicking outside closes the drawer.

Browsing a knowledge base

• KB dropdown — switches between knowledge bases (with article counts) without going back to the overview; ← back returns to it.
• Category tree (left) — the full hierarchy with per-node article counts, plus All articles and (when any exist) Uncategorised. Roots are always expanded; carets expand/collapse deeper branches. The Include subcategories toggle (default on) controls whether selecting a category also shows — and counts — everything beneath it.
• Search — case-insensitive substring match against titles and alternative phrases.
• State segment — All / Published / Draft / Archived.
• Label chips — the KB's 16 most-used labels with usage counts; any-of matching; a ✕ clear labels chip appears when any are active.
• Article table — Title (with an “N alternative phrase(s)” subline), State pill (plus a hidden pill when the article is invisible to search), Category path, Labels (first three + +N), Words, Modified. Title, State, Words and Modified sort on header click (Modified-descending by default). All filters compose, and the count readout always shows matching / total. Click a row to read.

Article reader

• Opens as a right-hand drawer (Esc or click outside to close). The page address tracks it, so a specific article can be bookmarked or sent to a colleague; after they sign in, the deep link opens straight onto the article.
• Header — full category breadcrumb, state / hidden from search / label chips, and a metadata grid: created + by, modified + by, publish date, published version, word count and document ID. Every alternative phrase is listed as a chip.
• Published / Draft tabs — only sides that actually have content appear, each with its variation count; a picker appears when a side holds more than one variation.
• Faithful rendering — paragraphs, ordered/unordered lists (nested), tables, images (loaded from their original Genesys URLs, hyperlinked where the source is), videos (as links), bold/italic/underline/strikethrough, hyperlinks and embedded line breaks. Content is built strictly as DOM text — article bodies are data, never markup, so a malicious article cannot script the page. Any block type the renderer doesn't know degrades to an inspectable “Unsupported block” panel showing its raw JSON — nothing is silently dropped.
• Copy JSON / Download JSON — the complete raw article record for deeper inspection.

Exports

4Snapshot model

Owner scoping

A snapshot's owner is the region + Client ID that harvested it. Everyone signing in with the same region + client shares one snapshot and one harvest slot; different clients — even in the same org — have fully separate snapshots. Purging deletes only the caller's own snapshot. The owner key is also why a re-login (or a colleague's login) reattaches to a running harvest: jobs are keyed by owner, not by session.

What a snapshot contains

• Identity & provenance — org id/name, region, harvest timestamp, duration, total API calls, and the harvest warnings list.
• Totals — KBs, categories, labels, articles (with a by-state breakdown) and variations — plus the previous harvest's timestamp and totals, which drive the overview deltas.
• Per KB — id, name, description, core language, published flag, created/modified dates; all categories (id, name, description, parent id); all labels (id, name, colour); all documents.
• Per document — title, state, visibility, category id, label ids, alternative phrases, created/modified/published dates, last published version, author names, a computed word count (from published content, falling back to draft), and its variations: separate draft and published arrays, each variation carrying id, name, priority, dates, contexts and the full body block tree.

Storage

• One compressed snapshot per owner, kept in the app’s private store, with a small summary used at sign-in.
• Saves are atomic, so an interruption mid-save can never leave a corrupt snapshot; a re-harvest replaces the snapshot.
• The app keeps one snapshot per owner, not a history — download the raw snapshot before re-harvesting if you want to diff two points in time externally.

5Genesys endpoints & permissions

Every Genesys call the app can make, all read-only. Listings page at 100 items per call, following the nextUri cursor (with a classic pageNumber fallback), with pacing and automatic 401/429/5xx recovery.

OAuth client requirements

• Grant type: Client Credentials.
• The client's assigned role must include the Knowledge view permissions: knowledge > knowledgeBase > view · knowledge > category > view · knowledge > document > view · knowledge > label > view (a Knowledge read-only role, or Knowledge > All with view, also works). A harvest that hits 403 fails with a message naming exactly these permissions.
• Division scope matters — the client only sees knowledge bases in divisions its role covers.

6Storage, privacy & security

• What is stored — harvested knowledge content and metadata (the snapshot), per owner, in the app’s private store. Knowledge articles are business content rather than personal data, but drafts may contain unreviewed or unreleased material — treat snapshots and exports with the same care as the knowledge base itself.
• What is never stored — Client Secrets and tokens are held on the server only for your session and never sent to the browser or written to storage. Sessions end after a period of inactivity; a repeat region+client sign-in replaces its older session.
• Owner scoping — snapshots belong to the region + Client ID that harvested them; the purge action deletes only the caller's own snapshot and is blocked while that owner's harvest runs.
• Multi-user — sessions are independent; several people can browse the same snapshot while another owner's harvest runs.
• Content safety — article content is rendered strictly as text and never injected as HTML, so a hostile article body cannot script the review portal.
• Images — the reader loads images from their original Genesys-hosted URLs, so viewing them requires those URLs to be reachable from your browser; everything else is served from the snapshot.
• Read-only Genesys client — GET-only by construction (§5); the app cannot modify the org. Content is stored verbatim, not masked — the mitigations are owner scoping and the read-only client.

7Technology

• Web application — sign-in, the paced Genesys client (token lifecycle, retries, paging), the harvest job engine, the snapshot store, word counts and the CSV export.
• Browser interface — a single page; the article reader tracks the page address so specific articles deep-link (§3).
• Harvest engine — background jobs per owner: phases, counters, clean cancellation at step boundaries, parallel article-content fetches, and warning capture (up to 50) that ends up in the snapshot.

8Troubleshooting

Login fails with “authentication failed”.

Wrong Client ID/Secret — or the right credentials in the wrong region (a client only authenticates against its own region's login host). Check both.

Harvest fails immediately with a 403 message.

The OAuth client's role lacks the Knowledge view permissions (§5). Add them (or assign a Knowledge read-only role) and re-harvest.

Harvest completes but with many permission warnings.

Almost always permission propagation lag: role changes take a minute or two to reach every Genesys API node, so a harvest started straight after editing the role sees a random mix of allowed and 403'd calls — the same permission passing for one KB and failing for another is the tell-tale. Wait a couple of minutes and re-harvest; the fresh snapshot replaces the patchy one. Warnings that persist across re-harvests are a real gap: a missing §5 permission or a division the role doesn't cover.

Harvest succeeds but shows 0 knowledge bases.

The org genuinely has none visible to this client — check the role's division scope covers the divisions the knowledge bases live in.

An article shows “no content variations were captured”.

The article is empty, it belongs to a legacy V1 knowledge base (§1), or its content fetch failed — per-item warnings are recorded in the harvest banner and the snapshot's warnings panel; re-harvest to retry.

An article body shows an “Unsupported block” panel.

Genesys added a block type this renderer doesn't know yet. The raw JSON is shown so nothing is hidden — report it so the renderer can be extended.

Images inside articles don't display.

Images load from their original Genesys-hosted URLs, not from the snapshot — the browser needs those URLs to be reachable (and still valid).

Harvest seems slow.

That's the rate-limit pacing (§3) — by design, so harvests are safe during business hours. The API-call counter should tick steadily; a long stall means Genesys is returning 429s and the app is backing off, which resolves itself.

“A harvest is already running for this org / client.”

Someone using the same Client ID started one — your session automatically attaches to its progress. Wait for it, or Cancel it.

Overview deltas look odd after a re-harvest.

Deltas compare against the previous snapshot of the same owner. A first harvest, or the first after a purge, has no baseline, so no deltas appear.

“The service is busy – try again shortly.”

The service is handling as many sign-ins as it can. Re-signing in with a region+client that already holds a session replaces that session instead; otherwise try again shortly.

Signed out unexpectedly / everything 401s.

Sessions end after a period of inactivity. Sign back in — the snapshot is untouched, and a running harvest reattaches.