Dokumentationssystem einrichten

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plug-ins. Aktualisieren Sie das hier beschriebene Plug-in, um die Dokumentation verwenden zu können.

Das agorum core documentation system können Sie mit diversen Einstellungen individuell anpassen und nach eigenen Bedürfnissen einrichten, etwa um weitere Bereiche erweitern.

Parameter

baseQuery

Default Eintrag: inpath:${ID:/agorum/roi/Files/acds}

Eine baseQuery muss eingetragen werden, damit der Benutzer das Suchfeld gezielt verwenden kann und die Dokumente findet, die er finden soll / darf.
Dieses Suchfeld übergibt den Start-Bereich an die agorum core smart search und ermöglicht somit das Suchen und Finden von Dokumenten.
Die eingegebene ID (FOLDERPATH) muss derselbe Pfad sein, der unter baseFolder angegeben wird.

tagField

Default Eintrag: ag_tags

Standard-Metadatum, in dem das System die Tags der Dokumente speichert.
Das Metadatum erlaubt Mehrfacheinträge und somit mehrere Tags auf einem Dokument.

baseUrl

Definiert die base-URL für externe Links (Zugriffe). Klickt ein Benutzer im agorum core documentation system auf Dokumentenlink, verwendet das System diese URL, um externe Links zu erzeugen.

help

Definiert ein Startdokument für die Hilfefunktion des Editors. Diese Hilfe öffnet sich, wenn ein Benutzer auf Hilfe im Editor klickt.

Das Startdokument muss ein Dokument sein, auf dem eine Übersicht erzeugt ist. Es kann in den unterschiedlichsten Möglichkeiten angegeben werden. Beispiele dazu sind:

Als URL
Definiert die URL, die das entsprechende Hilfe-Dokument direkt öffnet. Diese können Sie aus der Dokumentationsansicht aus dem Browser kopieren.

help: 'https://<agorum-Server>/roiwebui/acds_module/overview2/index.html#/f997cae0-e8da-11e9-a3bc-005056aa0ecc/e771b290-e8df-11e9-a3bc-005056aa0ecc',

Als ID, UUID oder Pfad
Definiert eine URL, ID, UUID oder einen Pfad.

help: 'f997cae0-e8da-11e9-a3bc-005056aa0ecc',

help: '12121279',

help: '/agorum/roi/Files/acds/public/editHelp.html',

publicHelp

Definiert ein Startdokument für die Hilfefunktion der Dokumentations-Anzeige an. Die Hilfefunktion öffnet sich, wenn ein Benutzer in der Kopfzeile der Dokumentationsansicht auf klickt.

Das Startdokument muss ein Dokument sein, auf dem eine Übersicht erzeugt ist. Sie können es in den unterschiedlichsten Möglichkeiten angeben. Beispiele dazu sind:

Als URL
Definiert die URL an, die das entsprechende Hilfe-Dokument direkt öffnet. Diese können Sie aus der Dokumentationsansicht aus dem Browser kopieren.

publicHelp: 'https://<agorum-server>/roiwebui/acds_module/overview2/index.html#/ab8e49e0-ea6b-11e9-a3bc-005056aa0ecc',

Als ID, UUID oder Pfad
Definiert eine URL, ID, UUID oder einen Pfad.

help: 'ab8e49e0-ea6b-11e9-a3bc-005056aa0ecc',

help: '232121212',

help: '/agorum/roi/Files/acds/public/elp.html',

defaultOverview

Definiert Verweise auf Dokumentationen. Das System verwendet diese Verweise, wenn der Benutzer die URL manipuliert und dort die UUIDs entfernt.

Hier können Sie nochmals die UUIDs Ihrer Einstiegsdokumentationen für die entsprechenden Bereiche eintragen.

Beispiel

  defaultOverview: {
    public: '21fbebd0-dc3b-11e9-93a4-02420a0a0009',
    internal: '21fbebd0-dc3b-11e9-93a4-02420a0a0009'
  },

Nachdem Sie die UUIDs Ihrer Einstiegsdokumentationen eingetragen haben, generieren Sie die Übersichten für alle Versionen manuell oder warten, bis der nächtliche Automatismus durchgelaufen ist. Ansonsten zeigt das System leere Seiten an, wenn ein Leser die Bereiche public oder internal in der Dokumentation aufruft.

aclWorker

agorum core liefert einen Worker für das Dokumentationssystem mit, der die Berechtigungen automatisch auf neue Dokumente setzt, die im Dokumentationsbereich abgelegt werden.

Hinweis: Damit der Worker funktioniert, muss zwingend jeder konfigurierte Dokumentationsbereich ein eigenes ACL besitzen.

