Workflow Beispiele

Beispiel-Workflows für typische Automatisierungen in Belegen, Projekten und Angeboten.

Versandlieferscheine übernehmen

Mit diesem Workflow werden Versandlieferscheine beim Speichern automatisch in den Status “Übernommen” versetzt – somit können diese nicht mehr in eine Rechnung übernommen werden. Dies kann nützlich sein, um eine individuell angelegte Belegarten wie den “Versandauftrag” und den “Versandlieferschein” beispielsweise für kostenlose Mustersendungen zu verwenden.

Alle anderen Belegarten der Belegkategorie “Lieferschein” werden trotzdem weiterhin wie gewohnt erst bei der Übernahme in den Folgebeleg in den Status “Übernommen” gesetzt.

Voraussetzungen:

Damit die entsprechenden Schritte im Workflow ausgeführt werden können, muss die Belegart Versandlieferschein im Bereich Einstellungen/Belege/Belegarten vorhanden sein.

Um diesen Workflow anzulegen, gehe wie folgt vor:

1

Lege einen Workflow an und wähle als Auslöser entweder “Vor dem Speichern von Belegen” oder “Übernahme von Belege“.

2

Füge dem Start-Element den Element “Benutzerskript” hinzu.

3

Wechsle in den Reiter “Skript” des Benutzerskript-Elements und ersetze den vorhandenen Inhalt durch folgendes Skript:

Skript des Benutzerskript-Elements

Benutzerskript für den Workflow

import workItem from ‘work_item_script’;

workItem.setAction((ctx) => {
var documentService = ctx.services.documentService;
var document = documentService.readById(ctx.parameters[‘documentId’]);
if (document.documentType === ‘Versandlieferschein’) { ctx.parameters[‘targetState’] = ‘ACCEPTED’;
}
});

4

Klicke auf “Speichern“, um das Benutzerskript-Element anzulegen.

5

Füge das Element “Abschließen” hinzu und verbinde die drei Elemente – Start, Benutzerskript und Abschließen – wie im folgenden Bild dargestellt.

6

Speichere und aktiviere den Workflow, damit er bei zukünftigen Belegen automatisch ausgeführt wird.

Der Workflow kann selbstverständlich beliebig erweitert und mit anderen Workflow-Pfaden und –Schritten kombiniert werden.

Belege beim Speichern in Folgebeleg übernehmen

In einem Workflow mit dem Auslöser “Nach dem Speichern von Belegen” kannst Du in einem Benutzerskript-Element folgendes Skript hinterlegen, um Belege einer bestimmten Belegart automatisch beim Speichern in den jeweiligen Folgebeleg übernehmen zu lassen – in diesem Beispiel ein Angebot in einen Auftrag. Der Aufbau des Workflows kann dabei an den Workflow “Versandlieferscheine übernehmen” angelehnt oder individuell erweitert und angepasst werden.

Skript für das Benutzerskript-Element

Benutzerskript für den Workflow

import workItem from “work_item_script”;

workItem.setAction( ctx => {
var documentService = ctx.services.documentService;
var document = documentService.readById(ctx.parameters[‘documentId’]);
if (document.documentType === ‘Angebot’) {
let documentTransferToTypeRequest = documentService.getDocumentTransferToTypeRequest(); documentTransferToTypeRequest.documentId = document.id;
documentTransferToTypeRequest.targetDocumentType = ‘Auftrag’; documentService.transferToType(documentTransferToTypeRequest);
ctx.parameters[‘skipTransitionToTargetState’] = true;
}
});

Die in diesem Beispiel verwendeten Belegarten “Angebot” und “Auftrag” lassen sich durch beliebige, selbst angelegte Belegarten ersetzen, sofern diese in der Belegkette direkt aufeinanderfolgen.

VQL in Workflow-Skripten

Mit VQL kannst Du in einem Workflow-Skript auf bestimmte Daten zugreifen. Dazu steht Dir im Skript-Editor der vql-Service zur Verfügung. Du erreichst ihn dort ganz einfach über: ctx.services.vqlservice

