@dynatrace-sdk/client-document v1.15.0

@dynatrace-sdk/client-document

Overview

This API allows you to create and manage documents, as well as manage access to them.

Have a look at the service documentation to familiarize yourself with its key concepts.

Note, that the document's content is not inspected by the document-store, therefore it can be entirely schemaless. If your content adheres to a schema, it's your responsibility to enforce that.

Information about authorization can be found here.

Access Management

There are 2 different permission mechanisms. Most operations involve both mechanisms.

Endpoint Permissions

IAM permissions (e.g. document:documents:read) guard endpoints. If the user does not have the permission required by an endpoint, the request gets rejected.

These permissions can not be modified via the doc-store API.

Document Permissions

These permissions guard individual documents. They are modelled in the service itself, independent of IAM permissions.

They can be modified via the API, e.g. by using the sharing endpoints.

Therefore, a user needs to have access both in the DT IAM layer (by having specific IAM permissions) as well as access to the specific documents (e.g. by being document owner).

Sharing

By default, documents are only accessible to their owner. There are 3 ways of sharing documents. Only the document owner may share a document.

Documents can be made public (via the updateDocument operation). This immediately grants read access to all users in the environment.

Environment-Shares grant read or read-write access to users of the same environment, but users need to actively claim the share. The owner effectively loses control over who exactly gains access, as any user can claim the share and therefore receive access.

Direct-Shares immediately grant read or read-write access to specific users and groups. The owner is in total control of who exactly receives access, and can also revoke access retrospectively.

The sharing mechanisms are not mutually exclusive - a document can be shared via multiple sharing mechanisms at the same time.

Document Locking

Optimistic Locking

Operations which modify a document generally use mandatory optimistic locking.

When such operations are executed, the user must provide the version upon which they operate.

If the document version in the service does not match, because the document has been modified in the meantime, then the operation gets rejected.

Active Locking

In addition to the mandatory Optimistic Locking, there is optional Active Locking.

Active locking can be optionally utilized to prevent conflicts caused by multiple users concurrently updating the same document.

A user can lock a document to prevent other users from updating the document for some time.

Once the user is done updating the document, they can release the lock and therefore enable updates by other users.

Deletion and Restoration

Deleted documents are moved to the trash and permanently deleted after 30 days.

The Trash API can be used to manage deleted documents.

Restoring a deleted document makes the document accessible again for the owner as well as all users who had previously received access via shares.

Snapshots

Document snapshots allow to reset a document's content back to an earlier state.

Snapshots must be explicitly created when updating the document. Multiple snapshots can be created per document.

Restoring a snapshot means that the document's content gets changed to the state it had when the snapshot was originally created. It doesn't change access-related data like the document's shares or ownership.

Snapshot creation is rate-limited to 5 snapshots per 60 seconds per document.

The maximum amount of snapshots per document is 50. Additional snapshots result in the deletion of the oldest existing snapshot.

All snapshots get automatically deleted after 30 days.

Snapshot Permissions

All users with read access to a document may read its snapshots.

All users with write access to a document may create snapshots of it.

Only the owner may restore or delete a snapshot.

External Id

Every document has a system-generated, immutable, unique id.

In addition to that, you can optionally specify an external id when creating a document.

It must be unique per environment. It serves as an alias for the system-generated id within one environment and can be resolved via the getDocumentMetadata operation.

Installation

npm install @dynatrace-sdk/client-document

Getting help

• Visit SDK for Typescript guide in the Dynatrace Developer
• Ask a question in the Dynatrace Community

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

API reference

Full API reference for the latest version of the SDK is also available at the Dynatrace Developer.

directSharesClient

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

addDirectShareRecipients

Add recipients to the share.

Required scope: document:direct-shares:write

Add one or multiple SSO-users and/or SSO-groups to this share. The affected users immediately gain access to the document.

Only share's owner is permitted to do this. The maximum number of recipients is 1000.

The validity of the SSO-users and SSO-groups is not verified. It's technically possible, albeit pointless, to add non-existing users and groups.

Already added users or groups are ignored.

Parameters

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.addDirectShareRecipients({
    id: "...",
    body: {
      recipients: [
        {
          id: "441664f0-23c9-40ef-b344-18c02c23d789",
          type: "group",
        },
      ],
    },
  });

createDirectShare

Create a direct-share for one of your own documents.

Required scope: document:direct-shares:write

