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.

---

Element and Collection ID Requirements

Dossier Organizer uses strict UUID v7 identifiers for both element and collection IDs.

• If you assign an ID manually (for example, when creating collections or elements via the REST API), ensure that it conforms to the UUID v7 standard. If no ID is specified, Dossier Organizer will automatically generate a valid UUID v7 during creation or update.
• If an invalid ID is provided, the API will respond with Error Code 406 (Not Acceptable). This typically means the specified ID does not meet the UUID v7 requirements.
• Currently, it is not possible to add multiple items (e.g., documents) in a single call to ./api/v1/collections/{collectionID}/elements. Each element must be added individually.

---

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"
}