Akten und Ordnerstrukturen per JavaScript mit dem structure-builder anlegen

Mit dem structure-builder legen Sie Akten und andere Ordnerstrukturen inklusive Metadaten, ACLs, Benutzergruppen und Systemflags per JavaScript an, etwa eine Kundenakte oder eine Projektakte. Die Struktur beschreiben Sie in einer structure-yml-Datei mit Platzhaltern. Beim Aufruf übergeben Sie die Werte für die Platzhalter und optional einen Startordner.

Vorgehensweise im Überblick

1. Legen Sie die Struktur der Akte in einer structure-yml-Datei im Ordner yml Ihres Konfigurationsprojekts an, etwa structure-projektakte.yml.
2. Verwenden Sie in Ordnernamen und Metadaten Platzhalter, etwa ${projektNummer}.
3. Markieren Sie den Ordner, der die Akte selbst ist, mit <--.
4. Rufen Sie den structure-builder in einem JavaScript auf und übergeben Sie die Werte für die Platzhalter.

Die structure-yml für eine Akte schreiben

Das folgende Beispiel beschreibt eine Projektakte. Ein Kunde kann mehrere Projektakten haben. Die Projektakte liegt deshalb im Konfigurationsprojekt des Kunden und enthält die Unterordner Angebot, Vertrag und Korrespondenz.

Speicherort: /agorum/roi/customers/<Konfigurationsprojekt>/yml/structure-projektakte.yml

#
# Projektakte: ein Kunde hat mehrere Projektakten
#
# Platzhalter:
#   ${kunde}          Name des Kunden
#   ${projektNummer}  Nummer des Projekts, Name der Projektakte
#   ${projektName}    Name des Projekts

_prefix: agorum_doc_test_
_postfix: Bereich
_aclPrefix: ACL_agorum_doc_test_
_grpPrefix: GRP_agorum_doc_test_

+ ${kunde:f} -- Kunde:
  + ${projektNummer:f} -- Projektakte <--:
    ~~agorum_doc_test_projektNummer: ${projektNummer}
    ~~agorum_doc_test_projektName: ${projektName}
    + Angebot:
    + Vertrag:
    + Korrespondenz:

Die wichtigsten Bestandteile:

Bestandteil	Bedeutung
${kunde:f}	Platzhalter. Er wird beim Aufruf durch den Wert ersetzt, den Sie unter diesem Namen übergeben. Platzhalter können in Ordnernamen, ACL-Namen und Metadatenwerten stehen. Der Zusatz :f ersetzt Zeichen, die im Dateisystem nicht erlaubt sind, durch _. Aus Müller/Söhne wird so der Ordner Müller_Söhne.
-- Kunde	Legt die Metadaten area und identifier des Ordners fest. Ohne -- verwendet das System den Ordnernamen.
<--	Markiert den Zielordner. Der Aufruf create() gibt diesen Ordner zurück. update() verwendet ihn, um die Akte zu finden. Ohne die Markierung gibt create() nichts zurück.
~~agorum_doc_test_projektName: ${projektName}	Setzt ein vererbtes Metadatum am Ordner. Die Unterordner und Dokumente der Akte erben es.
_prefix: agorum_doc_test_	Präfix der Metadaten, die das System aus den Ordnernamen erzeugt. Bei diesem Beispiel setzt es zusätzlich agorum_doc_test_kunde mit dem Namen des Kunden und agorum_doc_test_projektakte mit der Projektnummer. Die Projektakte erbt das Metadatum des Kunden.

Die Akte per JavaScript anlegen

Das folgende JavaScript legt eine Projektakte an. Der Ordner Projektakten ist der Startordner.

let objects = require('common/objects');
let structureBuilder = require('/agorum/roi/customers/Standard/js/structure-builder');

let yaml = objects.find('/agorum/roi/customers/<Konfigurationsprojekt>/yml/structure-projektakte.yml');
let startFolder = objects.find('/agorum/roi/Files/Projektakten');

let akte = structureBuilder(yaml).create(startFolder, {
  kunde: 'Muster GmbH',
  projektNummer: 'P-2026-001',
  projektName: 'Neubau Lagerhalle',
});

console.log('Akte angelegt: ' + akte.anyFolderPath);

Ergebnis: Das System legt den Pfad /agorum/roi/Files/Projektakten/Muster GmbH/P-2026-001 mit den Unterordnern Angebot, Vertrag und Korrespondenz an und setzt die Metadaten. akte ist der Ordner P-2026-001.

