Usage Guidelines

The page summarizes best practices for using the operations of Documaster Noark5 API.

All Operations

Access Token Management

The topic of managing the access tokens is dicussed in Authorization and Authentication section of the documentation.

Error Handling

Calls made to the API can result in a number of HTTP status codes returned, which are detailed in Operations/Overview section. Below are guidelines to be followed when error status codes are returned.

  • [NON RETRIABLE] - Any calls that result in an code from Integration Error HTTP Status Codes to be returned should not be retried from consumer side in production environments. Those error indicate that consumer implementation should be reviewed in order to avoid such errors in the future.
  • [RETRIABLE] - Error HTTP status codes in Operational Error HTTP Status Codes should be handled following the guidelines below:
    • 401 Unauthorized - indicates either an expired access token or no token provided at all. In production setup, this error should indicate to the consumer that the token needs to be renewed (take a look at Authorization and Authentication). In case renewal of the token does not resolve it, it would indicate that access to the environment is revoked and consumer should get in touch with Documaster Integration Team.
    • 403 Forbidden -
    • 404 Not Found -
    • 409 Conflict - Documaster Archive uses optimistic locking for updating entity objects and will returned this code in the situations when an entity object was updated while the current transaction also tries to update it. Very common scenario in which this status can be returned is when RegistryEntry (Journalpost) objects are added to the same CaseFile (Saksmappe) concurrently. Keeping consistent sequence numbering of the registry entries within the case file requires additional checks, which may fail resulting in a response with HTTP 409 Conflict status code.
    • 500 Internal Server Error - indicates that there is an issue on Documaster side processing the request and should be investigated by the operations team in production environments.
    • 503 Service Unavailable - same as with the HTTP 500 code, Documaster operational team would investigate the error.

Transaction

Key Usage Points

  • Actions order is important since they are executed sequentially
  • All transaction actions should succeed for the transaction to be successful
  • Each action works on a single entity, identified by the combination of $.actions[].type and $.actions[].id
  • save action manages entity fields, while link and unlink actions use the reference field (prefixed with ref)
  • Creating an entity object with save should always be followed by a link action, where a reference of the new entity is used to link it to another entity
  • Always link the new entity objects to the existing structure or to another new entity which was already linked to the structure
  • Temporary IDs in $.actions[].id are used only for objects that are being created in the tranasction. The validity of the temporary IDs is only in the scope of the transaction. Temporary IDs must be non-numberic values, while permanent IDs are numeric values.

Best Practices

  • Although the transaction operation allows creating many entity objects at once, restrict its usage to entities at atmost 2 levels (Folders Level, Records Level, etc.), where having it restricted to a single level makes it more easily reusable
    • Create a Case File (Saksmappe) linked to a primary Class (Klasse) and an ExternalID (EksternId) 1 level - Folder Level
    • Create a Registry Entry (Journalpost) linked to a Correspondence Party (Korrespondansepart) 1 level - Records Level
    • Create a Registry Entry (Journalpost), Document (Dokument) and Dokument Version (Dokumentversjon) 2 levels - Records and Document Level
  • Avoid modifying in the same transacton unrelated entities
  • link actions should be executed against the child object which is linking to an entity up the structure, not the other way around. Registry Entry is linking itself to the Case File, through the refMappe reference, not the Case File adding the Registry Entry to the list of its records.