Connecting Hudu documentation

A Hudu source lets Qubit and Sherlock research cite the articles and assets in your Hudu. QuantumOps reads Hudu through Hudu's REST API with an API key that you create, so you decide what the key can see. This page gives the exact address and key to use, and what each error message means.

Before you start: you need the Administrator role in QuantumOps and the Documentation module on, and someone who can create an API key in Hudu (a Hudu administrator). If that is someone else, give them the section below.

What QuantumOps reads from Hudu

QuantumOps reads your companies, articles, the knowledge base folders the articles are filed in, assets together with their custom fields, and asset layouts. It uses the companies so that each article and asset can be tied to a client, the folders and layouts to give each document its category, and it reads nothing back into Hudu. Articles that belong to no company (Hudu's global knowledge base) are read too, and are not tied to a client. QuantumOps does not read Hudu password entries.

Only published articles are read. An article that is still a draft in Hudu is left out, because everything QuantumOps syncs becomes text that Qubit and research can quote to your technicians, and a draft may be unfinished. Publish the article in Hudu and the next sync picks it up. A sync never removes documents, so an article that was synced while published and later set back to a draft stays in QuantumOps.

Create the API key in Hudu

1. In Hudu, open Hudu Admin, then Basic Information, then API Keys.
2. Create a new API key and give it a name that says what it is for, for example QuantumOps documentation.
3. Choose the least access that still lets it read what Qubit should use. The key does not need password access or permission for destructive actions, so leave both off.
4. If you limit the key to some companies, only those companies are read. If you limit it to certain IP addresses, the requests from QuantumOps must come from an allowed address, otherwise Hudu answers 403 Forbidden.
5. Copy the key now. Hudu shows it once. Copy all of it, with no spaces before or after (QuantumOps removes stray spaces and line breaks for you).

Which address to use

Use the address of your own Hudu instance, the one you open in the browser, and nothing after it:

• Hudu cloud: https://your-instance.huducloud.com
• Self-hosted: https://hudu.example.com, with the port if it is not the standard one, for example http://hudu.example.com:3000. If Hudu sits behind a reverse proxy under a path, include that path, for example https://gateway.example.com/hudu.

QuantumOps accepts the address any reasonable way you have it: with or without https://, with a closing slash, or with /api or /api/v1 on the end (that part is removed). On Hudu cloud you can also paste the address of any page of Hudu, and everything after the host name is dropped. On a self-hosted address only a trailing /api or /api/v1 is removed and every other path is kept, because it may be your reverse-proxy path. Do not paste a page of Hudu there (for example https://hudu.example.com/companies/5): enter only the address of the instance. Do not put the API key in the address.

Add the source

1. Open the Documentation Hub and select Sources.
2. Under Add Documentation Source, choose Hudu.
3. Enter the API URL and the API Key.
4. Select Test Connection. A green message beginning Connected to and ending Hudu accepted the API key means the address and the key are right. A red message says what is wrong; the table below explains each one.
5. Select Save Source. If the source cannot be saved, a message says why and nothing is stored.
6. Select Sync on the new source card. The first sync can take a while for a large Hudu.

Select Test Connection again after any change. It makes one request and gives up after 30 seconds, so it never leaves you waiting.

Common errors

Every message starts with the address it was talking to or with Hudu, and never contains your key.

During a sync, a failed part shows on the source card with the reason, for example Could not read assets from Hudu: ... (403 Forbidden). The records that were read before the failure are still saved and indexed, and the card shows Error until a sync finishes without errors. If the database cannot save the documents, nothing from that run is saved, and the card says why.

Two parts only improve the category names: the asset layouts (the category of an asset) and the knowledge base folders (the category of an article). If Hudu refuses either one, for example with 403 Forbidden, the sync still succeeds and files those documents under a generic category such as General. The card then shows an amber note beginning Synced with warnings, and the message after you select Sync ends with Warnings, so you can give the key access to them. If the same sync also had an error, for example the assets could not be read, the warnings follow the error on the card and in the message, so neither hides the other.

Where failures are recorded

Every failed test and failed sync is also written to the error log with your organization, so support can see what happened. The log holds the same sentence you see, and never the API key.

Related pages

• Documentation sources: the Sources tab, syncing, pausing and deleting a source.
• Documentation Hub: mapping Hudu companies to clients and the search settings.
• What Qubit can use: tools and sources: how Qubit uses what you connect.