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
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
| 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:
|
| config.id*required | string | The unique identifier for the app |
| config.latestAppVersion | boolean | If If 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 |
Returns
OK
Code example
import { appEngineRegistryAppsClient } from "@dynatrace-sdk/client-app-engine-registry";
const data = await appEngineRegistryAppsClient.getApp({
id: "...",
});
getApps
List all installed apps.
Required scope: app-engine:apps:run
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:
|
| config.includeAllAppVersions | boolean | If If 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 |
| config.includeDeactivated | boolean | If true, apps that are DEACTIVATED because of missing entitlements are included in the response. |
| config.includeNonRunnable | boolean | If 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
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
| Name | Type |
|---|---|
| config.body*required | Blob |
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
Search actions of installed apps.
Required scope: app-engine:apps:run
Parameters
| Name | Type | Description |
|---|---|---|
| config.query | string | 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
Uninstall an app.
Required scope: app-engine:apps:delete
Parameters
| Name | Type | Description |
|---|---|---|
| config.id*required | string | The 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
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
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.
| Name | Type |
|---|---|
| policyDirectives*required | AppDefaultCspPolicyDirectives |
AppDefaultCspPolicyDirectives
type: Record<string, string[] | undefined>
The policy directives
AppIcon
Representation of an app icon.
| Name | Type | Description |
|---|---|---|
| href*required | string | The reference to an app icon |
AppInfo
A minimal representation of an app.
| Name | Type | Description |
|---|---|---|
| appIcon | AppIcon | |
| description*required | string | The description of the app |
| id*required | string | The id of the app |
| isBuiltin | boolean | Whether this is a built-in app or not. Built-in apps are provided by Dynatrace and installed on every environment. |
| isolatedUri | AppIsolatedUri | |
| manifest | AppInfoManifest | |
| modificationInfo*required | ModificationInfo | |
| name*required | string | The name of the app |
| resourceContext | ResourceContext | |
| resourceStatus*required | ResourceStatus | |
| signatureInfo*required | AppSignatureInfo | |
| version*required | string | The version of the app |
AppInfoList
A list of minimal app representations.
| Name | Type | Description |
|---|---|---|
| apps*required | Array<AppInfo> | The list of minimal app representations. |
AppIsolatedUri
Representation of an app's isolated uri.
| Name | Type | Description |
|---|---|---|
| baseUrl*required | string | The base URL of an app |
| url*required | string | The URL of an app |
| widgetUrl*required | string | The base URL for widgets of an app |
AppSignatureInfo
Representation of an app's signature verification.
| Name | Type | Description |
|---|---|---|
| publisher | string | The organization name of the app publisher. |
| signed*required | boolean | App is signed and its signature has been verified. |
AppStub
A minimal representation of an installed/updated app.
| Name | Type | Description |
|---|---|---|
| id*required | string | Id of the installed/updated app |
| warnings | Array<Warning> | Contains warning information although the request was successful |
ConstraintViolation
Contains information about a constraint violation caused by invalid input.
| Name | Type | Description |
|---|---|---|
| message*required | string | The error message |
| path*required | string | The path of the property that caused the constraint violation |
Error
Contains information for 4xx and 5xx errors.
| Name | Type | Description |
|---|---|---|
| code*required | number | The HTTP status code |
| details | ErrorDetails | |
| help | string | Additional information related to the error |
| message*required | string | The error message |
| retryAfterSeconds | number | Seconds to wait until the next retry |
ErrorDetails
Contains details for 4xx and 5xx errors.
| Name | Type | Description |
|---|---|---|
| constraintViolations | Array<ConstraintViolation> | A list of constraint violations |
| errorCode | MaxNumberOfInstalledCustomAppsExceeded | |
| errorCodeProperties | ErrorDetailsErrorCodeProperties | |
| errorRef | string | Generated unique value for 5xx errors. |
| traceId | string | OpenTelemetry trace id of the trace where error occurs. |
ErrorDetailsErrorCodeProperties
Additional properties related to the provided error code
| Name | Type | Description |
|---|---|---|
| customAppLimit | string | Limit for max amount of installed custom apps in a tenant |
ErrorEnvelope
Error response for all 4xx and 5xx errors.
| Name | Type |
|---|---|
| error*required | Error |
ModificationInfo
Modification information about the app
| Name | Type | Description |
|---|---|---|
| createdAt*required | string | Timestamp when the resource was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z') |
| createdBy*required | string | UserId of the user that created the resource |
| lastModifiedAt*required | string | Timestamp when the resource was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z') |
| lastModifiedBy*required | string | UserId of the user that last modified the resource |
ResourceContext
Additional resource context information
| Name | Type | Description |
|---|---|---|
| operations | Array<ResourceContextOperationsItem> | Operations that are allowed on the app depending on the user's permissions.
|
ResourceStatus
The status of the app plus additional details.
| Name | Type | Description |
|---|---|---|
| operationStateBeforeError | ResourceStatusOperationStateBeforeError | |
| pendingOperation | ResourceStatusPendingOperation | |
| status*required | ResourceStatusStatus | |
| subResourceStatuses | Array<SubResourceStatus> | The statuses of the app's sub resources. |
SearchAppAction
List of apps with actions. Apps are sorted by name in ascending order.
| Name | Type | Description |
|---|---|---|
| actions*required | Array<SearchAppActionActionsItem> | List of app actions. Actions are sorted by name in ascending order. Actions without name are last. |
| id*required | string | App id |
| name*required | string | App name |
SearchAppActionList
| Name | Type | Description |
|---|---|---|
| apps*required | Array<SearchAppAction> | |
| totalCount*required | number | Total actions count. |
SubResourceConstraintViolation
Contains information about a constraint violation caused by invalid input.
| Name | Type | Description |
|---|---|---|
| message*required | string | The error message |
| path | string | The path of the property that caused the constraint violation |
SubResourceError
Additional error information that can be present if the sub resource status is FAILED
| Name | Type | Description |
|---|---|---|
| constraintViolations | Array<SubResourceConstraintViolation> | A list of constraint violations |
| errorCode | string | An error code that can be used determine the nature of an error and why it occurred. |
| errorRef | string | Optional generated unique value to reference this error. |
| message*required | string | The error message. |
SubResourceStatus
The status of the sub resource.
| Name | Type |
|---|---|
| error | SubResourceError |
| status*required | SubResourceStatusStatus |
| subResourceType*required | SubResourceStatusSubResourceType |
Warning
A warning.
| Name | Type | Description |
|---|---|---|
| message | string | The 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