> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/reference/functions/utilities/data-simulation.md).

# Data simulation

Random values, random records and fixed demo datasets, for laying out a page before any real data exists.

Data simulation invents values: random numbers and strings, random records such as people and addresses, and a few fixed demo datasets. Use it while you lay out a page, size a table or try an expression, and to provoke an error on purpose.

You find the functions under **Utilities** > **Data Simulation** in the Functions explorer. This class provides static functions only and does not require an instance. The code class name is `Simulator`.

{% hint style="info" %}

#### Not for simulating a machine

A signal that has to look like a real one over time, and a flow that is to keep working when the machine is connected, belong to the [Signal Simulator](https://docs.heisenware.com/reference/functions/utilities/signal-simulation.md): it feeds the real sink (an OPC UA server, a publish, a widget) with the shape of the real signal, so connecting the machine later changes an address, not the logic. Data simulation answers a value per call and knows nothing about the value before it.
{% endhint %}

## Basic values

### `randomInteger`

Returns a random whole number between a minimum and a maximum value (both inclusive).

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>min</code></td><td>The minimum possible integer. Default 0.</td><td>integer</td></tr><tr><td></td><td><code>max</code></td><td>The maximum possible integer. Default 99999.</td><td>integer</td></tr></tbody></table>

#### Output

Returns a random integer.

#### Example

```yaml
# options
min: 1
max: 10
```

### `randomNumber`

Returns a random floating-point number between a minimum and a maximum value.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>min</code></td><td>The minimum possible number. Default 0.</td><td>number</td></tr><tr><td></td><td><code>max</code></td><td>The maximum possible number (exclusive). Default 1.</td><td>number</td></tr></tbody></table>

#### Output

Returns a random floating-point number.

#### Example

```yaml
# options
min: 0
max: 100
```

### `randomString`

Generates a string of a specified length composed of random printable characters from `!` to `}` (character codes 33 to 125).

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td>The desired length of the string. Maximum is 2^20. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns a random string.

#### Example

```yaml
# length
12
```

### `randomText`

Generates random placeholder text in a lorem ipsum style to populate text fields and layout paragraphs.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="180">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>count</code></td><td>The number of units to generate. Default 1.</td><td>integer</td></tr><tr><td></td><td><code>units</code></td><td>The type of unit to generate: <code>words</code>, <code>sentences</code>, or <code>paragraphs</code>. Default <code>sentences</code>.</td><td>string</td></tr><tr><td></td><td><code>format</code></td><td>The output format, either <code>plain</code> or <code>html</code>. Default <code>plain</code>.</td><td>string</td></tr><tr><td></td><td><code>sentenceLowerBound</code></td><td>The minimum number of words per sentence.</td><td>integer</td></tr><tr><td></td><td><code>sentenceUpperBound</code></td><td>The maximum number of words per sentence.</td><td>integer</td></tr><tr><td></td><td><code>paragraphLowerBound</code></td><td>The minimum number of sentences per paragraph.</td><td>integer</td></tr><tr><td></td><td><code>paragraphUpperBound</code></td><td>The maximum number of sentences per paragraph.</td><td>integer</td></tr><tr><td></td><td><code>suffix</code></td><td>The line ending used between units. Defaults to the system line break.</td><td>string</td></tr></tbody></table>

#### Output

Returns a string of random text.

#### Examples

Example 1: Generate words

```yaml
# options
count: 5
units: words
```

Example 2: Generate paragraphs with HTML tags

```yaml
# options
count: 1
units: paragraphs
format: html
```

### `error`

Throws an execution error with a specified or random message to test error-handling logic.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>customMessage</code></td><td>An optional string to use as the error message. If omitted, the function uses a random lorem ipsum sentence.</td><td>string</td></tr></tbody></table>

#### Output

Throws an execution error.

## Complex structures

### `randomObject`

Generates an object with a random number of keys and values of various types.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>min</code></td><td>The minimum number of key-value pairs. Default 3.</td><td>integer</td></tr><tr><td></td><td><code>max</code></td><td>The maximum number of key-value pairs. Default 7.</td><td>integer</td></tr><tr><td></td><td><code>allowNesting</code></td><td>Lets a value be another random object or an array of objects. With false, every value is a number, a string, a text or an array of numbers, digits or strings. Default true.</td><td>boolean</td></tr></tbody></table>

#### Output

Returns a random object.

### `randomArrayOfIntegers`

Returns an array of random integers.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td>The length of the array. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of integers.

### `randomArrayOfNumbers`

Returns an array of random floating-point numbers.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td>The length of the array. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of numbers.

### `randomArrayOfDigits`

Returns an array of random single digits (0 to 9).

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td>The length of the array. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of integers.

### `randomArrayOfStrings`

Returns an array of random words.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td>The length of the array. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of strings.

### `randomArrayOfObjects`

Returns an array of random objects with flat, non-nested values.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>length</code></td><td></td><td>The length of the array. Default 10.</td><td>integer</td></tr><tr><td><code>options</code></td><td><code>min</code></td><td>The minimum number of entries per object. Default 3.</td><td>integer</td></tr><tr><td></td><td><code>max</code></td><td>The maximum number of entries per object. Default 7.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of objects.

## Specialized datasets

### `randomNumericData`

Generates numeric datasets using a Gaussian distribution to create realistic random fluctuations around a mean value, typically used for charts.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>nDataSets</code></td><td>The number of separate datasets to generate. Default 1.</td><td>integer</td></tr><tr><td></td><td><code>nDataPoints</code></td><td>The number of data points per dataset. Default 100.</td><td>integer</td></tr><tr><td></td><td><code>addTimeAxis</code></td><td>Adds a <code>date</code> field to each data point, incrementing by one second per point. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>timeFormat</code></td><td>The format of the <code>date</code> field when <code>addTimeAxis</code> is true: <code>epoch</code>, <code>iso</code>, <code>string</code>, or <code>object</code>. Default <code>epoch</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns a single array of numbers if `nDataSets` is 1 and `addTimeAxis` is false. Otherwise returns an array of objects with one key per dataset (`dataset0`, `dataset1`, ...) and, if enabled, the `date` field.

#### Examples

Example 1: Single dataset array

```yaml
# options
nDataSets: 1
nDataPoints: 5
```

Example 2: Multiple datasets with an ISO time axis

```yaml
# options
nDataSets: 2
nDataPoints: 3
addTimeAxis: true
timeFormat: iso
```

### `randomAddressData`

Returns an array of realistic address objects containing street, building number, city, state, and country fields.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>entries</code></td><td>The number of address objects to generate. Default 10.</td><td>integer</td></tr><tr><td></td><td><code>locale</code></td><td>The geographic locale format for the data: <code>DE</code> or <code>US</code>. Default <code>DE</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of address objects.

### `randomPersonData`

Returns an array of realistic personal identity records.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>entries</code></td><td>The number of person objects to generate. Default 10.</td><td>integer</td></tr><tr><td></td><td><code>locale</code></td><td>The regional locale format for names and data: <code>DE</code> or <code>US</code>. Default <code>DE</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of objects containing `avatar` (a base64-encoded random JPEG image), `title`, `firstName`, `lastName`, `company`, `phone`, `verified` (always `true`), `validUntil` (a random ISO date within the next 30 hours), and `note` (always empty).

### `randomChatData`

Generates an array of simple chat message objects with alternating `role` values (`You` and `ChatBot`) and random `content` to simulate a conversation.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>messages</code></td><td>The total number of chat messages to generate. Default 10.</td><td>integer</td></tr></tbody></table>

#### Output

Returns an array of chat message objects.

### `timelineData`

Generates randomized chronological timeline events spanning a specific duration and ending at the current time. This function supports tracking machine states, operator assignments, and work shifts.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="150">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>totalDurationHours</code></td><td>The total duration of the generated data in hours. Default 24.</td><td>number</td></tr><tr><td></td><td><code>includeState</code></td><td>Includes the machine state track (values <code>Running</code>, <code>Idle</code>, <code>Maintenance</code>, or <code>Error</code>). Default true.</td><td>boolean</td></tr><tr><td></td><td><code>includeOperator</code></td><td>Includes the operator assignment track. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>includeShift</code></td><td>Includes the work shift track. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>timeFormat</code></td><td>The timestamp format: <code>epoch</code>, <code>iso</code>, <code>string</code>, or <code>object</code>. Default <code>epoch</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of timeline event objects with a `timestamp` and the enabled tracks.

### `randomPointInCircle`

Generates a random GPS coordinate within a specified radius of a central point.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>distance</code></td><td></td><td>The radius of the circle in meters. Default 5000.</td><td>integer</td></tr><tr><td><code>coord</code></td><td><code>lat</code></td><td>The latitude of the central coordinate point. Default 53.5511 (Hamburg, Germany).</td><td>number</td></tr><tr><td></td><td><code>lng</code></td><td>The longitude of the central coordinate point. Default 9.9937 (Hamburg, Germany).</td><td>number</td></tr></tbody></table>

#### Output

Returns a coordinate object containing `lat` and `lng` properties.

### `energyData` / `populationDataset` / `marketValueDataset` / `australianMedalsDataset` / `populationVsAgeDataset` / `kanbanData`

Fixed demo datasets. They take no parameters, never change, and are there to give a chart, a data grid or a kanban board something recognizable to show while you arrange it.

#### Parameters

None.

#### Output

<table><thead><tr><th width="250">Function</th><th>Rows</th><th>Fields</th></tr></thead><tbody><tr><td><code>energyData</code></td><td>6</td><td><code>country</code>, <code>hydro</code>, <code>oil</code>, <code>gas</code>, <code>coal</code>, <code>nuclear</code>: energy per source and country.</td></tr><tr><td><code>populationDataset</code></td><td>6</td><td><code>country</code>, <code>y014</code>, <code>y1564</code>, <code>y65</code>: population by age band.</td></tr><tr><td><code>marketValueDataset</code></td><td>6</td><td>The same rows as <code>populationDataset</code>. The market value rows the name promises sit unused in the agent.</td></tr><tr><td><code>australianMedalsDataset</code></td><td>31</td><td><code>year</code>, <code>gold</code>, <code>silver</code>, <code>bronze</code>: Olympic medals from 1896 on.</td></tr><tr><td><code>populationVsAgeDataset</code></td><td>7</td><td><code>total1</code>…<code>total4</code>, <code>older1</code>…<code>older4</code>, <code>perc1</code>…<code>perc4</code>, <code>tag1</code>…<code>tag4</code>: up to four countries per row, for a bubble chart.</td></tr><tr><td><code>kanbanData</code></td><td>-</td><td>Answers nothing: the dataset behind it is missing.</td></tr></tbody></table>

{% hint style="warning" %}
`kanbanData` currently answers nothing and `marketValueDataset` answers the population rows. To fill a kanban board, write the columns and cards you want as a static value or keep them in a table.
{% endhint %}

## Execution control

### `longExecution`

Simulates a long-running asynchronous process by pausing execution for a specified duration.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>time</code></td><td>The simulated execution duration in milliseconds.</td><td>integer</td></tr></tbody></table>

#### Output

Returns the execution duration value after the specified delay.


---

# 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://docs.heisenware.com/reference/functions/utilities/data-simulation.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.