Skript für das Benutzerskript-Element

In diesem Beispiel berechnen wir die Summe aller Nettobeträge der Belege einer Adresse und schreiben den Wert ins Log.

Im Element "Benutzerskript" kannst Du folgendes Beispiel-Skript mit VQL-Anteil einfügen:

Benutzerskript

import workItem from ‘work_item_script’;

workItem.setGuard((ctx) => {
// Skript-Methode “action” ausführen?

return true; });
workItem.setAction((ctx) => {
let document = ctx.services.documentService.readById(ctx.availableInput.documentId);
let accountId = document.accountId;
let totalBoughtGoods = ctx.services.vqlService.queryAll(
`SELECT sum(totalNetPrice) FROM document.querySalesDocuments WHERE accountId = ${accountId}`
);
ctx.services.logger.info(totalBoughtGoods);
});

Im Workflow-Log findest Du dann die mit dieser Beispiel-VQL errechnete Summe:

Fehlermeldungen in Workflows

In bestimmten Fällen ist es sinnvoll, einen Workflow gezielt in einen Fehler laufen zu lassen – beispielsweise, wenn ein bestimmtes Feld nicht ausgefüllt wurde oder bestimmte Bedingungen nicht erfüllt sind. Im Skript des betroffenen Elements (z. B. Benutzerskript) kann dazu eine individuelle Fehlermeldung hinterlegt werden, die dem Benutzer beim Ausführen des Workflow-Schritts angezeigt wird.

Beispiel: Fehler beim Speichern eines Belegs

In diesem Beispiel wird ein Fehler innerhalb eines Workflows mit dem Auslöser “Vor dem Speichern von Belegen” integriert.

Im Benutzerskript wird dazu mit throw eine Fehlermeldung beim Speichern des Belegs ausgegeben, um die Speicherung aktiv zu verhindern.

Mit ctx.services.logger.info(...) kann zusätzlich eine Log-Info im Workflow-Protokoll und Element-Log erzeugt werden, um den Grund der Unterbrechung nachvollziehbar zu dokumentieren.

Beim Speichern des Belegs erscheint eine Hinweismeldung mit dem definierten Fehlertext.

Sowohl der Inhalt der Meldung als auch die Log-Info sind im Log des Benutzerskript-Elements und im Gesamtprotokoll des Workflows einsehbar.

Zahlungs- und Lieferbedingungen für Angebote ohne Geschäftsbeziehungen

Mit diesem Workflow kannst Du die Erstellung von Angeboten für Interessenten vereinfachen, bei denen noch keine Geschäftsbeziehung hinterlegt ist.

Standardmäßig müssten in solchen Fällen die Zahlungs- und Lieferungsmodalitäten manuell im Angebot eingetragen werden. Mit diesem Workflow werden diese Angaben automatisch mit vordefinierten Standardwerten ausgefüllt, die im Workflow festgelegt wurden.

Voraussetzungen:

Damit die im Beispiel definierte Zahlungs- und Lieferungsmodalitäten eingetragen werden können, müssen diese im Vorfeld unter folgenden Bereichen angelegt sein:

• Einstellungen/Finanzen/Zahlungsmodalitäten: Zahlungsart “UEB” und Zahlungsbedingung “SN”

• Einstellungen/Lager/Lieferungsmodalitäten: Versandart “DL” und Lieferbedingung “FH”

Im Skript des Benutzerskript-Elements kannst Du die entsprechenden Werte an Deine eigenen Zahlungs- und Lieferungsmodalitäten anpassen.

Um diesen Workflow anzulegen, gehe wie folgt vor:

1

Lege einen Workflow an und wähle den Auslöser “Bei Erstellung von Belege”.

2

Füge dem Start-Element den Element “Abfrage” hinzu.

3

Wechsle in den Reiter “Skript” des Abfrage-Elements und ersetze den vorhandenen Inhalt durch folgendes Skript:

Skript des Abfrage-Element

Skript des Abfrage-Element

