Workflow-SDK 1.0.0

Diese Seite ist die API-Referenz von @acriva/workflow-sdk 1.0.0, dem SDK, gegen das Sie Skripte im Workflow-Designer schreiben. Sie wird aus den Deklarationen des SDK erzeugt und ändert sich nicht mehr, sobald die Version veröffentlicht ist. Wie Sie ein Skript schreiben, testen und veröffentlichen, beschreibt die Anleitung Workflows anpassen und programmieren; was sich je Version geändert hat, steht im Changelog.

SDK 1.x wächst nur additiv: Neue Hooks, Mitglieder von ctx, Hilfen und optionale Parameter kommen hinzu, nichts fällt weg. Unions, die ein Skript empfängt (Hook, TaskOutcome, die Schlüssel der Typen des Arbeitsbereichs), können deshalb neue Mitglieder bekommen; ein switch darüber braucht einen default-Zweig.

Schnittstellen

Reference

Ein Verweis auf ein anderes Objekt des Arbeitsbereichs, etwa einen Kontakt in einem Feld „Lieferant“.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
id	readonly	string	Die ID des Objekts.
name	readonly	string	Der Anzeigename des Objekts.

---

DocumentFields

Die Felder, die ein Skript als ctx.document.fields liest: die Eingaben seines Schritts, Schlüssel → Typ. Leer im SDK; die Typen des Arbeitsbereichs (tenant.d.ts, GET /workflows/sdk/types) ergänzen es per Module Augmentation. Ein Pflichtfeld hat seinen Typ, ein optionales Feld Typ | null. Typen: string (Text), number, Money, PlainDate, boolean, eine Union der Optionsschlüssel (Auswahl) und Reference.

Beispiel

tenant.d.ts

import type { Money, Reference } from '@acriva/workflow-sdk';
declare module '@acriva/workflow-sdk' {
  interface DocumentFields {
    bruttobetrag: Money;
    lieferant: Reference;
    kostenstelle: string | null;
  }
}

---

SettableFields

Die Felder, die ein Skript mit EffectContext.setField setzen darf, Schlüssel → Typ: die Felder des Dokumenttyps des Auslösers ohne die, die Finanzen für eine Rechnung liest, und die Felder, die der Workflow deklariert. Leer im SDK; tenant.d.ts ergänzt es wie DocumentFields.

---

DocumentTypeRegistry

Die Dokumenttypen des Arbeitsbereichs: ein Eintrag je Schlüssel (eingangsrechnung: true). Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist DocumentTypeKey string.

---

FileTypeRegistry

Die Akten-Typen des Arbeitsbereichs: ein Eintrag je Schlüssel. Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist FileTypeKey string.

---

TagRegistry

Die Schlagwörter des Arbeitsbereichs: ein Eintrag je Name ('über 500 €': true). Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist TagName string.

---

RoleRegistry

Die Rollen des Arbeitsbereichs: ein Eintrag je Rolle, eine Standardrolle mit ihrem Schlüssel (admin), eine eigene Rolle mit ihrem Namen. Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist RoleKey string.

---

CostCenterRegistry

Die Kostenstellen des Arbeitsbereichs: ein Eintrag je Nummer ('4200': true), die aktiven aus Finanzen. Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist CostCenterNumber string.

---

DocumentTypeFieldsRegistry

Die Felder jedes Dokumenttyps: Schlüssel des Typs → (Schlüssel des Felds → Typ), wie bei DocumentFields. Leer im SDK; tenant.d.ts ergänzt es. FieldsOf liest einen Typ daraus.

---

SettableFieldKeysRegistry

Die Felder jedes Dokumenttyps, die ein Skript setzen darf: Schlüssel des Typs → Union der Schlüssel (ohne die, die Finanzen für eine Rechnung liest). Leer im SDK; tenant.d.ts ergänzt es. SettableFieldsOf liest einen Typ daraus.

---

FileRef

Eine Akte, in der das Dokument liegt.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
type	readonly	FileTypeKey	Der Schlüssel des Akten-Typs.
number	readonly	string	Die Nummer der Akte.

---

ScriptDocument

