JobRouter Developer Manual

https://docs.jobrouter.com/2026.1/de/developer
Admin
The JobRouter Developer Manual provides comprehensive guidance on building custom dashboard widgets,...
Tokens:98,038
Snippets:786
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Starting a Process with Process and Sub-table Data

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_vorgangstarten.html

This example demonstrates how to start a JobRouter process and pass data for both main process fields and nested sub-tables. It includes setting a step, summary, escalation date, and populating fields and attachments for a sub-table.

```php
<?php

// User has already been authenticated
// Define process data
$input = [
    [
        'name' => 'step',
        'contents' => '1',
    ],
    [
        'name' => 'summary', // Process subject
        'contents' => 'Vorgang gestartet über REST API',
    ],
    [
        'name' => 'step_escalation_date', // Step escalation
        'contents' => '2017-10-12T11:00:00+01:00',
    ],
    [
        'name' => 'processtable[fields][0][name]',
        'contents' => 'INVOICENR',
    ],
    [
        'name' => 'processtable[fields][0][value]',
        'contents' => 'IN02984',
    ],
    [
        'name' => 'processtable[fields][1][name]',
        'contents' => 'INVOICE_DATE',
    ],
    [
        'name' => 'processtable[fields][1][value]',
        'contents' => '2017-08-29T00:00:00+01:00',
    ],
    [
        'name' => 'processtable[fields][2][name]',
        'contents' => 'AMOUNT',
    ],
    [
        'name' => 'processtable[fields][2][value]',
        'contents' => '12000.78',
    ],
    [
        'name' => 'processtable[fields][3][name]',
        'contents' => 'INVOICE_FILE',
    ],
    [
        'name' => 'processtable[fields][3][value]',
        'contents' => fopen('/path/to/invoice/file.pdf', 'r'),
    ],
    [
        'name' => 'subtables[0][name]',
        'contents' => 'SINVOICE_ATTACHMENTS' // Name of a sub-table
    ],
    [
        'name' => 'subtables[0][rows][0][fields][0][name]',
        'contents' => 'ATT_IN_DATE', // first row of the sub-table begins here
    ],
    [
        'name' => 'subtables[0][rows][0][fields][0][value]',
        'contents' => '2017-09-02T14:30:00+01:00',
    ],
    [
        'name' => 'subtables[0][rows][0][fields][1][name]',
        'contents' => 'ATT_FILE',
    ],
    [
        'name' => 'subtables[0][rows][0][fields][1][value]',
        'contents' => fopen('/path/to/attachment/note.txt', 'r'),
    ],
    [
        'name' => 'subtables[0][rows][1][fields][0][name]',
        'contents' => 'ATT_IN_DATE', // second row begins here
    ],
    [
        'name' => 'subtables[0][rows][1][fields][0][value]',
        'contents' => '2017-09-06T11:28:43+01:00',
    ],
];

// The actual API call would follow, using a client like GuzzleHTTP
// Example: $client->post('/application/incidents/yourProcessName', ['multipart' => $input]);
?>
```

--------------------------------

### Start Process Incident with Process and Sub-table Data

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_vorgangstarten.html=

This example demonstrates how to start a process incident by sending data for both the main process fields and nested sub-tables. It uses the Guzzle HTTP client to make a POST request to the /application/incidents/:processName endpoint.

```php
<?php
// Benutzer wurde bereits authentifiziert
// Vorgangsdaten definieren
$input = [
[
'name' => 'step',
'contents' => '1',
],
[
'name' => 'summary', // Prozessbetreff
'contents' => 'Vorgang gestartet über REST API',
],
[
'name' => 'step_escalation_date', // Schritteskalation
'contents' => '2017-10-12T11:00:00+01:00',
],
[
'name' => 'processtable[fields][0][name]',
'contents' => 'INVOICENR',
],
[
'name' => 'processtable[fields][0][value]',
'contents' => 'IN02984',
],
[
'name' => 'processtable[fields][1][name]',
'contents' => 'INVOICE_DATE',
],
[
'name' => 'processtable[fields][1][value]',
'contents' => '2017-08-29T00:00:00+01:00',
],
[
'name' => 'processtable[fields][2][name]',
'contents' => 'AMOUNT',
],
[
'name' => 'processtable[fields][2][value]',
'contents' => '12000.78',
],
[
'name' => 'processtable[fields][3][name]',
'contents' => 'INVOICE_FILE',
],
[
'name' => 'processtable[fields][3][value]',
'contents' => fopen('/path/to/invoice/file.pdf', 'r'),
],
[
'name' => 'subtables[0][name]',
'contents' => 'SINVOICE_ATTACHMENTS' // Name einer Untertabelle
],
[
'name' => 'subtables[0][rows][0][fields][0][name]',
'contents' => 'ATT_IN_DATE',
],
[
'name' => 'subtables[0][rows][0][fields][0][value]',
'contents' => '2017-09-02T14:30:00+01:00',
],
[
'name' => 'subtables[0][rows][0][fields][1][name]',
'contents' => 'ATT_FILE',
],
[
'name' => 'subtables[0][rows][0][fields][1][value]',
'contents' => fopen('/path/to/attachment/note.txt', 'r'),
],
[
'name' => 'subtables[0][rows][1][fields][0][name]',
'contents' => 'ATT_IN_DATE',
],
[
'name' => 'subtables[0][rows][1][fields][0][value]',
'contents' => '2017-09-06T11:28:43+01:00',
],
[
'name' => 'subtables[0][rows][1][fields][1][name]',
'contents' => 'ATT_FILE',
],
[
'name' => 'subtables[0][rows][1][fields][1][value]',
'contents' => fopen(
'/path/to/another/attachment/confirmation.pdf', 'r'
),
],
];
try {
// Vorgang mit den oben definierten Daten starten
// (als multipart/form-data)
$response = $client->request('POST', 'application/incidents/invoice',
[
'multipart' => $input,
]
);
// Antwort bearbeiten
echo "Status code: " . $response->getStatusCode() . "\n";
$body = $response->getBody();

```

