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.

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 und dem 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 alles neu setzt und das System alles neu durch den Index sendet.

Speicherort der Datei

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

Aufbau der Datei

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

_prefix: agorum_dokutest_
_postfix: _postfix
_aclPrefix: ACL_agorum_dokutest_
_grpPrefix: GRP_agorum_dokutest_

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

_leaf:
#  systemFlags: 28

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

# acl setzen, das es schon gibt
  acl: acl:Published
  + Schulung:
    acl: acl:Published
# Metadatum setzen    
    ~~demo_schulung: "Schulung"
    ~demo_schulungSparte: "Schulung"
    + Videos:
      acl: acl:Published
      ~~demo_schulung: "Video"
      ~demo_schulungSparte: "Schulung"
  + tmp_:
    acl: acl:Public
    flags: 39   
    
#
# 
#
# -- user - Name der area und identifier wird überschrieben 
#+ /agorum/roi/Files/Demo-Beispiel:
+ /agorum/roi/Files/Demo-Beispiel -- user:
  acl:
  unique: true
  systemFlags: 65564
  + Bereich 1:
    systemFlags: 65564
    acl:
    leaf: true
    unique: true
    + Bereich 1.1:
      systemFlags: 28
    + Bereich 1.2:
      systemFlags: 28
    + Bereich 1.3:
      systemFlags: 28
#
# "Bereich 2" werden die ACL mit der ordnerID angelegt
#
  + Bereich 2:
    acl:
    + Bereich 2.1:
      acl:
    + Bereich 2.2:
      acl:
    + Bereich 2.3:
      acl:
# Hier wird verlinkt
  + tmp_: /agorum/roi/Files/tmp_

Einstellungen in der Datei

_prefix

_prefix: demo_

Setzt das Präfix allen internen Namen der Metadaten voran.

Beispiel

demo_<Metadatum>

_postfix

_postfix: _Bereich

Hängt das Postfix allen internen Namen der Metadaten an.

Beispiel

<Metadatum>_Bereich

_aclPrefix

_aclPrefix: ACL_DEMO_

Verwendet das Präfix für angelegte ACLs.

Beispiel

ACL_DEMO_<ACL>

_grpPrefix

_grpPrefix: GRP_DEMO_

Verwendet das Präfix für angelegte Benutzergruppen.

Beispiel

GRP_DEMO_<Gruppe>

_default

_default:
  acl:
  unique: true
  systemFlags: 65564

Definiert Definitionen, die als Standardwerte für jeden angelegten Ordner gesetzt werden.

_leaf

_leaf:
  systemFlags: 28

Definiert Definitionen, die für jeden letzten Ordner gesetzt werden.

Der letzte Ordner ist der Ordner, der in der Strukturordnung am weitesten eingerückt ist.

Beispiel

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

In diesem Beispiel sind demnach die letzten Ordner:

• 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

Erstellen Sie per Datei structure-basis.yml einen Ordner, 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“

Definiert auf verschiedene Art und Weise eine ACL für die neu angelegten Ordner:

• Verwendung einer vorhandenen ACL
• Definition einer neuen ACL
  • ohne festgelegten Namen
  • mit festgelegten Namen
  • mit ID des Ordners
  • ohne ID des Ordners
• Automatische Vererbung der übergeordneten ACLs

Hinweise zur Verwendung

• Wenn Sie nichts weiter definieren, wird die ACL des übergeordneten Ordners vererbt.
  • Haben Sie in der Einstellung _default oder _leaf ein abweichendes Verhalten festgelegt, aktivieren Sie die Vererbung explizit mit der Angabe acl: ^.
• Wird eine ACL angelegt, wird dieses 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 End-Ordner (_leaf nicht zutreffend)
Anlegen einer Read-Benutzergruppe: Gruppenname>_Read

Ist End-Ordner
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

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 mit der Bezeichnung ACL_DEMO_<ID des Ordners Demo>_Demo an.

• 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 Zusatz des Keyword unique entfällt die Notwendigkeit der ID des Ordners. Dadurch lautet der Name des ACLs ACL_DEMO_Demo (_aclPrefix + Name Ordner).

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: Keine neue ACL anlegen, stattdessen die ACL des übergeordneten Ordners 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 jedem untersten Ordner werden jeweils 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 wird die read-, write- und all-Benutzergruppen angelegt:

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

Metadaten „area“ und „identifier“ setzen

Auf einen neuen Ordner setzt das System automatisch die Metadaten „area“ und „identifier“. Beide Metadaten werden mit dem Namen des neuen Ordners gesetzt.

Beispiel

+ /agorum/roi/Files/Demo:

Auf den Ordner Demo setzt das System demnach die Metadaten area und identifier jeweils mit dem Wert Demo.

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

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

Auf den Ordner Demo setzt das System demnach die Metadaten area und identifier jeweils mit dem Wert user.

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 neuen Ordner setzen.

• Schreiben Sie den Namen des Metadatums zwingend mit dem definierten _prefix.
• 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

Beispielstruktur

• Ordner 1
• ~kundenname: A
• ~~projekt: Test
  • Ordner 1.1
    • ~~projektdetail: TestDerivat
  • Ordner 1.2
  • Beide Ordner haben automatisch ~~projekt: Test geerbt, außerdem hat Ordner 1.1 das Metadatum ~~projektdetail: TestDerivat weitervererbt
• Ordner 2
  • ~~kundenname: B
    • Ordner 2.1
    • ~status: silber
    • Ordner 2.1 erhält automatisch kundenname: B und hat dazu noch das eigene Metadatum ~status: silber.

Ordner verlinken

Sie können Ordner verlinken, indem Sie hinter dem neu anzulegenden Ordner den vollständigen Ziel-Pfad setzen. Der neue Ordner sollte dazu gleich lauten wie der letzte Ordner des Pfades, auf den Sie verlinken.

Beispiel

.
.
  + 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

Stellen Sie fest, dass Sie im Nachgang Ihre Hauptordnerstruktur mit Systemflags sichern wollen, müssen Sie das deploy-Skript zur structure-basis.yml anpassen:

1. Öffnen Sie folgendes Skript:

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

2. Nehmen Sie folgende Änderungen (blau markiert) im Skript vor:

   /* 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 Folgendes neu:
   
   • acls
   • systemFlags

   Hinweis: Alternativ setzen Sie die Systemflags gezielt mit einem JavaScript, d. h. über ein eigenes Skript in dem Ordnerabschnitt deploy/pre innerhalb Ihres Konfigurationsprojekts.