> For the complete documentation index, see [llms.txt](https://developer.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.vario-software.de/documentation/apps/app-manifest.md). # 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": "app_demo_license_key", "permissions": [ { "resource": "crm-activity", "verb": "read" }, { "resource": "crm-activity", "verb": "create" } ] } ``` #### `requirements.licenseKey` Type: `string` The App's **own** license key, which grants access to the App itself. {% hint style="info" %} **You do not author this value.** VARIO Cloud generates it when the App is created, in the form `app__`, and preserves it whenever the manifest is refreshed — a manifest you send cannot overwrite it. It must be globally unique. {% endhint %} 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. ```json "requirements": { "licenseKeys": ["workflow_license"] } ``` Common values include `workflow_license` and `scripting_license`. {% hint style="warning" %} 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. {% endhint %} *** #### `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. ``` "authorizationVerbs": [ { "verb": "use-app", "description": "Allowed to use the demo app" }, { "verb": "add-activity", "description": "Allowed to add activities" } ] ``` 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": [ { "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" } ] } ``` #### `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](#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](https://help.vario-software.de/support/melden-von-problemen-in-vario-cloud/support-modus). 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 | | ------------------------ | --------------------------------------------------------------------------------- | | `.badge` | Renders a badge on the tab of your own integration whose `id` matches the prefix. | {% hint style="danger" %} **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. {% endhint %} **`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: ```javascript sendMain({ dialog: { open: { integrationId: 'settings.graphql-queries.editor', title: 'GraphQL Editor', }, }, }); ``` 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`. {% hint style="info" %} 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](https://developer.vario-software.de/api-reference). Requesting a permission that doesn't exist is silently ignored. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.vario-software.de/documentation/apps/app-manifest.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.