Struktur mit der Datei „structure-basis.yml“ definieren

Mit der Datei structure.yml legen Sie im agorum core explorer Ordnerstrukturen inklusive ACLs, Benutzergruppen, Systemflags und Metadaten an.
Wenn Sie mit dem agorumc ore template manager ein neues Konfigurationsprojekt erstellen, wird die Datei structure-basis.yml mit den Standardeinstellungen im Ordner yml angelegt.

structure-basis.yml ausführen

Die Datei structure-basis.yml führen Sie mit einem JavaScript aus. Das kann etwa über die JavaScript-Konsole oder mit einem JavaScript beim Deployment geschehen.

Das JavaScript zum Aufruf der Datei structure-basis.yml über den structure-builder.js kann folgenden Aufbau haben:

/* global sc */

global.sessionControllerAdmin = sc;

let objects = require('common/objects');
let sb = require('/agorum/roi/customers/Standard/js/structure-builder');
let yamlbasis = objects.find('/agorum/roi/customers/<CONFIGURATIONPROJECT>/yml/structure-basis.yml');

sb(yamlbasis).create();

// ATTENTION: when using true, everything is reset, should only be used for testing
// sb(yamlbasis, true).create();

Das Skript wird normalerweise ohne den Parameter true aufgerufen, da dieser sehr viele Einstellungen neu setzt und das System die betroffenen Objekte erneut indizieren muss.

Speicherort der Datei

/agorum/roi/customers/<Konfigurationsprojekt>/yml/structure-basis.yml

Aufbau der Datei

Das folgende Beispiel zeigt die Einträge in der Datei structure-basis.yml mit den Standardeinstellungen für das Testprojekt agorum.test.temp:

#
# This file defines the base structure with access rights
#

_prefix: agorum_test_temp_
_postfix: Bereich
_aclPrefix: ACL_agorum_test_temp_
_grpPrefix: GRP_agorum_test_temp_

#
# In _default everything can be set, what should be valid for each folder
#
_default:
  acl:
  unique: false
  systemFlags: 65564

_leaf:
  systemFlags: 28

# No area and identifier is to be set here.
#+ /agorum/roi/Files --:

#
# Internal workspace folder, can be used to store things for the module, e.g. for the drop area
#
+ /agorum/roi/workspace -- workspace:
  acl: acl:Published
  + agorum.test.temp:
    acl: acl:Published

Einstellungen in der Datei

_prefix

_prefix: demo_

Setzt das Präfix allen internen Namen von Metadaten voran, die durch die Struktur automatisch erzeugt werden (z. B. bei localIdentifiers).

Beispiel

demo_<Metadatum>

_postfix

_postfix: Bereich

Hängt das Postfix an interne Namen an, die bei aktivierten localIdentifiers automatisch erzeugt werden.

Beispiel

<Metadatum>_Bereich

_aclPrefix

_aclPrefix: ACL_DEMO_

Verwendet das Präfix für neu angelegte ACLs.

Beispiel

ACL_DEMO_<ACL>

_grpPrefix

_grpPrefix: GRP_DEMO_

Verwendet das Präfix für automatisch angelegte Benutzergruppen.

Beispiel

GRP_DEMO_<Gruppe>

_default

_default:
  acl:
  unique: false
  systemFlags: 65564

Definiert Einstellungen, die als Standardwerte für jeden angelegten Ordner gelten (sofern sie nicht am Ordner selbst überschrieben werden). Typisch sind hier: ACL-Erzeugung, unique und systemFlags.

_leaf

_leaf:
  systemFlags: 28

Definiert Einstellungen, die für jeden Endordner (oder Blatt-Ordner) gesetzt werden.

Ein Endordner ist ein Ordner, der in der Struktur am weitesten eingerückt ist (d. h. keine Unterordner mehr definiert).

Beispiel

Ordner 1
  Ordner 1.1
    Ordner 1.1.1
Ordner 2
  Ordner 2.1
Ordner 3

In diesem Beispiel sind demnach die Endordner:

• Ordner 1.1.1
• Ordner 2.1
• Ordner 3

Auf diese werden die Einträge unter _leaf: gesetzt.

Die Ordnerstruktur anlegen

Nach der Definition der globalen Einstellungen legen Sie die Ordnerstruktur an.

1. Definieren Sie einen Einstieg in die Struktur. Dazu stellen Sie ein + voran:

   + /agorum/roi/Files --:
   

   Das -- hinter Files bedeutet, dass das System die Metadaten area und identifier nicht setzen soll.
