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.

Admin-access

Regular users can only access documents owned by them or shared with them.

Users with the permission document:documents:admin can act with elevated permission - they can access all users' documents of the current environment, regardless of ownership.

The admin-access can be enabled on a per-request basis, by setting the optional request parameter admin-access to true.

Currently, this is only supported by these endpoints:

• listDocuments
• getDocument
• getDocumentMetadata
• downloadDocumentContent
• deleteDocument
• transferDocumentOwner

User Data

No user data like names or email addresses are stored. Instead, SSO ids are persisted.

Every user's last access to every document gets stored to allow ordering of results so that least recently accessed documents appear first.

@dynatrace-sdk/client-document

v1.20.0

npm install @dynatrace-sdk/client-document

directSharesClient

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

addDirectShareRecipients

directSharesClient.addDirectShareRecipients(config): Promise<void>

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

Name	Type	Description
config.body*required	AddDirectShareRecipients
config.id*required	string	System-generated id of a share.

Returns

Return type	Status code	Description
void	204	The recipients have been added.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

createDirectShare

directSharesClient.createDirectShare(config): Promise<DirectShare>

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

Name	Type
config.body*required	CreateDirectShare

Returns

Return type	Status code	Description
DirectShare	201	A new share for the specified document has been created.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
ShareAlreadyExists	Share creation failed - a share with the specified permission already exists for the document.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

directSharesClient.deleteDirectShare(config): Promise<void>

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

Name	Type	Description
config.id*required	string	System-generated id of a share.

Returns

Return type	Status code	Description
void	204	The share has been deleted.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getDirectShare

directSharesClient.getDirectShare(config): Promise<DirectShare>

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

Name	Type	Description
config.id*required	string	System-generated id of a share.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getDirectShareRecipients

directSharesClient.getDirectShareRecipients(config): Promise<DirectShareRecipientList>

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

Name	Type	Description
config.id*required	string	System-generated id of a share.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

listDirectShares

directSharesClient.listDirectShares(config): Promise<DirectShareList>

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

Name	Type	Description
config.filter	string	The filter query, as explained here. Filtering is only possible on the documentId property, and only with the equals operator. Via this you can effectively request all shares of a specific document owned by you. If this parameter is omitted, all direct-shares of this user will be returned.
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.

Returns

Return type	Status code	Description
DirectShareList	200	A list of your direct-shares.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await directSharesClient.listDirectShares();

removeDirectShareRecipients

directSharesClient.removeDirectShareRecipients(config): Promise<void>

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

Name	Type	Description
config.body*required	RemoveDirectShareRecipients
config.id*required	string	System-generated id of a share.

Returns

Return type	Status code	Description
void	204	The recipients have been removed.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

documentLockingClient

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

acquireLock

documentLockingClient.acquireLock(config): Promise<AcquireLockResult>

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

Name	Type	Description
config.body*required	AcquireLock
config.id*required	string	System-generated id of a document.

Returns

Return type	Status code	Description
AcquireLockResult	200	The lock has been acquired by the user.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
DocumentAlreadyLocked	Lock acquisition failed as the document is already locked.
LockedDocumentsLimitReached	Lock acquisition failed as number of locked documents reached or exceeded the allowed limit.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

inspectLock

documentLockingClient.inspectLock(config): Promise<DocumentLockDetails>

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

Name	Type	Description
config.id*required	string	System-generated id of a document.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

releaseLock

documentLockingClient.releaseLock(config): Promise<void>

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

Name	Type	Description
config.id*required	string	System-generated id of a document.

Returns

Return type	Status code	Description
void	200	The lock on the document has been released.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

documentsClient

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

bulkDeleteDocument

documentsClient.bulkDeleteDocument(config): Promise<BulkDeleteResponse>

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

Name	Type
config.body*required	BulkDeleteRequest

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

createDocument

documentsClient.createDocument(config): Promise<DocumentMetaData>

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

Name	Type
config.body*required	CreateDocumentBody

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentTooLarge	Maximum content size exceeded.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.
InsufficientStorage	The storage quota has been exceeded.

Code example

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

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

deleteDocument

documentsClient.deleteDocument(config): Promise<void>

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