Das Dokument, für das der Workflow läuft: seine Metadaten, nie sein Text.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
id	readonly	string	Die ID des Dokuments.
type	readonly	DocumentTypeKey	Der Schlüssel seines Dokumenttyps.
fields	readonly	Readonly<DocumentFields>	Die Felder, die der Schritt als Eingaben deklariert, typisiert aus tenant.d.ts (DocumentFields).
tags	readonly	readonly TagName[]	Die Namen seiner Schlagwörter.
files	readonly	readonly FileRef[]	Die Akten, in denen es liegt.

---

ScriptInstance

Die Workflow-Instanz, in der das Skript läuft.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
id	readonly	string	Die ID der Instanz.
step	readonly	string	Der Name des Skript-Schritts.
lastTaskOutcome	readonly	TaskOutcome | null	Das Ergebnis der letzten erledigten Aufgabe der Instanz, null vor der ersten.

---

ScriptResult

Was run zurückgibt: das Ergebnis von EffectContext.branch oder EffectContext.result. Nur das SDK erzeugt es.

Typenparameter

Typenparameter
O extends Outputs

Eigenschaften

Eigenschaft	Modifikator	Typ
[resultBrand]	readonly	O

---

Notice

Eine Benachrichtigung von EffectContext.notify.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
to	readonly	readonly Recipient[]	Die Empfänger.
text	readonly	string	Reiner Text, höchstens 1.000 Zeichen. Wer das Dokument nicht lesen darf, bekommt nur einen Link.

---

ScriptContext

Was jedes Skript in run bekommt, an jedem Hook. ctx ist eingefroren; Uhr und Zufall gibt es nur hier, weil Date.now und Math.random im Skript fehlen.

Erweitert durch

• EffectContext

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
document	readonly	ScriptDocument	Das Dokument, für das der Workflow läuft.
instance	readonly	ScriptInstance	Die Workflow-Instanz.
sources	readonly	Sources	Die Datenquellen des Arbeitsbereichs, nur lesend (Sources): externe JSON-Endpunkte, die eine Administratorin oder ein Administrator eingerichtet hat.
tables	readonly	Tables	Die Datentabellen des Arbeitsbereichs, nur lesend (Tables): Stammdaten wie eine Lieferantenliste.

Methoden

now()

now(): Date;

Der Zeitpunkt des Laufs; innerhalb eines Laufs immer derselbe.

Rückgabewert

Date

today()

today(): PlainDate;

Der heutige Tag in Deutschland (Europe/Berlin), zum Zeitpunkt des Laufs.

Rückgabewert

PlainDate

random()

random(): number;

Eine Zufallszahl in [0, 1), anstelle von Math.random.

Rückgabewert

number

log()

log(...values): void;

Schreibt eine Zeile in die Konsole des Laufs (höchstens 1.000 Zeichen je Zeile, 1.000 Zeilen je Lauf).

Parameter

Parameter	Typ	Beschreibung
…values	readonly unknown[]	Die Werte der Zeile, durch Leerzeichen getrennt.

Rückgabewert

void

hint()

hint(text): void;

Hängt einen Hinweis an die nächste Aufgabe der Instanz (reiner Text, höchstens 500 Zeichen, als Ausgabe des Skripts gekennzeichnet). Die einzige Wirkung an beforeApproval.

Parameter

Parameter	Typ	Beschreibung
text	string	Der Hinweis.

Rückgabewert

void

---

EffectContext

ctx an den Hooks mit Wirkungen (onDocumentArrived, onApproved, onRejected, onTimer). Wirkungen werden gesammelt und erst nach dem Lauf geprüft und als die Instanz angewendet; ein Testlauf wendet nichts an.

Erweitert

• ScriptContext

Typenparameter

Typenparameter	Standardtyp
O extends Outputs	Outputs

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung	Geerbt von
document	readonly	ScriptDocument	Das Dokument, für das der Workflow läuft.	ScriptContext.document
instance	readonly	ScriptInstance	Die Workflow-Instanz.	ScriptContext.instance
sources	readonly	Sources	Die Datenquellen des Arbeitsbereichs, nur lesend (Sources): externe JSON-Endpunkte, die eine Administratorin oder ein Administrator eingerichtet hat.	ScriptContext.sources
tables	readonly	Tables	Die Datentabellen des Arbeitsbereichs, nur lesend (Tables): Stammdaten wie eine Lieferantenliste.	ScriptContext.tables