--------------------------------

### startProcess

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?webservice_startprocess.html=

Starts a new process instance for a given process. It can be specified whether the instance should start synchronously or asynchronously. The call returns a unique identifier for the started process instance. For a synchronous start, the process ID of the new instance is returned. For an asynchronous start, the task ID of the new instance is returned.

```APIDOC
## startProcess

### Description
Starts a new process instance for a given process. It can be specified whether the instance should start synchronously or asynchronously. The call returns a unique identifier for the started process instance. For a synchronous start, the process ID of the new instance is returned. For an asynchronous start, the task ID of the new instance is returned.

### Method
POST

### Endpoint
/startProcess

### Parameters
#### Request Body
- **soProcessInstance** (ServiceObject_ProcessInstance) - Required - Process instance object
- **soStepInstance** (ServiceObject_StepInstance) - Required - Step instance object
- **asynchronous** (bool) - Optional - Flag indicating if the process start should be asynchronous. Defaults to false.
- **taskId** (string) - Optional - Unique identifier for asynchronous process start. If no value is passed, a task ID will be automatically generated.

### Response
#### Success Response (200)
- **string** - Process ID for synchronous start, or Task ID for asynchronous start of the process.
```

--------------------------------

### List Available Start Steps

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_boxen.html=

Retrieves a list of all available steps that can be initiated by the authenticated user.

```APIDOC
## GET /application/workitems/start

### Description
Lists available start steps for the authenticated user.

### Method
GET

### Endpoint
/application/workitems/start

### Response
#### Success Response (200)
- The response will be a JSON object containing a list of available start steps. The exact structure of the work items will be similar to the general inbox, with process-specific details.

### Request Example
```http
GET /application/workitems/start HTTP/1.1
Host: example.org
Authorization: Bearer YOUR_ACCESS_TOKEN
```
```

--------------------------------

### Example: Fetching Process Inbox Items

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_referenz.html

This example demonstrates how to call a specific route to retrieve process inbox items. It shows the full URL construction, including placeholders for process name, version, and inbox ID.

```http
http://example.org/jobrouter/api/rest/v2/application/workitems/urlaub_beantragen/1/42
```

--------------------------------

### Start and End Session with cURL

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_authentifizierung-mit-session-id.html

Demonstrates how to start a session by sending credentials and then end the session using cURL. It includes setting headers, handling responses, and managing cookies. Note that a curl_reset might be necessary before subsequent requests.

```bash
$data = '{
"username": "jdoe",
"password": "2r5iq|!O%{o@?ApR1q%8"
}';
$headers = [
'Accept: application/json',
'Content-Type: application/json',
];
$url = 'http://example.org/jobrouter/api/rest/v2/application/sessions';
// Sitzung beginnen (Benutzer authentifizieren)
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POST, 1);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_COOKIEJAR, 'path/to/cooke/file.cookie');
$response = curl_exec($curlHandle);
$code = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
if ($code === 201) {
$response = json_decode($response, true);
$sessionId = $response['sessions'][0]['sessionId'];
} else {
echo 'Fehler beim Authentifizieren: ' . $code;
var_export($response);
}
// ... weitere Aktionen hier ...
// Bitte beachten Sie, dass eventuell ein curl_reset-Aufruf notwendig ist,
// um die cURL-Optionen vor der nächsten Anfrage zurückzusetzen!
// Sitzung beenden
curl_reset($curlHandle);
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cooke/file.cookie');
curl_exec($curlHandle);
curl_close();
```

--------------------------------