Name	Type	Description
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.id*required	string	System-generated id of a document.
config.optimisticLockingVersion*required	string	To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
Conflict	Optimistic locking failed, or the document is actively locked by another user, or some other conflict.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

deleteSnapshot

documentsClient.deleteSnapshot(config): Promise<void>

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

Name	Type	Description
config.id*required	string	System-generated id of a document.
config.snapshotVersion*required	number	System-generated snapshot version.

Returns

Return type	Status code	Description
void	204	The snapshot has been deleted.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
SnapshotNotFound	Snapshot not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

downloadDocumentContent

documentsClient.downloadDocumentContent(config): Promise<Binary>

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

Name	Type	Description
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.filename	string	The optional filename query parameter can be passed to give the file that is being downloaded a user-provided name and file extension for downloading purposes. This name will be sent back to the client via the Content-Disposition HTTP header. The passed filename will be trimmed that it does not contain any space characters around the name. When the filename is not specified, then the name of the document is used as file name and no extension is added, since the service is not aware of file extensions.
config.id*required	string	System-generated id of a document.
config.snapshotVersion	number	Snapshot version, to be used if you want to access a snapshot of the document.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentOrSnapshotNotFound	Document or snapshot not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getDocument

documentsClient.getDocument(config): Promise<GetDocumentResponse>

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

Name	Type	Description
config.addFields	string	Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields: userContext.lastAccessedTime
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.filename	string	The optional filename query parameter can be passed to give the file that is being downloaded a user-provided name and file extension for downloading purposes. This name will be sent back to the client via the Content-Disposition HTTP header. The passed filename will be trimmed that it does not contain any space characters around the name. When the filename is not specified, then the name of the document is used as file name and no extension is added, since the service is not aware of file extensions.
config.id*required	string	System-generated id of a document.
config.snapshotVersion	number	Snapshot version, to be used if you want to access a snapshot of the document.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentOrSnapshotNotFound	Document or snapshot not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getDocumentMetadata

documentsClient.getDocumentMetadata(config): Promise<DocumentMetaData>

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

Name	Type	Description
config.addFields	string	Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields: userContext.lastAccessedTime
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.id*required	string	System-generated id or user-given external id of a document.
config.snapshotVersion	number	Snapshot version, to be used if you want to access a snapshot of the document.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentOrSnapshotNotFound	Document or snapshot not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getSnapshotMetadata

documentsClient.getSnapshotMetadata(config): Promise<SnapshotMetadata>

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

Name	Type	Description
config.id*required	string	System-generated id of a document.
config.snapshotVersion*required	number	System-generated snapshot version.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
SnapshotNotFound	Snapshot not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

listDocuments

documentsClient.listDocuments(config): Promise<DocumentList>

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

Name	Type	Description
config.addFields	string	Comma-separated list of field names that are added to the default set of fields. You can include the following additional fields: description userContext.lastAccessedTime
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.filter	string	The filter parameter, as explained here. If this parameter is omitted, no filtering is applied and all documents available to you will be returned. Filtering by string type parameters (name, type) when using one of the operators contains, starts-with and ends-with is case insensitive. When using the equals operator or the not-equals operator, filtering is case sensitive. The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response: id, name, type, version, owner, modificationInfo.createdTime, modificationInfo.createdBy, modificationInfo.lastModifiedTime, modificationInfo.lastModifiedBy, externalId, originAppId The following constraints apply: Parameter names are case-sensitive. Maximum nesting depth (via brackets) is 3. Maximum length is 256 characters. Examples: name = 'my-document-name' name == 'my-document-name' (name starts-with 'awesome' or type != 'dashboard') and version >= 5 modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (name contains 'new') originAppId exists
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.
config.sort	string	The sort parameter, as explained here If this parameter is omitted, the documents are sorted by their ids. Sorting by string types (name, type) is done in a case insensitive manner. The following fields are legal sorting parameters - any other sorting parameters will result in a HTTP 400 response: name, type, version, owner, modificationInfo.createdTime, modificationInfo.createdBy, modificationInfo.lastModifiedTime,modificationInfo.lastModifiedBy,originAppId, userContext.lastAccessedTime The following constraints apply: Maximum number of sorting parameters is 5. Exceeding this limit will result in a HTTP 400 response. Note that blanks are not ignored and will result in a HTTP 400 response. Examples: name name,-type,modificationInfo.lastModifiedTime

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await documentsClient.listDocuments();