Methoden

now()

now(): Date;

Der Zeitpunkt des Laufs; innerhalb eines Laufs immer derselbe.

Rückgabewert

Date

Geerbt von

ScriptContext.now

today()

today(): PlainDate;

Der heutige Tag in Deutschland (Europe/Berlin), zum Zeitpunkt des Laufs.

Rückgabewert

PlainDate

Geerbt von

ScriptContext.today

random()

random(): number;

Eine Zufallszahl in [0, 1), anstelle von Math.random.

Rückgabewert

number

Geerbt von

ScriptContext.random

log()

log(...values): void;

Schreibt eine Zeile in die Konsole des Laufs (höchstens 1.000 Zeichen je Zeile, 1.000 Zeilen je Lauf).

Parameter

Parameter	Typ	Beschreibung
…values	readonly unknown[]	Die Werte der Zeile, durch Leerzeichen getrennt.

Rückgabewert

void

Geerbt von

ScriptContext.log

hint()

hint(text): void;

Hängt einen Hinweis an die nächste Aufgabe der Instanz (reiner Text, höchstens 500 Zeichen, als Ausgabe des Skripts gekennzeichnet). Die einzige Wirkung an beforeApproval.

Parameter

Parameter	Typ	Beschreibung
text	string	Der Hinweis.

Rückgabewert

void

Geerbt von

ScriptContext.hint

setField()

setField<K>(key, value): void;

Setzt ein Feld des Dokuments; null leert es. Nach einer Freigabe (onApproved, ein onTimer danach) nur ein leeres Feld, das der Workflow deklariert.

Typenparameter

Typenparameter
K extends keyof SettableFields & string

Parameter

Parameter	Typ	Beschreibung
key	K	Der Schlüssel des Felds.
value	| FieldInput<NonNullable<SettableFields[K]>> | null	Der neue Wert.

Rückgabewert

void

addTag()

addTag(name): void;

Fügt dem Dokument ein vorhandenes Schlagwort hinzu.

Parameter

Parameter	Typ	Beschreibung
name	TagName	Der Name des Schlagworts.

Rückgabewert

void

fileInto()

fileInto(file): void;

Legt das Dokument in einer Akte ab.

Parameter

Parameter	Typ	Beschreibung
file	FileRef	Akten-Typ und Nummer der Akte.

Rückgabewert

void

notify()

notify(notice): void;

Benachrichtigt Mitglieder oder Rollen des Arbeitsbereichs.

Parameter

Parameter	Typ	Beschreibung
notice	Notice	Empfänger und Text.

Rückgabewert

void

branch()

branch(value, values?): ScriptResult<O>;

Wählt den Ausgang des Schritts: einen der festen Werte aus outputs. Geben Sie das Ergebnis aus run zurück.

Parameter

Parameter	Typ	Beschreibung
value	BranchValue<O>	Der Wert des Ausgangs.
values?	OutputValues<O>	Weitere Rückgaben.

Rückgabewert

ScriptResult<O>

Das Ergebnis für run.

result()

result(values): ScriptResult<O>;

Gibt Rückgaben ohne Ausgang zurück; der Schritt geht dann zu seinem Standard-Nachfolger.

Parameter

Parameter	Typ	Beschreibung
values	OutputValues<O>	Die Rückgaben.

Rückgabewert

ScriptResult<O>

Das Ergebnis für run.

---

HookContexts

Die Hooks: wo ein Skript-Schritt im Workflow steht, und welches ctx er bekommt.

Typenparameter

Typenparameter	Standardtyp
O extends Outputs	Outputs

Eigenschaften