Parameter und Rückgabewerte

Aufruf	Beschreibung
structureBuilder(yaml)	Erzeugt den Builder. yaml ist die structure-yml als Datei-Objekt oder als Text.
structureBuilder(yaml, true)	Setzt alle ACLs und Flags der vorhandenen Ordner neu. Verwenden Sie diesen Aufruf nur zum Testen.
create(data)	Legt die Struktur an. data enthält die Werte der Platzhalter. Die Struktur beginnt im Wurzelverzeichnis, in der structure-yml steht deshalb ein absoluter Pfad.
create(startFolder, data)	Legt die Struktur unterhalb des Startordners an.
update(akte, data)	Ändert eine vorhandene Akte, siehe Eine vorhandene Akte ändern.
update(startFolder, akte, data)	Wie oben, mit ausdrücklich angegebenem Startordner.
metadata()	Gibt eine metadata.yml für die gesetzten Metadaten als Text zurück.
result(object)	Gibt eine Liste der geänderten Objekte zurück (Einträge refresh:<ID>). Als letzten Eintrag hängt es das übergebene Objekt an.

create() und update() geben den mit <-- markierten Ordner zurück.

Startordner

Ob Sie einen Startordner angeben, hängt davon ab, wie die structure-yml beginnt. Es gibt zwei Varianten:

Variante	Beispiel
Die structure-yml beginnt mit einem relativen Namen. Sie geben den Startordner beim Aufruf an.	+ ${kunde:f} -- Kunde: create(startFolder, data)
Die structure-yml beginnt mit einem absoluten Pfad. Sie geben keinen Startordner an.	+ /agorum/roi/Files/Projektakten -- Projektakten: create(data)

Sprungziel und angelegte Ordner weiterverwenden

Der Ordner, den Sie in der structure-yml mit <-- markieren, ist das Sprungziel. create() und update() geben ihn zurück. Von diesem Ordner aus erreichen Sie die Ordner, die der structure-builder angelegt hat. Bei der Anlage über den smart assistant konfigurator entspricht das dem Sprungziel und dem Rückgabewert der Anlage.

let akte = structureBuilder(yaml).create(startFolder, data);

// the Sprungziel by its UUID, e.g. to hand it over to another script
let uuid = akte.UUID;
let again = objects.find(uuid);

// the folders below the Akte
akte.items().map(item => item.name); // Angebot, Korrespondenz, Vertrag
let vertrag = akte.getItem('Vertrag');

// the folders above the Akte
let kunde = akte.firstParent;

// by path
let byPath = objects.find(akte.anyFolderPath + '/Vertrag');

// continue working in a created folder
let entwuerfe = akte.getItem('Angebot').createPath('Entwuerfe');

// all Projektakten of a customer
let total = objects
  .query('inpath:' + kunde.ID + ' identifier_ci:Projektakte')
  .limit(0)
  .search().total;

Aufgabe	Aufruf
Sprungziel weitergeben	akte.UUID, später wieder mit objects.find(uuid) laden. Die Beispiel-Bibliothek in undefined>Eingaben vor dem Anlegen einer Akte prüfen und Meldungen anzeigen gibt deshalb die UUID zurück.
Unterordner finden	akte.items() liefert alle, akte.getItem('Name') einen bestimmten Unterordner.
Übergeordneten Ordner finden	akte.firstParent, im Beispiel der Kunde. Von dort liefert items() alle Projektakten des Kunden.
Ordner über den Pfad finden	objects.find(akte.anyFolderPath + '/Vertrag')
In einem angelegten Ordner weiterarbeiten	Etwa akte.getItem('Angebot').createPath('Entwuerfe') für einen weiteren Unterordner.
Alle Akten eines Bereichs suchen	Suche mit inpath: und identifier_ci:Projektakte. identifier und area setzt der Zusatz -- Projektakte in der structure-yml.

Markieren Sie in der structure-yml den Ordner, mit dem Sie weiterarbeiten wollen, mit <--. Fehlt die Markierung, gibt create() nichts zurück. Dann müssen Sie die Akte über den Pfad suchen. result(akte) liefert zusätzlich die Liste der geänderten Objekte, siehe die Tabelle der Rückgabewerte.

Mehrfacher Aufruf mit denselben Werten