listSnapshots

documentsClient.listSnapshots(config): Promise<SnapshotList>

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

Name	Type	Description
config.id*required	string	System-generated id of a document.
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

restoreSnapshot

documentsClient.restoreSnapshot(config): Promise<RestoreDocumentResult>

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.

If no snapshot of the current document state exists, then a new snapshot is created before restoring the selected snapshot. 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

Name	Type	Description
config.id*required	string	System-generated id of a document.
config.snapshotVersion*required	number	System-generated snapshot version.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentOrSnapshotNotFound	Document or snapshot not found.
Conflict	Optimistic locking failed, or the document is actively locked by another user, or some other conflict.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

transferDocumentOwner

documentsClient.transferDocumentOwner(config): Promise<void>

Transfers ownership of the document to a new owner.

Required scope: document:documents:write

Transfers ownership of the document to a new owner. The previous owner loses access to the document. This operation can only be performed by the document owner.

Parameters

Name	Type	Description
config.adminAccess	boolean	Indicates whether the operation should be performed with elevated permissions - additionally requires document:documents:admin. If provided, the user has the same permissions as the document owner. This is not supported for ready-made documents.
config.body*required	TransferOwner
config.id*required	string	System-generated id of a document.

Returns

Return type	Status code	Description
void	204	Ownership has been transferred successfully.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

updateDocument

documentsClient.updateDocument(config): Promise<UpdateDocumentMetadata>

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

Name	Type	Description
config.body*required	UpdateDocumentBody
config.createSnapshot	boolean	Indicates whether a new snapshot shall be created after the update was executed.
config.id*required	string	System-generated id of a document.
config.optimisticLockingVersion*required	string	To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
SnapshotCreationRateLimitExceeded	Too many snapshots have been created for this document in the recent time. Try again later.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

updateDocumentContent

documentsClient.updateDocumentContent(config): Promise<DocumentMetaData>

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

Name	Type	Description
config.body*required	UpdateDocumentContentBody
config.id*required	string	System-generated id of a document.
config.optimisticLockingVersion*required	string	To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
Conflict	Optimistic locking failed, or the document is actively locked by another user, or some other conflict.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.
InsufficientStorage	The storage quota has been exceeded.

Code example

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

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

updateDocumentMetadata

documentsClient.updateDocumentMetadata(config): Promise<DocumentMetaData>

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

Name	Type	Description
config.body*required	UpdateDocumentMetadataBody
config.id*required	string	System-generated id of a document.
config.optimisticLockingVersion*required	string	To protect users from accidental overrides, the current version of the document must match the optimistic locking version parameter - otherwise, this request will fail and the entity is left unchanged.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
Conflict	Optimistic locking failed, or the document is actively locked by another user, or some other conflict.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

environmentSharesClient

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

claimEnvironmentShare

environmentSharesClient.claimEnvironmentShare(config): Promise<EnvironmentShareClaimResult>

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

Name	Type	Description
config.id*required	string	Share id.

Returns

Return type	Status code	Description
EnvironmentShareClaimResult	200	You have successfully claimed this share and can now access the document with the granted permissions.

Throws

Error Type	Error Message
ClaimingOwnedShareNotAllowed	A user can't claim one of their own shares.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

createEnvironmentShare

environmentSharesClient.createEnvironmentShare(config): Promise<EnvironmentShare>

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

Name	Type
config.body*required	CreateEnvShare

Returns

Return type	Status code	Description
EnvironmentShare	201	A new share for the specified document has been created.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
DocumentNotFound	Document not found.
ShareAlreadyExists	Share creation failed - a share with the specified permission already exists for the document.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

deleteEnvironmentShare

environmentSharesClient.deleteEnvironmentShare(config): Promise<void>

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 the access which has been granted to all users which have claimed this share. This is the only way to revoke access to your document from other users. It's not possible to revoke access of individual users.

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 readwrite-access (via one read-share and another readwrite-share), and the read-share gets deleted, access is still granted to the user via the readwrite-share.

