If something’s missing or unclear, let us know.
Send feedback
Ctrlk
npmGitHubAdmin-Center
For the complete documentation index, see llms.txt. This page is also available as Markdown.

App Manifest

Reference for every manifest field — metadata, URLs, permissions and UI integrations.

App manifest reference

The App manifest is a JSON document that describes your App to VARIO Cloud. It defines metadata, technical URLs, permissions and UI integration points.

{
  "appVersion": "1.0.0",
  "label": "Demoapp",
  "description": "Just a demo app",
  "shortName": "demoapp",
  "rootUrl": "https://app.example.com/",
  "pcInstallationUrl": "https://app.example.com/ui/install.html",
  "pcInstallationDeletionUrl": "https://app.example.com/ui/uninstall.html",
  "pcManifestUrl": "https://app.example.com/manifest",
  "requirements": {
    "licenseKey": "app_demo_license_key",
    "permissions": [
      {
        "resource": "crm-activity",
        "verb": "read"
      },
      {
        "resource": "crm-activity",
        "verb": "create"
      }
    ]
  },
  "authorizationVerbs": [
    {
      "verb": "use-app",
      "description": "Allowed to use the demo app"
    },
    {
      "verb": "add-activity",
      "description": "Allowed to add activities"
    }
  ],
  "uiIntegrations": {
    "integrations": [
      {
        "pointOfIntegration": "navigation.root",
        "id": "demo-page",
        "url": "https://app.example.com/ui/demo.html",
        "iconClass": "fal fa-atom-simple",
        "msgKey": "Demoapp",
        "permissionKey": "use-app"
      },
      {
        "id": "demo-dialog",
        "url": "https://app.example.com/ui/demo-dialog.html"
      },
      {
        "id": "demo-vr",
        "url": "https://app.example.com/ui/demo-vr.html"
      }
    ]
  }
}

Below is a description of all fields used in the example manifest.

Top-level fields

appVersion

Type: string (semantic version, e.g. "1.0.0")

Version of the App itself..

label

Type: string

Human-readable name of the App. This is shown in the VARIO-Cloud UI.

description

Type: string

Short description of what the App does. Used in the UI to help users understand the purpose of the App.

shortName

Type: string

Unique identifier used by the VARIO-Cloud as a suffix to identify what app, for example, a role is connected to.

  • Must be unique across all apps.

  • Only accepts EN-letters and _ or -

rootUrl

Type: string (URL)

Base URL of the App backend / web application.

  • Example: https://app.example.com/

pcInstallationUrl

Type: string (URL)

URL called when the App is installed for a tenant.

Typical use cases:

  • Initialize data or configuration for this tenant.

  • Register webhooks or background jobs.

pcInstallationDeletionUrl

Type: string (URL)

URL called when the App is uninstalled from a tenant.

Typical use cases:

  • Clean up tenant-specific data or configuration.

  • Deregister webhooks or background jobs.

pcManifestUrl

Type: string (URL)

URL where VARIO-Cloud can fetch additional technical metadata for the App (the “runtime manifest”).

  • Used by the platform to understand capabilities, endpoints or configuration dynamically.

  • Should return a JSON document.

requirements object

The requirements section declares what the App needs from the VARIO-Cloud platform.

requirements.licenseKey

Type: string

The App's own license key, which grants access to the App itself.

You do not author this value. VARIO Cloud generates it when the App is created, in the form app_<random>_<shortName>, and preserves it whenever the manifest is refreshed — a manifest you send cannot overwrite it. It must be globally unique.

To declare licenses your App depends on, use requirements.licenseKeys instead.

requirements.licenseKeys

Type: array of string

Additional existing platform licenses the tenant must already have for your App to be installable.

Common values include workflow_license and scripting_license.

Installation fails with 422 if the tenant is missing any required license — both licenseKey and every entry in licenseKeys are checked.

At runtime, a missing or exceeded license produces 402 Payment Required instead. If your App can work without an optional license, check for it and degrade gracefully rather than failing.

requirements.permissions

Type: array of Permission objects

Declares which API permissions the App requires to operate.

Each entry has:

permission.resource

Type: string Example: "crm-activity"

Name of the resource in the VARIO-Cloud API that the App wants to access (e.g. customers, orders, CRM activities, …).

permission.verb

