> 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/scripting/batch-processing.md).

# Batch Processing

Process imported CSV or JSON data row by row, with full control over mapping and errors.

VARIO Cloud Batch Processing lets you run server-side JavaScript scripts that process imported data (CSV/JSON) row by row. Batch scripts are not limited to importing new records — they can also update existing entities in bulk, create related objects in mass, or combine both approaches. Since the full service layer is available, anything you can do in a workflow script can also be done per row in a batch script.

***

## Script Structure

Every VARIO Cloud batch script starts with an import and registers one or more callbacks:

```javascript
import batchAction from 'batch_script';

batchAction.setGuard((ctx) =>
{
  // Return false to skip this row
  return ctx.importData.ID !== '';
});

batchAction.setAction((ctx) =>
{
  // Process a single row — return true on success, false on failure
  const id = ctx.importData.ID;
  // ...
  return true;
});

batchAction.setAfterBatch((ctx) =>
{
  // Runs once after all rows are processed
  // ctx.importData is empty here — use ctx.importSession for accumulated data
});
```

### Callbacks

| Callback        | Runs                                                    | Return                                        | Purpose                                       |
| --------------- | ------------------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
| `setGuard`      | Per row                                                 | `boolean` — `false` skips the row             | Filter rows before processing                 |
| `setAction`     | Per row                                                 | `boolean` — `true` = success, `false` = error | Process a single import row                   |
| `setAfterBatch` | Once after all rows, only if at least one row succeeded | —                                             | Finalize the batch (e.g. trigger a print job) |

***

## The Context Object

Almost every callback in a VARIO Cloud batch script receives a context object `ctx` with the following properties:

| Property            | Description                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `ctx.importData`    | The current CSV/JSON row as a map. Keys are column headers.                                   |
| `ctx.importSession` | A shared map that persists across all rows in a run. Use it to accumulate state.              |
| `ctx.services`      | Same services as in workflow scripts (`vqlService`, `accountService`, `articleService`, etc.) |
| `ctx.parameters`    | Import parameters configured on the rule set                                                  |
| `ctx.errorMessages` | Accumulate error messages for the current row                                                 |

***

## Typical Pattern — Create or Update

Most VARIO Cloud batch scripts follow this pattern when importing data: check if the entity already exists via VQL, then create or update accordingly:

```javascript
import batchAction from 'batch_script';

batchAction.setAction((ctx) =>
{
  const number = ctx.importData.Artikelnummer;

  // Check if article already exists
  const existing = ctx.services.vqlService.queryAll(
    `SELECT id FROM article.query WHERE number = '${number}' LIMIT 1`
  );

  let article;

  if (!existing || existing.length === 0)
  {
    article = ctx.services.articleService.getNewDto();
    article.number = number;
  }
  else
  {
    article = ctx.services.articleService.readById(existing[0].id);
  }

  // Map import data to entity fields
  article.description = ctx.importData.Bezeichnung;
  article.custom.mygroup.FIELD = ctx.importData.CustomValue;

  // Persist
  if (!existing || existing.length === 0)
  {
    ctx.services.articleService.create(article);
  }
  else
  {
    ctx.services.articleService.update(article);
  }

  return true;
});
```

***

## Logging

Use `ctx.services.logger` the same way as in workflow scripts:

```javascript
ctx.services.logger.info('Article created: ' + number);
ctx.services.logger.warn('Missing field, skipping row.');
ctx.services.logger.error('Failed to create article.');
```

{% hint style="info" %}
Each row is processed in its own transaction. Workflows and webhooks can be suppressed during batch processing via the import configuration.
{% endhint %}

{% hint style="info" %}
**Develop with an AI assistant.** Through the VARIO Cloud MCP server an assistant can list batch templates and their import target fields, start a run with preview and violations, and read the result of a run. It also knows the batch scripting conventions from a built-in guide. See [AI Assistants (MCP)](https://developer.vario-software.de/documentation/ai-assistants-mcp.md).
{% endhint %}

***

## Scheduled Execution

VARIO Cloud batch imports can be scheduled to run automatically using Cron expressions. Open a script processing and use the clock icon **Automatisiert ausführen** to create a scheduled processing, then set the Cron expression in **System → Task-Manager** and activate the task there (it is created inactive). The system triggers the processing at the defined intervals without manual interaction. Scheduling requires the workflow licence.

A scheduled processing reads its rows from one of two data sources:

| Data source | Rows                                                    | Typical use                                                                               |
| ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Datei**   | A file stored in the DMS (CSV, JSON, TXT, XLSX, XML)    | Recurring file imports                                                                    |
| **Abfrage** | The records of a list selection, evaluated at every run | Nightly updates of matching records, e.g. "all customers", "articles without description" |

There is no FTP, SFTP or URL source. To fetch data from an external system, call its API with the [HTTP client](https://developer.vario-software.de/documentation/scripting/http-and-secrets.md) inside the script. A selection that returns a single record works as a plain timer for such polling jobs, see [Use Cases](https://developer.vario-software.de/documentation/scripting/use-cases.md#pull-leads-from-a-web-form).

Files from an FTP or SFTP server can reach a script through **VARIO Local Link**. Local Link watches a local folder and uploads new files to the DMS automatically. Point it at a folder that receives the FTP files (for example a directory synchronised with the FTP server) and choose the DMS type **Datenimport** with a linked automated import. Every uploaded file is then added to that import, and your batch script processes it.


---

# 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/scripting/batch-processing.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.