Create a direct-share for a document owned by you. The share can be used to grant access to a specific set of users and/or groups, via addRecipients

You can optionally add users and/or groups which will directly be registered as recipients of the share. The users and groups are specified via their sso-ids. The maximum number of recipients is 1000.

The validity of the SSO-users and SSO-groups is not verified. It's technically possible, albeit pointless, to add non-existing users and groups.

The share can be created with either read or read-write access.

A document can have maximally one direct-share per access type, therefore it's not possible to create multiple read-shares or multiple read-write-shares for a single document.

This means, that you can create one read-share for a document, and this single read-share can be used to give read-access to an arbitrary number of users (and/or groups). The same applies to a read-write-share.

Parameters

Returns

A new share for the specified document has been created.

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.createDirectShare({
  body: {
    documentId: "...",
    access: "...",
    recipients: [
      {
        id: "441664f0-23c9-40ef-b344-18c02c23d789",
        type: "group",
      },
    ],
  },
});

deleteDirectShare

Delete one of your direct-shares.

Required scope: document:direct-shares:delete

Delete the share. This will not delete the share's document.

You can only delete shares of your own documents.

This operation effectively revokes the access of all of the share's recipients.

Be aware that deleting a share does not necessarily prevent a user from accessing a document, as the user might still have access via another share (of the same document). E.g., if a user has 'read' and 'read-write' access (via one 'read' and another 'read-write' share), and the 'read' share gets deleted, access is still granted to the user via the other 'read-write' share.

Parameters

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.deleteDirectShare({
  id: "...",
});

getDirectShare

Retrieve one of your direct-shares.

Required scope: document:direct-shares:read

Retrieve a direct-share via its id.

Only the share's owner is permitted to do this.

Parameters

Returns

A direct-share.

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.getDirectShare({
  id: "...",
});

getDirectShareRecipients

List the recipients of one of your direct-shares.

Required scope: document:direct-shares:read

Retrieve a share's recipients. If there are groups among the recipieints, the groups always appear before the users.

Only share's owner is permitted to do this.

Parameters

Returns

A list of recipients of the direct-share.

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.getDirectShareRecipients({
    id: "...",
  });

listDirectShares

List your direct-shares.

Required scope: document:direct-shares:read

List all shares of your documents.

If you are only concerned with a specific document's shares, or a specific share, you can use the filter parameter to narrow down the result set. This does not circumvent the restriction of being able to only get shares of your own documents. If you attempt to retrieve shares of another user's document, the result set will be empty.

Note, that at the moment we offer a naive pagination, and therefore interim mutations can lead to result inconsistencies (such as duplicates, missing entries).

Parameters

Returns

A list of your direct-shares.

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data = await directSharesClient.listDirectShares();

removeDirectShareRecipients

Remove recipients from the share.

Required scope: document:direct-shares:write

Remove one or multiple recipients from the share. The affected users immediately lose access to the document.

Only share's owner is permitted to do this. The maximum number of recipients is 1000.

Non-existing users or groups are ignored.

Parameters

Throws

import { directSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await directSharesClient.removeDirectShareRecipients({
    id: "...",
    body: { ids: ["..."] },
  });

documentLockingClient

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

acquireLock

Acquire the lock on the document.

Required scope: document:documents:write

Acquire the lock on the document. A user can lock a maximum of five documents at any given time. Once the lock is acquired by the user, other users cannot make any updates to the document.

The user acquiring the lock can optionally specify the duration for which the lock can be attained. However, the specified duration must not exceed the maximum allowed duration of 15 minutes. If not specified, the lock is acquired for 10 minutes.

If the user who has currently locked the document attempts to acquire the lock for the same document again, the duration of the lock gets extended by the specified duration or by a default duration of 10 minutes, if not specified.

The other users would not be allowed to acquire the lock on an already locked document.

Parameters

Returns

The lock has been acquired by the user.

Throws

import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.acquireLock({
  id: "...",
  body: { documentVersion: 10 },
});

inspectLock

Inspect whether the document is locked.

Required scope: document:documents:read

Inspect whether the document is locked.

This provides the information about whether the document is locked and the user that currently owns the lock.

Parameters

Returns

Lock details for a document.

Throws

import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.inspectLock({
  id: "...",
});

releaseLock

Release the lock on the document.

Required scope: document:documents:write

Release the lock on the document. The lock on the document can be released only by the user who owns it.

Parameters

Throws

import { documentLockingClient } from "@dynatrace-sdk/client-document";

const data = await documentLockingClient.releaseLock({
  id: "...",
});

documentsClient

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

bulkDeleteDocument

Bulk-delete multiple documents

Required scope: document:documents:delete

Move the documents with the given IDs into the trash. They are no longer accessible until they're restored from the trash.

Parameters

Returns

Result of the bulk operation for the individual objects.

Throws

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

const data = await documentsClient.bulkDeleteDocument({
  body: { ids: ["..."] },
});

createDocument

Create a new document.

Required scope: document:documents:write

Create a new document which is then owned by you (the user specified by the provided Authorization header). The document is not accessible to other users.

The document's name and type must be provided. These two properties can later be used for filtering purposes, when listing accessible documents.

Be aware, that the type is not the same as the Content-Type of the document, but instead adds user-defined semantics of which the document-store is entirely agnostic.

The content size must not exceed 50 MB.

Parameters

Returns

A new document has been created.

Throws

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

const data = await documentsClient.createDocument({
  body: { name: "...", type: "...", content: "..." },
});

deleteDocument

Delete the document

Required scope: document:documents:delete

Move the document into the trash. It is no longer accessible until it's restored from the trash.

Optimistic locking is enforced via the optimistic-locking-version parameter.

You must own the document in order to delete it.

Parameters

Throws

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

const data = await documentsClient.deleteDocument({
  id: "...",
  optimisticLockingVersion: "...",
});

deleteSnapshot

Delete the snapshot.

Required scope: document:documents:write

Irrevocably delete the snapshot. Only the document owner may do this.

This operation does not affect the current state of the document.

Instead, it prevents that the document may ever be restored to the state it had when the snapshot was created.

Parameters

Throws

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

const data = await documentsClient.deleteSnapshot({
  id: "...",
  snapshotVersion: 10,
});

downloadDocumentContent

Download document content

Required scope: document:documents:read

Download latest document content.

If the snapshot-version param is provided, the content of the specified snapshot gets returned instead. This requires write-access to the document.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

The response's Content-Type header has the same value that has been used during the upload.

Parameters

Returns

Content of the document

Throws

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

const data = await documentsClient.downloadDocumentContent({
  id: "...",
});

getDocument

Retrieve metadata and content.

Required scope: document:documents:read

Return metadata and content in one multipart response.

If the snapshot-version param is provided, the metadata and content of the specified snapshot gets returned instead. This requires write-access to the document.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

Parameters

Returns

Metadata and content in a multipart response.

Throws

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

const data = await documentsClient.getDocument({
  id: "...",
});

getDocumentMetadata

Retrieve document metadata.

Required scope: document:documents:read

Retrieve a document's metadata.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

If the snapshot-version param is provided, the metadata of the specified snapshot gets returned instead. This requires write-access to the document.

This endpoint supports external ids.

Parameters

Returns

Metadata of document

Throws

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

const data = await documentsClient.getDocumentMetadata({
  id: "...",
});

getSnapshotMetadata

Retrieve snapshot metadata.

Required scope: document:documents:read

Retrieve snapshot metadata. Requires write-access to the document.

This does not return data of the snapshotted document, instead it returns data about the snapshot itself.

Parameters

Returns

Metadata of a specific snapshot.

Throws

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

const data = await documentsClient.getSnapshotMetadata({
  id: "...",
  snapshotVersion: 10,
});

listDocuments

List all documents accessible to you.

Required scope: document:documents:read

List the metadata of all documents accessible to you.

This includes your own documents, as well as other users' documents which have been shared with you.

Note, that at the moment we offer a naive pagination, and therefore interim document mutations and/or an insufficient sort clause, if provided, can lead to result inconsistencies (such as duplicates, missing entries).

Parameters

Returns

A list of metadata objects of documents which are accessible to you.

Note, that this includes your own documents as well as other users' documents which are shared with you.

Throws

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

const data = await documentsClient.listDocuments();

listSnapshots

List all snapshots of the document

Required scope: document:documents:read

Returns metadata of all snapshots of the document, in descending order of the snapshot's creation date. Requires write-access to the document.

You can apply pagination via the pageKey and pageSize parameters.

Note, that at the moment we offer a naive pagination, and therefore interim mutations can lead to result inconsistencies (such as duplicates, missing entries).

Parameters

Returns

A list of snapshots of the document.

Throws

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

const data = await documentsClient.listSnapshots({
  id: "...",
});

restoreSnapshot

Restore the snapshot.

Required scope: document:documents:write

Reset the document to the state it had when the snapshot was created. Requires write-access to the document.

A new snapshot is created afterwards. If the document has more than 50 snapshots, its oldest snapshot gets automatically deleted.

This operation only changes the document's content. It doesn't change ownership or access/sharing data.

Parameters

Returns

Document has been restored. New snapshot has been created.

Throws

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

const data = await documentsClient.restoreSnapshot({
  id: "...",
  snapshotVersion: 10,
});

updateDocument

Update metadata and content. Optionally, create a snapshot.

Required scope: document:documents:write

Update metadata and/or the content of the document.

Name, type and content must be non-empty, but are optional. At least one of them must be provided.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

As part of this operation, you can optionally create a snapshot of the updated document. In that case, if the document has more than 50 snapshots, its oldest snapshot gets automatically deleted. It's not possible to create more than 5 snapshots per 60 seconds, per document.

Parameters

Returns

Result of updating metadata & content. Contains document metadata and snapshot metadata.

Throws

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

const data = await documentsClient.updateDocument({
  id: "...",
  optimisticLockingVersion: "...",
  body: {},
});

updateDocumentContent

Update document content

Required scope: document:documents:write

Update a document's content, by completely replacing it.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

Optimistic locking is enforced via the optimistic-locking-version parameter.

The content size must be greater than 0 and must not exceed 50 MB.

The Content-Type header must be set for the multipart part; it will be used as the (new) content type of the document. Illegal (non-mime-type) content types result in a 400 - Bad Request error.

The Content-Disposition header must be set for the multipart part;

Parameters

Returns

Document content successfully updated

Throws

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

const data = await documentsClient.updateDocumentContent({
  id: "...",
  optimisticLockingVersion: "...",
  body: { content: "..." },
});

updateDocumentMetadata

Update document metadata

Required scope: document:documents:write

Partially update a document's user-defined metadata. At least one property must be updated, otherwise the operation fails.

The document's content is not affected by this operation.

Optimistic locking is enforced via the optimistic-locking-version parameter.

The document must be accessible to you - therefore, you must either own it or you have received access through sharing.

Parameters

Returns

The document has been updated. The updated metadata is returned.

Throws

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

const data = await documentsClient.updateDocumentMetadata({
  id: "...",
  optimisticLockingVersion: "...",
  body: {},
});

environmentSharesClient

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

claimEnvironmentShare

Claim another user's environment-share.

Required scope: document:environment-shares:claim

Claim this environment-share, therefore gaining access to the share's document. From thereafter, the document will be accessible to you with the specific permissions defined by the share. You can then access the document as usual, via the same endpoints which you would use to access your own documents.

Claiming your own shares is not possible. You can only claim shares of documents belonging to other users of the same environment.

Once you have claimed access to a document, you can not revoke that access again.

The document's owner can revoke your access by deleting the share. This will effectively revoke the access you have been granted by claiming this share.

You can claim multiple shares of the same document, and each share will grant you different permissions.

Claiming the same share multiple times does not have any effect.

Parameters

Returns

You have successfully claimed this share and can now access the document with the granted permissions.

Throws

import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.claimEnvironmentShare({
    id: "...",
  });

createEnvironmentShare

Create an environment-share for one of your own documents.

Required scope: document:environment-shares:write

Create a document share, which can be used to give one or multiple other users access to this document.

This is only possible if you are the owner of the document.

A share can be created with either read or read-write access.

A document can have maximally one share per access type, therefore it's not possible to create multiple read-shares or multiple 'read-write'-shares for a single document.

This means, that you can create one read-share for a document, and this single read-share can be used to give read-access to an arbitrary number of users. The same applies to a 'read-write'-share.

Creating a share does not automatically allow users to access the document - only those users who explicitly claim the share gain access to the document.

Revoking access from users can be done by deleting the share.

Parameters

Returns

A new share for the specified document has been created.

Throws

import { environmentSharesClient } from "@dynatrace-sdk/client-document";

const data =
  await environmentSharesClient.createEnvironmentShare({
    body: { documentId: "...", access: "..." },
  });

deleteEnvironmentShare

Delete one of your environment-shares.

Required scope: document:environment-shares:delete

Delete the share. This will not delete the share's document.

Only the share's owner is permitted to do this.

This operation effectively revokes