Creating collections

Using Dossier Organizer's REST API to upload documents and create collections

Storing documents and creating collections (which is just a fancy name for the dossier of documents you're currently working on) is typically handled by the process Dossier Organizer is integrated in.

For this purpose, Dossier Organizer provides a REST endpoint to create collections:

POST: <HOST>/api/v1/collections/
with body: collection represented in json (for an example of a collection in JSON, see below)

A full API definition can be found at REST APIs.

What is a collection?

A collection can be considered as a folder or dossier holding several documents and metadata. A collection represents a group of related documents or resources. A collection is the basic data structure in order to be able to work with Dossier Organizer.

A Dossier Organizer collection provides:

• its unique ID
• a reference to its collection type - this is determined by their typeId. There's a default type "generic" delivered with Dossier Organizer, but usually a customer-specific collection type will be created upon installation & customizing together, according to costumer needs.
• metadata (per collection and per element). Metadata is used by the views to display the elements in the elements tree and to group and sort the elements. When implementing a project, it is therefore agreed at the beginning which metadata (section " metadata") will be stored in the collections.
• elements - typically documents, but other content is supported as well. Different types are provided (compositePaged,embeddedArtifact,artifact); for more details , see Collection element specifications.
• annotations per document - only applicable on compositePaged elements; holds markers, redactions, textual annotations and more
• bookmarks per element- applicable to compositePaged documents, but also videos

Sample collection

A sample collection of collection type "generic" may look as follows:

{
  "typeId": "generic",                          // the unique name of the collection type
  "id": "ae1f82c9-b67b-447c-a949-c7510ff0b3be", // may be omitted when generating a collection
  "state": "active",
  "dateCreated": "2023-11-10T07:36:06.969Z",
  "dateModified": "2023-11-10T07:36:06.969Z",
  "createdBy": "me",
  "metadata": {
  },
  "elements": [
    //definition of a subcollection
    {
      "id": "ab223547-5c4f-459d-a02d-7a0e07349c71",
      "dateCreated": "2022-06-28T12:54:39.526Z",
      "dateModified": "2022-06-28T12:54:39.526Z",
      "tags": [],
      "metadata": null,
      "specification": {
        "type": "collectionReference",
        "collectionId": "ab223547-5c4f-459d-a02d-7a0e07349c71"
      }
    },
    // definition of an embedded artifact 
    {
      "id": "2d1f630f-ea59-4eb9-a9a2-51beaae5323b",
      "dateCreated": "2020-11-09T14:28:09.632Z",
      "dateModified": "2020-11-09T14:28:09.632Z",
      "tags": [],
      "metadata": null,
      "specification": {
        "type": "embeddedArtifact",
        "mediaType": "text/markdown",
        "content": "# Telefonnotiz\n\nEingehendes Telefonat\n\nTelefonnummer: +494321/345678\nKunde: Herr XY ....",
        "bookmarks": null
      }
    },
    // definition of a composite paged element
    { 
      "id": "834cf8e5-bb80-4a3b-a447-86bbb53e9c3b",
      "dateCreated": "2020-11-09T13:34:56.747Z",
      "dateModified": "2023-11-07T11:01:40.051122Z",
      "tags": [],
      "metadata": null,
      "specification": {
        "type": "compositePaged",
        "pageSequences": [
          {
            "mediaType": null,
            "contentURI": "https://mystore.com/documents/1f0623bc-05cb-49a9-81a1-86888c6a83c0",
            "pageIndices": [
              0,
              1,
              3
            ],
            "sequenceId": 0,
            "annotationData": null,
            "bookmarks": null,
          }
        ]
      }
    }
  ]
}

Creating a collection

When creating a collection, most of the fields in the JSON data structure can be omitted and will be generated automatically.

Only these fields are mandatory:

{
  "typeId": "generic",                  // `generic` is a default collection type. The specified collection type must exist in the servers configuration.
  "elements": [],                       // can be filled with collection elements
  "createdBy": "User (user@levigo.de)", // optional but recommended
}

As a response to your request, you will receive a JSON representation of the created or updated collection. Verify the response data to ensure the collection was created or updated as expected.

After creating a collection, the backend will automatically generate omitted properties to the collection. So, when processing the minimal json above, we will receive a collection as follows:

{
  "id": "34f4f619-31ce-4614-b25a-7b4c6bdb4b79",
  "versionTimestamp": "2024-02-20T16:25:26.470Z",
  "state": "Active",
  "dateCreated": "2024-02-20T16:25:26.344030Z",
  "dateModified": "2024-02-20T16:25:26.344030Z",
  "createdBy": "User (user@levigo.de)",
  "metadata": null,
  "elements": [],
  "typeId": "generic"
}