Eigenschaft	Typ	Beschreibung
onDocumentArrived	EffectContext<O>	Sobald ein Dokument eingegangen und erkannt ist, vor dem ersten Schritt. Alle Wirkungen.
beforeApproval	ScriptContext	Vor einer Freigabe oder Prüfung, nur lesend: die einzige Wirkung ist ScriptContext.hint an dieser Aufgabe.
onApproved	EffectContext<O>	Nach einer Freigabe. Alle Wirkungen; Felder nur, wenn sie leer und deklariert sind.
onRejected	EffectContext<O>	Nach einer Zurückweisung. Alle Wirkungen.
onTimer	EffectContext<O>	Nach einer Frist oder einem Zeitplan. Alle Wirkungen; nach einer Freigabe Felder nur, wenn sie leer und deklariert sind.

---

EffectScriptDefinition

Ein Skript an einem Hook mit Wirkungen.

Typenparameter

Typenparameter
O extends Outputs

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
hook	readonly	EffectHook	Der Hook; er muss der des Schritts sein.
outputs?	readonly	O	Die Rückgaben des Skripts.

Methoden

run()

run(ctx): MaybePromise<void | ScriptResult<O>>;

Der Code des Skripts. Ohne Rückgabe geht der Schritt zu seinem Standard-Nachfolger.

Parameter

Parameter	Typ	Beschreibung
ctx	EffectContext<O>	Dokument, Instanz und Wirkungen.

Rückgabewert

MaybePromise<void | ScriptResult<O>>

---

ReadOnlyScriptDefinition

Ein Skript an beforeApproval: nur lesend, ohne Rückgaben.

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
hook	readonly	"beforeApproval"	Der Hook.

Methoden

run()

run(ctx): MaybePromise<void>;

Der Code des Skripts.

Parameter

Parameter	Typ	Beschreibung
ctx	ScriptContext	Dokument und Instanz, nur lesend, und ctx.hint.

Rückgabewert

MaybePromise<void>

---

Script

Ein definiertes Skript, der Default-Export der Datei. Nur das SDK erzeugt es.

Typenparameter

Typenparameter
O extends Outputs

Eigenschaften

Eigenschaft	Modifikator	Typ
[scriptBrand]	readonly	O

---

MoneyHelpers

Geldbeträge in deutscher Schreibweise.

Methoden

format()

format(value): string;

Formatiert einen Betrag: 1249.5 → '1.249,50 €'.

Parameter

Parameter	Typ	Beschreibung
value	number	Der Betrag in Euro.

Rückgabewert

string

parse()

parse(text): Money | null;

Liest einen Betrag in deutscher Schreibweise, mit oder ohne Tausenderpunkte und €: '1.249,50 €' → 1249.5. null, wenn der Text kein Betrag ist.

Parameter

Parameter	Typ	Beschreibung
text	string	Der Text.

Rückgabewert

Money | null

round()

round(value): Money;

Rundet kaufmännisch auf Cent: 12.345 → 12.35.

Parameter

Parameter	Typ	Beschreibung
value	number	Der Betrag.

Rückgabewert

Money

---

DateHelpers

Kalendertage (PlainDate) in deutscher Schreibweise.

Methoden

format()

format(value): string;

Formatiert einen Tag als TT.MM.JJJJ: '2026-10-14' → '14.10.2026'. Ein Date gilt in Europe/Berlin.

Parameter

Parameter	Typ	Beschreibung
value	PlainDate | Date	Der Tag.

Rückgabewert

string

parse()

parse(text): PlainDate | null;

Liest einen Tag als TT.MM.JJJJ oder JJJJ-MM-TT. null, wenn der Text kein gültiger Tag ist.

Parameter

Parameter	Typ	Beschreibung
text	string	Der Text.

Rückgabewert

PlainDate | null

addDays()

addDays(value, days): PlainDate;

Addiert Kalendertage; negative ziehen ab.

Parameter

Parameter	Typ	Beschreibung
value	PlainDate	Der Tag.
days	number	Die Anzahl der Tage.

Rückgabewert

PlainDate

daysBetween()

daysBetween(from, to): number;

Die Kalendertage von from bis to, negativ, wenn to früher ist.

Parameter

Parameter	Typ	Beschreibung
from	PlainDate	Der erste Tag.
to	PlainDate	Der zweite Tag.

Rückgabewert

number

---

DataSourceRegistry

