Skip to main content

Reference

How documents are kept​

Every document is a record in the platform's documentation service. A record has:

FieldWhat it is
scope, entity, nameWhat the document is about. Together with language they identify it
languageThe language code, en by default
documentationTypeDefault (markdown in content), Link (url and an optional CSS selector) or JSON (json and an optional template)
tagsA list of tags. The title is kept as a tag starting title:

The same documents can be read in ODSL, for example d = ${documentation:"private"/"guides:curves:gas-curve-build"}, and through the REST API (documentation/v1/private/guides:curves:gas-curve-build).

When the scope is the name of a platform service, such as object, and the entity is the id of one of its records, saving the document adds a documentation link named after the document to that record.

Who can read and change documents​

Reading and changing documents follows the security policies on the documentation service in your company. Common and public documentation is shared with every client and can only be changed by OpenDataDSL: if you try, the screen shows the reason the platform gives. The extension's feature policy, extension.odsl.documentation_manager, controls who sees the Documentation menu item.

Opening the screen on a document​

Home page tasks and other extensions can open the screen with these properties:

PropertyWhat it does
SOURCEprivate, common or public
QText to find
CONTENTtrue to search the text of the documents too
SCOPEShow only this scope
IDOpen the document with this id
SCOPE, ENTITY, NAME, LANGUAGEOpen the document with this key (and language)
ACTIONnew to start a new document, with SCOPE, ENTITY, NAME and TITLE filled in

Troubleshooting​

What you seeWhat to do
The documents could not be readYou may not be allowed to read this documentation. Ask your administrator about the security policies on the documentation service
Could not save: ... not authorisedYou are not allowed to change this documentation, for example common or public documentation
There is already a document ...A document with the same scope, entity, name and language exists. Choose another name, or open that one
A web page link shows nothingThe page may not be reachable from the platform, or the selector finds nothing on it. Check the address and selector
The record still shows a link to a deleted documentDeleting a document does not remove the link the platform added to the record