2. Rücken Sie die Unterordner jeweils in der nächsten Zeile um zwei Leerzeichen ein.
3. Kennzeichnen Sie diese Unterordner ebenfalls mit einem +.

   Beispiel

   + /agorum/roi/Files --:
     acl: acl:Published
     + Schulung:
       acl: acl:Published
       + Videos:
         acl: acl:Published
     + tmp_:
       acl: acl:Public
       flags: 39

Automatisch angelegte Metadaten

Wenn Sie per Datei structure-basis.yml einen Ordner erstellen, legt das System automatisch folgende Metadaten an:

+ /agorum/roi/Files --:
  acl: acl:Published
  + Schulung:
    acl: acl:Published
    localIdentifiers: true
    + Videos:
      acl: acl:Published
      localIdentifiers: true
  + tmp_:
    acl: acl:Public
    flags: 39

Keyword „acl“

Das Keyword acl definiert, welche ACL ein neu angelegter Ordner erhält. Es gibt mehrere Varianten:

• Vorhandene (System-)ACL verwenden
• Neue ACL automatisch erstellen (mit/ohne ID)
• Neue ACL mit festem Namen erstellen (mit/ohne ID)
• ACL vom Parent erben (acl: ^)

Hinweise zur Verwendung

• Wenn Sie nichts definieren, wird standardmäßig die ACL des übergeordneten Ordners vererbt.
• Wenn Sie in _default oder _leaf explizit eine ACL-Erstellung eingestellt haben, müssen Sie die Vererbung am Ordner explizit aktivieren: acl: ^.
• Wird eine ACL neu angelegt, wird diese automatisch unter dem Namen des zugehörigen Ordners abgelegt.
• Zu jedem neu angelegten ACL werden automatisch Benutzergruppen angelegt. Diese werden nach folgendem Vorgehen angelegt:

Name der Benutzergruppe
Präfix der Benutzergruppe + Name der ACL

Kein Endordner (_leaf nicht zutreffend)
Anlegen einer Read-Benutzergruppe: Gruppenname>_Read

Ist Endordner
Drei Benutzergruppen:
<Gruppenname>_Read
<Gruppenname>_Write
<Gruppenname>_All

Benutzergruppen werden an denselben Ordnern angelegt wie die ACL.

Das Keyword unique = definiert eine ACL als einzigartig, wenn true (Standard: false).

Beispiele (acl)

Möglichkeit 1: Vorhandene ACL wählen

+ /agorum/roi/Files/Demo:
  acl: acl:Public

Setzt die bereits vorhandene ACL Public auf den neu anzulegenden Ordner Demo.

Möglichkeit 2: Neue ACL mit ID des Ordners definieren

+ /agorum/roi/Files/Demo:
  acl:

Legt eine neue ACL an, die u. a. die Ordner-ID im Namen enthält. Das ist besonders hilfreich bei gleichen Strukturen mit identischen Ordnernamen in unterschiedlichen Pfaden.

• ACL_Demo stammt vom festgelegten _aclPrefix und _DEMO vom Namen des Ordners.
• Dieses Vorgehen hat bei gleichen Strukturen den Vorteil, dass die ACL immer eindeutig ist:

+ /agorum/roi/Files --:
  acl: acl:Published
    + Firma Kurz AG:
    acl:
    + Niederlassung 1:
      acl:
      + Finanzen:
        acl:
        + Belege:
          acl:
    + Niederlassung 2:
      acl:
      + Finanzen:
        acl:
        + Belege:
          acl:

Hier wäre die ACL auf den Ordnern Finanzen und Belege dasselbe, wenn diese ohne die ID angelegt wurden. Mit ID besitzen alle Ordner eine andere ACL und unterscheiden sich durch die ID im Namen der ACL.

Die ACL kann nicht in anderen Skripten verwendet werden, da der Name unbekannt ist. Soll die ACL auch anderweitig zur Verfügung stehen, empfiehlt sich Möglichkeit 5, bei der die Namen selbst vergeben werden.

Möglichkeit 3: Neue ACL ohne ID des Ordners definieren

+ /agorum/roi/Files/Demo:
  acl:
  unique: true

Durch unique: true entfällt die Ordner-ID im ACL-Namen. Dadurch lautet der Name des ACLs ACL_DEMO_Demo (_aclPrefix + Name Ordner). Der Name wird damit stabiler, setzt aber voraus, dass er eindeutig bleibt. 