### Fetch Inbox Steps using cURL

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_boxen.html

This cURL command-line example shows how to retrieve work items from the general inbox. It includes setting the URL, enabling return transfer, specifying the GET request, and using a cookie file for authentication. Error handling for non-200 status codes is also included.

```bash
// Benutzer wurde bereits authentifiziert
curl_setopt($curlHandle, CURLOPT_URL,
'http://example.org/jobrouter/api/rest/v2/application/workitems/inbox');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cooke/file.cookie');
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
if ($statusCode == 200) {
$boxData = json_decode($response, true);
echo "Anzahl Schritte in der Eingangsbox: ";
echo $boxData['meta']['pagination']['total'] . "\n\n";
foreach ($boxData['workitems'] as $item) {
echo "Prozessname: " . $item['jrprocessname'] . "\n";
echo "Schrittbezeichnung: " . $item['jrsteplabel'] . "\n";
echo "Workflow-ID: " . $item['jrworkflowid'] . "\n\n";
}
} else {
echo "Fehler beim Ausführen: Code - " . $statusCode . ", ";
echo "Response: " . var_export($response, true);
}
```

--------------------------------

### Initialize Client and Send GET Request

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_allgemeines-zu-guzzlehttp.html=

Initializes the GuzzleHttp client with a base URI and cookie support, then sends a GET request and retrieves the response body. Handles potential exceptions during the request.

```php
$client = new Client(
[
'base_uri' => 'http://example.org/jobrouter/api/rest/v2/',
'cookies' => true
]
);
try {
// Anfrage senden
$response = $client->get(
'http://example.org/jobrouter/api/rest/v2/path/to/some/get/route'
);
$body = $response->getBody();
// Weitere Informationen aus der Antwort auslesen ... 
} catch (Exception $e) {
echo "Fehler bei der Ausführung: " . $e->getMessage();
}
```

--------------------------------

### List Inbox Work Items for the Main Instance

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_instanzen.html

This example demonstrates how to call the API for the main JobRouter instance when no specific instance number is required.

```APIDOC
## GET /api/rest/v2/application/workitems/inbox

### Description
Retrieves a list of work items in the inbox for the authenticated user from the main JobRouter instance.

### Method
GET

### Endpoint
/api/rest/v2/application/workitems/inbox

### Response
#### Success Response (200)
- **workItems** (array) - A list of work items available in the inbox.

### Response Example
{
  "workItems": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Task B",
      "status": "In Progress"
    }
  ]
}
```

--------------------------------

### Preparing Data for Workflow Start

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_vorgangstarten.html=

Prepares an array of data, including file uploads and process fields, to initiate a workflow. Uses CURLFile for file attachments.

```php
$mainFile = new CURLFile('/path/to/invoice/file.pdf');
$fileForFirstRow = new CURLFile('/path/to/invoice/myTest1.txt');
$fileForSecondRow = new CURLFile('/path/to/invoice/myTest2.txt');
$inputData = [
'step' => '1',
'initiator' => 'REST',
'summary' => 'Vorgang gestartet über REST API', // Prozessbetreff
'step_escalation_date' => '2017-10-12T11:00:00+01:00', // Schritteskalation
'processtable[fields][0][name]' => 'INVOICENR',
'processtable[fields][0][value]' => 'IN02984',
'processtable[fields][1][name]' => 'INVOICE_DATE',
'processtable[fields][1][value]' => '2017-08-29T00:00:00+01:00',
'processtable[fields][2][name]' => 'AMOUNT',
'processtable[fields][2][value]' => '12000.78',
'processtable[fields][3][name]' => 'INVOICE_FILE',
'processtable[fields][3][value]' => $mainFile,
'subtables[0][name]' => 'SINVOICE_ATTACHMENTS', // Name der Untertabelle
// hier beginnt die erste Zeile der Untertabelle
'subtables[0][rows][0][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][0][fields][0][value]' => '2017-09-02T14:30:00+01:00',
'subtables[0][rows][0][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][0][fields][1][value]' => $fileForFirstRow,
// hier beginnt die zweite Zeile
'subtables[0][rows][1][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][1][fields][0][value]' => '2017-09-06T11:28:43+01:00',
'subtables[0][rows][1][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][1][fields][1][value]' => $fileForSecondRow,
];
```

--------------------------------

### Start Incident with cURL (PHP)

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_vorgangstarten.html

Starts a new incident using cURL, defining main and sub-table data, including file attachments. Processes the response to extract incident and workflow IDs or error information.