Parameters

Name	Type	Description
config.id*required	string	Environment-share id.

Returns

Return type	Status code	Description
void	204	The share has been deleted.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getEnvironmentShare

environmentSharesClient.getEnvironmentShare(config): Promise<EnvironmentShare>

Retrieve one of your environment-shares.

Required scope: document:environment-shares:read

Retrieve a share via its id.

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

Parameters

Name	Type	Description
config.id*required	string	Environment-share id.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

getEnvironmentShareClaimers

environmentSharesClient.getEnvironmentShareClaimers(config): Promise<EnvironmentShareClaimerList>

List the claimers of one of your environment-shares.

Required scope: document:environment-shares:read

Retrieve a share's claimers.

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

You can control the result's pagination via the pageKey, page and pageSize parameters.

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

Name	Type	Description
config.id*required	string	Environment-share id.
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
ShareNotFound	Share not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

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

listEnvironmentShares

environmentSharesClient.listEnvironmentShares(config): Promise<EnvironmentShareList>

List your environment-shares.

Required scope: document:environment-shares:read

List all environment-shares of your own documents.

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

Furthermore, you can apply pagination via the pageKey, page 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

Name	Type	Description
config.filter	string	The filter query, as explained here. Filtering is only possible on the documentId property, and only via the equals operator. Via this you can effectively request all shares of a specific document owned by you. If this parameter is omitted, all environment-shares of this user will be returned.
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.

Returns

Return type	Status code	Description
EnvironmentShareList	200	A list of your environment-shares.
If the list was paginated (see pageKey, page and pageSize), and there are more environment-shares available, you will find a non-empty nextPageKey which can be used for a follow-up query. The totalCount property will let you know the number of all matching environment-shares, as if no pagination would have been applied.

Throws

Error Type	Error Message
BadRequest	Malformed request or invalid parameters.
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data =
  await environmentSharesClient.listEnvironmentShares();

trashClient

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

deleteTrashedDocument

trashClient.deleteTrashedDocument(config): Promise<void>

Irreversibly destroy the document.

Required scope: document:trash.documents:delete

This operation irreversibly destroys the document. Only the document owner is permitted to do this.

Parameters

Name	Type	Description
config.id*required	string	System-generated id of a document.

Returns

Return type	Status code	Description
void	204	The document has been permanently deleted.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
TrashedDocumentNotFound	Trashed document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await trashClient.deleteTrashedDocument({
  id: "...",
});

inspectTrashedDocument

trashClient.inspectTrashedDocument(config): Promise<TrashDocument>

Inspect the deleted document.

Required scope: document:trash.documents:read

Inspect the deleted document's metadata. Only the document owner is permitted to do this.

Parameters

Name	Type	Description
config.id*required	string	System-generated id of a document.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
TrashedDocumentNotFound	Trashed document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await trashClient.inspectTrashedDocument({
  id: "...",
});

listTrashedDocuments

trashClient.listTrashedDocuments(config): Promise<TrashDocumentList>

List your deleted documents.

Required scope: document:trash.documents:read

Lists all documents, owned by you, which currently reside in the trash.

Note that documents in the trash are irreversibly deleted after 30 days.

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

Name	Type	Description
config.filter	string	The filter parameter, as explained here. If this parameter is omitted, no filtering is applied and all your deleted documents will be returned. Filtering by string type parameters when using one of the operators contains, starts-with and ends-with is case insensitive. When using the equals operator or the not-equals operator, filtering is case sensitive. The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response: id, name, type, deletionInfo.deletedTime, deletionInfo.deletedBy The following constraints apply: Parameter names are case-sensitive. Maximum nesting depth (via brackets) is 3. Maximum length is 256 characters.
config.page	number	The page parameter is used to directly access a specific page. The value of the page parameter, if specified, has to be a value greater than zero. If the value of the page parameter exceeds the highest available page on the backend, an empty page is returned.
config.pageKey	string	The page key is used to query results from the next page. You get a nextPageKey parameter in the return value of this method to use here. If this parameter is omitted, the first page will be returned.
config.pageSize	number	The page size which defines the requested number of result entries. You can request a maximum of 1000 result entries. If this parameter is omitted, the default value of 20 will be used.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await trashClient.listTrashedDocuments();