import workItem from ‘work_item_split_gateway’;

workItem.setSplit((ctx) => {
var category = ctx.parameters[‘targetCategory’];
if (category === ‘CUSTOMER_OFFER’) {
return category;
}
return ‘UNKNOWN’;
});

4

Füge im Reiter “Abzweigungen” die Abzweigungen CUSTOMER_OFFER und UNKNOWN hinzu.

5

Klicke auf “Speichern“, um das Abfrage-Element anzulegen.

6

Füge anschließend das Benutzerskript-Element hinzu und im Reiter “Skript” des Elements das folgende Skript:

Skript des Benutzerskript-Elements

import workItem from ‘work_item_script’;

const DELIVERY_METHOD = ‘DL’;
const DELIVERY_TERM = ‘FH’;
const PAYMENT_METHOD = ‘UEB’;
const PAYMENT_TERM = ‘SN’;

workItem.setAction((ctx) => {
const { documentId } = ctx.parameters;
const {
documentService,
accountService,
deliveryMethodService,
deliveryTermService,
paymentMethodService,
paymentTermService,
utils,
logger,
} = ctx.services;
const document = documentService.readById(documentId);
const account = accountService.readById(document.accountId);
if (account.types.includes(‘CUSTOMER’)) {
return;
}
let changed = false;
if (!document.deliveryMethodRef) {
logger.info(‘Setze Versandart: ‘ + DELIVERY_METHOD);
changed = true;
const deliveryMethod = deliveryMethodService.findByLabel(DELIVERY_METHOD);
document.deliveryMethodRef = utils.toApiReference(deliveryMethod);
}
if (!document.deliveryTermRef) {
logger.info(‘Setze Lieferbedingung: ‘ + DELIVERY_TERM);
changed = true;
const deliveryTerm = deliveryTermService.findByLabel(DELIVERY_TERM);
document.deliveryTermRef = utils.toApiReference(deliveryTerm);
}
if (!document.paymentMethodRef) {
logger.info(‘Setze Zahlungsart: ‘ + PAYMENT_METHOD);
changed = true;
const paymentMethod = paymentMethodService.findByLabel(PAYMENT_METHOD);
document.paymentMethodRef = utils.toApiReference(paymentMethod);
}
if (!document.paymentTermRef) {
logger.info(‘Setze Zahlungsbedingung: ‘ + PAYMENT_TERM);
changed = true;
const paymentTerm = paymentTermService.findByLabel(PAYMENT_TERM);
document.paymentTermRef =
paymentTermService.createPaymentTermRef(paymentTerm);
}
if (!changed) {
return;
}
const updateRequest = documentService.getUpdateDocumentRequest();
updateRequest.document = document;
documentService.update(updateRequest);
});

Anpassung der Zahlungs- und Lieferungsmodalitäten

Die im Benutzerskript angegebenen Zahlungs- und Lieferungsmodalitäten können bei Bedarf individuell angepasst werden. Dazu musst Du lediglich folgende Angaben im Skript des Benutzerskript-Elements ändern:

const DELIVERY_METHOD = ‘DL‘; – statt DL kannst Du hier die Bezeichnung der gewünschten Versandart eintragen &#xNAN;const DELIVERY_TERM = ‘FH‘; – statt FH kannst Du hier die Bezeichnung der gewünschten Lieferbedingung eintragen &#xNAN;const PAYMENT_METHOD = ‘UEB‘; – statt UEB kannst Du hier die Bezeichnung der gewünschten Zahlungsart eintragen &#xNAN;const PAYMENT_TERM = ‘SN‘; – statt UEB kannst Du hier die Bezeichnung der gewünschten Zahlungsbedingung eintragen

7

Füge die Elemente “Warten (eins)” und “Abschließen” hinzu.

8

Verbinde die Elemente Start, Abfrage, Benutzerskript, Warten und Abschließen miteinander sowie die Elemente Abfrage und Warten (eins), so dass eine Darstellung wie im Bild entsteht.

9

