Skip to content

Document Hub

OMD users can access documents related to the following OMD entities:

  • customers
  • service objects
  • resources
  • tasks
  • task locations
  • products
  • territory
  • configuration

The documents for these entities are mapped to specific folders in the cloud storage system. For example, a task on instance prod in configuration 1234567 having externalId SE29474 is stored in prod-1234567/tasks/SE29474.

Note that documents related to task locations are prefixed with the customer's account number. For example, a service report related to account KLRT-6947 is prefixed with customers/KLRT-6947/taskLocations instead of just taskLocations.

S3 Storage

For S3 storage, files are referred to with a key value. Folders do not exist and are therefore represented by a prefix of the key. For the example above, the key of the file is tasks/SE29474, having prefix tasks/. It is stored in bucket prod-1234567.

Preferences

All preferences of a configuration are retrieved from OMD's preference table. The preferences include:

  • omd.documents.serviceprovider (default s3)
  • omd.documents.s3.endpoint
  • omd.documents.s3.region
  • omd.documents.s3.pathstyle
  • omd.documents.s3.bucketname
  • omd.documents.s3.accesskey
  • omd.documents.s3.secretkey
  • omd.documents.s3.expiration (in seconds)

The preferences are declared and configured by OMD staff.

Access to the Document Hub

The following rules apply:

  • web users having read access to a configuration can read documents for all entities
  • web users having read-write access to a configuration can read and write documents for all entities
  • resources can read documents for all entities

To access the Document Hub, you will have to apply a three-step approach:

  • obtain an OMD configuration token
  • obtain a URL to access the Document Hub
  • upload or download the document for the URL obtained in step 2

Step 1

Use the following URL to obtain an OMD configuration token:

https://{instance}.optimizemyday.com/omdservices/rs/v1/tokens/configuration?configId={configId}

This call will have to use one of the supported OMD authentication methods.

Step 2

Call a Document Hub request:

Pass the OMD configuration token obtained in step 1 in the Authorization header to your Document Hub request, with the Bearerprefix:

Authorization: Bearer {the OMD configuration token}

Step 3

For put and get, the above request will respond with a URL that is valid for a few minutes. You can use that URL to POST (put) or GET (get) a document from the Document Hub.

The list function will respond with a JSON containing the list of documents that are stored in the provided path.

Recycle Bin

All providers implement a recycle bin, i.e. all deleted files are temporarily moved to a dedicated space before they are finally purged. The infrastucture providing the document storage implements the purge individually by appling a job that deletes outdated objects in the bin folder on a regular basis.

For S3, we apply a .deleted folder with an identical structure, i.e. an object in {{bucketname}}/tasks/{taskId}/file.txt is copied to {bucketname}/.deleted/tasks/{{taskId}}/file.txt before it is purged. Note that moving an object in S3 is not possible.