Möglichkeit 4: Neue ACL mit ID des Ordners und mit festgelegten Namen definieren

+ /agorum/roi/Files/Demo:
  acl: Demo_demo

Legt die ACL mit dem Namen ACL_DEMO_<ID des Ordners>Demo_demo an, da das Präfix nicht weggelassen werden kann.

Möglichkeit 5: Neue ACL ohne ID des Ordners und mit festgelegten Namen definieren

+ /agorum/roi/Files/Demo:
  acl: Demo_demo
  unique: true

Legt die ACL mit dem Namen ACL_DEMO_Demo_demo an.

Dieses Vorgehen hat bei gleichen Strukturen den Vorteil, dass die ACL eindeutig ist und trotzdem einen eindeutigen Namen hat, den Sie in anderen Skripten verwenden können:

+ /agorum/roi/Files --:
  acl: acl:Published
  + Firma Lang AG:
    acl: "Firma Lang AG"
    unique: true
    + Niederlassung 1:
      acl: "Firma Lang AG_Niederlassung 1"
      unique: true
      + Finanzen:
        acl: "Firma Lang AG_Niederlassung 1_Finanzen"
        unique: true
        + Belege:
          acl: "Firma Lang AG_Niederlassung 1_Finanzen_Belege"
          unique: true
    + Niederlassung 2:
      acl: "Firma Lang AG_Niederlassung 2"
      unique: true
      + Finanzen:
        acl: "Firma Lang AG_Niederlassung 2_Finanzen"
        unique: true
        + Belege:
          acl: "Firma Lang AG_Niederlassung 2_Finanzen_Belege"
          unique: true

Der Name der ACL für .../Niederlassung 2/Finanzen/Belege lautet hier:

<ACL-Prefix>Firma Lang AG_Niederlassung 2_Finanzen_Belege

Möglichkeit 6: ACL vom Parent-Ordner erben

+ /agorum/roi/Files/Demo:
  acl: ^

Der Ordner Demo erbt die ACL des Ordners Files.

Keyword „generateGroups“

Steuert die Generierung von Benutzergruppen, die in Abhängigkeit der ACLs angelegt werden.

Wird eine ACL angelegt, wird im Standardfall eine Read-Benutzergruppe pro Ordner erzeugt. Bei Endordnern (den letzten Ordnern in der Ordnerstruktur) werden Read-, Write- und All-Benutzergruppen erzeugt.
Geben Sie das Keyword an, können Sie steuern, welche der 3 Benutzergruppen erstellt werden. Soll mehr als nur eine Benutzergruppe erzeugt werden, verwenden Sie den Trenner |.

In folgendem Beispiel werden die read-, write- und all-Benutzergruppen angelegt:

_default:
  acl:
  unique: true
  generateGroups: "read|all|write"

Mitglieder in Gruppen initial setzen

Optional können Sie initiale Mitglieder für die automatisch erzeugten Gruppen definieren:

+ /agorum/roi/Files/Projekt:
  acl:
  unique: true
  generateGroups: "read|write|all"
  read:
    - user:roi
    - group:Vertrieb
  write:
    - group:Sachbearbeitung
  all:
    - group:Administratoren

Metadaten „area“ und „identifier“ setzen

Auf einen neuen Ordner setzt das System automatisch die Metadaten „area“ und „identifier“. Beide erhalten standardmäßig den Namen des neuen Ordners.

Standard

+ /agorum/roi/Files/Demo:

Das System setzt auf den Ordner Demo die Metadaten area und identifier jeweils mit dem Wert Demo.

Anderen Wert setzen (gilt für area und identifier)

Sollen area und identifier einen anderen Namen erhalten, erreichen Sie dies mit dem Parameter --. Dazu tragen Sie den Parameter mit dem gewünschten Namen nach dem Ordnernamen und vor dem Doppelpunkt ein:

+ /agorum/roi/Files/Demo -- user:

Das Syste, setzt die Metadaten area und identifier jeweils mit dem Wert user  auf den Ordner Demo.

Nichts setzen (weder area noch identifier)

Sollen area und identifier nicht gesetzt werden, tragen Sie hinter dem Parameter nichts ein, auch kein Leerzeichen:

+ /agorum/roi/Files/Demo --:

Metadaten setzen

Sie können zusätzlich Metadaten auf einen neu angelegten Ordner setzen.