Einstellung des Workers im Standard:

  aclWorker: {
    // enable/disable acl worker, setting access rights to all documentAreas
    active: true,
    
    // optional, if defined, all notes beneath the documentAreas get a special acl, so that they are hidden for public users
    aclNotes: 'ACL_acds_creator'
  },

logging

Suchanfragen, die Benutzer im Dokumentationssystem eingeben (auch die gewählten Tags), können mit Setzung dieser Eigenschaft protokolliert werden.
Die Ausgabe-Datei hat das Format CSV.
Je Monat erstellt das System eine neue CSV-Datei unter logFolder und mit dem Namen [logFilePrefix]_MM-yyyy.csv : acds_03-2018.csv
Unter logFolder wird der Pfad zum Ablageort der Log-Dateien angegeben.

Default Eintrag: '/agorum/roi/Files/acds'

logFilePrefix: Präfix der CSV-Dateien.

Default Eintrag: 'acds_'

active: Aktivieren (true) oder Deaktivieren (false) des Loggings.

Default Eintrag: true

Hinweis: Das System protokolliert keine internen Aufrufe. Interne Aufrufe sind solche, die eine Bearbeitung der Dokumentation erlauben.

docQuery

Stellt die agorum core smart search-Suche zusammen und definiert, was alles im Bereich Dokumentation angezeigt wird.

Grund für eine weitere Eingrenzung ist der, dass in den Ordnern innerhalb des baseFolders auch andere Dokumente mit Styleguide-Regeln oder Ähnliches zu finden seien können. Diese sind nicht für die Dokumentation gedacht, gehören aber dennoch in diesen Bereich. Um somit andere Dokumententypen oder auch Ordnernamen selbst nicht anzuzeigen, grenzt die docQuery diese Einträge ein.

  Default Eintrag: 'classname:fileobject nameextension:html NOT classname:noteobject'

Parameter	Beschreibung
classname:fileobject	Zeigt nur Objekte an, die Dateien darstellen (Ordner sind ausgeschlossen).
ameextension:html	Zeigt nur Objekte an, die die Dateiendung html besitzen.
NOT classname:noteobject	Schließt Notizen aus.

Weitere Dokumententypen erlauben

Passen Sie die nameextension:html an, um weitere Dokumententypen zu erlauben.

Beispiel für doc- und ppt-Dateien:

nameextension:(html OR doc OR docx OR ppt OR pptx)

homePage

In der Dokumentationsansicht können Sie auf das Symbol oben Links einen Link hinterlegen, der zu Ihrer Homepage wechselt (oder auch zu einer anderen Seite).

Beispiel

homePage: 'https://www.agorum.com'

documentAreaIcons

Definiert optional, welche Symbole das System links in der Seitenleiste für die einzelnen Dokumentationsbereiche anzeigt.

Im Standard verwendet das System diese Einstellungen:

 documentAreaIcons: {
    intern: 'agorum:rounded-square-5;color=#003f85;scale=0.9|ionicon:document-text;color=white;scale=0.8|agorum:circle;color=#00b2cc;slot=bottom-right;scale=0.8;translate=0.1,0.1|ionicon:information;color=white;slot=bottom-right;scale=0.7;translate=0.1,0.1',
    public: 'agorum:rounded-square-5;color=#003f85;scale=0.9|ionicon:document-text;color=white;scale=0.8|agorum:circle;color=#00b2cc;slot=bottom-right;scale=0.8;translate=0.1,0.1|mdi:public;color=white;slot=bottom-right;scale=0.65;translate=0.1,0.1',
    partner: 'agorum:rounded-square-5;color=#003f85;scale=0.9|ionicon:document-text;color=white;scale=0.8|agorum:circle;color=#00b2cc;slot=bottom-right;scale=0.8;translate=0.1,0.1|mdi:group;color=white;slot=bottom-right;scale=0.65;translate=0.1,0.1',
  },

Sie bearbeiten Sie die Symbole für die Seitenleiste:

Kopieren Sie den obigen Code aus der Datei und fügen Sie ihn in diese Datei ein:
```
Eigene Dateien/Administration/workspace/acds/js/config.js
```
• Diese Datei stellt Ihre individuelle Konfiguration für Ihr Dokumentationssystem dar.
Kopieren Sie den Code für einen Dokumentationsbereich (intern, public, partner) aus dieser Datei.
Klicken Sie oben rechts in der Kopfleiste auf und dann auf Icon erstellen.
Fügen Sie den Code in das Feld Code ein und bearbeiten Sie das Icon.
Kopieren Sie den fertigen Code aus dem Feld Code und fügen Sie ihn in die Datei aus Schritt 1 ein.
Wiederholen Sie die Schritte 2 bis 5 pro Dokumentationsbereich.