Die Datenquellen des Arbeitsbereichs: Schlüssel → { params; response }, also die Query-Parameter, die die Quelle annimmt, und der JSON-Typ ihrer Antwort. Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist DataSourceKey string, die Parameter sind beliebig und die Antwort ist unknown.

Beispiel

tenant.d.ts

declare module '@acriva/workflow-sdk' {
  interface DataSourceRegistry {
    erp: { params: { lieferantId: string }; response: { kostenstelle: string; kreditor: string } };
  }
}

---

DataTableRegistry

Die Datentabellen des Arbeitsbereichs: Schlüssel → { key; row }, also der Typ des Schlüssels der Tabelle und ihre Zeile (Spaltenschlüssel → Typ). Leer im SDK; tenant.d.ts ergänzt es. Ohne Einträge ist DataTableKey string.

Beispiel

tenant.d.ts

declare module '@acriva/workflow-sdk' {
  interface DataTableRegistry {
    lieferanten: { key: string; row: { lieferantId: string; name: string; kostenstelle: string } };
  }
}

---

SourceRequest

Eine Anfrage an eine Datenquelle für Sources.get.

Typenparameter

Typenparameter
K extends DataSourceKey

Eigenschaften

Eigenschaft	Modifikator	Typ	Beschreibung
path?	readonly	string	Ein Pfad relativ zur Basis-URL der Quelle ('lieferanten/4711'). Der Broker kodiert jedes Segment, sodass .., //, @ und ein Backslash den Basispfad nicht verlassen und den Host nicht ändern.
query?	readonly	SourceParams<K>	Die Query-Parameter; der Broker kodiert sie.

---

Sources

ctx.sources: liest externe Daten über den Broker der Plattform. Das Skript selbst hat kein Netz.

Hinweise

Ein Schritt muss die Quelle unter seinen Eingaben deklarieren (eine Eingabe der Art Source), sonst antwortet der Aufruf 'not-declared'. Höchstens 10 Aufrufe und 30 s Broker-Zeit je Lauf, danach 'limit'; ein Treffer im Cache zählt als Aufruf. Nur GET.

Methoden

get()

get<K>(key, request?): Promise<SourceResult<SourceResponse<K>>>;

Ruft die Datenquelle key auf.

Typenparameter

Typenparameter
K extends DataSourceKey

Parameter

Parameter	Typ	Beschreibung
key	K	Der Schlüssel der Quelle.
request?	SourceRequest<K>	Pfad und Query-Parameter.

Rückgabewert

Promise<SourceResult<SourceResponse<K>>>

Die Daten oder der Grund, warum es keine gibt.

---

Tables

ctx.tables: liest Zeilen der Datentabellen des Arbeitsbereichs über den Broker der Plattform.

Hinweise

Ein Schritt muss die Tabelle unter seinen Eingaben deklarieren (eine Eingabe der Art Table); die Prüfung meldet eine nicht deklarierte Tabelle schon vor dem Veröffentlichen. Höchstens 50 Abfragen je Lauf, lookup und query zusammen. Anders als bei Sources ist eine Ablehnung hier kein Ergebnis: Eine nicht deklarierte Tabelle (table-not-declared) oder die 51. Abfrage (limit-table-lookups) beendet den Lauf mit diesem Code, wie ein überschrittenes Limit, und ein catch hält ihn nicht auf. Ein stilles null sähe sonst aus wie „nicht in der Liste“ und könnte ein Dokument falsch weiterleiten (etwa bei einer Sperrliste).

Methoden

lookup()

lookup<K>(table, key): Promise<TableRow<K> | null>;

Die Zeile mit dem Schlüssel key, oder null, wenn es keine gibt.

Typenparameter

Typenparameter
K extends DataTableKey

Parameter

Parameter	Typ	Beschreibung
table	K	Der Schlüssel der Tabelle.
key	TableKeyOf<K>	Der Schlüssel der Zeile; verglichen wird seine kanonische Textform.

Rückgabewert

Promise<TableRow<K> | null>

Die Zeile oder null.

query()

query<K>(table, filter): Promise<readonly TableRow<K>[]>;

Die Zeilen, deren Spalten dem Filter gleichen: höchstens 100, nach Schlüssel sortiert, sodass die Grenze jedes Mal dieselben Zeilen liefert.

