Automation l Workflow-Bibliothek

Diese Dokumentation enthält Bibliotheken, die zu Automation | Workflow (agorum core workflow 3.0) gehören und hauptsächlich zum Entwickeln von Subworkflows und Knoten genutzt werden.

Sie erfahren, wie Sie die Workflow-Anhänge sowie Variablen validieren, laden und speichern können. 

Verwendung

Allgemeine Bibliothek laden

// Übergabe des eindeutigen Namens eines Knotens
let NODE_NAME = 'agorum_office_fill';
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, NODE_NAME);

// Beispiel mit explizitem Setzen des sessionControllers
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, NODE_NAME, sc);

// Siehe unten: Laden mit bereits vorhandenen Parametern
/* global sc, sca, token, instance, outlets, inlet, parameters */
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);

Funktionen und Bibliotheken verwenden

Über das Einbinden der Bibliothek workflow können Sie diverse Bibliotheken und Funktionen verwenden, in dem folgenden Beispiel die Funktion validate.

In folgendem Beispiel wird geprüft, ob der Parameter path vom Datentyp string ist und zwingend vorhanden ist. Falls nein, erscheint eine Fehlermeldung. 

let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);
workflow.validate.string('path', false);

Eine einzelne Bibliothek laden

Wenn Sie nur einzelne Funktionen verwenden möchten, können Sie diese als separate Bibliothek laden. Sie müssen dann nicht die Bibliothek workflow laden.

let wfValidate = require('/agorum/roi/customers/acworkflow/js/workflow/validate')(parameters);
wfValidate.string('path', false);

Alle Bibliotheken laden

// Entweder alle gesammelt laden ...
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);

// ... oder die Bibliotheken einzeln laden
let wfValidate = require('/agorum/roi/customers/acworkflow/js/workflow/validate')(nodeParameters);
let wfParameters = require('/agorum/roi/customers/acworkflow/js/workflow/parameters')(nodeParameters);
let wfVariables = require('/agorum/roi/customers/acworkflow/js/workflow/variables')(token, nodeParameters);
let wfObjects = require('/agorum/roi/customers/acworkflow/js/workflow/objects')(token, nodeParameters);

Parameter laden (per NODE_NAME)

Die Workflow 3.0-Bibliothek verwendet intern die Parameter des Subworkflows. Diese müssen Sie beim Laden der Bibliothek angeben.

Wird in dem erstellten Subworkflow der Knoten, der diese Bibliothek verwendet, nicht an erster Stelle verwendet, speichern Sie die Parameter in einem internen Bereich für den Knoten zwischen. Diese Funktion übernimmt der Knoten agorum.basic.initialize, der dann an erster Stelle steht.

Im Knoten initzialize geben Sie einen internen Namen an, dieser wird hier in dem Beispiel als NODE_NAME verwendet. Dort speichern und übergeben Sie den internen Namen des Subworkflows.

Die Workflow-Bibliothek arbeitet stark mit diesem Knoten zusammen. Wenn die Bibliothek einen Namen erhält, versucht sie, genau deren Parameter aus dem internen Bereich auszulesen.

let NODE_NAME = 'agorum_office_fill';
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, NODE_NAME);

// Zugriff auf interne Daten des Knotens
let nodeScope = workflow.nodeScope;
let nodeParameters = nodeScope.parameters;

Dieses Beispiel orientiert sich am Knoten agorum.office.fill. Als erster Knoten wird der Knoten initialize verwendet und erhält den technischen Namen agorum_office_fill.

Beim Laden der Workflow-Bibliothek übergeben Sie diesen Namen, damit die Parameter dort ausgelesen werden. Das Arbeiten über diesen Weg mit dem Parameter NODE_NAME stellt den empfohlenen Weg dar und wird daher in allen zukünftigen Beispielen verwendet.

Übergabe vorhandener Parameter

Neben dem Laden der Parameter können Sie diese direkt übergeben.

Bei Subworkflows bekommt nur der Startknoten (der erste Knoten, der ausgeführt wird) die Parameter übergeben. Diese sind im Header des Skripts zu finden:

/* global sc, sca, token, instance, outlets, inlet, parameters */

Ohne „agorum.basic.initialize“ laden

/* global sc, sca, token, instance, outlets, inlet, parameters */

// Übergabe der Parameter
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);

// Beispiel mit explizitem setzen des sessionControllers
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters, sc);

workflow (workflow/index.js)