Speichere und aktiviere den Workflow, damit er bei zukünftigen Angeboten automatisch ausgeführt wird.

Zuweisung des Projektleiters in Aufgaben des Projekts

Mit diesem Workflow wird beim Wechsel eines bestimmten Projektstatus, in unserem Beispiel vom Status “00 – Angelegt” in den Status “05 – in Vorbereitung für Kick-Off”, der im Projekt hinterlegte Projektmanager (intern) als zugeordneter Benutzer in den verknüpften Aufgaben eingetragen. Zusätzlich wird der Status der betroffenen Aufgaben auf einen vordefinierten Status gesetzt, bspw. “Zugeordnet“.

Voraussetzungen:

Damit die entsprechenden Schritte im Workflow korrekt ausgeführt werden können, müssen folgende Projekt- und Aufgabenstatus zuvor unter folgenden Bereichen in der VARIO Cloud angelegt sein:

• Einstellungen/CRM/Aufgaben: Aufgabenstatus “Zugeordnet”

• Einstellungen/CRM/Projekte: Projektstatus “00 – Angelegt” und “05 – in Vorbereitung für Kick-Off”

Im Skript des Benutzerskript-Elements kannst Du die entsprechenden Werte an deine eigenen Statusbezeichnungen anpassen.

Zusätzlich wird eine Selektion aus der Adressverwaltung mit den folgenden Einstellungen benötigt:

• Die Bezeichnung “Eigene Adresse”

• Der Toggle “Für Workflow” im Reiter “Allgemein” muss aktiviert sein

• Die Spalte “ID“

• Ein Filter mit dem Feld “Geschäftsbeziehung”, der Operation “Ist gleich” und dem Wert “Eigene Firma” als fester Wert

Weitere Informationen zur Konfiguration von Selektionen findest Du hier.

1

Lege einen Workflow an und wähle den Auslöser “Nach dem Speichern von Projekten” aus.

2

Füge dem Start-Element den Element “Benutzerskript” hinzu.

3

Wechsle in den Reiter “Skript” des Benutzerskript-Elements und ersetze den vorhandenen Inhalt durch folgendes Skript:

Skript des Benutzerskript-Elements

Skript des Benutzerskript-Elements

import workItem from ‘work_item_script’;

const PROJEKT_STATUS_ANGELEGT = ’00 – Angelegt’;
const PROJEKT_STATUS_VORBEREITUNG = ’05 – in Vorbereitung für Kick-Off’;
const AUFGABE_STATUS_ZUGEORDNET = ‘Zugeordnet’;