documentAreaStartDocuments

Definiert optional, welche Start-Dokumentationen das System für die Dokumentationsbereiche verwendet.

Im Standard verwendet das System diese Einstellungen:

 documentAreaStartDocuments: {
    intern: 'Dokumentation Einstieg - Intern.html',
    public: 'Dokumentation Einstieg - Öffentlich.html',
    partner: 'Dokumentation Einstieg - Partner.html'
  },

Sie bearbeiten Sie die Start-Dokumentationen für die Dokumentationsbereiche:

Kopieren Sie den obigen Code aus der Datei und fügen Sie ihn in diese Datei ein:
```
Eigene Dateien/Administration/workspace/acds/js/config.js
```
Diese Datei stellt Ihre individuelle Konfiguration für Ihr Dokumentationssystem dar.
Ändern Sie das HTML-Dokument pro Dokumentationsbereich in dieser Datei ab.
Speichern Sie.

excludeTags

Schließt optional Dokumentationen mit bestimmten Tags aus. Das System zeigt Dokumentationen mit diesen Tags nicht mehr im Dokumentationssystem an.

Im Standard verwendet das System diese Einstellungen, es schließt also die beiden Tags archiv und hidden aus:

excludeTags: [
    '^archiv$',
    '^hidden$'
  ],

Sie bearbeiten Sie die Tags:

Kopieren Sie den obigen Code aus der Datei und fügen Sie ihn in diese Datei ein:
```
Eigene Dateien/Administration/workspace/acds/js/config.js
```
Diese Datei stellt Ihre individuelle Konfiguration für Ihr Dokumentationssystem dar.
Ändern Sie die Tags in dieser Datei.

Verwenden Sie reguläre Ausdrücke, um Tags auszuschließen. Halten Sie sich dazu an die obige Schreibweise.
Speichern Sie.

Aufrufe

Das Dokumentationssystem rufen Sie über diesen Befehl auf:

http://<agorum-server>/roiwebui/acds_module/overview2/index.html#

Hinter dem # können weitere Parameter nach folgendem Schema folgen:

<UUID-des-Startdokumentes>/<UUID-des-Dokumentes>/<Anker-auf-dem-Dokument>

Parameter	Beschreibung
UUID-des-Startdokumentes	Definiert ein Dokument aus dem Dokumentationsbereich, das als Übersichtsdokument markiert wurde. Das System zeigt die Baustruktur ab diesem Dokument an. Das System lädt das konfigurierte Startdokument aus der Datei config.js, wenn Sie nichts angeben.
UUID-des-Dokumentes	Definiert die UUID eines Dokuments, das direkt erscheinen soll. Das Startdokument erscheint, wenn Sie nichts angeben.
Anker-auf-dem-Dokument	Springt direkt zu einer Überschrift im jeweils angezeigten Dokument.

Über das Internet extern zugreifen

Schalten Sie einen Proxyserver (etwa Apache oder nginx) vor agorum core, wenn Sie die Dokumentationen nach außen hin verfügbar machen möchten. Richten Sie zudem im Header ein Basic-Auth auf den Benutzer agorumdocproxy ein, sodass das System diese bestimmte Berechtigung für die Darstellung der Dokumente verwendet.

Mitgelieferte Bereiche

Im Standard liefert agorum core bei der Installation des Plug-ins folgende Bereiche mit:

intern (Name: 'Intern')
public (Name: 'Öffentlich')
partner (Name: 'Partner')

Die Bereiche sehen Sie links in der Seitenleiste und wenn Sie Weitere Apps aufrufen.

Die Bereiche finden Sie innerhalb der Ordnerstruktur folgendermaßen:

Öffnen Sie links in der Seitenleiste Administration und dann Root.
Öffnen Sie den Pfad:
```
agorum/roi/Dateien/acds/
```

Einen Bereich erstellen

Sie können beliebig weitere Bereiche erstellen.

Hinweis: Sie benötigen das Plug-in agorum core template manager, um die nachfolgenden Schritte ausführen zu können. Installieren Sie das Plug-in über den agorum core plugin manager.

Ein neues Projekt anlegen

Öffnen Sie links in der Seitenleiste Administration und dann Root.
Erstellen Sie über das Kontextmenü ein neues Projekt (aus Vorlage).
Vergeben Sie einen Namen und ein Kürzel für das Projekt.
Klicken Sie auf Anlegen.

