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.subResourceTypes
    • resourceStatus.subResourceStatuses
    • manifest
    • any top-level manifest field to include a part of the manifest, for example, manifest.scopes or manifest.intents
    • 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

    Return typeStatus codeDescription
    AppInfo200OK

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    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.subResourceTypes
    • resourceStatus.subResourceStatuses
    • manifest
    • any top-level manifest field to include a part of the manifest, for example, manifest.scopes or manifest.intents
    • isBuiltin
    • isolatedUri
    config.filterstring

    The filter parameter, as explained here.

    Filtering is supported on the following fields:

    • id
    • resourceStatus.subResourceTypes

    Examples:

    • id = 'my.custom-app'
    • id contains 'custom'
    • id starts-with 'my.'
    • not(id starts-with 'my.')
    • id in ('my.custom-app', 'my.other-custom-app')
    • resourceStatus.subResourceTypes contains 'DOCUMENTS'
    • resourceStatus.subResourceTypes contains 'DOCUMENTS' or resourceStatus.subResourceTypes contains 'FUNCTIONS'

    If this parameter is omitted, all apps will be returned.

    The maximum nesting depth (via parentheses) is 3. The maximum expression length is 256 characters.

    Fields that are used for filtering are always included in the response, even if they are not in the default set of fields.

    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 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

    Return typeStatus codeDescription
    AppInfoList200OK

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    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

    Return typeStatus codeDescription
    AppStub202Accepted; new app will be installed/updated

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorBad Request | Client side error. | Server side error.

    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

    Return typeStatus codeDescription
    SearchAppActionList200OK

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    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

    Returns

    Return typeStatus codeDescription
    void202Accepted; app will be uninstalled

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    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(config): Promise<Record<string | any>>

    Get JSON schema for app manifests

    Returns

    Return typeStatus codeDescription
    void200OK

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    Code example

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

    const data =
    await appEngineRegistrySchemaManifestClient.getAppManifestSchema();

    getDefaultCspProperties

    appEngineRegistrySchemaManifestClient.getDefaultCspProperties(config): Promise<AppDefaultCsp>

    Get default CSP rules for apps

    Returns

    Return typeStatus codeDescription
    AppDefaultCsp200OK

    Throws

    Error TypeError Message
    ErrorEnvelopeErrorClient side error. | Server side error.

    Code example

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

    const data =
    await appEngineRegistrySchemaManifestClient.getDefaultCspProperties();

    Types

    AppDefaultCsp

    Default Content Security Policies for apps.

    NameTypeDescription
    policyDirectives*requiredAppDefaultCspPolicyDirectivesThe policy directives

    AppDefaultCspPolicyDirectives

    The policy directives

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

    AppIcon

    Representation of an app icon.

    NameTypeDescription
    href*requiredstringThe reference to an app icon

    AppInfo

    A minimal representation of an app.

    NameTypeDescription
    appIconAppIconRepresentation of an app icon.
    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.

    isolatedUriAppIsolatedUriRepresentation of an app's isolated uri.
    manifestAppInfoManifestThe manifest of the app
    modificationInfo*requiredModificationInfoModification information about the app
    name*requiredstringThe name of the app
    resourceContextResourceContextAdditional resource context information
    resourceStatus*requiredResourceStatusThe status of the app plus additional details.
    signatureInfo*requiredAppSignatureInfoRepresentation of an app's signature verification.
    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
    errorCode"DependencyVersionIncompatible" | "DependencyUnknown"

    An optional error code that contains more detailed error information.

    Possible error codes:

    • DependencyVersionIncompatible: The app's manifest contains a dependency with an incompatible version.
    • DependencyUnknown: The app's manifest contains a dependency that is unknown.
    errorCodePropertiesConstraintViolationErrorCodePropertiesAdditional properties related to the provided error code.
    message*requiredstringThe error message
    path*requiredstringThe path of the property that caused the constraint violation

    ConstraintViolationErrorCodeProperties

    Additional properties related to the provided error code.

    NameTypeDescription
    availableVersionstringThe version that is available. This value is present if the error code is DependencyVersionIncompatible.
    dependencystringThe name of the dependency. This value is present if the error code is DependencyUnknown or DependencyVersionIncompatible.
    incompatibleVersionstringThe version that is incompatible. This value is present if the error code is DependencyVersionIncompatible.

    Error

    Contains information for 4xx and 5xx errors.

    NameTypeDescription
    code*requirednumberThe HTTP status code
    detailsErrorDetailsContains details for 4xx and 5xx errors.
    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
    errorCode"MaxNumberOfInstalledCustomAppsExceeded"

    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
    errorCodePropertiesErrorDetailsErrorCodePropertiesAdditional properties related to the provided error code
    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 number of installed custom apps in an environment. This value is present if the error code is `MaxNumberOfInstalledCustomAppsExceeded'.

    ErrorEnvelope

    Error response for all 4xx and 5xx errors.

    NameTypeDescription
    error*requiredErrorContains information for 4xx and 5xx errors.

    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<"run" | "update" | "uninstall">

    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
    operationStateBeforeError"OK" | "PENDING_INSTALL" | "PENDING_UPDATE" | "PENDING_DELETE"

    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.

    pendingOperation"INSTALL" | "UPDATE" | "DELETE"

    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.

    status*required"OK" | "PENDING" | "DEACTIVATED" | "ERROR"

    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.

    subResourceStatusesArray<SubResourceStatus>The statuses of the app's sub resources.
    subResourceTypesArray<"FUNCTIONS" | "FILES" | "SETTINGS_SCHEMAS" | "DOCUMENTS">The sub resource types that the app contains.

    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.

    NameTypeDescription
    errorSubResourceErrorAdditional error information that can be present if the sub resource status is FAILED
    status*required"SCHEDULED" | "DEPLOYING" | "DEPLOYED" | "FAILED" | "NO_RESOURCES"

    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

    subResourceType*required"FUNCTIONS" | "FILES" | "SETTINGS_SCHEMAS" | "DOCUMENTS"

    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.

    Warning

    A warning.

    NameTypeDescription
    messagestringThe warning message.

    Enums

    ConstraintViolationErrorCode

    An optional error code that contains more detailed error information.

    Possible error codes:

    • DependencyVersionIncompatible: The app's manifest contains a dependency with an incompatible version.
    • DependencyUnknown: The app's manifest contains a dependency that is unknown.

    Enum keys

    DependencyUnknown | DependencyVersionIncompatible

    DeploymentStatus

    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

    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

    OperationStateBeforeError

    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

    PendingOperation

    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

    ResourceContextOperationsItem

    Enum keys

    Run | Uninstall | Update

    Status

    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

    SubResourceType

    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