# 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**](https://developer.vario-software.de/documentation/apps/create-an-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**](https://developer.vario-software.de/documentation/apps/create-an-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](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](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**](https://developer.vario-software.de/documentation/apps/create-an-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.