Skip to main content

AppEngine - Registry

Overview

The Registry is mainly responsible for

  • installing / updating / storing apps
  • uninstalling / removing apps
  • getting apps

Asynchronous behavior

Both the install and the uninstall process are performed asynchronously. The Registry persists the app bundle and defines the desired state of the app (e.g. installed, uninstalled). The installation / uninstallation process is then handled asynchronously by a separate service.

The current status of the app is provided by the status in the response body of the respective GET request, e.g. /apps/{id}.

npm install @dynatrace-sdk/client-app-engine-registry

appEngineRegistryAppsClient

import { appEngineRegistryAppsClient } from '@dynatrace-sdk/client-app-engine-registry';

getApp

appEngineRegistryAppsClient.getApp(config): Promise<AppInfo>

Get an installed app

Required scope: app-engine:apps:run

During an app update, when a current version and a new version exists, the current one is returned.

Parameters

NameTypeDescription
config.addFieldsstring

Comma-separated list of field names that are added to the default set of fields.

You can include the following additional fields:

  • resourceContext
  • resourceStatus.subResourceStatuses
  • manifest
  • isBuiltin
  • isolatedUri
config.id*requiredstringThe unique identifier for the app
config.latestAppVersionboolean

If true, the latest version of the app is returned.

If false, the current version of the app is returned.

This is relevant while an app is being updated. During this time typically two versions of the same app exist, the current version and the latest version with status=PENDING.

Returns

OK

Code example

import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";

const data = await appEngineRegistryAppsClient.getApp({
id: "...",
});

getApps

appEngineRegistryAppsClient.getApps(config): Promise<AppInfoList>

List all installed apps.

Required scope: app-engine:apps:run

Parameters

NameTypeDescription
config.addFieldsstring

Comma-separated list of field names that are added to the default set of fields.

You can include the following additional fields:

  • resourceContext
  • resourceStatus.subResourceStatuses
  • manifest
  • isBuiltin
  • isolatedUri
config.includeAllAppVersionsboolean

If true, all versions of every app are included in the response.

If false, only the current version of every app is included.

This is relevant while an app is being updated. During this time typically two versions of the same app exist, the current version and the latest version with status=PENDING.

config.includeDeactivatedbooleanIf true, apps that are DEACTIVATED because of missing entitlements are included in the response.
config.includeNonRunnablebooleanIf true, apps that the user is not allowed to run because of missing permissions are included in the response.

Returns

OK

Code example

import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";

const data = await appEngineRegistryAppsClient.getApps();

installApp

appEngineRegistryAppsClient.installApp(config): Promise<AppStub>

Install or update an app.

Required scope: app-engine:apps:install

An app ID always starts with a namespace and a dot, e.g. dynatrace. for Dynatrace apps. Custom apps can be installed in the my namespace, e.g. my.first-app.

The zipped app bundle has to be provided via the request body

Parameters

NameType
config.body*requiredBlob

Returns

Accepted; new app will be installed/updated

Code example

import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";

const data = await appEngineRegistryAppsClient.installApp({
body: new Blob(),
});

searchActions

appEngineRegistryAppsClient.searchActions(config): Promise<SearchAppActionList>

Search actions of installed apps.

Required scope: app-engine:apps:run

Parameters

NameTypeDescription
config.querystring

A whitespace separated list of search terms. For an action to match, each search term must be contained in either: app name, app description, action name or action description.

Search terms are case insensitive and each additional search term restricts actions further. Maximum length is 256 characters.

Returns

OK

Code example

import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";

const data =
await appEngineRegistryAppsClient.searchActions();

uninstallApp

appEngineRegistryAppsClient.uninstallApp(config): Promise<void>

Uninstall an app.

Required scope: app-engine:apps:delete

Parameters

NameTypeDescription
config.id*requiredstringThe unique identifier for the app

Code example

import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";

const data = await appEngineRegistryAppsClient.uninstallApp(
{ id: "..." },
);

appEngineRegistrySchemaManifestClient

import { appEngineRegistrySchemaManifestClient } from '@dynatrace-sdk/client-app-engine-registry';