Ergebnis: Das System erstellt im Ordner /agorum/roi/customers das gewünschte Projekt mit dem eingetragenen Kürzel. Das Projekt enthält diverse Ordner:

• deploy
• doc
• js
• yml

Die Datei „structure-basis.yml“ anpassen

Im Ordner yml Ihres neu erstellten Projekts passen Sie nachfolgend die Datei structure-basis.yml an. Sie erweitern die Datei um Ihren neuen Bereich und um eine neue ACL. Die Datei sorgt dafür, dass die bereits mitgelieferten Bereiche intern, partner und public um den neuen Bereich inklusive der Berechtigung dafür ergänzt werden.

Öffnen Sie den Pfad:
```
agorum/roi/customers/acds/yml
```
Öffnen Sie die Datei structure-basis.yml mit einem Doppelklick.

Kopieren Sie diesen Text:

# Hier soll kein area und identifier gesetzt werden
+ /agorum/roi/Files/acds --acds:
  acl: acds
  + intern --acds_intern:
    acl: intern
  + public --acds_public:
    acl: public
  + partner --acds_partner:
    acl: partner

Öffnen Sie den Ordner Ihres neu erstellten Projekts.
Wechseln Sie in den Unterordner yml.
Öffnen Sie die Datei structure-basis.yml mit einem Doppelklick.
Fügen Sie den kopierten Text ein.

Passen Sie den eingefügten Text an.

Beispiel für den neuen Bereich Meine Doku:

# Erweiterung Dokumentationssystem
+ /agorum/roi/Files/acds --acds:
  acl: acds
  + Meine Doku -- acds_Meine Doku:
    acl: Meine Doku

Speichern Sie.
Klicken Sie auf Run.

Ergebnis: Das System ergänzt den Ordner agorum/roi/Dateien/acds/ um einen weiteren Ordner. Es handelt sich hierbei um Ihren gewünschten Bereich (im Beispiel um den neuen Bereich Meine Doku):

• intern
• Meine Doku
• partner
• public

Die Datei „config.js“ anpassen

In diesem Schritt teilen Sie dem System den neu erstellten Bereich mit, damit der Bereich anschließend bei der Anlage eines neuen Dokumentationsdokuments gewählt werden kann.

Öffnen Sie den Pfad:
```
agorum/roi/workspace/acds/js
```
Öffnen Sie die Datei config.js mit einem Doppelklick.

