# `vorlage_docx` — DOCX aus Vorlagen-Skript erzeugen

**Zweck:** Ruft serverseitig eine Vorlage des zentralen Vorlagen-Dienstes auf (dieselbe, die auch interaktiv im Browser genutzt wird), befüllt deren Formularfelder aus dem Workflow-Kontext und übernimmt das erzeugte DOCX in den Workflow. Läuft einphasig durch — kein Warten auf Nutzereingaben. Parallele Workflows sind durch einen eindeutigen Vorgangs-Schlüssel und einen Zeitstempel-Check gegen veraltete Ergebnisse abgesichert.

**Parameter**

| Name | Pflicht? | Default | Beschreibung |
|---|---|---|---|
| `vorlage` | ja | — | Relativer Pfad der Vorlage innerhalb des Vorlagen-Katalogs (muss auf `.php` enden; `..` ist nicht erlaubt). |
| `docx_name` | ja | — | Dokumentname, unter dem die Vorlage ihr DOCX ablegt. |
| `prefill` | nein | — | Block aus `<var>`-Einträgen: die Formularfelder der Vorlage (siehe unten). |
| `output_var` | nein | — | Zusätzlicher Variablenname für den DOCX-Pfad (setzt auch `<output_var>_url`). |
| `timeout` | nein | `30` | Timeout des Aufrufs in Sekunden (min. 5). |

**`<var>`-Attribute im `<prefill>`-Block**

| Attribut | Beschreibung |
|---|---|
| `name` | Feldname im Vorlagen-Formular. Suffix `[]` = Array-Sammelposten (Element mehrfach wiederholen oder per `from_json` expandieren). |
| `from_json` | JSON-String aus einer Kontext-Variable (Platzhalter erlaubt); Einträge werden expandiert. |
| `field` | Bei `from_json`: Schlüssel innerhalb der JSON-Einträge, dessen Wert übernommen wird. |
| `index` | Bei `from_json`: nur den Eintrag an diesem Index als Einzelwert übernehmen. |
| `join` | Bei `from_json` ohne `index`: alle Werte zu **einem** String mit diesem Trenner verbinden (z. B. `,`). |
| `lookup_mail` | `1` = Wert als E-Mail-Adresse interpretieren und über das Personenverzeichnis in die Personen-ID auflösen (bei Nicht-Treffer bleibt der Originalwert erhalten). |
| `unique` | `1` = Duplikate entfernen (greift nach `lookup_mail`, dedupliziert also auf ID-Ebene). |

**Eingangswerte:** Kontext-Variablen für die Prefill-Werte, z. B. `{{vkz}}`, `{{ICH.id}}`, JSON-Variablen aus Auswahl-Tasks wie `{{mkz_auswahl_json}}`.

**Ausgangswerte:**
- `latest_docx_path`, `latest_docx_url` (Kopie des DOCX im Arbeitsverzeichnis des Workflows)
- `<task_id>_uuid` — Vorgangs-Schlüssel des Vorlagen-Aufrufs
- `<task_id>_quelle` — Herkunft des Dokuments (Diagnose)
- optional `<output_var>` und `<output_var>_url`

```xml
<task type="vorlage_docx" id="erstelle_bestaetigung">
  <config>
    <vorlage>Beispielbereich/Eingangsbestaetigung/Eingangsbestaetigung.php</vorlage>
    <docx_name>Eingangsbestätigung</docx_name>
    <prefill>
      <var name="vkz">{{vkz}}</var>
      <var name="bearbeiter">{{ICH.id}}</var>
      <var name="massnahmen[]" from_json="{{mkz_auswahl_json}}" field="mkz" />
      <var name="planer" from_json="{{planer_zuordnung_json}}"
           field="planer_mail" lookup_mail="1" join="," unique="1" />
    </prefill>
    <output_var>bestaetigung_docx</output_var>
  </config>
</task>
```