restoreTrashedDocument

trashClient.restoreTrashedDocument(config): Promise<void>

Restore the deleted document.

Required scope: document:trash.documents:restore

This operation restores the document from the trash. All users who had access before the deletion regain their access to the document. Only the document owner is permitted to do this.

Parameters

Name	Type	Description
config.id*required	string	System-generated id of a document.

Returns

Return type	Status code	Description
void	204	The document has been restored.

Throws

Error Type	Error Message
Unauthorized	API token or tenant missing or corrupt.
Forbidden	Access forbidden. This usually happens because the user lacks the permission to access the specific endpoint, or because the target entity is not accessible to the user.
TrashedDocumentNotFound	Trashed document not found.
InternalServerError	There is a problem in the backend.
ServiceUnavailable	There is a temporary problem in the backend.

Code example

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

const data = await trashClient.restoreTrashedDocument({
  id: "...",
});

Types

AcquireLock

Input to acquire the lock.

Name	Type	Description
documentVersion*required	number	The latest version of the document.
lockDurationInSeconds	number	Duration specified in seconds to acquire the lock on the document.

AcquireLockResult

Name	Type	Description
documentVersion*required	number	The latest version of the document.
lockedUntil*required	Date	Timestamp until the document remains locked.

AddDirectShareRecipients

Input required to add recipients to a direct-share.

Name	Type	Description
recipients*required	Array<SsoEntity>	An array of SSO entities (users and/or groups) to add to this share. They immediately get access to the document. Already added entities are ignored.

BulkDeleteRequest

Name	Type	Description
ids*required	Array<string>	The IDs of the documents that shall be deleted. Must not be empty.

BulkDeleteResponse

Result of the bulk operation for the individual objects.

Name	Type
documents	Array<BulkDeleteResponseDocumentsItem>

BulkDeleteResponseDocumentsItem

Name	Type	Description
code*required	number	HTTP code the single delete endpoint would return for a request with this Document ID
error	Error	An error response as defined here.
id*required	string	ID of the document.

CreateDirectShare

Input required to create a direct-share.

Name	Type	Description
access*required	string	Specifies which permissions shall be granted via the share: - read - grants permission to read the document, but not to update or delete it. - read-write - grants permission to read and update the document, but not to delete it.
documentId*required	string	Document id.
recipients*required	Array<SsoEntity>	An array of sso-users (sso-ids). These users will immediately get access to the document. Can be empty.

CreateDocumentBody

Name	Type	Description
content*required	Blob | Buffer | Binary | File	The binary content of this document. Its exact type is taken from the Content-Type header, which is thus mandatory.
description	string	Optional description of this document. Maximum length is 256 characters.
externalId	string	An optional user-provided id, in addition to the system-provided id. The following constraints apply: It must be unique in this environment Allowed characters: A-Z a-z 0-9 -. It must not be a UUID, however it can contain a UUID, so e.g. my-e015739d-da78-4fe4-bef1-e95c2420bc25 is allowed, while e015739d-da78-4fe4-bef1-e95c2420bc25 is not allowed. Maximum length is 100 characters.
name*required	string	The name of this document. This name doesn't need to be unique and is not used as identifier. Maximum length is 128 characters.
type*required	string	The type of this document. This type is not the Content-Type of the document, but instead adds a user-defined semantic. Maximum length is 128 characters.

CreateEnvShare

Input required to create a environment-share.