Typenparameter

Typenparameter
K extends DataTableKey

Parameter

Parameter	Typ	Beschreibung
table	K	Der Schlüssel der Tabelle.
filter	TableFilter<K>	Gleichheit auf 1 bis 3 Spalten.

Rückgabewert

Promise<readonly TableRow<K>[]>

Die Zeilen, vielleicht keine.

Typenaliasse

Money

type Money = number & object;

Ein Geldbetrag in Euro, als Zahl mit höchstens zwei Nachkommastellen. Er lässt sich wie eine Zahl vergleichen und rechnen (betrag > 500); das Ergebnis einer Rechnung ist eine number.

Typendeklaration

[moneyBrand]

readonly [moneyBrand]: "EUR";

---

PlainDate

type PlainDate = string & object;

Ein Kalendertag ohne Uhrzeit und Zeitzone, als ISO-Text JJJJ-MM-TT ('2026-10-14'). Zwei Tage lassen sich mit < und > vergleichen. Erzeugen Sie einen mit date oder ScriptContext.today.

Typendeklaration

[plainDateBrand]

readonly [plainDateBrand]: "PlainDate";

---

FieldsOf

type FieldsOf<T> = T extends keyof DocumentTypeFieldsRegistry ? DocumentTypeFieldsRegistry[T] : object;

Die Felder des Dokumenttyps T, Schlüssel → Typ; {} für einen Typ ohne Felder. Der Editor und die Prüfung leiten daraus DocumentFields eines Schritts ab (interface DocumentFields extends Pick<FieldsOf<'…'>, '…'> {}).

Typenparameter

Typenparameter
T extends DocumentTypeKey

---

SettableFieldsOf

type SettableFieldsOf<T> = Pick<FieldsOf<T>, Extract<T extends keyof SettableFieldKeysRegistry ? SettableFieldKeysRegistry[T] : never, keyof FieldsOf<T>>>;

Die Felder des Dokumenttyps T, die ein Skript setzen darf, Schlüssel → Typ; Grundlage von SettableFields.

Typenparameter

Typenparameter
T extends DocumentTypeKey

---

RegistryKey

type RegistryKey<R> = [keyof R] extends [never] ? string : Extract<keyof R, string>;

Die Schlüssel einer Registry, oder string, solange sie leer ist.

Typenparameter

Typenparameter
R

---

DocumentTypeKey

type DocumentTypeKey = RegistryKey<DocumentTypeRegistry>;

Der Schlüssel eines Dokumenttyps.

---

FileTypeKey

type FileTypeKey = RegistryKey<FileTypeRegistry>;

Der Schlüssel eines Akten-Typs.

---

TagName

type TagName = RegistryKey<TagRegistry>;

Der Name eines Schlagworts.

---

RoleKey

type RoleKey = RegistryKey<RoleRegistry>;

Der Schlüssel einer Rolle.

---

CostCenterNumber

type CostCenterNumber = RegistryKey<CostCenterRegistry>;

Die Nummer einer Kostenstelle.

---

FieldInput

type FieldInput<T> = T extends Money ? number : T extends Reference ? Pick<Reference, "id"> : T;

Der Wert, den EffectContext.setField für ein Feld des Typs T annimmt: eine Zahl für Money, die ID für Reference, sonst T.

Typenparameter

Typenparameter
T

---

TaskOutcome

type TaskOutcome = "Approved" | "Rejected" | "Returned" | "Done";

Das Ergebnis einer erledigten Aufgabe. Die Union kann in 1.x neue Werte bekommen.

---

OutputType

type OutputType =
  | readonly [string, ...string[]]
  | "text"
  | "number"
  | "money"
  | "date"
  | "boolean"
  | "reference";

Der Typ einer Rückgabe in outputs: eine Liste fester Werte (eine Auswahl, nach der der Schritt verzweigen kann) oder der Name eines Typs.

---

Outputs

type Outputs = object;

Die Rückgaben eines Skripts: Schlüssel (camelCase, höchstens 40 Zeichen) → OutputType. Spätere Bedingungen lesen sie; die Werte einer Auswahl sind die Ausgänge des Schritts.

