# Script Modules

VARIO Cloud Script Modules are reusable JavaScript files stored directly in the ERP. Instead of duplicating logic across workflows and batch scripts, you write it once as a module and import it wherever needed. Modules are managed under **System → Scripts** in VARIO Cloud.

***

## Module Groups

Groups organize modules into named collections. Every group has a unique `name` and an optional `description`. Beyond organization, groups serve as **namespaces** — they become part of the import path and prevent name collisions between unrelated modules.

A module can belong to exactly one group or exist ungrouped at the top level.

***

## Import Mechanism

Any workflow or batch script in VARIO Cloud can import a module using standard ES module syntax. The import path determines how the module is resolved at runtime through a virtual module system:

```javascript
// Ungrouped module — looked up by name alone
import helpers from "my_module";
```

```javascript
// Grouped module — looked up by module name within the specified group
import helpers from "my_group/my_module";
```

Module resolution is virtual — there is no filesystem involved. When a script executes, the engine resolves the import path against all registered modules in the database at runtime.

{% hint style="warning" %}
Module names and group names must be **alphanumeric**. The combination of module name and group must be unique.
{% endhint %}

\---

## Domains

Each module has a **domain** that indicates its intended usage context. The domain is organizational — it helps categorize modules in the UI and signals to other developers what the module is designed for.

| Domain                        | Purpose                                    |
| ----------------------------- | ------------------------------------------ |
| `LIBRARY`                     | Shared modules importable by other scripts |
| `WORKFLOW_SCRIPT`             | Workflow script tasks                      |
| `WORKFLOW_SPLIT_GATEWAY`      | Workflow split gateways                    |
| `WORKFLOW_INTERMEDIATE_EVENT` | Workflow intermediate events               |
| `IMPORT_BATCH_PROCESSING`     | Batch processing scripts                   |
| `APP`                         | App-specific modules                       |
| `UNDEFINED`                   | Not yet categorized                        |

***

## Parameters

Modules can define **typed parameters** that make them configurable. Each parameter has a `name` and a `valueType` (`string`, `boolean`, or `number`). When a module is used in a workflow or batch script, the parameter values are passed at runtime and accessible inside the script via `ctx.parameters`.

This allows a single module to serve multiple use cases — for example, one print module configured with different templates or output formats depending on the context it runs in.

***

## Presettings

VARIO Cloud ships with **preset modules** — default implementations for common tasks like printing documents, sending emails, or assigning images to articles. These presets belong to the group **Vorgabe-Stapel-Skripte** and can be used out of the box.

Users can customize a preset module by editing its script. The original version is preserved internally, and the module can be **reset to its presetting** at any time to restore the default implementation.

***

## Built-in Modules

The scripting engine provides built-in modules that are always available and cannot be modified. These are the entry points for workflows and batch scripts:

| Module                         | Context                                                       |
| ------------------------------ | ------------------------------------------------------------- |
| `work_item_script`             | Workflow script tasks (`setAction`, `setGuard`, `setPrepare`) |
| `work_item_split_gateway`      | Workflow split gateways (`setSplit`)                          |
| `work_item_intermediate_event` | Workflow intermediate events                                  |
| `batch_script`                 | Batch processing (`setAction`, `setGuard`, `setAfterBatch`)   |

These are imported at the top of every script — e.g. `import workItem from "work_item_script"`. User-created modules are imported alongside them using the same syntax.

***

## Example

A reusable module that validates address fields:

```javascript
// Module: "address_validation" in group "validators"
export default {
  validatePostcode(country, postcode)
  {
    if (country === 'DE' && (!postcode || postcode.length !== 5))
    {
      throw 'German postal codes must be exactly 5 digits.';
    }
  },

  requireField(value, fieldName)
  {
    if (!value || (typeof value === 'string' && value.trim() === ''))
    {
      throw fieldName + ' is required.';
    }
  }
};
```

Importing it in a workflow:

```javascript
import workItem from "work_item_script";
import address from "validators/address_validation";

workItem.setAction((ctx) =>
{
  const account = ctx.availableInput.accountToSave;
  const addr = account.defaultAddress;

  address.requireField(addr.city, 'City');
  address.requireField(addr.postcode, 'Postal code');
  address.validatePostcode(addr.country.isoAlpha2, addr.postcode);
});
```

{% hint style="info" %}
The same module can be imported in batch scripts, other workflow scripts, or even other modules — write once, use everywhere.
{% endhint %}