```PHP
// Benutzer wurde bereits authentifiziert
// Vorgangsdaten definieren
$mainFile = new CURLFile('/path/to/invoice/file.pdf');
$fileForFirstRow = new CURLFile('/path/to/invoice/myTest1.txt');
$fileForSecondRow = new CURLFile('/path/to/invoice/myTest2.txt');
$inputData = [
'step' => '1',
'initiator' => 'REST',
'summary' => 'Vorgang gestartet über REST API', // Prozessbetreff
'step_escalation_date' => '2017-10-12T11:00:00+01:00', // Schritteskalation
'processtable[fields][0][name]' => 'INVOICENR',
'processtable[fields][0][value]' => 'IN02984',
'processtable[fields][1][name]' => 'INVOICE_DATE',
'processtable[fields][1][value]' => '2017-08-29T00:00:00+01:00',
'processtable[fields][2][name]' => 'AMOUNT',
'processtable[fields][2][value]' => '12000.78',
'processtable[fields][3][name]' => 'INVOICE_FILE',
'processtable[fields][3][value]' => $mainFile,
'subtables[0][name]' => 'SINVOICE_ATTACHMENTS', // Name der Untertabelle
// hier beginnt die erste Zeile der Untertabelle
'subtables[0][rows][0][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][0][fields][0][value]' => '2017-09-02T14:30:00+01:00',
'subtables[0][rows][0][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][0][fields][1][value]' => $fileForFirstRow,
// hier beginnt die zweite Zeile
'subtables[0][rows][1][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][1][fields][0][value]' => '2017-09-06T11:28:43+01:00',
'subtables[0][rows][1][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][1][fields][1][value]' => $fileForSecondRow,
];
curl_setopt($curlHandle, CURLOPT_URL,
'http://example.org/jobrouter/api/rest/v2/application/incidents/invoice');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POST, 1);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $inputData);
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cookie/file.cookie');
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
if ($statusCode == 200) {
$incidentData = json_decode($response, true);
echo "Incident: " . $incidentData['incidents'][0]['incidentnumber'] . "\n";
echo "Workflow-ID: " . $incidentData['incidents'][0]['workflowId'] . "\n";
} else {
echo "Fehler beim Ausführen: Code - " . $statusCode . ", ";
echo "Response: " . var_export($response, true);
}
// Benutzer-Session beenden

```

--------------------------------

### checkProcessStart

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?webservice_checkprocessstart.html=

Queries the status of an asynchronously started process using its Task ID. If no Task ID is provided, one will be generated automatically.

```APIDOC
## checkProcessStart

### Description
Queries the status of an asynchronously started process using its Task ID. If no Task ID is provided, one will be generated automatically.

### Method
POST (Assumed, as it's a method call that likely modifies or retrieves state based on input)

### Endpoint
/checkProcessStart

### Parameters
#### Query Parameters
- **taskId** (string) - Optional - Unique identifier for the asynchronous process start. If not provided, a Task ID will be automatically generated.

### Response
#### Success Response (200)
- **ProcessStartInfo** (ServiceObject_ProcessStartInfo) - An object containing the current process start information.
```

--------------------------------

### checkProcessStart

Source: https://docs.jobrouter.com/2026.1/de/developer/webservice_checkprocessstart.html

Checks the current status of a newly started asynchronous process using the Task ID provided during initiation. It returns a ProcessStartInfo object containing the status.

```APIDOC
## checkProcessStart

### Description
Retrieves the status of an asynchronously started process using its unique Task ID.

### Method
POST (Assumed, as status retrieval often involves sending an identifier)

### Endpoint
/webservice/checkProcessStart

### Parameters
#### Query Parameters
- **taskId** (string) - Optional - Unique identifier for the asynchronous process start. If not provided, a Task ID will be automatically generated.

### Response
#### Success Response (200)
- **ServiceObject_ProcessStartInfo** (object) - An object containing the process start information and its current status.
```

--------------------------------

### Get Current Username Example

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?dashboard_getcurrentusername.html=

This snippet demonstrates how to retrieve the currently logged-in user's username using the deprecated getCurrentUsername function. It is useful for conditional logic, such as authorizing widgets.

```php
$currentUsername = $this->getCurrentUsername();
```

--------------------------------

### GET /application/users/:username/archives/:archive

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_archiveigenschaften-ermitteln.html=

Retrieves detailed properties of a specified archive, including its index field definitions. The archive can be identified by its database table name or GUID. The request must be made within a user's context, and only users with access to the archive can retrieve this information.