• Fasst die hier beschriebenen Standard-Bibliotheken zusammen (validate, parameters, variables und objects) und enthält die meistgenutzten Funktionen.
• Parameter (parameters) oder der NODE_NAME können mitgegeben werden. Aus dem NODE_NAME werden aus dem internen Bereich die zugehörigen Parameter geladen. Diese Variante ist für die Nutzung mit dem Knoten initialize ausgelegt.
• session controller (sc) ist optional. Wird dieser nicht angegeben, wird für Berechtigungen der Standardparameter Privileges geladen.
• Benötigt token + parameter (oder NODE_NAME) + optional sc.
• Löst intern den NODE_NAME auf, um an die Parameter zu kommen.

Funktionen

Diese Bibliothek enthält keine eigenen Funktionen.

Parameter

Folgende Parameter können übergeben werden:

Enthaltene Bibliotheken

• validate
• parameters
• variables
• objects

Eigenschaften

let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, NODE_NAME);
let objects = require('common/objects')(workflow.sc);

let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, NODE_NAME);
let internalData = workflow.nodeScope;

// Zugriff auf interne Daten des Knotens
let test = internalData.outputTarget;

// Zugriff auf die parameter des Knotens
let param = internalData.parameters;

validate

Validiert Parameter nach deren Typ. Sie können unterscheiden, ob Parameter optional sind oder nicht und folgende Datentypen angeben:

• object
• variable
• Datentypen
  • boolean
  • array
  • string
• date
• long
• float

Prüfung mit validate

Die Funktionen von validate prüfen Parameter nach folgenden Regeln:

• Ist optional nicht gesetzt oder false, muss der Parameter vorhanden sein. Fehlt er, wirft die Funktion den Fehler Parameter "name" not found.
• Das System prüft den Datentyp nur, wenn der Parameter einen Wert hat, der in JavaScript als wahr gilt. Leere Werte wie ein leerer Text, false oder 0 bestehen daher jede Typprüfung.
• Bei einem falschen Typ lautet der Fehler Parameter name has to be of type typ: wert.

Die Bibliothek laden

Direktes Laden über die Bibliothek „workflow“

workflow.validate.string('path', false);

Eigenständiges Laden der Bibliothek

Das Folgende muss nur mitgegeben werden, wenn die Bibliothek manuell, d. h. nicht über workflow.validate geladen wird:

• parameters
• optional: sc

let wfValidate = require('/agorum/roi/customers/acworkflow/js/workflow/validate')(parameters, sc); ​​​​
wfValidate.string('path', false);

Funktionen

Für jeden Typ muss nur der Name und der Hinweis optional / nicht optional angegeben werden. Parameter und sc werden am Anfang beim Laden der Bibliothek mitgegeben.

workflow.validate.object('content', false, sc);

workflow.validate.boolean('content', false);

workflow.validate.array('content', false);

workflow.validate.string('content', false);

workflow.validate.variable('content', false);

workflow.validate.date('content', false);

workflow.validate.long('content', false);

workflow.validate.float('content', false);

Aufruf

• In der Liste der Funktionen kann ein Datentyp ausgesucht werden, der aufgerufen wird.
• Übergeben wird der parameter name, der geprüft wird.
• Bei einigen Funktionen kann zusätzlich ein session controller übergeben werden.

Folgende Eigenschaften können angegeben werden:

Beispiel

In diesem Beispiel existiert der Parameter perObject, der vom Typ boolean sein soll, sofern der Parameter angegeben ist. Der Parameter ist hier jedoch optional, d. h. es kommt zu keiner Fehlermeldung, wenn er nicht angegeben ist.

Der Parameter abc ist eine Pflichtangabe.

let wfValidate = require('/agorum/roi/customers/acworkflow/js/workflow/validate')(parameters);

// Optionaler Parameter
wfValidate.boolean('perObject', true);

// Pflicht Parameter
wfValidate.object('abc', false);

// Übergabe eines session controllers
wfValidate.object('abc', false, sca);

parameters

Unterstützt Knoten im Umgang mit Parameter.

Die Bibliothek laden

Direktes Laden über die Bibliothek „workflow“

workflow.​​​​​parameters.privileged();

Eigenständiges Laden der Bibliothek

Das Folgende muss nur mitgegeben werden, wenn die Bibliothek manuell, d. h. nicht über workflow.parameters geladen wird:

• parameters
• optional: sc

let wfParameters = require('/agorum/roi/customers/acworkflow/js/workflow/parameters')(parameters, sc); ​​​​
​​​​​wfParameters.privileged();

Funktionen

workflow.parameters.get('ac_status', false);

workflow.parameters.find('ac_object');

workflow.parameters.privileged();

Beispiel für die Funktion „find“

Es wird angenommen, dass der Benutzer in den Parametern /agorum/roi/Files/Demo als Pfadname eingetragen hat. Der Name des Parameters heißt im Subworkflow baseFolder. Um die ID des Ordners zu ermitteln, kann workflow.parameters.find() verwendet werden.