Name	Type	Description
access*required	string	Specifies which permissions shall be granted via the share: read - grants permission to read the document, but not to update or delete it. - read-write` - grants permission to read and update the document, but not to delete it.
documentId*required	string	Document id.

CreatedSnapshot

Name	Type	Description
snapshotVersion*required	number	System-generated snapshot version.

CreationInfo

Info related to creation of the entity.

Name	Type	Description
createdBy*required	string	User who created this entity.
createdTime*required	Date	Creation time (in notation as defined by RFC 3339, section 5.6).

DeletionInfo

Info related to the deletion of the entity.

Name	Type	Description
deletedBy*required	string	User who deleted this entity.
deletedTime*required	Date	Time of deletion (in notation as defined by RFC 3339, section 5.6).

DirectShare

Name	Type	Description
access*required	Array<string>	The access granted by this share.
documentId*required	string	The shared document's id.
groupCount*required	number	Number of groups which have been assigned to this share.
id*required	string	System-generated id.
userCount*required	number	Number of users who have been directly assigned to this share and therefore can access the document and collaborate on it. Not that potentially assigned groups and their users (see groupCount) are not reflected in this number.

DirectShareList

A list of direct-shares.

Name	Type
direct-shares*required	Array<DirectShare>
nextPageKey	string
totalCount*required	number

DirectShareRecipientList

Envelope object for a list of recipients.

Name	Type	Description
nextPageKey	string	Use this as page-key query param to get the next page
recipients*required	Array<SsoEntity>
totalCount*required	number	Total number of recipients of the share.

DocumentList

Envelope object for a list of metadata

Name	Type	Description
documents*required	Array<DocumentMetaData>
nextPageKey	string	Use this as page-key query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned.
totalCount*required	number	The total amount of matching results for this query, as if no pagination would have been applied.

DocumentLockDetails

The locking details of the document.

Name	Type	Description
documentVersion*required	number	Latest version of the document.
isLocked	boolean	Document is locked or not.
isLockedByAnotherUser*required	boolean	Document is locked by another user or not.
lockedBy	string	The user that currently owns the lock.

DocumentMetaData

Name	Type	Description
access*required	Array<string>	Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values ['read', 'write', 'delete']. read - you may read, but not update or delete it. write - you may update, but not read or delete it. delete - you may delete, but not read or update it.
description	string	Description, provided by the user.
externalId	string	User-given id.
id*required	string	System-generated id.
isPrivate*required	boolean	Indicates whether this document is public. Public documents can be read by every user of the environment.
modificationInfo*required	ModificationInfo	Info related to creation and modification of the entity.
name*required	string	Name, provided by the user. The system is entirely agnostic of this value and there are no semantics attached to it.
originAppId	string	The id of the application that shipped that document. Null if the document was created by a user and was not shipped with an app.
owner*required	string	Unique user id derived from Authorization header.
type*required	string	Type, provided by the user. The system is entirely agnostic of this value and there are no semantics attached to it.
userContext	UserContext	User-specific information related to this document.
version*required	string	Initial value is 1. Every manipulation (of metadata or content) leads to an increment. This value is used for optimistic locking during modification operations.

EnvironmentShare

Name	Type	Description
access*required	Array<string>	Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values ['read', 'write', 'delete']. read - you may read, but not update or delete it. write - you may update, but not read or delete it. delete - you may delete, but not read or update it.
claimCount*required	number	Number of users who have claimed this share and therefore can access the document and collaborate on it.
documentId*required	string	The shared document's id.
id*required	string	System-generated id of a share resource.

EnvironmentShareClaimResult

Confirmation of claiming an environment-share.

Name	Type	Description
access*required	Array<string>	Indicates which operations you may apply to this document. For example, if you own the document, this array contains the values ['read', 'write', 'delete']. read - you may read, but not update or delete it. write - you may update, but not read or delete it. delete - you may delete, but not read or update it.
documentId*required	string	The shared document's id.
documentType*required	string	The shared document's type.

EnvironmentShareClaimerList

Envelope object for a list of claimers.

Name	Type	Description
claimers*required	Array<string>
nextPageKey	string	Use this as page-key query param to get the next page
totalCount*required	number	The total amount of results for this query

EnvironmentShareList

A list of environment-shares.

Name	Type	Description
environment-shares*required	Array<EnvironmentShare>
nextPageKey	string	Use this as page-key query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned.
totalCount*required	number	The total amount of matching results for this query, as if no pagination would have been applied.

Error

An error response as defined here.

Name	Type
code*required	number
details	ErrorDetails
message*required	string

ErrorDetails

Name	Type
errorRef	string

ErrorEnvelope

Name	Type	Description
error*required	Error	An error response as defined here.

GetDocumentResponse

Name	Type	Description
content	Binary	The binary content of this document.
metadata	DocumentMetaData

ModificationInfo

Info related to creation and modification of the entity.

Name	Type	Description
createdBy*required	string	User who created this entity.
createdTime*required	Date	Creation time (in notation as defined by RFC 3339, section 5.6).
lastModifiedBy*required	string	User who last modified this entity (metadata or content).
lastModifiedTime*required	Date	Time of last modification (in notation as defined by RFC 3339, section 5.6).

RemoveDirectShareRecipients

Input required to remove recipients from a direct-share.

Name	Type
ids*required	Array<string>

RestoreDocumentResult

Name	Type
createdSnapshot	CreatedSnapshot
documentMetadata*required	DocumentMetaData

SnapshotList

Envelope object for a list of snapshots of a document.

Name	Type	Description
nextPageKey	string	Use this as page-key query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned.
snapshots*required	Array<SnapshotMetadata>
totalCount*required	number	The total amount of matching results for this query, as if no pagination would have been applied.

SnapshotMetadata

Metadata of a snapshot of a document.

Name	Type	Description
description	string	An optional description of the snapshot's content or the changes it introduces to the previous snapshot. Provided by the user or app.
documentVersion*required	number	The document version associated with this snapshot. The document had this version when the snapshot was created.
modificationInfo*required	CreationInfo	Info related to creation of the entity.
snapshotVersion*required	number	System-maintained auto-incremented snapshot version, starting at 1. This is not the document version.

SsoEntity

A SSO user or SSO group.

Name	Type	Description
id*required	string	SSO id of a user or group.
type*required	string	Type of the SSO entity - either user or group.

TransferOwner

Input required to transfer document ownership.

Name	Type	Description
newOwnerId*required	string	SSO id of the new owner.

TrashDocument

A document which has been moved to the trash.

Name	Type	Description
deletionInfo*required	DeletionInfo	Info related to the deletion of the entity.
id*required	string	Id of the deleted document.
modificationInfo*required	ModificationInfo	Info related to creation and modification of the entity.
name*required	string	Name of the deleted document.
owner*required	string	Owner of the deleted document.
type*required	string	Type of the deleted document.
version*required	number	Version of the deleted document.

TrashDocumentList

Envelope object for a list of documents in trash.

Name	Type	Description
documents*required	Array<TrashDocumentListEntry>
nextPageKey	string	Use this as page-key query param to get the next page. If the list was paginated, and there are more results available, this parameter will be returned.
totalCount*required	number	The total amount of matching results for this query, as if no pagination would have been applied.

TrashDocumentListEntry

A document which has been deleted and now lives in the trash.

Name	Type	Description
deletionInfo*required	DeletionInfo	Info related to the deletion of the entity.
id*required	string	Id of the deleted document.
name*required	string	Name of the deleted document.
type*required	string	Type of the deleted document.

UpdateDocumentBody

Name	Type	Description
content	Blob | Buffer | Binary | File	The binary content of this document. Its exact type is taken from the Content-Type header, which is thus mandatory. Optional - if not provided, no change happens.
description	string	Description of this document. Maximum length is 256 characters. Optional - if not provided, no change happens.
isPrivate	boolean	Whether this document should be public. Public documents can be read by every user of the environment. This can only be changed by the document owner. Optional - if not provided, no change happens.
name	string	The name of this document. This name doesn't need to be unique and is not used as identifier. Maximum length is 128 characters. Optional - if not provided, no change happens.
snapshotDescription	string	An optional user-provided description of the snapshot's content or the changes it introduced. This description gets ignored if the query-param create-snapshot is not set to true. Maximum length is 128 characters.
type	string	The type of this document. This type is not the Content-Type of the document, but instead adds a user-defined semantic. Maximum length is 128 characters. Optional - if not provided, no change happens.

UpdateDocumentContentBody

Name	Type
content*required	Blob | Buffer | Binary | File

UpdateDocumentMetadata

Name	Type
createdSnapshot	CreatedSnapshot
documentMetadata*required	DocumentMetaData

UpdateDocumentMetadataBody

Name	Type	Description
name	string	Document name.
type	string	Document type.

UserContext

User-specific information related to this document.

Name	Type	Description
lastAccessedTime	Date	Time when the current user last opened or modified this document (in notation as defined by RFC 3339, section 5.6).