getAppManifestSchema

appEngineRegistrySchemaManifestClient.getAppManifestSchema(abortSignal?): Promise<Record<string | any>>

Get JSON schema for app manifests

Returns

OK

Code example

import { appEngineRegistrySchemaManifestClient } from "@dynatrace-sdk/client-app-engine-registry";

const data =
await appEngineRegistrySchemaManifestClient.getAppManifestSchema();

getDefaultCspProperties

appEngineRegistrySchemaManifestClient.getDefaultCspProperties(abortSignal?): Promise<AppDefaultCsp>

Get default CSP rules for apps

Returns

OK

Code example

import { appEngineRegistrySchemaManifestClient } from "@dynatrace-sdk/client-app-engine-registry";

const data =
await appEngineRegistrySchemaManifestClient.getDefaultCspProperties();

Types

AppDefaultCsp

Default Content Security Policies for apps.

NameType
policyDirectives*requiredAppDefaultCspPolicyDirectives

AppDefaultCspPolicyDirectives

type: Record<string, string[] | undefined>

The policy directives

AppIcon

Representation of an app icon.

NameTypeDescription
href*requiredstringThe reference to an app icon

AppInfo

A minimal representation of an app.

NameTypeDescription
appIconAppIcon
description*requiredstringThe description of the app
id*requiredstringThe id of the app
isBuiltinboolean

Whether this is a built-in app or not. Built-in apps are provided by Dynatrace and installed on every environment.

isolatedUriAppIsolatedUri
manifestAppInfoManifest
modificationInfo*requiredModificationInfo
name*requiredstringThe name of the app
resourceContextResourceContext
resourceStatus*requiredResourceStatus
signatureInfo*requiredAppSignatureInfo
version*requiredstringThe version of the app

AppInfoList

A list of minimal app representations.

NameTypeDescription
apps*requiredArray<AppInfo>The list of minimal app representations.

AppIsolatedUri

Representation of an app's isolated uri.

NameTypeDescription
baseUrl*requiredstringThe base URL of an app
url*requiredstringThe URL of an app
widgetUrl*requiredstringThe base URL for widgets of an app

AppSignatureInfo

Representation of an app's signature verification.

NameTypeDescription
publisherstringThe organization name of the app publisher.
signed*requiredbooleanApp is signed and its signature has been verified.

AppStub

A minimal representation of an installed/updated app.

NameTypeDescription
id*requiredstringId of the installed/updated app
warningsArray<Warning>Contains warning information although the request was successful

ConstraintViolation

Contains information about a constraint violation caused by invalid input.

NameTypeDescription
message*requiredstringThe error message
path*requiredstringThe path of the property that caused the constraint violation

Error

Contains information for 4xx and 5xx errors.

NameTypeDescription
code*requirednumberThe HTTP status code
detailsErrorDetails
helpstringAdditional information related to the error
message*requiredstringThe error message
retryAfterSecondsnumberSeconds to wait until the next retry

ErrorDetails

Contains details for 4xx and 5xx errors.

NameTypeDescription
constraintViolationsArray<ConstraintViolation>A list of constraint violations
errorCodeMaxNumberOfInstalledCustomAppsExceeded
errorCodePropertiesErrorDetailsErrorCodeProperties
errorRefstringGenerated unique value for 5xx errors.
traceIdstringOpenTelemetry trace id of the trace where error occurs.

ErrorDetailsErrorCodeProperties

Additional properties related to the provided error code

NameTypeDescription
customAppLimitstringLimit for max amount of installed custom apps in a tenant

ErrorEnvelope

Error response for all 4xx and 5xx errors.

NameType
error*requiredError

ModificationInfo

Modification information about the app

NameTypeDescription
createdAt*requiredstringTimestamp when the resource was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
createdBy*requiredstringUserId of the user that created the resource
lastModifiedAt*requiredstringTimestamp when the resource was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedBy*requiredstringUserId of the user that last modified the resource

ResourceContext

Additional resource context information

NameTypeDescription
operationsArray<ResourceContextOperationsItem>