```APIDOC
## GET /application/users/:username/archives/:archive

### Description
Retrieves detailed properties of a specified archive, including its index field definitions. The archive can be identified by its database table name or GUID. The request must be made within a user's context, and only users with access to the archive can retrieve this information.

### Method
GET

### Endpoint
/application/users/:username/archives/:archive

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user making the request.
- **archive** (string) - Required - The database table name or GUID of the archive to query.

### Response
#### Success Response (200)
- **users** (object) - Contains archive information.
  - **archives** (array) - A list of archives.
    - **name** (string) - The name of the archive.
    - **indexFieldDefinitions** (array) - A list of index field definitions for the archive.
      - **name** (string) - The name of the index field.
      - **required** (boolean) - Indicates if the index field is required.

### Response Example
```json
{
  "users": {
    "archives": [
      {
        "name": "Invoices",
        "indexFieldDefinitions": [
          {
            "name": "deadline",
            "required": true
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Create Dataset using cURL

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_anlegen_und_bearbeiten_von_dat.html

This example demonstrates creating a dataset via cURL. It includes setting headers, the request method, and the JSON payload. Ensure the cookie file path is correct.

```php
<?php
// Benutzer wurde bereits authentifiziert
// Datensatz definieren
$data = [
'dataset' => [
'sname' => 'Acme Corp.',
'sadress' => 'Acme Rd. 12',
'sdate' => '2017-09-03T13:22:45+01:00',
'sphone' => '076-343-5226',
'srating' => 6
],
];
$headers = [
'Accept: application/json',
'Content-Type: application/json',
];
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);
curl_setopt(
$curlHandle,
'http://example.org/jobrouter/api/rest/v2/application/jobdata/' .
'tables/2076E38C-3EC0-234E-EFFD-E15F14879CB1/datasets'
);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POST, 1);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cooke/file.cookie');
// Datensatz anlegen
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
if ($statusCode == 200) {
// Antwort anzeigen
$data = json_decode($response, true);
echo "Datensatz-ID: " . $data['datasets'][0]['jrid'] . "\n";
} else {
echo "Fehler beim Ausführen: Code - " . $statusCode . ", ";
echo "Response: " . var_export($response, true);
}
// Benutzer-Session beenden
?>

```

--------------------------------

### Handlebars Unless Block Example

Source: https://docs.jobrouter.com/2026.1/de/developer/dashboard_unless_block.html

Use the unless block to render content when a condition is false. This example shows rendering 'Unknown Author' when the 'author' object is not present or empty.

```handlebars
<div>
{{#unless author}}
<h1>Unknown Author</h1>
{{else}}
<h1>{{author.firstName}} {{author.lastName}}</h1>
{{/unless}}
</div>
```

--------------------------------

### Sitzung beginnen

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_authentifizierung-mit-session-id.html=

Fordert eine Session-ID an, indem Benutzername und Passwort im HTTP-Request-Body an den Endpunkt `/application/sessions` gesendet werden. Bei Erfolg wird eine Session-ID zurückgegeben, die für nachfolgende Anfragen verwendet wird. Bei fehlgeschlagener Authentifizierung wird ein 401-Statuscode zurückgegeben.

```APIDOC
## POST /application/sessions

### Description
Beginnt eine Benutzersitzung und fordert eine Session-ID an.

### Method
POST

### Endpoint
/application/sessions

### Parameters
#### Request Body
- **username** (string) - Required - Der Benutzername für die Authentifizierung.
- **password** (string) - Required - Das Passwort für die Authentifizierung.

### Request Example
```json
{
  "username": "jdoe",
  "password": "2r5iq|!O%{o@?ApR1q%8"
}
```

### Response
#### Success Response (201)
- **sessions** (array) - Enthält eine Liste von Session-Objekten.
  - **userName** (string) - Der Benutzername der Sitzung.
  - **sessionId** (string) - Die eindeutige ID der Sitzung.
  - **loginTime** (string) - Der Zeitpunkt des Logins.
  - **lastAction** (string) - Der Zeitpunkt der letzten Aktion.
  - **ip** (string) - Die IP-Adresse, von der die Sitzung gestartet wurde.
  - **sessionType** (string) - Der Typ der Sitzung (kann null sein).
  - **sessionName** (string) - Der Name der Sitzung (z.B. PHPSESSID).

#### Response Example
```json
{
  "sessions": [
    {
      "userName": "jdoe",
      "sessionId": "ad21c2d0bf7e4bc130943e2004fdce03",
      "loginTime": "2017-08-25T14:20:18+02:00",
      "lastAction": "2017-08-25T14:20:18+02:00",
      "ip": "2a02:8071:891:6000:f16b:8d12:d771:e057",
      "sessionType": null,
      "sessionName": "PHPSESSID"
    }
  ]
}
```

#### Error Response (401)
- **Message**: User is not authorized
```

--------------------------------

### Executing cURL Request to Start Workflow

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_vorgangstarten.html=

Configures and executes a cURL POST request to the JobRouter API to start a workflow. It sets the URL, POST data, and cookie file for authentication.

```php
curl_setopt($curlHandle, CURLOPT_URL,
'http://example.org/jobrouter/api/rest/v2/application/incidents/invoice');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POST, 1);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $inputData);
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cookie/file.cookie');
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
```

--------------------------------

### Handlebars Unless Block Example

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?dashboard_unless_block.html=

Use the unless block to display content when the specified condition evaluates to false. This example shows rendering an 'Unknown Author' heading when the 'author' object is not present or empty.

```html
<div>
{{#unless author}}
<h1>Unknown Author</h1>
{{else}}
<h1>{{author.firstName}} {{author.lastName}}</h1>
{{/unless}}
</div>
```

```json
{
author: {
}
}
```

--------------------------------

### Sitzung beginnen

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_authentifizierung-mit-session-id.html

Fordert eine Session-ID an, indem Benutzername und Passwort im HTTP-Request-Body an die /application/sessions POST-Route gesendet werden. Eine sichere Verbindung (HTTPS) wird empfohlen, da das Passwort im Klartext übertragen wird.

```APIDOC
## POST /application/sessions

### Description
Beginnt eine neue Sitzung und authentifiziert den Benutzer.

### Method
POST

### Endpoint
/application/sessions

### Parameters
#### Request Body
- **username** (string) - Required - Der Benutzername für die Authentifizierung.
- **password** (string) - Required - Das Passwort für die Authentifizierung.

### Request Example
```json
{
  "username": "jdoe",
  "password": "2r5iq|!O%{o@?ApR1q%8"
}
```

### Response
#### Success Response (200)
- **sessions** (array) - Enthält Details zur erstellten Sitzung.
  - **userName** (string) - Der authentifizierte Benutzername.
  - **sessionId** (string) - Die eindeutige ID der Sitzung.
  - **loginTime** (string) - Der Zeitpunkt des Logins.
  - **lastAction** (string) - Der Zeitpunkt der letzten Aktion.
  - **ip** (string) - Die IP-Adresse des Clients.
  - **sessionType** (string) - Der Typ der Sitzung (kann null sein).
  - **sessionName** (string) - Der Name der Sitzung (z.B. PHPSESSID).

#### Response Example
```json
{
  "sessions": [
    {
      "userName": "jdoe",
      "sessionId": "ad21c2d0bf7e4bc130943e2004fdce03",
      "loginTime": "2017-08-25T14:20:18+02:00",
      "lastAction": "2017-08-25T14:20:18+02:00",
      "ip": "2a02:8071:891:6000:f16b:8d12:d771:e057",
      "sessionType": null,
      "sessionName": "PHPSESSID"
    }
  ]
}
```

#### Error Response (401)
- **Message**: User is not authorized (wenn die Anmeldedaten falsch sind).
```

--------------------------------

### Sitzung beginnen und beenden mit GuzzleHttp

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_authentifizierung-mit-session-id.html=

Beispiel für die Authentifizierung eines Benutzers durch Anfordern einer Session-ID und anschließendes Beenden der Sitzung mit der GuzzleHttp-Bibliothek in PHP. Stellt sicher, dass die GuzzleHttp-Client-Instanz bereits initialisiert ist.

```php
// Client wurde bereits initialisiert
try {
// Sitzung beginnen (Benutzer authentifizieren)
$response = $client->post('application/sessions', [
'json' => [
'username' => 'jdoe',
'password' => '2r5iq|!O%{o@?ApR1q%8',
],
]);
// Session-ID ermitteln
$sessionData = json_decode($response->getBody(), true);
$sessionId = $sessionData['sessions'][0]['sessionId'];
echo "Session ID: " . $sessionId;
// ... weitere Aktionen hier ...
// Sitzung beenden
$response = $client->delete('application/sessions');
} catch(Exception $e) {
echo "Fehler: " . $e->getMessage();
}
```

--------------------------------

### PHP: Systemaktivität als abgeschlossen markieren

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?developer_beispiel_aendern_step_status.html=

Dieses PHP-Codebeispiel zeigt, wie die Methode `markActivityAsCompleted` innerhalb einer `csvSystemActivity`-Klasse aufgerufen wird, um eine Systemaktivität als abgeschlossen zu markieren. Dies ist notwendig, um die Aktivität in den Prozessverlauf zu integrieren und den Workflow fortzusetzen oder zu beenden.

```php
<?php
class csvSystemActivity extends AbstractSystemActivityAPI
{
...
private $fieldDelimiter;
private $csvFile;
private $csvFilePointer;
private $numberOfRows;
protected function exportCsv()
{
$this->increaseSystemActivityCalls();
$this->debug('exportCsv start');
$this->loadGlobalSettings();
$this->openCsvFile('w');
$this->debug('executeMethodForSubtable for '. $this->getFixSubtableName());
$this->initLineCounter();
$this->executeMethodForSubtable('writeSubtableLineIntoFile', $this->getFixSubtableName());
$this->storeOutputParameter('targetFile', $this->csvFile);
$this->storeOutputParameter('numberOfRows', $this->numberOfRows);
$this->markActivityAsCompleted();
}
protected function increaseSystemActivityCalls()
{
$systemActivityCalls = $this->getSystemActivityVar('systemActivityCalls', 0);
$systemActivityCalls++;
$this->debug('system activity calls: ' . $systemActivityCalls);
$this->setSystemActivityVar('systemActivityCalls', $systemActivityCalls);
}
protected function loadGlobalSettings()
{
$this->fieldDelimiter = $this->resolveInputParameter('fieldDelimiter');
}
protected function openCsvFile($mode)
{
$this->csvFile = $this->getTempPath() . DIRECTORY_SEPARATOR . 'test.csv';
$this->debug('csvFile: '.$this->csvFile);
$this->csvFilePointer = fopen($this->csvFile, $mode);
}
protected function initLineCounter()
{
$this->numberOfRows = 0;
}
protected function writeSubtableLineIntoFile()
{
$this->debug('writeSubtableLineIntoFile for '. $this->getFixSubtableName());
$subtableValues = $this->resolveInputParameterListValues('fieldList');
$csvLine = implode($this->fieldDelimiter, $subtableValues)."\r\n";
fwrite($this->csvFilePointer, $csvLine);
$this->numberOfRows++;
}
}

```

--------------------------------

### Basic cURL Request Workflow

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_allgemeines-zu-curl.html=

This snippet demonstrates the essential steps for making a GET request using cURL: initializing the handle, setting the URL and return transfer option, executing the request, checking for errors via HTTP status code, and closing the session.

```php
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL,
'http://example.org/jobrouter/api/rest/v2/path/to/some/get/route');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_COOKIEJAR, 'path/to/cooke/file.cookie');
$response = curl_exec($curlHandle);
$code = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
if ($code >= 400) {
echo "Fehler bei der Ausführung";
}
curl_close($curlHandle);
```

--------------------------------

### Get Accessible Archives

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_archive_ermitteln.html

Retrieves a list of JobRouter archives that the specified user has access to. The user is identified by their username.

```APIDOC
## GET /application/users/:username/archives

### Description
Fetches a list of JobRouter archives accessible to a specific user. The response includes the archive's name, GUID, and database table name.

### Method
GET

### Endpoint
/application/users/:username/archives

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user whose archives are to be retrieved.

### Response
#### Success Response (200)
- **users** (object) - Contains archive information.
  - **archives** (array) - A list of archives.
    - **name** (string) - The name of the archive.
    - **guid** (string) - The unique identifier (GUID) of the archive.
    - **table** (string) - The name of the database table associated with the archive.

### Request Example
(No request body for GET request)

### Response Example
```json
{
  "users": {
    "archives": [
      {
        "name": "Name des Archivs",
        "guid": "GUID",
        "table": "Datenbanktabelle"
      }
    ]
  }
}
```
```

--------------------------------

### Get User and Prename by Username

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?dashboard_getuserbyusername.html=

Fetches a user by username and returns their prename. Ensure the ApiUser object is correctly returned.

```php
$user = $this->getUserByUsername('admin');
return $user->getPrename();
```

--------------------------------

### getJobRouterVersion

Source: https://docs.jobrouter.com/2026.1/de/developer/webservice_getjobrouterversion.html

Retrieves the version of the JobRouter installation. The call returns the JobRouter version in the format {Version}.{ServicePack}.{PatchNr} as a string.

```APIDOC
## getJobRouterVersion

### Description
Retrieves the version of the JobRouter installation that the webservice is communicating with.

### Method
GET

### Endpoint
/getJobRouterVersion

### Parameters
None

### Response
#### Success Response (200)
- **JobRouter-Version** (string) - The JobRouter version in the format {Version}.{ServicePack}.{PatchNr}, e.g., 2026.1.1.
```

--------------------------------

### List Substitution Steps

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_boxen.html=

Retrieves a list of work items that the authenticated user is authorized to process as a substitute for another user.

```APIDOC
## GET /application/workitems/substitution

### Description
Lists steps (work items) that the authenticated user can process as a substitute.

### Method
GET

### Endpoint
/application/workitems/substitution

### Response
#### Success Response (200)
- The response will be a JSON object containing a list of work items available for substitution. The structure will be similar to the general inbox, detailing these items.

### Request Example
```http
GET /application/workitems/substitution HTTP/1.1
Host: example.org
Authorization: Bearer YOUR_ACCESS_TOKEN
```
```

--------------------------------

### Beispiel: Ausführen einer Funktion in einem bestehenden Schritt (cURL)

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_dialogfunktion-ausfuehren.html=

Führt eine Dialogfunktion in einem bestehenden Workflow-Schritt über cURL aus. Definiert Funktionsparameter und Dialogwerte für die Funktion. Beendet die Benutzersitzung nach der Ausführung.

```bash
# Benutzer wurde bereits authentifiziert
# Funktionsparameter und Dialogwerte angeben (z. B. für das Ermitteln mit getDialogValue in der PHP-Funktion)
$inputData = [
    "functionParameters" => [
        ["name" => "fullname", "value" => 1],
    ],
    "dialog" => [
        "fields" => [
            ["name" => "userNameField", "value" => "mmuster"],
        ],
    ],
];

$response = $client->post($route, $inputData, 200);
if (count($response)) {
    foreach ($response['dialogfunctions']['returnValues'] as $name => $value) {
        // Ausgabe: "userAccordingToCheckbox => Max Muster (mmuster)"
        echo $name . " => " . $value . PHP_EOL;
    }
}

# Benutzer-Session beenden

```

--------------------------------

### List JobData Datasets using cURL

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_suchen_und_anzeigen_von_datens.html

This cURL command-line example shows how to retrieve JobData records. It sets up the request, retrieves the response, and processes the JSON data to display the records.

```bash
// Benutzer wurde bereits authentifiziert
curl_setopt($curlHandle,
'http://example.org/jobrouter/api/rest/v2/application/jobdata/' .
'tables/2076E38C-3EC0-234E-EFFD-E15F14879CB1/datasets');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cooke/file.cookie');
// Datensatz anlegen
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
if ($statusCode == 200) {
// Antwort anzeigen
$data = json_decode($response, true);
foreach ($data['datasets'] as $dataSet) {
foreach ($dataSet as $columnName => $columnValue) {
echo $columnName . ": " . $columnValue . "\n";
}
echo "\n";
}
} else {
echo "Fehler beim Ausführen: Code - " . $statusCode . ", ";
echo "Response: " . var_export($response, true);
}
```

--------------------------------

### List JobData Datasets

Source: https://docs.jobrouter.com/2026.1/de/developer/_hm_print_window.htm?restapi_suchen_und_anzeigen_von_datens.html=

Retrieves a list of datasets from a specified JobData table. The table is identified by its GUID. The response is in JSON format.

```APIDOC
## GET /application/jobdata/tables/:guid/datasets

### Description
Retrieves a list of datasets from a specified JobData table, identified by its GUID.

### Method
GET

### Endpoint
/application/jobdata/tables/:guid/datasets

#### Query Parameters
- **withListDisplayValues** (boolean) - Optional - If used and the 'Display value in overview' option is enabled for a list column in the configuration, the display value will also be returned.

### Response
#### Success Response (200)
- **meta** (object) - Contains metadata about the response, including pagination information.
  - **pagination** (object)
    - **total** (integer) - The total number of data records in the table.
- **datasets** (array) - An array of dataset objects.
  - **jrid** (string) - The unique identifier for the dataset record.
  - **username** (string or object) - The username. If `withListDisplayValues` is used, this will be an object with 'name' and 'value' fields.
  - **registered** (string) - The registration timestamp of the record.

### Response Example (with `withListDisplayValues`)
{
  "meta": {
    "pagination": {
      "total": 159
    }
  },
  "datasets": [
    {
      "jrid": "1",
      "username": {
        "name": "John Doe",
        "value": "jdoe"
      },
      "registered": "2017-08-21T12:34:57+01:00"
    }
  ]
}
```

--------------------------------

### List Datasets

Source: https://docs.jobrouter.com/2026.1/de/developer/restapi_suchen_und_anzeigen_von_datens.html

Retrieves a list of datasets from a specified table using its GUID. Supports an optional query parameter to include display values.

```APIDOC
## GET /application/jobdata/tables/:guid/datasets

### Description
Use this route to list JobData database contents. The table is identified by its GUID.

### Method
GET

### Endpoint
/application/jobdata/tables/:guid/datasets

### Parameters
#### Query Parameters
- **withListDisplayValues** (boolean) - Optional - If used and the option 'Display value in overview' is enabled in the list column configuration, the display value will also be returned.

### Response
#### Success Response (200)
- **meta** (object) - Contains metadata about the response, including pagination information.
  - **pagination** (object)
    - **total** (integer) - The total number of data records in the table.
- **datasets** (array) - An array of dataset objects.
  - Each dataset object contains key-value pairs representing the columns and their values. If `withListDisplayValues` is used, some values might be objects with 'name' and 'value' properties.

### Request Example
```http
GET /application/jobdata/tables/2076E38C-3EC0-234E-EFFD-E15F14879CB1/datasets?withListDisplayValues
```

### Response Example
```json
{
  "meta": {
    "pagination": {
      "total": 159
    }
  },
  "datasets": [
    {
      "jrid": "1",
      "username": {
        "name": "John Doe",
        "value": "jdoe"
      },
      "registered": "2017-08-21T12:34:57+01:00"
    },
    ...
  ]
}
```
```
Tokens:
Raw