Store user-generated data

If your app allows the user to save user-generated data that needs to be available across multiple user sessions, the document service is your best option. One example of such user-defined data is to-do items that the user enters in the ToDo app. This guide explains how you can store, update, and delete data from the document service.

The @dynatrace-sdk/client-document package allows you to do all of these operations by providing the documentClient namespace.

Create document

To create a document, use the createDocument function from the @dynatrace-sdk/client-document package. Pass the document object as parameter as follows:

import { documentsClient, CreateDocumentBody } from '@dynatrace-sdk/client-document';

const todos = [
  {
    title: 'Send email to John about vacation',
    done: false,
    lastUpdate: new Date(),
  },
  {
    title: 'Plan workshop for next week',
    done: false,
    lastUpdate: new Date(),
  },
];

const document: CreateDocumentBody = {
  name: 'ToDoList - User A',
  type: 'ToDoDocument',
  content: new Blob([JSON.stringify(todos, null, 2)], {
    type: 'application/json',
  }),
};

documentsClient.createDocument({ body: document }).then((response) => console.log(JSON.stringify(response)));

Tip

This operation requires the scope document:documents:write. Read more about scopes in this guide.

Get document by name

For all modifying operations, you need to pass the document ID to the dedicated functions. To make the code cleaner, all examples use the following helper function, which uses the listDocuments function to return the first matching document for the provided document name:

import { documentsClient } from '@dynatrace-sdk/client-document';

const getDocumentByName = async (name: string) => {
  const myDocs = await documentsClient.listDocuments({
    filter: "name = '" + name + "'",
  });

  return myDocs.documents[0];
};

Tip

This operation requires the scope document:documents:read. Read more about scopes in this guide.

Get document content

To retrieve the content of a specific document, you can use the downloadDocumentContent function. This function expects the document ID as a parameter. This example shows how to download the content for the document that we created in the first step:

import { documentsClient } from '@dynatrace-sdk/client-document';

const getDocument = async () => {
  const documentContent = await documentsClient.downloadDocumentContent({
    id: '<Document-ID>',
  });
  console.log(await documentContent.get('text'));
};

Tip

This operation requires the scope document:documents:read. Read more about scopes in this guide.

Update document

Whenever the content of a document changes, use the updateDocumentContent or the updateDocumentMetadata functions. For all modifying operations, be aware of the optimistic locking concept. Every document has a version that is incremented whenever its metadata or content is modified. For every modifying operation, you have to pass this exact version. This could look like the following:

import { documentsClient } from '@dynatrace-sdk/client-document';

const updateDocument = async () => {
  const updatedTodos = [
    {
      title: 'Send e-mail to John concerning vacation',
      done: true,
      lastUpdate: new Date(),
    },
    {
      title: 'Plan workshop for next week',
      done: false,
      lastUpdate: new Date(),
    },
  ];

  const updateResponse = await documentsClient.updateDocumentContent({
    id: '<Document-ID>',
    optimisticLockingVersion: '<Locking-Version>',
    body: {
      content: new Blob([JSON.stringify(updatedTodos, null, 2)], {
        type: 'application/json',
      }),
    },
  });

  console.log(updateResponse);
};

Tip

This operation requires the scope document:documents:write. Read more about scopes in this guide.

Delete document

Of course, you can delete documents as well. To do this, use the deleteDocument function. For the deletion of a document you need to provide the optimisticLockingVersion of the document you want to delete. To delete the document we created in the first step, your code should look like this:

import { documentsClient } from '@dynatrace-sdk/client-document';

const deleteDocument = async () => {
  const deleteResponse = await documentsClient.deleteDocument({
    id: '<Document-ID>',
    optimisticLockingVersion: '<Locking-Version>',
  });

  console.log(deleteResponse);
};

Tip

This operation requires the scope document:documents:delete. Read more about scopes in this guide.

Related topics

• Document service