# App Manifest

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

??????

***

#### `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.

* `"navigation.root"` is a top-level entry in the main navigation.
* Other values may integrate into dialogs, detail views, etc.

**`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.

***