Der structure-builder verwendet vorhandene Ordner und legt nur an, was fehlt. Rufen Sie create() mit denselben Werten ein zweites Mal auf, erhalten Sie dieselbe Akte zurück und das System legt keine zweite Akte an. Das ist praktisch, bedeutet aber auch: Eine bereits vorhandene Projektnummer fällt beim Anlegen nicht auf. Prüfen Sie deshalb vor dem Aufruf, ob es die Akte schon gibt, siehe undefined>Eingaben vor dem Anlegen einer Akte prüfen und Meldungen anzeigen.

Platzhalter ohne Wert

Der Rückgabewert von create() ist in diesem Fall nicht die Akte, sondern der übergeordnete Ordner, im Beispiel der Ordner des Kunden. Prüfen Sie deshalb vor dem Aufruf, ob alle Platzhalter im Ordnernamen einen Wert haben.

Eine vorhandene Akte ändern

Mit update() ändern Sie die Metadaten einer vorhandenen Akte. Sie geben die Akte und die neuen Werte an:

let akte = objects.find('/agorum/roi/Files/Projektakten/Muster GmbH/P-2026-001');

structureBuilder(yaml).update(akte, {
  kunde: 'Muster GmbH',
  projektNummer: 'P-2026-001',
  projektName: 'Neubau Lagerhalle, Bauabschnitt 2',
});

Den Startordner ermittelt update() selbst: Es geht von der Akte so viele Ebenen nach oben, wie die structure-yml bis zum Ordner mit <-- verschachtelt ist. Im Beispiel ist das der Ordner Projektakten.

Ändern sich Werte, die im Ordnernamen stehen, benennt das System die Akte um und verschiebt sie. Das Objekt bleibt dabei dasselbe, es behält seine UUID, seine Dokumente und seinen Inhalt. Wird zum Beispiel der Kunde von Kunde A auf Kunde B und die Projektnummer von P-3000 auf P-3001 geändert, liegt die Akte danach unter Kunde B/P-3001. Den Ordner Kunde B legt das System an, falls er fehlt. Der Ordner Kunde A bleibt bestehen.

Metadaten-Vorlage erzeugen

Der structure-builder setzt Metadaten, die im System noch nicht definiert sein müssen. Mit metadata() erzeugen Sie nach dem Anlegen den Rohentwurf einer metadata.yml:

let builder = structureBuilder(yaml);

builder.create(startFolder, data);

console.log(builder.metadata());

Ergebnis:

# https://nodeca.github.io/js-yaml/

# -- global
_group: agorum_doc_test
_prefix: agorum_doc_test_
_dataPrefix: MAIN_MODULE_MANAGEMENT/customers/agorum_doc_test/Data/
_csvPrefix: /agorum/roi/customers/agorum_doc_test/csv/
_encoding: UTF-8

_default:
  type: string
  kind: inherited

# -- fields
kunde:
  displayName: kunde
  data: [ ]

projektakte:
  displayName: projektakte
  data: [ ]

projektNummer:
  displayName: projektNummer
  data: [ ]

projektName:
  displayName: projektName
  data: [ ]

projektakteBereich:
  displayName: projektakteBereich
  data: [ ]

Vom smart assistant konfigurator umsteigen

Die folgende Tabelle zeigt, was Sie in der Anlage-Konfiguration des agorum core smart assistant konfigurators eingetragen haben und wo Sie es beim structure-builder finden:

Anlage im smart assistant konfigurator	structure-builder
Ordnerstruktur im Elemente-Baum	structure-yml mit +-Einträgen
Platzhalter aus den Metadaten der Anlage	Platzhalter ${name} und die Werte im Objekt data
Metadaten der angelegten Ordner	~~ und ~ in der structure-yml
Zielordner der Anlage	Startordner in create(startFolder, data) oder absoluter Pfad in der structure-yml
Sprungziel und Rückgabewert	Ordner mit <-- und der Rückgabewert von create()
JavaScript (zuvor) und JavaScript (danach)	Ihr JavaScript vor und nach dem Aufruf von create(), ein Beispiel mit Prüfung und Masken beschreibt undefined>Eingaben vor dem Anlegen einer Akte prüfen und Meldungen anzeigen
Struktur testen	Aufruf in der JavaScript-Konsole mit Testwerten
service.create('Name', folder, parameter)	structureBuilder(yaml).create(folder, data)

Die Anlage-Konfiguration prüfen Sie im smart assistant konfigurator, siehe Elemente im agorum core smart assistant konfigurator anlegen.