ARCHIVED: KB web services: Getting documents

This content has been archived, and is no longer maintained by Indiana University. Information here may no longer be accurate, and links may no longer be available or reliable.

You can use the Knowledge Base web services to retrieve content in a specialized XML format, and then use that data to embed the content in your application.

Note: For more about the terms used below, see ARCHIVED: KB web services glossary.

On this page:

Getting documents with SOAP
Getting documents with REST
Gotchas
Errors

Getting documents with SOAP

kbDocumentInfo getDocument(string authKey, string whichKB, string docId, array domains, string audience)

Return the document docId. whichKB is the domain class you need. domains is a list of strings, naming the domains you can use when accessing this document. audience is the group to whom this document is being presented.

The kbDocumentInfo structure has a number of fields: text, title, refDocuments, refTitles, and docDomains. text is the only supported field; all other fields are deprecated, and may return incorrect information. That field contains the entire text of the requested document, along with metadata, in a special XML format. For more information about that format, see ARCHIVED: KB web services: KB document XML format.

Getting documents with REST

GET /REST/v0.2/whichKB/document[/preview]/audience/docId[/version/label][?domain=domainname][&domain=domainname]

Return the document docId. whichKB is the name of the domain class you need. audience is the group to whom this document is being presented.

The arguments enclosed in square brackets (preview, version, label, and domain) are optional. You can use these arguments to customize your REST call in two ways:

The preview, version, and label arguments allow you to request a pre-publication version of a document; these are sometimes created by Knowledge Management staff. Each pre-publication version is given a label, and you can request that version by including the label. All three arguments must appear in the REST URL to do this.
Note: When using the preview parameter, do not set the whichkb parameter.
The domain argument allows you to specify the user domain(s) to use when accessing this document. If you provide several values for domain, the request will use all of those domains together.

This method returns the entire text of the requested document, along with metadata, in a special XML format; for more, see ARCHIVED: KB web services: KB document XML format.

Headers in the HTTP response provide the document's metadata. Their names begin with X-Kb-. Most of them correspond directly to tags in the ARCHIVED: metadata section of ARCHIVED: KB web services: KB document XML format, and you can read about their semantics there. These headers include:

X-Kb-Approved (YYYY-MM-DD format)
X-Kb-Author
X-Kb-Birthdate (YYYY-MM-DD format)
X-Kb-Domains (comma-separated values)
X-Kb-Importance
X-Kb-Lastmodified (YYYY-MM-DD format)
X-Kb-Owner
X-Kb-Refbys (comma-separated values)
X-Kb-References (comma-separated values)
X-Kb-Resources (comma-separated values)
X-Kb-Status
X-Kb-Visibility
X-Kb-Volatility

Headers not corresponding directly to metadata tags are:

X-Kb-Live: This header will always have a value of 1.
X-Kb-Mtime: This header provides the last time at which the document's cache was updated, in seconds since the Unix epoch. This is different from X-Kb-Lastmodified, since it reflects changes to related documents or metadata on the editing server as well as the document itself.
X-Kb-Titles-Default, X-Kb-Titles-...: Every document will have an X-Kb-Titles-Audience header for each of its titles. The Audience in the header name will specify the title's intended audience. For example, suppose a document has both a default title and a second title for the ose audience. These will be stored in the X-Kb-Titles-Default and X-Kb-Titles-Ose headers, respectively.

If a document is missing a piece of metadata, the corresponding header will not appear at all. For example, if you request a document that does not have any resources associated with it, the response will not include an X-Kb-Resources header.

You may be able to use these headers to avoid processing the full XML that this method returns. For example, suppose you want to download the XML for all the documents in a list that have a visibility of visible. You could request each document on the list, and then use the X-Kb-Visibility header to decide whether or not to save the XML.

Gotchas

When using the preview parameter, do not set the whichKB parameter.
When retrieving documents from one domain that contain links to documents in another domain, be sure to supply both domains as parameters in your call; otherwise, the links will break. The links will be rendered with the target document's "access" attribute set to "restricted", and you won't be able to access the target documents. To supply two domain names using REST, append the domain parameters one at a time like this:
```
  ?domain=<domain1>&domain=<domain2>
```

Errors

You may encounter the following errors when trying to get a document:

Error description	Exception class	Example error message
Document ID has a bad format	BadIDFormat	The error message will be the bad document ID you provided.
The given domain class does not exist	UnknownDomainClass	The error message will be the name of the domain class you provided.
A given domain does not exist	UnknownDomain	The error message will be the name of the domain you provided.
Requested document does not exist	Experimental::Exception::Die	EXCEPTION: Invalid document identifier, wwqz
A document cannot be accessed from the domains you provided	Experimental::Exception::Die	EXCEPTION: Insufficient credentials to access tesa
The requested document cannot be rendered	Experimental::Exception::Die	EXCEPTION: Unable to load document tsta