workflow.parameters.find('baseFolder');

In dem Beispiel würde die ID des Ordners Demo zurückgeliefert werden.

Beispiele für die Funktion „privileged“

sc wird automatisch durch den übergebenen Parameter erkannt, wenn dort der Parameter privileges vorhanden ist:

​​​​​​ let parameters = require('/agorum/roi/customers/acworkflow/js/workflow/parameters')(parameters);

sc wird übergeben und explizit angegeben. Der Knoten hat somit keinen Parameter privileges oder verwendet ihn nicht:

​​​​​​ let workflowParameters = require('/agorum/roi/customers/acworkflow/js/workflow/parameters')(parameters, sc);

variables

Erleichtert das Holen und Setzen von Variablen. Sie können auch tiefere Strukturen laden. 

Die Funktionen get, set und merge unterstützen Dot-Notation, um auf verschachtelte Strukturen zuzugreifen.

Beispiel: workflow.variables.get('config.timeout', true) greift auf token.variables.config.timeout zu.

Nicht vorhandene Zwischensegmente werden bei set und merge automatisch als leere Objekte angelegt.

Beim Lesen mit get gilt: Fehlt der Wert (nicht vorhanden oder null) und ist optional nicht gesetzt, wirft die Funktion den Fehler Variable "key" not found. Mit optional = true liefert sie stattdessen undefined. Das gilt auch, wenn eine Zwischenebene fehlt. Ein leerer Schlüssel liefert alle Variablen des Tokens.

Die Bibliothek laden

Direktes Laden über die Bibliothek „workflow“

let sys_acw_processName = workflow.variables.get('sys_acw_processName', false);

Eigenständiges Laden der Bibliothek

Das Folgende muss nur mitgegeben werden, wenn die Bibliothek manuell, d. h. nicht über workflow.variables geladen wird:

• token
• parameters

let wfVariables = require('/agorum/roi/customers/acworkflow/js/workflow/variables')(token, parameters);
let sys_acw_processName = wfVariables.get('sys_acw_processName', true);

Funktionen

// Holen des optionalen parameters path
let path = workflow.variables.get('path', true);

// Setzen eines Status ag_status auf den Wert "in Bearbeitung"
workflow.variables.set('ag_status', 'in Bearbeitung');

// Bestehende Konfiguration erweitern, ohne andere Eigenschaften zu verlieren
workflow.variables.merge('config', {
  timeout: 5000,
  retries: 3
});

// Vorher: config = { host: 'server1', timeout: 3000 }
// Nachher: config = { host: 'server1', timeout: 5000, retries: 3 }

Beispiel für die Funktion „get“

Es wird angenommen, dass der Workflow einen Parameter mit dem Namen resultVariable besitzt. Dieser Parameter wird bei Nutzung des Workflows mit einem Variablennamen befüllt. Um diesen Variablennamen zu erhalten, benötigen Sie workflow.parameters.get, wobei Sie anschließend den Inhalt mit workflow.variables.get aus der eingegebenen Variable holen können.

workflow.variables.get(workflow.parameters.get('resultVariable', false), false);

objects

Behandelt das Arbeiten mit Anhängen (attachments) oder anderen Objekten im Workflow.

Die Bibliothek wertet folgende Parameter aus. Alle sind optional. Fehlen inputVariable oder outputVariable, trägt die Bibliothek sys_acw_attachments in das übergebene Parameter-Objekt ein.

Die Bibliothek laden

Direktes Laden über die Bibliothek „workflow“

let attachments = workflow.objects.get();

Eigenständiges Laden der Bibliothek

Das Folgende muss nur mitgegeben werden, wenn die Bibliothek manuell, d. h. nicht über workflow.objects geladen wird:

• token
• parameters
• sc (optional): Session, mit der die Bibliothek die Objekte der Anhänge lädt. Ohne Angabe verwendet sie den administrativen session controller sca. Beim Laden über die Bibliothek workflow gilt der session controller, der sich aus privileges ergibt.

let wfObjects = require('/agorum/roi/customers/acworkflow/js/workflow/objects')(token, parameters, sc);
let attachments = wfObjects.get();

Funktionen

// Laden der aktuellen Anhänge
let attachments = workflow.objects.get();

// update attachments
let newAttachments = [];
// ...

// Überschreiben der Anhänge und setzen der neuen
workflow.objects.set(newAttachments);

workflow.objects.fork([
  {
    name: 'left',
    objects: attachments.slice(0, parameters.index)
  },
  {
    name: 'right',
    objects: attachments.slice(parameters.index)
  }
]);

