> 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/rest-api/browser-tools.md).

# Browser tools (bookmarklets)

Run your own JavaScript tools in the open ERP tab via a browser bookmark: how it works, what you can build, where the limits are and what to watch for.

A browser tool is a small piece of JavaScript that a user starts from a bookmark while VARIO Cloud is open. It runs inside the ERP tab, uses the session of the signed-in user and calls the REST API directly from the browser — no App, no server, no API credentials.

{% hint style="danger" %}
**Not a product feature — no support, no maintenance.**

This page describes a technique, not a supported interface. It relies on internal details of the ERP web client that can change with any release without notice. VARIO does not maintain, test or support tools built this way, and does not guarantee how long the technique keeps working or that it works in every browser. Use it at your own risk and only for tasks you could also do by hand.

For anything that has to run reliably or for many customers, build an [App](https://developer.vario-software.de/documentation/apps/introduction.md) or a [script](https://developer.vario-software.de/documentation/scripting/introduction.md).
{% endhint %}

## When does a browser tool fit?

| You need …                                                                 | Use                                                                                                             |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| A one-off or occasional bulk task a user starts by hand, with a small form | **Browser tool**                                                                                                |
| Something that runs on a schedule or reacts to changes in the ERP          | [Workflows](https://developer.vario-software.de/documentation/scripting/workflows.md)                           |
| Processing a CSV or JSON file row by row                                   | [Batch Processing](https://developer.vario-software.de/documentation/scripting/batch-processing.md)             |
| Menus, dialogs or widgets inside the ERP, its own permissions, other users | [App](https://developer.vario-software.de/documentation/apps/introduction.md)                                   |
| An external system that talks to VARIO Cloud                               | [REST API](https://developer.vario-software.de/documentation/rest-api/introduction.md) with its own credentials |

## How it works

### Why not just an HTML file with `fetch`?

The API accepts browser requests only from your own tenant address (`https://{subdomain}.vario.cloud`). A page opened from disk (`file://`) or from any other domain is rejected by CORS — the preflight request already fails with `403`. The origin is fixed per tenant and cannot be configured.

A bookmark whose address starts with `javascript:` gets around this: when the user clicks it on an open VARIO Cloud tab, the code runs in that tab, on the tenant origin, like code typed into the developer console.

### Authentication: reuse the session token

The ERP keeps the access token of the current tab in `sessionStorage` under the key `oauth2-access-token`. This key is an internal detail and may change.

* **Read the token fresh before every request.** Access tokens live [60 seconds](https://developer.vario-software.de/documentation/rest-api/authentication.md#token-lifetimes). Never copy it into a variable for later, `localStorage` or a file.
* **The ERP renews the token, not your tool.** The web client renews it before its own API calls and only while the user is active. During a long run the stored token can be expired for a while.
* **Handle expiry by waiting.** If the token has expired (check the `exp` claim of the JWT) or a request returns `401`/`403` without a JSON body, wait until a new token appears in `sessionStorage`, then repeat the request. Show the user that the tool is waiting. Stop after a reasonable time (for example two minutes) and report what was done so far.
* **Do not build your own login.** Storing a refresh or offline token, a password or a client secret in the browser makes it readable for every script on the tenant origin and outlives the user's logout.

### Calling the API

Requests go to the relative path `/api/vario/...` with the header `Authorization: Bearer <token>`. Everything else is the normal REST API:

* **Read in bulk with VQL** (`POST /cmn/computed-queries/execute`) instead of one `GET` per record. Page with the response headers `x-query-more-elements` and `x-query-next-offset`. Send `offset` only when it is greater than `0` — older versions reject `0`. See [VQL](https://developer.vario-software.de/documentation/fundamentals/vql.md) and [Pagination and filtering](https://developer.vario-software.de/documentation/rest-api/pagination-and-filtering.md).
* **Respect the** [**rate limit**](https://developer.vario-software.de/documentation/rest-api/rate-limiting.md)**.** Run at most a few write requests in parallel. On `429`, pause all requests, wait for `x-rate-limit-retry-after-seconds` or `Retry-After`, then retry the same request.
* **Show readable errors.** Validation errors come as `errors.fieldErrors.<field>[].message` and `errors.services[].message`, each with a `messageCode` and `messageParameters` rather than a text. Map the codes you expect to your own messages.

### Building the bookmark

Write the tool as one self-contained function and turn its source into the bookmark address:

```html
<a id="tool">My tool</a>
<script>
  function myTool() {
    var token = sessionStorage.getItem('oauth2-access-token');
    // build the form, read with VQL, write with fetch('/api/vario/...')
  }
  document.getElementById('tool').href =
    'javascript:' + encodeURIComponent('(' + myTool.toString() + ')();void 0');
</script>
```

Hand out this HTML file. The user opens it once and drags the link into the bookmarks bar; from then on they click the bookmark while VARIO Cloud is open.

Proven patterns:

* Render the tool in an overlay inside a **Shadow DOM** so ERP styles and your styles do not interfere. A second click on the bookmark closes it.
* Keep **everything in the one function** — no external scripts and no CDN. The content security policy of the ERP only allows scripts from the tenant origin.
* After every code change the user has to **drag the bookmark again**; the bookmark holds a copy of the code. To avoid this, [load the tool from a DMS public link](#loading-the-tool-from-a-dms-public-link).
* Check `location.hostname` at the start and tell the user to open VARIO Cloud first if the bookmark is clicked elsewhere.

## Loading the tool from a DMS public link

Instead of the whole tool, the bookmark can hold a small loader. The tool itself is an HTML file in the DMS of the tenant, shared with a public link. On every click the loader fetches the current file and shows it in an overlay. To update the tool, upload a new revision of the DMS document — the link and every user's bookmark stay the same.

{% hint style="warning" %}
Whoever can upload a revision of the DMS document decides what runs in the session of every user who clicks the bookmark, administrators included. Restrict write access to the document to a few trusted people. Read the security notes below before you use this.
{% endhint %}

### Why this works

* A public DMS link is served by the tenant itself: `https://{subdomain}.vario.cloud/api/vario/public/dms/{public-id}`. The loader uses the relative path, so the request stays on the tenant origin and CORS does not apply.
* The link belongs to the DMS document, not to a single file version. It always returns the current revision.
* The file is streamed directly with its stored content type, without a redirect to a storage URL. Reading it with `fetch` and `text()` works for any content type.
* The loader shows the HTML in an `iframe` with `srcdoc`. Such a frame inherits the tenant origin and the content security policy of the ERP, so inline scripts run, `sessionStorage` holds the same token and API calls work as from the bookmark itself.

### The loader

Replace `<public-id>` with the last part of the public link, for example `3f9a0c….html`:

```javascript
javascript:(async()=>{var I='vario-browser-tool',o=document.getElementById(I);if(o){o.remove();return}try{var r=await fetch('/api/vario/public/dms/<public-id>?t='+Date.now(),{cache:'no-store'});if(!r.ok)throw new Error('HTTP '+r.status);var f=document.createElement('iframe');f.id=I;f.srcdoc=await r.text();f.style.cssText='position:fixed;inset:4vh 4vw;width:92vw;height:92vh;z-index:2147483647;border:0;border-radius:12px;box-shadow:0 12px 48px rgba(0,0,0,.35);background:#fff';document.body.appendChild(f)}catch(e){alert('Tool could not be loaded: '+e.message)}})();
```

* `cache: 'no-store'` and the `t` parameter make sure every click gets the latest revision.
* A second click removes the overlay instead of loading again.
* Keep `%` out of the loader — browsers decode percent signs in `javascript:` addresses.

### The tool file

The tool is a normal, self-contained HTML page with inline styles and scripts. Inside the `srcdoc` frame, `location.origin` is `null`, so take the tenant address from the parent window:

```html
<script>
  const TENANT = window.frameElement ? window.parent.location : location;
  const API = TENANT.origin + '/api/vario';
  const token = () => sessionStorage.getItem('oauth2-access-token');

  async function vql(statement) {
    const response = await fetch(API + '/cmn/computed-queries/execute', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + token() },
      body: JSON.stringify({ statement, variableSubstitutionList: { variableSubstitutions: [] } }),
    });
    if (!response.ok) throw new Error('HTTP ' + response.status);
    return response.json(); // { definition: [{ attribute, displayName }], data: [...] }
  }

  function close() {
    window.frameElement.remove();
  }
</script>
```

Show a version number in the tool. After an upload, users and support can see at a glance which revision is running.

### Share settings

Create the public link in the DMS document under **Public links** → **Share**:

| Field                        | Value         | Why                                                                         |
| ---------------------------- | ------------- | --------------------------------------------------------------------------- |
| **Permitted number of uses** | **Unlimited** | Every click counts as one use. A one-time link stops after the first click. |
| **Validity in minutes**      | empty         | A link with a validity stops working when it expires.                       |

An expired, deleted or used-up link answers `404`; the loader shows it as `HTTP 404`.

### Developing without uploading

For development, a second bookmark opens a local file in the same kind of overlay. It uses the real session, so you test against real data — use a test tenant for anything that writes.

```javascript
javascript:(()=>{var I='vario-browser-tool',o=document.getElementById(I);if(o){o.remove();return}var p=document.createElement('input');p.type='file';p.accept='.html';p.onchange=async()=>{var f=document.createElement('iframe');f.id=I;f.srcdoc=await p.files[0].text();f.style.cssText='position:fixed;inset:4vh 4vw;width:92vw;height:92vh;z-index:2147483647;border:0;border-radius:12px;box-shadow:0 12px 48px rgba(0,0,0,.35);background:#fff';document.body.appendChild(f)};p.click()})();
```

To debug, open the developer tools and pick the `about:srcdoc` frame in the console's context selector.

### Limits of the loader

* **Tied to one tenant.** The file must be in the DMS of the tenant where the bookmark is clicked. Loading it from another tenant fails: the API only accepts browser requests from the own tenant origin, and the content security policy only allows scripts from there.
* **Publicly readable.** Anyone who knows the link can download the file. Put nothing confidential into it.
* **Every click writes.** Each request increases the share's usage counter.

## What you can build

| Idea                         | Example                                                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Bulk price changes**       | Raise all customer-specific prices of one customer by a percentage from a given date as new price entries.    |
| **Bulk updates from a list** | Paste article numbers and values from Excel, preview the changes, then apply them.                            |
| **Data quality checks**      | List articles without EAN, customers without payment terms, duplicate e-mail addresses — with a link to each. |
| **Quick exports**            | Run a VQL query and download the result as CSV.                                                               |
| **Context tools**            | Read the record ID from the current address and act on the open article, customer or document.                |
| **Checks before an import**  | Compare a pasted list against existing master data and show what would be new or changed.                     |
| **Guided multi-step tasks**  | A small wizard that combines several API calls a user would otherwise click through by hand.                  |

## Limits

* **Only while the tab is open.** No schedule, no reaction to events, no background processing.
* **Only the signed-in user's permissions.** The tool can do exactly what the user can do — not more, and not less.
* **Internal contracts.** The token key in `sessionStorage`, the token renewal of the web client and the page's content security policy, which currently allows inline scripts, are internal. Any release can change them and break every tool at once.
* **Browsers differ.** Managed company browsers may block `javascript:` bookmarks, browsers handle them under a page's security policy differently, very long bookmarks can hit limits, and tablets, phones and MDE devices usually have no bookmarks bar.
* **No ERP integration.** No menu entries, no dialogs, no widgets — the tool lives in its own overlay.
* **No own identity.** Changes are recorded as made by the user; nothing shows that a tool made them.
* **Central updates only with a loader.** A bookmark that holds the code keeps the version the user dragged into their bar. Central updates need the [DMS loader](#loading-the-tool-from-a-dms-public-link), and only within one tenant.

## Security

A browser tool runs with **all permissions of the signed-in user** inside the ERP. There is no sandbox and no way to restrict it to certain endpoints. Treat it like code typed into the developer console.

* **Only run code from a source you trust, and keep it readable.** A manipulated tool can read and change everything the user can, send data elsewhere, or show a fake "session expired" prompt on the genuine VARIO Cloud address. Do not minify the code so the customer's IT can review it, and provide a checksum of the file.
* **Never drag buttons from unknown sources into the bookmarks bar** — attackers use the same trick.
* **Use a user with minimal permissions**, never an admin account.
* **Store no credentials.** No tokens, passwords or secrets in the file or in browser storage.
* **Treat API data as untrusted.** Render it with `textContent`, never `innerHTML`, and validate values before you put them into a VQL statement.
* **Load code at runtime only from a source few people can change.** A bookmark that fetches its code from a wiki page, the DMS or a server lets whoever can edit that source run code in the session of every user — including admins. With the DMS loader, restrict write access to the document to a few trusted people and never load from another domain. If many users or customers depend on the tool, build an App.
* **Limit the blast radius of writes.** Show a preview, ask for confirmation, let the user cap the number of records, make a second run create no duplicates, and log the IDs you created so a run can be undone.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.vario-software.de/documentation/rest-api/browser-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