workItem.setAction(ctx =>
{
const taskService = ctx.services.crmTaskService;
const projectService = ctx.services.crmProjectService;
const previous = ctx.parameters.previousCrmProject;
const projectId = ctx.parameters.crmProjectId;
if (!previous)
{
return;
}
const project = projectService.readById(projectId);
if (project.stateRef.label !== PROJEKT_STATUS_VORBEREITUNG)
{
return;
}
const previousState = projectService.findStateById(previous.stateRef.id);
if (previousState.label !== PROJEKT_STATUS_ANGELEGT)
{
return;
}
ctx.services.logger.info(‘Bereite verknüpfte Aufgaben vor’);
const responsibleUser = getUserFromAccountPerson(ctx, project.projectManagerOfContractor?.accountPersonRef?.id);
if (project.childRefs !== null)
{
const targetState = taskService.findStateByLabel(AUFGABE_STATUS_ZUGEORDNET);
project.childRefs.forEach(child =>
{
if (child.type === ‘TASK’)
{
const task = taskService.readById(child.id);
task.stateRef = ctx.services.utils.toApiReference(targetState);
if (responsibleUser)
{
task.assignedGroupRef = null;
task.assignedUserRef = ctx.services.utils.toApiReference(responsibleUser);

task.stateRef = ctx.services.utils.toApiReference(targetState);
taskService.update(task);
}
});
}
});

function getUserFromAccountPerson(ctx, accountPersonId)
{
const companyId = ctx.parameters.id;
if (!companyId || !accountPersonId)
{
return null;
}
const persons = ctx.services.accountService.getPersons(companyId);
const targetPerson = persons.find(
person => person.id === accountPersonId,
);
if (!targetPerson?.userRef?.id)
{
return null;
}
return ctx.services.userAndGroupService.findUserById(
targetPerson.userRef.id,
);
}

Anpassung der Projekt- und Aufgabenstatus

Die im Benutzerskript angegebenen Projekt- und Aufgabenstatus können bei Bedarf individuell angepasst werden. Dazu musst Du lediglich folgende Angaben im Skript des Benutzerskript-Elements ändern:

const PROJEKT_STATUS_ANGELEGT = ‘00 – Angelegt‘; – statt “00 – Angelegt” kannst Du hier die Bezeichnung des ersten gewünschten Projektstatus eintragen &#xNAN;const PROJEKT_STATUS_VORBEREITUNG = ‘05 – in Vorbereitung für Kick-Off’’; – statt “05 – in Vorbereitung für Kick-Off” kannst Du hier die Bezeichnung des zweiten gewünschten Projektstatus eintragen &#xNAN;onst AUFGABE_STATUS_ZUGEORDNET = ‘Zugeordnet‘; – statt Zugeordnet kannst Du hier die Bezeichnung des gewünschten Aufgabenstatus eintragen

4

Klicke im Reiter “Parameter” auf den Button , um einen Parameter auf Basis einer Selektion anzulegen.

5

Füge einen neuen Parameter mit den folgenden Angaben hinzu und wähle die im Voraus angelegte Selektion aus.

6

Klicke auf “Speichern“, um das Benutzerskript-Element anzulegen.

7

Füge das Element “Abschließen” hinzu und verbinde die drei Elemente – Start, Benutzerskript und Abschließen – wie im folgenden Bild dargestellt.

8

Speichere und aktiviere den Workflow, damit er bei zukünftigen Belegen automatisch ausgeführt wird.

Geschenk-Artikel zu Angeboten hinzufügen

Mit diesem Workflow kann ein beliebiger Artikel als Genschenk-Artikel automatisch mit einem vorgegebenen Rabatt zu einem Angebot hinzugefügt werden, beispielsweise für bestimmte Adressen, bei denen z. B. einen vordefinierten Umsatz erreicht wurde. Dabei kann frei definiert werden welcher Umsatz als Variable gesetzt wird und welcher Rabatt der Artikel erhalten soll.

In unserem Beispiel wird der Artikel “ACC-1083” mit einem Rabatt von 100% in Angebote für Adressen hinzugefügt, die einen Umsatz von mindestens 10.000 erreicht haben.

Voraussetzungen

Der im Workflow angegebene Artikel muss mit den entsprechenden Angaben angelegt werden (als Verkaufsartikel, rabattierbar, mit Verkaufspreis usw.)

1

Lege einen Workflow an und wähle den Auslöser “Vor dem Speichern von Belegen” aus.

2

Füge dem Start-Element das Element “Abfrage” hinzu.

3

Wechsle in den Reiter “Skript” des Abfrage-Elements und ersetze den vorhandenen Inhalt durch folgendes Skript:

Skript des Abfrage-Elements

Skript des Abfrage-Elements

import workItem from ‘work_item_split_gateway’;

workItem.setPrepare((ctx) => {});
workItem.setSplit((ctx) => {

// Dokument laden über die übergebene documentId
const document = ctx.services.documentService.readById(ctx.availableInput.documentId);

// Zuordnung zur Adresse (Account)
const accountId = document.accountId;

// Aggregation: Summe aller Nettoverkaufspreise für diesen Account (Hier müsste man auch Rechnungen etc einschränken)
const result = ctx.services.vqlService.queryAll(
`SELECT sum(totalNetPrice) FROM document.querySalesDocuments WHERE accountId = ${accountId}`
);
const totalNetSum = result?.[0]?.[“totalNetPrice.sum”] ?? 0;
ctx.services.logger.info(result?.[0]);
ctx.services.logger.info(totalNetSum);

// Entscheidung auf Basis der Gesamtsumme
if (totalNetSum > 10000 && document.documentTypeCategory === ‘CUSTOMER_OFFER’ ) {
return ‘SHOW_USER_DECISION’; // Falls der Schwellenwert überschritten wird
}
return ‘DO_NOTHING’; // Sonst keine Aktion
});

4

Füge im Reiter “Abzweigungen” die Abzweigungen SHOW_USER_DECISION und DO_NOTHING hinzu.

5

Klicke auf “Speichern“, um das Abfrage-Element anzulegen.

6

Füge anschließend das Benutzeraktion-Element hinzu und aktiviere den Toggle “Verantwortlicher Benutzer ist ausführender Benutzer“.

7

Stelle die folgenden Einstellungen im Reiter “Benutzeraktion” ein:

8

Nach dem Speichern des Elements “Benutzeraktion” füge ein Benutzerskript-Element hinzu.

9

Im Reiter “Skript” gib folgenden Skript ein und speichere das Element:

Skript des Benutzerskripts-Element

Skript des Benutzerskripts-Element

import workItem from ‘work_item_script’;

/**
* Vorbereitung – optional (z. B. Logging-Kontext setzen)
*/
workItem.setPrepare((ctx) => {
// keine spezielle Vorbereitung erforderlich
});

/**
* Guard – Antwort auf die Benutzeraktion bestimmt, ob der Skript ausgeführt wird
*/
workItem.setGuard((ctx) => {
let userDecision = ctx.parameters[‘ADD_PRESENT’];
if (userDecision == ‘true’) {
return true;}
if (userDecision == ‘false’) {
return false;}
});
/**
* Action – lädt den Beleg, fügt eine neue Position hinzu und hinterlegt einen Price-Modifier
*/
workItem.setAction((ctx) => {
const {
documentService,
articleService,
utils,
logger,
} = ctx.services;
const { documentId } = ctx.parameters;
const document = documentService.readById(documentId);
if (!document) {
logger?.warn?.(`Dokument ${documentId} nicht gefunden – Abbruch.`);
return;
}
const articleNumber = ‘ACC-1083’; // ⚠️ hier Artikelnummer. anpassen
const article = articleService.readByNumber(articleNumber);
if (!article) {
logger?.warn?.(`Artikel ${articleNumber} nicht gefunden – Abbruch.`);
return;
}
const newLine = documentService.getNewDocumentLine();
newLine.articleId = article.id;
newLine.number = article.number;
newLine.name = article.name;
newLine.description = ‘Dein Geschenk’;
newLine.quantity = 1;

// Price-Modifier mit Factory erzeugen
const priceModifier = documentService.getNewDocumentPriceModifier();
priceModifier.name = ‘Geschenkrabatt’; // ⚠️ siehe Hinweis unten zu Feldnamen
priceModifier.value = 100; // 100%
priceModifier.modifierType = ‘DISCOUNT’;
priceModifier.valueType = ‘PERCENT’;
priceModifier.sourceType = ‘CUSTOM’;

// Statt push(): Liste in einem Schritt neu setzen (bewahrt evtl. vorhandene Modifiers)
newLine.priceModifiers = [ …(newLine.priceModifiers || []), priceModifier ];
ctx.services.logger.info(newLine);

// Position anhängen
document.lines = [ …(document.lines || []), newLine ];

// Beleg aktualisieren
const updateRequest = documentService.getUpdateDocumentRequest();
updateRequest.document = document;
documentService.update(updateRequest);
});

10

Füge zwei Abschließen–Elemente hinzu und verbinde die Elemente untereinander, wie im folgenden Bild dargestellt. Die einzelnen Elemente sind anhand der entsprechenden Icons zu erkennen.

11

Speichere den Workflow. Nach Aktivierung des Workflows wird dieser nach dem Speichern von zukünftigen Belegen ausgeführt.