Operations that are allowed on the app depending on the user's permissions.

  • run: user is allowed to run the app.

  • update: user is allowed to update the app.

  • uninstall: user is allowed to uninstall the app.

ResourceStatus

The status of the app plus additional details.

NameTypeDescription
operationStateBeforeErrorResourceStatusOperationStateBeforeError
pendingOperationResourceStatusPendingOperation
status*requiredResourceStatusStatus
subResourceStatusesArray<SubResourceStatus>The statuses of the app's sub resources.

SearchAppAction

List of apps with actions. Apps are sorted by name in ascending order.

NameTypeDescription
actions*requiredArray<SearchAppActionActionsItem>List of app actions. Actions are sorted by name in ascending order. Actions without name are last.
id*requiredstringApp id
name*requiredstringApp name

SearchAppActionList

NameTypeDescription
apps*requiredArray<SearchAppAction>
totalCount*requirednumberTotal actions count.

SubResourceConstraintViolation

Contains information about a constraint violation caused by invalid input.

NameTypeDescription
message*requiredstringThe error message
pathstringThe path of the property that caused the constraint violation

SubResourceError

Additional error information that can be present if the sub resource status is FAILED

NameTypeDescription
constraintViolationsArray<SubResourceConstraintViolation>A list of constraint violations
errorCodestringAn error code that can be used determine the nature of an error and why it occurred.
errorRefstringOptional generated unique value to reference this error.
message*requiredstringThe error message.

SubResourceStatus

The status of the sub resource.

NameType
errorSubResourceError
status*requiredSubResourceStatusStatus
subResourceType*requiredSubResourceStatusSubResourceType

Warning

A warning.

NameTypeDescription
messagestringThe warning message.

Enums

ErrorDetailsErrorCode

An optional error code that contains more detailed error information than the HTTP response code alone.

Possible error codes:

  • MaxNumberOfInstalledCustomAppsExceeded: The app bundle could not be uploaded because the max number of custom apps was exceeded. Learn more: https://dt-url.net/upgrade-license

Enum keys

MaxNumberOfInstalledCustomAppsExceeded

ResourceContextOperationsItem

Enum keys

Run | Uninstall | Update

ResourceStatusOperationStateBeforeError

Details about the state when an error occurred. Only present if the app's status is ERROR.

  • PENDING_INSTALL: The error occurred while installing the app.

  • PENDING_UPDATE: The error occurred while updating the app.

  • PENDING_DELETE: The error occurred while deleting the app.

  • OK: At least one sub resource failed while the app was already running.

Enum keys

Ok | PendingDelete | PendingInstall | PendingUpdate

ResourceStatusPendingOperation

The pending operation of the app. Only present if the app's status is PENDING.

  • INSTALL: The app is currently being installed.

  • UPDATE: The app is currently being updated.

  • DELETE: The app is currently being deleted.

Enum keys

Delete | Install | Update

ResourceStatusStatus

The status of the app.

  • OK: The app is fully installed and running.

  • PENDING: The app is currently being installed, updated or deleted.

  • DEACTIVATED: The app is deactivated and cannot be executed.

  • ERROR: The app failed with an error.

Enum keys

Deactivated | Error | Ok | Pending

SubResourceStatusStatus

The deployment status of the app's sub resource:

  • SCHEDULED: Only the uploaded app bundle is persisted.

  • DEPLOYING: The app's sub resources are currently being deployed.

  • DEPLOYED: The app's sub resources were successfully deployed.

  • FAILED: The deployment of the app's sub resources failed.

  • NO_RESOURCES: The app bundle does not contain any sub resources of this type

Enum keys

Deployed | Deploying | Failed | NoResources | Scheduled

SubResourceStatusSubResourceType

The sub resource type.

  • FUNCTIONS: app functions.

  • FILES: static files of an app.

  • SETTINGS_SCHEMAS: settings schemas of an app.

  • DOCUMENTS: documents, e.g. templates, that are part of an app bundle.

Enum keys

Documents | Files | Functions | SettingsSchemas

Still have questions?
Find answers in the Dynatrace Community