Workflow 3.0-Bibliothek

Diese Dokumentation enthält Bibliotheken, die zum 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.
  • Ausgelegt für die Nutzung mit dem intialize-Knoten.
• 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

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 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');

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 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 (wird meistens nicht benötigt, aktuell nur für die Funktion object)

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;
});

assignment

Dient zum programmatischen Lesen und Setzen von UI-Zuweisungen von Bearbeitern in Workflow-Knoten. Mit der assignment-Bibliothek können Sie

• aktuelle Berechtigungen per Skript abfragen
• aktuelle Berechtigungen per Skript zuweisen

Wenn ein Workflow nach einem Speichervorgang nicht mehr direkt dem aktuellen Bearbeiter zugewiesen ist, navigiert die UI zu einem anderen Eintrag. Mit dem assign-Knoten wird die Zuweisung für den nächsten Schritt durchgeführt. Mit dem Skript-Knoten wird die aktuelle Token-Zuweisung, token.variables.sys_acw_assignee, gelöscht.

Die Bibliothek laden

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

Funktionen

assignment.assign(token, {
  assignees: [
    'group:GRP_Demo',
    {
      attachmentPermission: 'write',
      id: 'group:d4wdr'
    }
  ],
  substitutes: [],
  viewers: [],
});

{"viewers":[],"substitutes":[],"assignees":[{"attachmentPermission":"read","id":"group:GRP_Demo"},{"attachmentPermission":"write","id":"group:d4wdr"}]}

assignment.getAssignment(token)

Beispiel

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

// Laden der assignment-Bibliothek 
let assignment = require('/agorum/roi/customers/acworkflow/js/common/assignment');

// Laden weiterer Bibliotheken
let objects = require('common/objects');

assignment.assign(token, {
  assignees: [
    // assignees: [{ attachmentPermission: 'read', id: 'group:GRP_Demo' }]
    'group:GRP_Demo',
    {
      attachmentPermission: 'write',
      id: 'group:d4wdr'
    }
  ],
  // substitutes werden zurückgesetzt
  substitutes: [],
  // viewers bleiben erhalten
  //viewers: [],
});

console.log(assignment.getAssignment(token));
// {"viewers":[],"substitutes":[],"assignees":[{"attachmentPermission":"read","id":"group:GRP_Demo"},{"attachmentPermission":"write","id":"group:d4wdr"}]}

// direkt einem Benutzer zuweisen
token.variables.sys_acw_assignee = objects.find('user:demo').UUID;

// Zuweisung zu Benutzer entfernen
//delete token.variables.sys_acw_assignee;

// Sendet das Token über das Standard-Outlet
token.leave('');

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);