290 lines
15 KiB
Markdown
290 lines
15 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.
|
||
|
||
## Bausteine: ein Abschnitt für mehrere Vorlagen
|
||
|
||
„Datensicherung prüfen“ steht in vier der sieben mitgelieferten Vorlagen, wortgleich. Wer den Ablauf
|
||
ändert, ändert ihn viermal — oder dreimal und vergisst den vierten. Ein **Baustein** ist ein
|
||
Abschnitt, den mehrere Vorlagen teilen und der an einer Stelle gepflegt wird.
|
||
|
||
Die Liste steht hinter dem Knopf **Bausteine** oben auf der Vorlagenseite. Ein Baustein wird dort
|
||
angelegt (nur ein Name), bekommt dann einen Titel und seine Schritte, und wird **veröffentlicht** —
|
||
genau wie eine Vorlage, mit denselben Regeln: höchstens ein Entwurf, und eine veröffentlichte
|
||
Fassung wird nie wieder verändert.
|
||
|
||
### Einsetzen
|
||
|
||
Im Editor einer Vorlage steht unten neben **Abschnitt hinzufügen** das Feld **Baustein einsetzen**.
|
||
Angeboten werden nur veröffentlichte Fassungen nicht archivierter Bausteine. Der Abschnitt erscheint
|
||
dann als Einheit: mit dem Kennzeichen „Baustein“, dem Namen der Quelle und der Zahl seiner Schritte.
|
||
|
||
**Titel und Schritte lassen sich dort nicht ändern.** Beides kommt beim Veröffentlichen aus dem
|
||
Baustein — ein Feld, das man ausfüllen kann und das danach überschrieben wird, wäre eine Falle.
|
||
Geändert wird am Baustein.
|
||
|
||
### Was eine Änderung am Baustein bewirkt — und was nicht
|
||
|
||
Das ist der Punkt, den man einmal verstanden haben muss:
|
||
|
||
- **Schon veröffentlichte Vorlagenversionen ändern sich nicht.** Sie tragen beim Veröffentlichen
|
||
eingesetzte **Kopien** der Schritte. Ein Lauf von vor zwei Jahren zeigt genau das, was damals
|
||
abgearbeitet wurde — daran ändert kein Baustein etwas.
|
||
- **Laufende Arbeiten ändern sich nicht.** Aus demselben Grund.
|
||
- **Die neue Fassung wirkt in der nächsten veröffentlichten Version** einer Vorlage. Wer sie dort
|
||
haben will, legt einen neuen Entwurf an und veröffentlicht ihn.
|
||
|
||
Auf der Seite eines Bausteins steht unter **Wo er steckt**, in welchen Vorlagen er vorkommt und
|
||
welche **Fassung** dort eingesetzt ist. Vor einer Änderung ist das die Liste, die man lesen will.
|
||
|
||
### Archivieren
|
||
|
||
Gelöscht wird ein Baustein nie: veröffentlichte Vorlagenversionen tragen seine Herkunft. Archiviert
|
||
lässt er sich nicht mehr neu einsetzen, bleibt aber in jeder Vorlage lesbar, die ihn schon benutzt.
|
||
Steht er noch in einem **Entwurf**, weist Laufzettel das Archivieren ab — diese Vorlage ließe sich
|
||
danach nicht mehr veröffentlichen.
|
||
|
||
### In einer Austauschdatei steht kein Baustein
|
||
|
||
Ein Export trägt die **aufgelösten** Schritte, keinen Verweis. Eine Kennung aus dieser Installation
|
||
bedeutet in einer anderen nichts, und ein Verweis auf einen Baustein, den es dort nicht gibt, wäre
|
||
eine Vorlage, die sich nicht veröffentlichen lässt. Wer einen Baustein mitgeben will, exportiert die
|
||
Vorlage und legt den Baustein in der anderen Installation neu an.
|
||
|
||
## 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.
|