This page describes how to import, into the Portail ZAPP knowledge bases, the user documentation shipped with the application.
When to use it
After the application is updated, administrators see a reminder: the imported documentation is no longer up to date with version 0.1.0. The Update the documentation button (Knowledge base menu, administrators only) starts the import.
What the import does
- It creates the missing articles, published directly.
- It updates an article whose text has changed, with a new revision.
- It leaves unchanged articles alone: no needless revision.
- It never deletes anything: an article whose source has disappeared is reported as an orphan.
The import runs in the background: the screen shows the current step (reading, articles, help links, semantic indexing), the number of pages processed and the page being processed. You can leave the page, the import keeps running; when you come back, you see its progress again. Only one import runs at a time: starting another one during an import shows the one in progress.
Articles and Help links are saved first; indexing for semantic search, the longest step, comes next. If no AI is configured, this step is skipped and the report says so: the articles can still be found by full-text search.
The report lists the articles created, updated, unchanged and orphaned.
Who can read the shipped pages
Pages meant for every signed-in user are in the Help base. Pages meant for teams (Service Desk agents, stock or asset managersā¦) are in the Documentation base: each category names the groups that read it, and the import grants them read access to that category. Everyone reads the help for their own screens, and the Help link takes them there.
A right you grant yourself in a base's permissions screen is never changed by the import. Rights set by the import carry the Shipped documentation badge there: if you revoke one, the next import sets it again as long as the documentation declares it. A group named by the documentation that does not exist on your instance is reported in the summary.
Variables in pages
Pages can use {{ProductName}} (the application name of the instance), {{ProductVersion}} and {{AppVersion}}, replaced at import time.
Screenshots
A page can show screenshots: they are imported with it, stored as files of the article and shown only to the people who can read the article. A changed screenshot replaces the previous one, without duplicates.
Publishing the documentation on another site
The Export the documentation button produces a package (.zip file) containing the Portail ZAPP documentation: pages, screenshots and table of contents, under the product name and version.
On another instance, such as a documentation portal, an administrator imports it with Import a documentation package. The rules are the same as for the update: nothing is deleted, an unchanged article gets no revision, an article written in the application is never overwritten. A package never changes the Help links of the instance that imports it, and it is refused if one of its knowledge bases already belongs to another source.
See also
- "Administer a knowledge base": the permissions screen of a base.