Type: string Examples: "read", "create", "update", "delete"

Operation the App wants to perform on the given resource. The exact set of verbs is defined by the VARIO-Cloud.

Together, resource + verb define a single permission, such as crm-activity:read or crm-activity:create.

authorizationVerbs array

Declares App-specific authorization permissions that can later be assigned to users or roles inside VARIO-Cloud.

Each entry defines a custom capability.

authorizationVerbs[].verb

Type: string Example: "use-app"

A symbolic key representing a permission inside the App.

  • They are used by VARIO-Cloud to control what different users may do in the App.

authorizationVerbs[].description

Type: string

Human-readable explanation of what the permission allows. Shown in the UI when assigning permissions to users or roles.

uiIntegrations object

Defines how the App integrates into the VARIO-Cloud user interface.

uiIntegrations.integrations

Type: array of Integration objects

Each entry describes one UI integration point.

Common fields:

integration.id

Type: string Example: "demo-page"

Unique identifier of this integration within the App manifest.

integration.url

Type: string (URL)

URL where VARIO-Cloud can find actions / ui elements when the user triggers this integration

Additional fields for navigation entries:

integration.pointOfIntegration

Type: string Example: "navigation.root"

Specifies where in the VARIO-Cloud UI this integration appears. Omit it entirely for integrations you open yourself (see Integrations without a point of integration).

Some points contain the placeholder {APP_IDENTIFIER}, which is replaced with your App's identifier at runtime — these points are reserved for the App that owns the object being displayed.

Finding the available integration points

The set of integration points grows with every release, so this page deliberately does not list them. Read them out of the running application instead — that way you always see the points your version actually offers:

  1. Open your ERP in support mode.

  2. Enable the toggle "App-Integrationspunkte anzeigen" ("Show app integration points").

  3. Reload when prompted — the setting only takes effect after a reload.

The ERP then renders a placeholder at every available integration point, labelled with the pointOfIntegration string you need for your manifest. Navigate to the screen you want to extend and read the value off it.

One value is not discoverable that way, because it renders nothing of its own:

Value
Meaning

<integration-id>.badge

Renders a badge on the tab of your own integration whose id matches the prefix.

An unknown pointOfIntegration fails silently. Matching is exact string comparison, and there is no manifest validation — a typo means your integration simply never appears, with no error anywhere. The same is true for an unknown resource or verb in requirements.permissions: the permission is just never granted.

integration.iconClass

Type: string Example: "fal fa-atom-simple"

FontAwesome class for the icon that will be displayed in the UI.

integration.msgKey

Type: string Example: "Demoapp"

Label displayed in the UI for this integration.

integration.permissionKey

Type: string Example: "use-app"

Links this UI integration to one of the App’s authorizationVerbs.

  • Only users who have this verb assigned are allowed to see or use the integration.

integration.contextAttribute

Type: object

Free-form metadata attached to the integration. Only meaningful where a specific integration point reads it.

Integrations without a point of integration

An integration with an id but no pointOfIntegration is never rendered by the ERP on its own. It exists so the URL is registered, and is opened on demand — typically as a dialog your own UI requests:

The ERP resolves the id in your manifest, opens it in a full-screen dialog, and returns the result to your App. Use this for editors, wizards and confirmation dialogs.

Sub-pages that you navigate to inside your own App still need a manifest entry so the URL exists, even though nothing opens them by id.

requirements.permissions vs authorizationVerbs

These two are easy to confuse and do completely different things:

requirements.permissions

authorizationVerbs

Grants access to

your App's technical user, calling the ERP API

human users, for actions inside your App

Shape

{ resource, verb }

{ verb, description }

Checked against

ERP resources and operations

your App's own identifier

Failure

403 from the ERP API

403 from your own permission check

Used with

API calls

integration.permissionKey, and your own checks

For requirements.permissions, resource is an ERP domain (for example account, article, document, sales-channel, eav, masterdata) and verb is either a standard operation — create, read, update, delete, activate, deactivate — or a domain-specific one such as document:readSalesDocuments or crm-task:updateForeignCrmTask.

The authoritative list of resources and verbs for your installation is available from the ERP itself via the roles/permissions endpoint — see the API Reference. Requesting a permission that doesn't exist is silently ignored.

PreviousCreate an App
NextUI Integration

Last updated

Was this helpful?