// Iteriere über die perObject Anhänge und führe für jedes Objekt die Funktion aus
workflow.objects.load(obj => {
  // Liefere Daten für dieses Objekt zurück
  return {
    ag_status: 'Test',
    name: obj.name
  };
});

// Hole den ag_status der Objekte. Hier wird nur der letzte Wert gespeichert. 

let fileStatus;

// Iteriere über die perObject Anhänge und führe für jeden die Funktion saveResult aus
workflow.objects.save((obj, dataToSave) => {
  fileStatus = dataToSave.ag_status;
});

// Scope-Daten für Objekte auslesen
let attachments = workflow.objects.get();
workflow.objects.getScope(attachments, (obj, scope) => {
  console.log(obj.name, scope);
});

// Scope-Daten für Objekte setzen
let attachments = workflow.objects.get();
workflow.objects.setScope(attachments, obj => {
  return {
    ag_status: 'verarbeitet',
    name: obj.name
  };
});

Weitere Bibliotheken

Für Automation | Workflow stehen zusätzlich zur Bibliothek workflow die Bibliotheken filter und definition bereit. Sie laden Sie einzeln.

filter

Die Bibliothek filter bereitet einen Filter-Parameter auf, damit Sie ihn immer als Array verwenden können. Die Knoten zum Laden und Speichern von Metadaten nutzen sie, siehe die Beispiele am Ende der Seite.

let filterLib = require('/agorum/roi/customers/acworkflow/js/common/filter');

filterLib.convert('name');
// ['name']

filterLib.convert(['name', 'size']);
// ['name', 'size']

filterLib.convert(undefined);
// undefined

definition

Die Bibliothek definition findet die Definition eines Workflows. Sie arbeitet mit den Workflows, die im Workflow-Repository (/agorum/roi/workspace/acworkflow/repository) bereitgestellt sind. Ein Workflow liegt dort in einem Ordner je Version, der Ordnername ist die Versionsnummer. Die Definition ist die Datei definition.acwd in diesem Ordner.

let definitionLib = require('/agorum/roi/customers/acworkflow/js/common/definition');

// latest version by name
let latest = definitionLib.getWorkflowDefinition('projekt.workflow.name');

// specific version by path
let version = definitionLib.getWorkflowDefinition(
  '/agorum/roi/workspace/acworkflow/repository/projekt/workflow/name/3/definition.acwd'
);

let uuids = definitionLib.getRegisteredWorkflows();
let objects = require('common/objects');

// log the name of each workflow folder
uuids.forEach(uuid => console.log(objects.find(uuid).firstParent.firstParent.name));

Komplette Beispiele

Knoten „agorum.object.metadata.load“

Das folgende Beispiel orientiert sich am Knoten agorum.object.metadata.load:

/* global sc, sca, token, instance, outlets, inlet, parameters */
// Laden der Bibliothek mit direkten parametern
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);

// Laden weiterer Bibliotheken
let metadata = require('common/metadata');
let filterLib = require('/agorum/roi/customers/acworkflow/js/common/filter');

// Validierung des Filter Parameters, dieser ist optional und vom Typ ein array
workflow.validate.array('filter', true);

// Funktion, um die Daten zu Laden
let loadData = obj => {
  let m = metadata();

  if (parameters.filter) {
    // load filtered metadata
    m.load.apply(m, [ obj ].concat(filterLib.convert(parameters.filter)));
  }
  else {
    // load all metadata
    m.load(obj);
  }

  return m.data();
};

// Iteriere über die perObject Anhänge und führe für jeden die Funktion loadData aus
workflow.objects.load(loadData);

Knoten „agorum.object.metadata.save“

Das folgende Beispiel orientiert sich am Knoten agorum.object.metadata.save:

/* global sc, sca, token, instance, outlets, inlet, parameters */
// Laden der Bibliothek mit direkten parametern
let workflow = require('/agorum/roi/customers/acworkflow/js/workflow')(token, parameters);

// Laden weiterer Bibliotheken
let metadata = require('common/metadata');
let filterLib = require('/agorum/roi/customers/acworkflow/js/common/filter');

// Validierung des Filter Parameters, dieser ist optional und vom Typ ein array
workflow.validate.array('filter', true);
let filter = parameters.filter;

// Funktion, um die Daten zu Speichern
let saveResult = (obj, dataToSave) => {
  if (dataToSave) {
    let m = metadata(dataToSave);

    if (filter) {
      // load filtered metadata
      m.save.apply(m, [ obj ].concat(filterLib.convert(filter)));
    }
    else {
      // load all metadata
      m.save(obj);
    }
  }
};

// Iteriere über die perObject Anhänge und führe für jeden die Funktion saveResult aus
workflow.objects.save(saveResult);