Indexsignatur

[key: string]: OutputType

---

OutputValue

type OutputValue<T> = T extends readonly string[] ? T[number] : T extends "text" ? string : T extends "number" | "money" ? number : T extends "date" ? PlainDate : T extends "boolean" ? boolean : T extends "reference" ? Pick<Reference, "id"> : never;

Der Wert einer Rückgabe des Typs T.

Typenparameter

Typenparameter
T extends OutputType

---

BranchValue

type BranchValue<O> = { [K in keyof O]: O[K] extends readonly string[] ? O[K][number] : never }[keyof O];

Die Werte, nach denen ein Skript verzweigen kann: alle festen Werte seiner Auswahl-Rückgaben.

Typenparameter

Typenparameter
O extends Outputs

---

OutputValues

type OutputValues<O> = { readonly [K in keyof O]?: OutputValue<O[K]> | null };

Rückgaben mit ihren Werten; jede ist optional, null heißt „kein Wert“.

Typenparameter

Typenparameter
O extends Outputs

---

Recipient

type Recipient =
  | {
  member: string;
  role?: never;
}
  | {
  role: RoleKey;
  member?: never;
};

Ein Empfänger von EffectContext.notify: ein Mitglied des Arbeitsbereichs per E-Mail-Adresse oder eine Rolle per Schlüssel, nie eine freie Adresse.

---

Hook

type Hook = keyof HookContexts;

Der Name eines Hooks. Die Union kann in 1.x neue Hooks bekommen (onExport kommt später).

---

EffectHook

type EffectHook = Exclude<Hook, "beforeApproval">;

Die Hooks mit Wirkungen.

---

MaybePromise

type MaybePromise<T> = T | Promise<T>;

Ein Wert oder ein Promise darauf.

Typenparameter

Typenparameter
T

---

ScriptDefinition

type ScriptDefinition<O> =
  | EffectScriptDefinition<O>
  | ReadOnlyScriptDefinition;

Die Beschreibung eines Skripts für defineScript; hook entscheidet, welches ctx run bekommt.

Typenparameter

Typenparameter
O extends Outputs

---

DataSourceKey

type DataSourceKey = RegistryKey<DataSourceRegistry>;

Der Schlüssel einer Datenquelle.

---

DataTableKey

type DataTableKey = RegistryKey<DataTableRegistry>;

Der Schlüssel einer Datentabelle.

---

SourceParamValue

type SourceParamValue = string | number | boolean;

Der Wert eines Query-Parameters; der Broker kodiert ihn.

---

SourceParams

type SourceParams<K> = K extends keyof DataSourceRegistry ? DataSourceRegistry[K] extends object ? { readonly [N in keyof P]: P[N] & SourceParamValue } : never : object;

Die Query-Parameter der Datenquelle K, aus DataSourceRegistry.

Typenparameter

Typenparameter
K extends DataSourceKey

---

SourceResponse

type SourceResponse<K> = K extends keyof DataSourceRegistry ? DataSourceRegistry[K] extends object ? R : unknown : unknown;

Der JSON-Typ der Antwort der Datenquelle K, aus DataSourceRegistry; unknown ohne Eintrag.

Typenparameter

Typenparameter
K extends DataSourceKey

---

SourceError

type SourceError =
  | "data-source-blocked"
  | "timeout"
  | "too-large"
  | "invalid-response"
  | "http-error"
  | "not-declared"
  | "confidential"
  | "limit";

Warum ein Aufruf einer Datenquelle keine Daten liefert. Die Union kann in 1.x neue Werte bekommen.

• 'data-source-blocked': Der Schutz vor internen Adressen hat die Adresse abgelehnt.
• 'timeout': Die Quelle hat nicht innerhalb ihres Timeouts geantwortet.
• 'too-large': Die Antwort ist größer als 1 MiB.
• 'invalid-response': Die Antwort ist kein JSON, oder sie erfüllt das Schema der Quelle nicht.
• 'http-error': Die Quelle hat mit einem Status außerhalb von 2xx geantwortet (siehe status).
• 'not-declared': Der Schritt deklariert die Quelle nicht unter seinen Eingaben.
• 'confidential': Das Dokument ist vertraulich, und die Quelle lässt vertrauliche Dokumente nicht zu.
• 'limit': Der Lauf hat seine 10 Aufrufe (oder 30 s Broker-Zeit) verbraucht.