• Schreiben Sie den Namen des Metadatums zwingend mit dem definierten _prefix (z. B. demo_), sofern es sich um „Ihre“ Metadaten handelt.
• Der Name des Metadatums darf nicht mit dem Inhalt von _postfix enden. Metadaten, die mit dem Inhalt von _postfix enden, speichert das System nicht, da diese für den Automatismus mit der Option localIdentifiers: true reserviert sind (siehe Automatisch angelegte Metadaten).
• Stellen Sie ~ für ein nicht vererbtes Metadatum voran.
• Stellen Sie ~~ für ein vererbtes Metadatum voran.
• Ohne ~ oder ~~ handelt es sich um ein internes Attribut.

Beispiel

+ /agorum/roi/Files/Demo:
  ~demo_kbNummer: "12345"
  ~~demo_kbZeichen: "z776-ab"
  flags: 39
  systemFlags: 28

Das System setzt in diesem Beispiel folgende Metadaten:

~demo_kbNummer
nicht vererbt

~~demo_kbZeichen
vererbt

Listen / Multi-Metadaten (Array) korrekt angeben

Wenn ein Metadatum in metadata.yml als Array (Multi-Metadatum) definiert ist (z. B. Tags, Mehrfachauswahl, mehrere Werte), müssen Sie in der structure-basis.yml eine YML-Liste setzen.

Variante A: Einfache Liste von Strings

+ /agorum/roi/Files/Demo:
  ~~demo_tags:
    - "Newsletter"
    - "Wartungsvertrag"
    - "A-Kunde"

Variante B: Liste mit Zahlen/Boolean

+ /agorum/roi/Files/Demo:
  ~demo_jahre:
    - 2024
    - 2025
  ~demo_aktivFlags:
    - true
    - false

Variante C: Inline-Array (kurz)

+ /agorum/roi/Files/Demo:
  ~~demo_tags: ["Newsletter", "Wartungsvertrag", "A-Kunde"]

Variante D: Liste von Objekten (nur wenn das Metadatum ein JSON-Array erwartet)

Wenn Ihr Metadatum als Array von Objekten verwendet wird (z. B. ein JSON/Objekt-Array), können Sie auch eine Liste von Objekten setzen:

+ /agorum/roi/Files/Demo:
  ~~demo_contacts:
    - name: "Max Mustermann"
      email: "max@example.com"
    - name: "Erika Musterfrau"
      email: "erika@example.com"

Variante E: Globale Tags / Benutzer-Tags (Beispiele)

Typische Multi-Metadaten in agorum core sind Tags. Beispiel (globales Tagging):

+ /agorum/roi/Files/Demo:
  ~ag_tags:
    - "Newsletter"
    - "Wartungsvertrag"

Beispiel (persönliche Tags des aktuellen Benutzers):

+ /agorum/roi/Files/Demo:
  ~user_ag_tags:
    - "Wichtig"
    - "FollowUp"

Ordner verlinken

Sie können Ordner verlinken, indem Sie hinter dem neu anzulegenden Ordner den vollständigen Zielpfad angeben. Der neue Ordner sollte dazu idealerweise gleich heißen wie der letzte Ordner des Pfades, auf den Sie verlinken.

Beispiel

+ /agorum/roi/Files/Ablage:
  acl: acl:Published
  + tmp_: /agorum/roi/Files/tmp_

Bei diesem Beispiel wird der neue Ordner tmp_ mit dem nach dem Doppelpunkt angegebenen, gleichnamigen Pfad verlinkt.

ACLs und Systemflags nachträglich anpassen

Wenn Sie im Nachgang Ihre Struktur (z. B. Systemflags) „nachziehen“ müssen, müssen Sie das Deploy-Skript zur structure-basis.yml anpassen.

1. Öffnen Sie das Skript:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/deploy/pre/js/020 create-structure-basis.js

2. Ändern Sie den Aufruf so, dass der Builder mit true ausgeführt wird:

   /* global sc */
   
   global.sessionControllerAdmin = sc;
   
   let objects = require('common/objects');
   let sb = require('/agorum/roi/customers/Standard/js/structure-builder');
   let yamlbasis = objects.find('/agorum/roi/customers/academy.workflow/yml/structure-basis.yml');
   
   //sb(yamlbasis).create();
   
   // ATTENTION: when using true, everything is set newly, should only be used for testing
   sb(yamlbasis, true).create();

   
   Ergebnis: Das System setzt u. a. folgende Aspekte neu: acls, systemFlags.

   Hinweis: Alternativ setzen Sie Systemflags gezielt per eigenem JavaScript (z. B. in deploy/pre), statt die gesamte Struktur neu aufzubauen.