Erweitern Sie den folgenden Abschnitt in der Datei um Ihren neuen Bereich (hier Meine Doku, fett hervorgehoben).

  // the document areas, where documents can be stored, the name is the folder beneath baseFolder
  documentAreas: {
    intern: 'Intern',
    public: 'Öffentlich',
    partner: 'Partner',
    'Meine Doku': 'Meine Doku'

Hinweise:

• Die Angabe, die Sie hinzufügen, muss exakt dem Eintrag aus Datei „structure-basis.yml“ anpassen entsprechen (fett hervorgehoben):

# Erweiterung Dokumentationssystem
+ /agorum/roi/Files/acds --acds:
  acl: acds
  + Meine Doku -- acds_Meine Doku:
    acl: Meine Doku

Bei der Angabe in Hochkommata (erster Eintrag vor dem Doppelpunkt) handelt es sich um einen String. Einen String benötigen Sie hier nur, wenn Sie Sonderzeichen, Leerzeichen oder Umlaute in Ihrem neuen Bereich verwenden. Andernfalls verwenden Sie folgende Schreibweise:

// the document areas, where documents can be stored, the name is the folder beneath baseFolder
  documentAreas: {
    intern: 'Intern',
    public: 'Öffentlich',
    partner: 'Partner',
    Meinedoku: 'Meine Doku'

Verwenden Sie hier Meinedoku, müssen Sie auch die Einträge in der Datei „structure-basis.yml“ korrekt setzen:

# Erweiterung Dokumentationssystem
+ /agorum/roi/Files/acds --acds:
  acl: acds
  + Meinedoku -- acds_Meinedoku:
    acl: Meinedoku

Die Datei „050 base-document.js“ kopieren, in Projekt einfügen und ausführen

Hinweis: Die Schritte in diesem Abschnitt sind nur notwendig, sofern Sie den neuen Bereich auch als eigenes Symbol auf der Startseite von agorum core im Bereich Dokumentation benötigen. Andernfalls sind Sie fertig. Der neu erstellte Bereich steht beim Erstellen eines Dokumentationsdokuments ab sofort zur Verfügung.

Im letzten Teilschritt müssen Sie dem System noch Einträge für die MetaDB mitteilen. Dazu führen Sie ein JavaScript aus. Das System erstellt daraufhin automatisch die notwendigen Einträge in der MetaDB. Manuelle Einträge oder Anpassungen sind Ihrerseits nicht notwendig.

Öffnen Sie den Pfad:

agorum/roi/customers/acds/deploy/post/js

Kopieren Sie die Datei 050 base-document.js und fügen Sie sie in Ihren Projektordner ein:
```
agorum/roi/customers/<Name Ihres Projekts>/deploy/post/js
```
Öffnen Sie die Datei mit Doppelklick.
Klicken Sie auf Run.

Ergebnis: Das System erstellt im Hintergrund automatisch die notwendigen Einträge in der MetaDB. Auf der Startseite von agorum core finden Sie jetzt Ihren neuen Bereich als weiteres Symbol.

Die Datei „config.js“ nach Export des Projekts auf dem produktiven System anpassen

Sobald Sie Ihr neues Projekt finalisiert und auf Ihrem Testsystem ausgiebig getestet haben, übertragen Sie es auf Ihr Produktivsystem. Dazu führen Sie die Datei export.yml in Ihrem Projekt aus.

Anschließend, d. h. nach dem Import des Projekts auf dem Zielsystem, passen Sie auf dem Zielsystem die Datei config.js an und erweitern sie wie unter Datei „config.js“ anpassen beschrieben um die entsprechende Zeile:

 // the document areas, where documents can be stored, the name is the folder beneath baseFolder
  documentAreas: {
    intern: 'Intern',
    public: 'Öffentlich',
    partner: 'Partner',
    'Meine Doku': 'Meine Doku'

Tipp: Legen Sie im Ordner doc Ihres Projekts ein HTML-Dokument an, das Sie an diesen Schritt erinnert, damit Sie ihn nicht vergessen.

Eine Vorlage für Dokumentationen erstellen

Als Administrator können Sie neue Vorlagen erstellen, damit diese zur Auswahl im Dokumentationssystem erscheinen.

Öffnen Sie links in der Seitenleiste Explorer.
Öffnen Sie den Pfad:
```
Eigene Dateien/Administration/workspace/acds/chapter/
```
Ergebnis: Die Vorlagen Kapitel - Anwendung, Administration, Entwicklung und Kapitel - ohne Struktur erscheinen.
Kopieren Sie eine der Vorlagen und benennen Sie die kopierte Vorlage um.

Ergebnis: Die neue Vorlage erscheint zur Auswahl im Dokumentationssystem (siehe Eine Dokumentation (aus Vorlage) anlegen).

Berechtigungen vergeben

Den Zugriff auf das Dokumentationssystem steuern Sie über ACLs und Benutzergruppen.

ACLs

Öffnen Sie links in der Seitenleiste Administration und dann ACLs/Rechte.
Öffnen Sie den Pfad:
```
acds
```

Benutzergruppen

Öffnen Sie links in der Seitenleiste Administration und dann Gruppen.
Öffnen Sie den Pfad:
```
acds
```

ACLs und Benutzergruppen für Bereiche

Durch Ausführen der Datei structure-basis.yml beim Installieren des Pakets definiert das System im Standard folgende ACLs und Benutzergruppen:

Bereich	ACL	Benutzergruppe
agorum core documentation system	ACL_acds_acds	–
intern	aclds_intern	GRP_acds_intern_All
public	aclds_public	GRP_acds_partner_All
partner	aclds_partner	GRP_acds_public_All

Weitere ACLs und Benutzergruppen

Neben den oben aufgeführten Berechtigungen existieren weitere ACLs und Benutzergruppen, mit denen Sie den Zugriff auf das Dokumentationssystem einschränken oder erweitern.

ACL	Benutzergruppe	Beschreibung
ACL_acdsacds	–	Ohne Funktion
ACL_acds_creator	GRP_acds_creator	Diese ACL ist im Standard bei jedem Benutzer eingetragen und berechtigt dazu, Dokumentationen und alles Dazugehörige anzulegen.
ACL_acds_creator_actions	GRP_acds_creator_actions	Diese ACL berechtigt Benutzer zu folgenden Dingen: Dokumentationsbereich öffnen Neue Dokumention anlegen Neues Kapitel anlegen Neue Kategorie anlegen Dokumentation bearbeiten Einstellung Erstelle eine neue Übersicht ab hier verwenden Dokumente suchen und hierhin verschieben Abschnitt Verlinkte Medien auf dieser Seite verwenden Abschnitt Enthalten in folgenden Übersichten verwenden