Quickstart

Getting started with the VARIO App Framework

This guide walks you through building and connecting a new VARIO Cloud App using:

• the VARIO App Framework (Node.js)

• the VARIO App Demo as a starting point

• a VARIO-Cloud tenant where you can register Apps

You will:

1. Clone the demo app and install dependencies

2. Configure the manifest and API client

3. Run the app and see it embedded into VARIO Cloud via iframe

4. Start extending the app’s backend and frontend

---

Prerequisites

You should have:

• A VARIO Cloud tenant with access to the Developer (Entwickler) section

• A registered App in VARIO Cloud including its API credentials

  • appIdentifier, clientId, clientSecret

  • See: Creating a new App

• Node.js and npm installed

• Git installed

• Access to public git Repository:

  • VARIO App Framework: https://github.com/vario-software/vario-app-framework

  • VARIO App Demo: https://github.com/vario-software/vario-app-demo

---

1. Prepare your App and credentials

Before you start development, make sure you have followed the steps in Creating a new App and that you have:

• an App created in the VARIO Cloud Developer section

• the corresponding AppClient values:

{
  "appIdentifier": "your-app-identifier",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "appJWK": "JWK_TOKEN"
}

These credentials will be used by the demo app to authenticate against the VARIO-Cloud API.

---

2. Use the demo app as a starting point

The easiest way to get started is to use the VARIO App Demo as a template and adapt it to your needs.

2.1. Clone the demo repository

git clone https://github.com/vario-software/vario-app-demo.git
cd vario-app-demo

You will find (among other things):

• backend/ – Node.js backend using the VARIO App Framework

• frontend/ – static assets / UI for the app

• app-manifest.json – sample manifest

• app-client.json – placeholder for API credentials

• package.json – project configuration & npm scripts

2.2. Install dependencies

From the root of the demo app:

npm install

This installs the VARIO App Framework and any other required libraries.

---

3. Connect the demo app to your VARIO Cloud App

Now you tie your tenant App (configured in VARIO-Cloud) to your demo app.

3.1. Align the manifest in the repo

Open app-manifest.json in the demo project and align it with the manifest you used when creating the App in VARIO-Cloud:

• Ensure that key metadata matches:

  • label, description, shortName, appVersion

• Adjust URLs to reflect your environment:

  • rootUrl

  • pcInstallationUrl

  • pcInstallationDeletionUrl

  • pcManifestUrl

---

3. Connect the demo app to your VARIO-Cloud App

Now you tie your tenant App (configured in VARIO Cloud) to your demo app.

3.1. Align the manifest in the repo

Open app-manifest.json in the demo project and align it with the manifest you used when creating the App in VARIO-Cloud:

• Ensure that key metadata matches:

  • label, description, shortName, appVersion

• Adjust URLs to reflect your environment:

  • rootUrl

  • pcInstallationUrl

  • pcInstallationDeletionUrl

  • pcManifestUrl

For local development you typically:

• You have to make sure your app is publicly reachable from the internet. If you are developing on a local machine, you probably have to use a tunneling service like ngrok or DynDNS. The Vario Cloud must be able to connect to the running app.

• run the app on https://public-ip:<port>

• expose it through a tunnel (e.g. https://<random>.ngrok.io) or use a test host with HTTPS

The URLs in the manifest must be reachable by VARIO-Cloud.

3.2. Add your AppClient credentials

Open app-client.json in the demo project and fill it with the values from your AppClient:

{
  "appIdentifier": "your-app-identifier",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "appJWK": "JWK_TOKEN"
}

---

4. Run the app locally

The demo app defines npm scripts in package.json to start the backend and frontend. Check the scripts section and use the appropriate command, for example:

# example – adjust to the actual script names in package.json
npm run dev

Once the app is running:

• the backend listens on its configured port (e.g. https://public-ip:3000)

• the frontend serves the UI pages referenced in your uiIntegrations manifest section

---

5. See the app inside VARIO-Cloud

Because the manifest defines one or more UI integrations, VARIO Cloud embeds your App in an iframe at those integration points.

Example integration:

"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"
    }
  ]
}

For your development environment, ensure:

1. The url points to a reachable HTTPS endpoint of your running app (for local dev: via tunnel or test host).

2. The users you test with have the corresponding permissionKey (here: use-app) assigned in VARIO Cloud.

Then:

1. Log in to VARIO Cloud.

2. Open the main navigation.

3. Click the navigation entry for your App (e.g. “Demoapp”).

4. VARIO-Cloud will open your App UI in an iframe.

---

6. Start developing your own functionality

From here, you can extend both the backend and frontend.

Backend (Node.js with VARIO App Framework)

In the backend folder you can:

• add new routes/endpoints

• use the framework’s helpers to:

  • authenticate with VARIO-Cloud (OAuth2 using clientId and clientSecret)

  • call VARIO-Cloud REST APIs

  • execute VQL queries and return data to the frontend

Typical flow for a new feature:

1. Decide which VARIO-Cloud data you need (e.g. customers, orders, CRM activities).

2. Implement a backend route that:

   • obtains/refreshes an access token

   • calls the appropriate VARIO-Cloud API or VQL endpoint

   • returns the processed data as JSON

3. Handle errors and logging for easier debugging.

Frontend (UI pages)

In the frontend folder you can:

• modify existing HTML/JS pages or add new ones

• use the framework’s CSS/JS assets to match VARIO Cloud’s look & feel

• call your backend routes using fetch from within the iframe context

---

7. Summary

In short, to get started with the VARIO App Framework:

1. Create and configure an App in VARIO-Cloud and obtain appIdentifier, clientId, clientSecret

   • See: Creating a new App

2. Clone the VARIO App Demo and run npm install.

3. Align app-manifest.json with your registered App and environment.

4. Fill app-client.json with your AppClient credentials.

5. Start the app using the npm scripts in package.json.

6. Open VARIO-Cloud and use the UI integration to reach your App.

7. Extend backend and frontend using the VARIO App Framework to build your own features.