---

SourceResult

type SourceResult<T> =
  | {
  ok: true;
  status: number;
  data: T;
  cached: boolean;
}
  | {
  ok: false;
  error: SourceError;
  status?: number;
};

Das Ergebnis von Sources.get: Daten bei ok: true, sonst ein SourceError. Eine Ablehnung ist ein Ergebnis, nie eine Ausnahme; prüfen Sie ok, bevor Sie data lesen.

Typenparameter

Typenparameter
T

Union-Mitglieder

Typenliteral

{
  ok: true;
  status: number;
  data: T;
  cached: boolean;
}

ok

readonly ok: true;

Die Quelle hat geantwortet.

status

readonly status: number;

Der HTTP-Status (2xx).

data

readonly data: T;

Die Antwort als JSON.

cached

readonly cached: boolean;

true, wenn die Antwort aus dem Cache der Quelle kommt; auch das zählt als Aufruf.

---

Typenliteral

{
  ok: false;
  error: SourceError;
  status?: number;
}

ok

readonly ok: false;

Der Aufruf hat keine Daten geliefert.

error

readonly error: SourceError;

Der Grund.

status?

readonly optional status?: number;

Der HTTP-Status, wenn die Quelle geantwortet hat ('http-error').

---

TableCellValue

type TableCellValue = string | number | boolean | null;

Der Wert einer Zelle einer Datentabelle ohne Eintrag in DataTableRegistry: Text, Zahl, Betrag, Datum (ISO-Text), Wahrheitswert oder null.

---

TableRow

type TableRow<K> = K extends keyof DataTableRegistry ? DataTableRegistry[K] extends object ? Readonly<R> : never : object;

Eine Zeile der Datentabelle K, Spaltenschlüssel → Wert, die Schlüsselspalte eingeschlossen.

Typenparameter

Typenparameter
K extends DataTableKey

---

TableKeyOf

type TableKeyOf<K> = K extends keyof DataTableRegistry ? DataTableRegistry[K] extends object ? Key : never : string | number;

Der Typ des Schlüssels der Datentabelle K. Der Broker vergleicht die kanonische Textform: Text getrimmt und Unicode-normalisiert (NFC), eine Zahl als kanonische Dezimalzahl, ein Datum als ISO-Text ('2026-10-14').

Typenparameter

Typenparameter
K extends DataTableKey

---

TableFilter

type TableFilter<K> = Partial<TableRow<K>>;

Ein Filter für Tables.query: Gleichheit auf höchstens 3 Spalten der Zeile. Mehr Spalten oder keine lehnt der Broker ab.

Typenparameter

Typenparameter
K extends DataTableKey

Variablen

moneyBrand

const moneyBrand: unique symbol;

---

plainDateBrand

const plainDateBrand: unique symbol;

---

resultBrand

const resultBrand: unique symbol;

---

scriptBrand

const scriptBrand: unique symbol;

---

money

const money: MoneyHelpers;

Die Hilfen für Geldbeträge.

---

date

const date: DateHelpers;

Die Hilfen für Kalendertage.

Funktionen

defineScript()

function defineScript<O>(script): Script<O>;

Definiert ein Skript. Jede Skriptdatei exportiert genau ein defineScript(…) als Default-Export und importiert nichts außer '@acriva/workflow-sdk'.

Typenparameter

Typenparameter	Standardtyp
O extends Outputs	object

Parameter

Parameter	Typ	Beschreibung
script	ScriptDefinition<O>	Hook, Rückgaben und Code.

Rückgabewert

Script<O>

Das Skript für den Default-Export.

Beispiel

import { defineScript } from '@acriva/workflow-sdk';

export default defineScript({
  hook: 'onDocumentArrived',
  outputs: { weg: ['gf', 'kostenstelle'] },
  async run(ctx) {
    return ctx.branch(ctx.document.fields.bruttobetrag > 500 ? 'gf' : 'kostenstelle');
  },
});