Florian Wilde
4bd34c4233
Welche Vorlagen auf der Geraeteseite als Kachel erscheinen, stand nur im Seed. Wer eine eigene Vorlage dort haben wollte, kam nicht heran; wer eine mitgelieferte loswerden wollte, auch nicht. Neue Seite Verwaltung -> Schnellstart: je Geraetetyp eine Liste, Reihenfolge ueber Hoch und Runter. Kein Drag & Drop -- der Editor braucht dnd-kit fuer hundert Schritte, hier sind es zwei bis vier Kacheln, und zwei Knoepfe sind am Handy verlaesslicher als eine Ziehgeste neben einer scrollenden Seite. Gespeichert wird die ganze Liste; position kommt aus ihrer Reihenfolge, damit es nur eine Wahrheit darueber gibt. Zur Auswahl stehen nur veroeffentlichte, nicht archivierte Vorlagen. Einstellung.schnellstartGepflegt haelt den Seed heraus, sobald jemand gespeichert hat -- auch bei unveraenderter Liste. Eine fehlende Zeile sagt nicht, ob sie noch nie da war oder bewusst entfernt wurde. Das Durchklicken des gebauten Stands fand einen Fehler, den die Suite nicht gesehen haette: die Umsortierung wurde nicht gespeichert. Altdaten tragen mehrere Zeilen auf position 0, und bei gleicher Position ist die Reihenfolge in Postgres nicht festgelegt -- Lesemodell und Dienst gaben sie unterschiedlich zurueck, und der Vergleich hielt die Umsortierung fuer einen Leerlauf. Behoben durch einen eindeutigen Tiebreak in beiden Abfragen, mit Regressionstest. Closes #34
241 lines
12 KiB
Markdown
241 lines
12 KiB
Markdown
# Vorlagen bauen
|
||
|
||
Eine Vorlage ist die Checkliste selbst: was bei einer PC-Neuinstallation zu tun ist, in welcher
|
||
Reihenfolge, mit welchen Hilfetexten und welchen Befehlen. Vorlagen anlegen, bearbeiten und
|
||
veröffentlichen darf die Rolle **Redakteur** oder **Administrator**.
|
||
|
||
Die wichtigste Regel steht am Anfang, weil alles andere daraus folgt:
|
||
|
||
> **Eine veröffentlichte Version wird nie verändert.** Sonst zeigte ein alter Lauf Schritte, die es
|
||
> damals nicht gab. „Bearbeiten“ legt deshalb eine vollständige Kopie als **Entwurf** an. Je Vorlage
|
||
> gibt es höchstens einen Entwurf. Läufe starten nur an veröffentlichten Versionen und hängen für
|
||
> immer an der Version, mit der sie gestartet wurden.
|
||
|
||
## Die Vorlagenliste
|
||
|
||
|
||
|
||
Gefiltert wird nach **Suche**, **Kategorie**, **Schlagwort** und mit dem Häkchen **auch
|
||
archivierte**, dann **Filtern**.
|
||
|
||
Die Kennzeichen an einer Zeile sagen den Zustand:
|
||
|
||
| Kennzeichen | Bedeutung |
|
||
|---|---|
|
||
| **v3** | Version 3 ist veröffentlicht und gültig |
|
||
| **noch nicht veröffentlicht** | es gibt nur einen Entwurf; daran lässt sich kein Lauf starten |
|
||
| **Entwurf vorhanden** | es wird gerade an einer neuen Version gearbeitet |
|
||
| **archiviert** | aus dem Angebot genommen |
|
||
| **nur …** | gilt nur für einen Kunden (Modus Dienstleistung) |
|
||
|
||
Gibt es einen Entwurf, führt **Entwurf öffnen** direkt in den Editor — der häufigste Fall ist,
|
||
weiterzuarbeiten an dem, was man gestern angefangen hat.
|
||
|
||
Unten auf der Seite steht **Vorlage anlegen**: **Name**, **Beschreibung (optional)**, **Kategorie
|
||
(optional)**, **Schlagworte, mit Komma getrennt** und im Modus Dienstleistung **Nur für einen
|
||
Kunden (optional)**. Die neue Vorlage beginnt als Entwurf. Namen sind nicht eindeutig; zwei
|
||
Vorlagen dürfen gleich heißen.
|
||
|
||
## Die Vorlagenseite
|
||
|
||
|
||
|
||
Sie beantwortet drei Fragen auf einen Blick: Was ist gerade gültig? Wird gerade daran gearbeitet?
|
||
Was wurde wann veröffentlicht?
|
||
|
||
**Bearbeiten** ist der wichtigste Knopf. Er erzeugt eine tiefe Kopie der letzten veröffentlichten
|
||
Version als neuen Entwurf und führt in den Editor. Gibt es schon einen Entwurf, heißt der Knopf
|
||
**Entwurf weiter bearbeiten** und führt genau dorthin — auch wenn zwei Redakteure gleichzeitig
|
||
klicken.
|
||
|
||
Unter **Versionen** steht die Geschichte: Nummer, Veröffentlichungszeitpunkt und -person, die Zahl
|
||
der Läufe und die Änderungsnotiz. Je Zeile **Ansehen** (beziehungsweise **Im Editor öffnen** beim
|
||
Entwurf) und **Als JSON exportieren**.
|
||
|
||
Unter **Kopfdaten** stehen Name, Beschreibung, Kategorie, Schlagworte und die Kundenzuordnung. Sie
|
||
hängen an der Vorlage, nicht an einer Version — ein Tippfehler im Namen kostet also keine neue
|
||
Version. **Kopfdaten speichern** übernimmt sie.
|
||
|
||
Unter **Weiteres**:
|
||
|
||
- **Duplizieren** — legt eine neue Vorlage an, mit dem Inhalt der neuesten Version als Entwurf.
|
||
Gut als Ausgangspunkt für eine Abwandlung.
|
||
- **archivieren** / **wieder freigeben** — archiviert wird, was nicht mehr angeboten werden soll.
|
||
Gelöscht wird nichts: an einer Vorlage hängen Läufe. Ein Entwurf einer archivierten Vorlage lässt
|
||
sich noch bearbeiten, aber nicht veröffentlichen.
|
||
- **Entwurf verwerfen** — mit Rückfrage. Der Entwurf ist danach weg und nicht wiederherstellbar;
|
||
die veröffentlichte Version bleibt unberührt.
|
||
|
||
## Der Editor
|
||
|
||
|
||
|
||
Oben stehen Name, **Version N** und der Zustand — **Entwurf** oder **veröffentlicht** — und daneben
|
||
**Nicht gespeichert** oder **gespeichert**.
|
||
|
||
Unten klebt eine Leiste mit **Speichern** und derselben Auskunft in Worten. **Es gibt kein
|
||
automatisches Speichern**: eine halb umgebaute Vorlage soll nicht nebenbei zur Wahrheit werden.
|
||
Solange etwas nicht gespeichert ist, fragt der Browser vor dem Verlassen der Seite nach.
|
||
|
||
Eine veröffentlichte Version öffnet der Editor nur lesend — mit denselben Feldern, nur
|
||
schreibgeschützt. Oben steht dann, warum.
|
||
|
||
### Abschnitte
|
||
|
||
Ein Abschnitt fasst die Schritte zusammen, die zusammengehören. **Abschnitt hinzufügen** legt einen
|
||
an; er bekommt einen **Titel des Abschnitts** und darunter seine Schritte.
|
||
|
||
Die zweistellige Nummer (`01 · Vorbereitung`) kommt aus der Position und wird **nie gespeichert**.
|
||
Schreib sie also nicht in den Titel — beim ersten Umsortieren wäre sie falsch.
|
||
|
||
Sortiert wird auf zwei Wegen: mit dem Anfasser links ziehen, oder über die Pfeile **nach oben** und
|
||
**nach unten** an der Zeile. Der zweite Weg ist am Handy der bessere. Schritte werden innerhalb
|
||
ihres Abschnitts sortiert und lassen sich nicht in einen anderen ziehen.
|
||
|
||
Höchstens 200 Abschnitte, höchstens 500 Schritte je Abschnitt.
|
||
|
||
### Schritte und ihre Typen
|
||
|
||
Jeder Schritt hat **Titel**, **Typ** und das Häkchen **Pflichtschritt**. Dazu je nach Typ:
|
||
|
||
| Typ | Was der Techniker tut | Einstellungen |
|
||
|---|---|---|
|
||
| **Haken** | abhaken | keine |
|
||
| **Text** | Text eintragen | **Mehrzeiliges Feld** |
|
||
| **Zahl** | Zahl eintragen | **Mindestens**, **Höchstens**, **Einheit** |
|
||
| **Auswahl** | aus einer Liste wählen | **Optionen** (mindestens eine) |
|
||
| **Datum** | Datum wählen | keine |
|
||
| **Befehl** | Befehl kopieren und ausführen | **Shell** (powershell, bash, cmd), **Befehl** |
|
||
|
||
Mindestens und Höchstens sind **Hinweise, kein Verbot**: ein Wert außerhalb wird im Lauf markiert
|
||
und trotzdem gespeichert.
|
||
|
||
**Pflichtschritt** heißt: der Lauf lässt sich nicht abschließen, solange dieser Schritt weder
|
||
erledigt noch ausdrücklich als nicht zutreffend eingetragen ist. Setz das sparsam — sind alle
|
||
Schritte Pflicht, ist keiner Pflicht.
|
||
|
||
Beim Wechsel des Typs räumt der Editor die Einstellungen auf, damit nicht der Befehl eines
|
||
ehemaligen Befehlsschritts unsichtbar mitwandert.
|
||
|
||
### Hilfetext und Doku-Link
|
||
|
||
Der **Hilfetext** ist in der Abarbeitungsansicht ausklappbar und darf **Markdown** enthalten:
|
||
`**fett**`, Listen, Links, `` `Code` ``. **Kein HTML.** Hier steht das, was jemand beim ersten Mal
|
||
wissen muss — im Modus „Kompakt“ blendet der Techniker ihn später aus.
|
||
|
||
Der **Doku-Link** erscheint im Lauf als **Anleitung öffnen**. Nur `http`- und `https`-Adressen.
|
||
|
||
### Variablen
|
||
|
||
Variablen werden **beim Start eines Laufs abgefragt** und füllen die Platzhalter. **Variable
|
||
hinzufügen** legt eine an:
|
||
|
||
- **Schlüssel** — der Name im Platzhalter `{{schluessel}}`. Ein Variablenschlüssel beginnt mit einem
|
||
Kleinbuchstaben und besteht aus Kleinbuchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
|
||
`vorname`, `ad_gruppe` und `raum2` gehen; `Vorname`, `mit-strich` und `2te_wahl` nicht. Die
|
||
Strenge hat einen Grund: derselbe Schlüssel steht in PowerShell-Befehlen, und `{{Vor-Name}}` ließe
|
||
sich dort nicht mehr von der Syntax der Shell trennen.
|
||
- **Beschriftung** — was im Startformular über dem Feld steht.
|
||
- **Typ** — Text, Zahl, Auswahl oder Datum.
|
||
- **Pflichtangabe beim Start** — ohne Eingabe lässt sich der Lauf nicht anlegen.
|
||
- **Optionen** — nur bei Auswahl.
|
||
|
||
Ein Schlüssel darf nur einmal vorkommen; der Editor markiert eine Doppelung sofort. Eine Variable,
|
||
die nirgends verwendet wird, ist erlaubt — sie wird trotzdem beim Start abgefragt.
|
||
|
||
Fünf Namen sind als Variable gesperrt: `techniker`, `datum`, `kunde`, `kundenkuerzel` und
|
||
`generiertes_passwort`. Sie sagen, **wer, wann und für wen** — eine Variable dafür hieße, dass in
|
||
einem fertigen Befehl ein fremder Name oder ein falsches Datum stehen kann, ohne dass es auffällt.
|
||
|
||
Höchstens 200 Variablen.
|
||
|
||
### Platzhalter
|
||
|
||
Ein Platzhalter `{{schluessel}}` in **Titel, Hilfetext oder Befehl** wird beim Abarbeiten ersetzt.
|
||
Leerzeichen in den Klammern sind erlaubt: `{{ vorname }}` wird erkannt.
|
||
|
||
Er wird aus einer Variablen der Vorlage gefüllt — oder aus einem der **eingebauten** Werte. Welche
|
||
es gibt, steht im Editor hinter **Welche Platzhalter gibt es?**, nach Quelle gruppiert:
|
||
|
||
| Quelle | Platzhalter |
|
||
|---|---|
|
||
| Gerät und Lauf | `hostname`, `seriennummer`, `inventarnummer`, `ticket`, `datum`, `techniker`, und im Modus Dienstleistung `kunde`, `kundenkuerzel` |
|
||
| Mitarbeiter | `mitarbeiter`, `benutzer`, `vorname`, `nachname`, `upn`, `sam`, `mail`, `abteilung`, `titel`, `vorgesetzter`, `vorgesetzter_sam`, `dn` |
|
||
| Abteilung | `ou` (Ziel-Container), `gruppen` (Standardgruppen, kommagetrennt) |
|
||
| Einstellungen | `ou_gesperrt` (Ziel-OU für deaktivierte Konten) |
|
||
| Besonders | `generiertes_passwort` |
|
||
|
||
`{{generiertes_passwort}}` ist der Sonderfall: **20 Zeichen, bei jeder Anzeige neu erzeugt und
|
||
nirgends gespeichert** — nicht im Lauf, nicht im Kommentar, nicht im Protokoll, nicht im Ausdruck.
|
||
Auf einem Ausdruck steht an seiner Stelle `[Passwort – nicht gespeichert]`. Bau also keinen Ablauf,
|
||
der davon ausgeht, dass man das Passwort später nachschlagen kann.
|
||
|
||
Ein Platzhalter, der zu keiner Variablen und keinem eingebauten Wert passt, wird oben im Editor
|
||
**gewarnt**, aber nicht abgewiesen: ein Tippfehler soll hier auffallen und nicht erst dem Techniker
|
||
im Lauf — es kann aber sein, dass die Variable gleich noch kommt. Im Lauf bleibt ein unbekannter
|
||
Platzhalter als Text stehen.
|
||
|
||
Für Befehlsschritte gilt eine zusätzliche Regel: **die Anführungszeichen gehören in die Vorlage,
|
||
nicht in den Wert.** Schreib also `New-ADUser -Name "{{vorname}} {{nachname}}"`. Steht ein
|
||
Platzhalter in einem Befehl nicht zwischen den erwarteten Anführungszeichen, wird der Schritt im
|
||
Lauf abgewiesen, statt einen halb maskierten Befehl zum Kopieren anzubieten.
|
||
|
||
### Vorschau
|
||
|
||
**Vorschau** zeigt die Vorlage so, wie sie im Lauf aussieht: mit Beispielwerten in allen
|
||
Platzhaltern, abgeschalteten Feldern und nummerierten Abschnitten. Gespeichert wird dabei nichts,
|
||
und für `{{generiertes_passwort}}` entsteht **kein** Passwort — dort steht
|
||
`BEISPIEL-PASSWORT-NICHT-ECHT`.
|
||
|
||
Nutz sie vor dem Veröffentlichen, besonders bei Befehlen: erst hier sieht man, ob der fertige Befehl
|
||
so aussieht, wie er aussehen soll.
|
||
|
||
## Veröffentlichen
|
||
|
||
Im Abschnitt **Veröffentlichen** trägst du eine **Änderungsnotiz (optional)** ein — ein Satz, was
|
||
sich gegenüber der letzten Version geändert hat; sie steht später in der Versionsgeschichte. Dann
|
||
**Veröffentlichen**.
|
||
|
||
**Veröffentlicht wird das Gespeicherte, nicht das, was auf dem Bildschirm steht.** Gibt es nicht
|
||
gespeicherte Änderungen, warnt der Editor — erst speichern, dann veröffentlichen.
|
||
|
||
Danach ist die Version unveränderlich, und Läufe können daran starten. Der Editor schaltet in den
|
||
Lesemodus.
|
||
|
||
Willst du weiter daran arbeiten, drückst du auf der Vorlagenseite wieder **Bearbeiten**: es entsteht
|
||
ein neuer Entwurf mit der nächsthöheren Nummer.
|
||
|
||
## Export und Import
|
||
|
||
**Als JSON exportieren** auf der Vorlagenseite lädt eine Version als Datei herunter. Das Dokument
|
||
enthält Kopfdaten, Variablen, Abschnitte und Schritte — und ausdrücklich keine Kennungen,
|
||
Zeitstempel, Läufe oder Kundenzuordnung. Damit lässt es sich in eine **andere**
|
||
Laufzettel-Installation einspielen.
|
||
|
||
Eingespielt wird in der Vorlagenliste unter **Vorlage aus einer Datei einspielen**: Datei wählen
|
||
oder den Inhalt einfügen, dann **Einspielen**. Zu wissen:
|
||
|
||
- Es entsteht immer eine **neue** Vorlage; der Import schreibt nie in eine bestehende hinein.
|
||
- Sie bekommt genau eine Version als **Entwurf**. Erst nach dem Ansehen und Veröffentlichen lässt
|
||
sich ein Lauf daran starten.
|
||
- Die Versionsnummer der Quelle wandert nicht mit: hier fängt die Vorlage wieder bei 1 an.
|
||
- Eine eingespielte Vorlage gilt zunächst für alle Kunden. Die Zuordnung setzt du danach in den
|
||
Kopfdaten.
|
||
- Schlägt die Prüfung fehl, wird **nichts** geschrieben, und die Meldung nennt die erste
|
||
Beanstandung mit ihrem Pfad, etwa
|
||
`struktur.abschnitte.1.schritte.2.titel: Ein Schritt braucht einen Titel.`
|
||
|
||
Das Format ist vollständig beschrieben in [docs/vorlagen-format.md](../vorlagen-format.md) — für
|
||
den Fall, dass jemand eine Vorlage von Hand schreiben oder ein Skript dafür bauen will.
|
||
|
||
## Vorlagen einem Gerätetyp zuordnen
|
||
|
||
Damit auf der Geräteseite ein **Schnellstart** erscheint, muss für den Gerätetyp eine Vorlage
|
||
hinterlegt sein — etwa „PC Neuinstallation“ für den Typ PC. Gepflegt wird das unter
|
||
**Verwaltung → Schnellstart**; das verlangt die Rolle Administrator und ist in Kapitel 07
|
||
beschrieben.
|
||
|
||
Ohne Zuordnung bleibt der Schnellstart leer, und das ist kein Mangel: unter **Vorlage zuweisen**
|
||
steht auf der Geräteseite jede Vorlage, die zu diesem Gerät passt, und der Start-Dialog kennt sie
|
||
ohnehin alle.
|