Externer User Task

Überblick

Der Externe User Task ermöglicht es, Aufgaben an Personen außerhalb von Pantarey zu vergeben – ohne dass diese einen Benutzeraccount benötigen. Externe Personen erhalten einen sicheren Link und können darüber Freigaben erteilen, Dokumente prüfen, Formulare ausfüllen oder individuell gestaltete Seiten nutzen.

So lassen sich Freigabe- und Abstimmungsprozesse mit Kunden, Lieferanten oder Partnern direkt in den eigenen Workflow integrieren – vollständig automatisiert und nachvollziehbar.

Warum das hilfreich ist

Externe Personen werden direkt in den Prozess eingebunden, ohne Pantarey-Konto und ohne manuellen Aufwand. Das beschleunigt Abstimmungen und eliminiert Medienbrüche.

---

Wann wird der Externe User Task eingesetzt?

Anwendungsfall	Beschreibung
Freigaben durch Externe	Ein Kunde oder Vorgesetzter genehmigt einen Auftrag per Klick.
PDF-Prüfung	Eine Rechnung oder ein Vertrag wird zur Prüfung bereitgestellt.
Formulare für Externe	Daten werden von externen Personen erfasst (z. B. Kontaktdaten, Rückmeldungen).
Kundeninteraktion	Individuelle Seiten für Bestellbestätigungen, Statusabfragen oder Feedback.

---

Konfiguration im Prozess-Designer

Der Externe User Task wird im Prozess-Designer als Aktivität eingefügt. Im Properties-Panel stehen folgende Einstellungen zur Verfügung:

• Empfänger: E-Mail-Adresse der externen Person (kann dynamisch aus Prozessdaten befüllt werden).
• Benachrichtigungskanal: Auswahl des Versandwegs (siehe unten).
• HTML-Vorlagen: Drei individuell gestaltbare Seiten (Aufgabenseite, Erfolgsseite, Bereits-erledigt-Seite).
• Input-Parameter: Daten, die in den Vorlagen als Platzhalter zur Verfügung stehen.

Ein Assistent (Wizard) führt Schritt für Schritt durch die Konfiguration.

---

Benachrichtigungskanäle

Die externe Person wird über einen der folgenden Kanäle benachrichtigt:

Kanal	Beschreibung
E-Mail (intern)	Versand über die interne Pantarey-E-Mail-Infrastruktur.
SMTP	Versand über einen eigenen Mailserver (SMTP-Konfiguration erforderlich).
Office 365	Versand über Microsoft Graph (Microsoft 365-Integration erforderlich).
Microsoft Teams	Benachrichtigung über eine Teams-Nachricht mit Link zur Aufgabe.

---

Dynamische Werte in den Versandfeldern

Alle Eingabefelder der Benachrichtigungskonfiguration – Empfänger, Absender, Betreff, E-Mail-Text, Teams-Nachricht sowie sämtliche Credentials (SMTP, Office 365, Teams) – können dynamisch aus Prozessdaten befüllt werden.

Hierfür wird die Pantarey-Platzhalter-Syntax mit runden Klammern verwendet:

$(pfad.zum.feld)

Nicht mit Handlebars verwechseln

In den Versandfeldern greift nicht Handlebars ({{…}}), sondern ausschließlich die $(…)-Syntax. Handlebars wird nur in den HTML-Vorlagen (Aufgaben-, Erfolgs-, Bereits-erledigt-Seite) sowie in Betreff und E-Mail-Text ausgewertet.

Datenzugriff

Die Auflösung erfolgt gegen den kombinierten Scope aus Input-Parameter-Root und dem Business-Payload unter data:

• Felder, die direkt auf der Wurzel des Input-Parameters liegen, sind per Kurzform erreichbar: $(recipient).
• Felder aus dem Business-Payload werden über ihren Pfad angesprochen: $(kunde.email).
• Bei Namenskollisionen gewinnt die Wurzel des Input-Parameters.

Empfohlenes Muster

Der Business-Payload bleibt unter data, Meta-Felder (Empfänger, Absender, Credentials) werden explizit auf der Wurzel abgelegt:

{
  "data": $,
  "recipient": kunde.email,
  "senderAddress": "noreply@firma.de"
}

Im Properties-Panel des Externen User Tasks wird dann eingetragen:

Feld	Wert
Empfänger	$(recipient)
Absender	$(senderAddress)
Betreff	Freigabe für $(kunde.name)

Weitere Anwendungsfälle

• Tenant-spezifische SMTP-Credentials pro Prozessinstanz: $(smtpHost), $(smtpUser), $(smtpPass).
• Empfänger aus einer Liste im Business-Payload: $(kunde.email) (Kurzform für $(data.kunde.email), sofern kunde nicht auch auf der Wurzel existiert).
• Mehrstufige Freigaben mit unterschiedlichen Absendern je Stufe – der Wert wird im inputParameter der jeweiligen Aktivität gesetzt.

Mehrere Empfänger (CC/BCC)

Für die Kanäle SMTP und Office 365 stehen im Dialog „Versandweg ändern" neben dem Empfänger-Feld zusätzlich die optionalen Felder CC und BCC zur Verfügung. Damit lassen sich weitere Adressaten in Kopie oder Blindkopie einbinden, ohne dass mehrere Aktivitäten hintereinander geschaltet werden müssen.

Nur SMTP und Office 365

Beim internen Pantarey-Kanal sind CC und BCC nicht möglich. Die Felder werden im Dialog nicht angeboten und beim Versand nicht berücksichtigt. Microsoft Teams versendet ohnehin keine E-Mail, sondern eine Chat-Nachricht.

Was in den Feldern eingetragen werden darf

Alle drei Felder (Empfänger, CC, BCC) unterstützen die gleichen Eingabeformen:

• Einzelne Adresse

  text max@firma.de

• Mehrere Adressen, getrennt mit Komma oder Semikolon

  text max@firma.de, chef@firma.de; archiv@firma.de

• Platzhalter (aufgelöst aus dem Input-Parameter, siehe Datenzugriff)

  text $(email)

• Mehrere Platzhalter kombiniert

  text $(chef), $(vertreter)

• Platzhalter und feste Adressen gemischt

  text $(email), archiv@firma.de

Platzhalter auf Listen-Felder

Zeigt ein Platzhalter auf ein Array im Input-Parameter, wird das Array vollständig übernommen. Damit kann eine Empfängerliste komplett aus dem Prozess-Payload gesteuert werden.

Beispiel — inputParameter (JSONata):

{
  "data": $,
  "hauptempfaenger": auftrag.verantwortlicher.email,
  "cc_liste": auftrag.beteiligte.email
}

Ergebnis im Input-Parameter:

{
  "hauptempfaenger": "max@firma.de",
  "cc_liste": ["chef@firma.de", "archiv@firma.de"]
}

Einträge im Dialog:

Feld	Wert
Empfänger	$(hauptempfaenger)
CC	$(cc_liste)
BCC	$(cc_liste), compliance@firma.de

Hinweise zum Verhalten

• CC und BCC dürfen leer bleiben – das ist kein Fehler. Nur das Empfänger-Feld muss nach der Auflösung mindestens eine gültige Adresse enthalten.
• Innerhalb eines Feldes werden doppelte Adressen automatisch entfernt.
• Zwischen den Feldern wird nicht dedupliziert: Steht eine Person sowohl im Empfänger- als auch im CC-Feld, erhält sie die E-Mail zweimal.
• Platzhalter-Pfade sind groß-/kleinschreibungsempfindlich. $(email) und $(Email) sind unterschiedliche Pfade.
• E-Mail-Adressen werden intern auf Kleinschreibung normalisiert.

Typische Fehlermeldungen

Der Task bricht mit einer Fehlermeldung ab, wenn die Empfängerfelder nicht sauber aufgelöst werden können. Die Meldungen kommen in englischer Sprache aus dem System und lauten z. B.:

Field "To" contains an unresolved placeholder ("$(chefmail)"). Please check the placeholder path and the input parameter data.

Der Platzhalter-Pfad existiert im Input-Parameter nicht. Typischer Fall: Tippfehler im Pfad oder Feld heißt im Payload anders.

Field "To" contains "undefined" — the placeholder path exists but has no value. Please check the input parameter data.

Der Pfad existiert, der Wert ist aber null oder undefined. Häufig, wenn ein Feld im Vorprozess nicht gesetzt wurde.

Field "BCC" contains "max mustermann" — this is not a valid email address (missing @).

Ein Token ist keine gültige E-Mail-Adresse. Häufig, wenn statt einer Adresse ein Name oder eine Zahl im Payload steht.

External User Task "Freigabe einholen": no To recipient after placeholder resolution — please check the recipient field and the input parameter data.

Das Empfänger-Feld ist nach der Auflösung leer. Tritt z. B. auf, wenn $(email) ausschließlich auf einen leeren String oder ein leeres Array zeigt.

Enthält ein aufgelöster Wert geschweifte Klammern ({ oder }), wird der Versand ebenfalls abgebrochen. Das ist ein Hinweis darauf, dass statt einer Adresse versehentlich ein ganzes Objekt in den Platzhalter geschrieben wurde – typischerweise ein Pfad wie $(kunde) statt $(kunde.email).

---

Die drei HTML-Vorlagen

Jeder Externe User Task verfügt über drei individuell gestaltbare HTML-Seiten:

Aufgabenseite (Page Template)

Die Hauptseite, die der externen Person angezeigt wird. Hier werden Informationen dargestellt, Dokumente eingebettet und Aktionen (z. B. Genehmigen/Ablehnen) bereitgestellt.

Erfolgsseite (Success Template)

Wird angezeigt, nachdem die Aufgabe erfolgreich abgeschlossen wurde – z. B. nach dem Klick auf „Genehmigen". Typischerweise enthält sie eine Bestätigung oder Danksagung.

Bereits-erledigt-Seite (Completed Template)

Wird angezeigt, wenn die externe Person den Link erneut öffnet und die Aufgabe bereits abgeschlossen ist. Damit wird verhindert, dass eine Aufgabe doppelt bearbeitet wird.

---

Platzhalter und Template-Syntax

Die HTML-Vorlagen unterstützen drei Arten von Platzhaltern, die beim Rendern der Seite automatisch ersetzt werden:

Ebene	Syntax	Zweck
Handlebars-Variablen	{{variablenname}}	Dynamische Daten aus dem Input-Parameter
System-Platzhalter	%%PLATZHALTER%%	Vom System bereitgestellte Werte (URLs, Dateien)
Action-Buttons	data-action="..."	Aktionen, die an den Prozess zurückgemeldet werden

---

Handlebars-Variablen

Die Vorlagen verwenden Handlebars als Template-Engine. Alle Variablen aus dem Input-Parameter der Aktivität stehen in den Vorlagen zur Verfügung.

Einfache Variablen

<p>Sehr geehrte/r {{kundenname}},</p>
<p>Ihre Bestellung Nr. {{bestellnummer}} ist eingegangen.</p>

Verschachtelte Objekte (Dot-Notation)

Werte aus verschachtelten Objekten werden mit Punktnotation angesprochen:

<p>Rechnungsempfänger: {{rechnung.empfaenger.name}}</p>
<p>Betrag: {{rechnung.betrag}}</p>

HTML-Ausgabe ohne Escaping (Triple-Stache)

Standardmäßig werden Sonderzeichen escaped. Mit dreifachen geschweiften Klammern wird der Wert als HTML ausgegeben:

<div>{{{formatierterText}}}</div>

Bedingte Anzeige

{{#ifEquals status "dringend"}}
  <div style="color: red; font-weight: bold;">⚠️ Dringende Freigabe erforderlich!</div>
{{/ifEquals}}

{{#greaterThan betrag 5000}}
  <p>Hinweis: Beträge über 5.000 € benötigen die Freigabe der Geschäftsleitung.</p>
{{/greaterThan}}

---

Verfügbare Handlebars-Helper

Alle verfügbaren Helper für Datum, Zahlen, Bedingungen, Text, QR-Code und mehr sind in der Handlebars-Helper-Referenz dokumentiert.

Kurzbeispiel – QR-Code für Überweisungsdaten:

<img src="{{{qrCode (buildString "BCD\n001\n1\nSCT\n" bic "\n" empfaengerName "\n" iban "\nEUR" betrag "\n\n\nRechnung " rechnungsnummer)}}}" width="200" />

---

System-Platzhalter

System-Platzhalter werden mit doppelten Prozentzeichen (%%...%%) gekennzeichnet und vom System automatisch ersetzt. Sie sind unabhängig von Handlebars.

%%EXTERNAL_URL%% — Link zur Aufgabenseite

Enthält die eindeutige URL zur externen Aufgabenseite. Wird typischerweise in der Benachrichtigungs-E-Mail verwendet:

<a href="%%EXTERNAL_URL%%" style="display: inline-block; background: #ec7404; color: white; padding: 12px 24px; border-radius: 8px; text-decoration: none;">
  Zur Aufgabe
</a>

%%FILE:variablenname%% — Sichere Datei-URL

Erzeugt eine sichere Proxy-URL zu einer Datei, die im Input-Parameter referenziert ist. Damit können Dokumente eingebettet oder zum Download bereitgestellt werden.

PDF im iFrame anzeigen:

<iframe src="%%FILE:rechnungPdf%%" width="100%" height="600px" style="border: none;"></iframe>

Bild einbetten:

<img src="%%FILE:produktbild%%" alt="Produktfoto" style="max-width: 400px;" />

Download-Link:

<a href="%%FILE:vertragsdokument%%">Vertrag herunterladen</a>

Dot-Notation wird unterstützt, um auf verschachtelte Dateiobjekte zuzugreifen:

<iframe src="%%FILE:auftrag.anlage_pdf%%" width="100%" height="500px"></iframe>

Voraussetzung für %%FILE%%

Die referenzierte Variable muss im Input-Parameter ein Dateiobjekt mit referenceId und contentType enthalten. Dies ist typischerweise das Ergebnis eines Datei-Uploads oder einer PDF-Generierung im vorherigen Prozessschritt.

---

Action-Buttons

Buttons mit dem HTML-Attribut data-action werden automatisch in Formulare umgewandelt, die die gewählte Aktion an den Prozess zurückmelden. Die Action-ID (z. B. approve, reject) wird als Ergebnis an den weiteren Prozessverlauf weitergegeben und kann z. B. in einem Gateway als Entscheidungsgrundlage eingesetzt werden.

<button data-action="approve" style="background: #22c55e; color: white; padding: 12px 24px; border: none; border-radius: 8px; cursor: pointer; font-size: 16px;">
  ✅ Genehmigen
</button>

<button data-action="reject" style="background: #ef4444; color: white; padding: 12px 24px; border: none; border-radius: 8px; cursor: pointer; font-size: 16px;">
  ❌ Ablehnen
</button>

Die Action-IDs sind frei wählbar und können beliebig benannt werden (z. B. approve, reject, request_info, escalate).

---

Vollständiges Beispiel — Freigabe mit PDF-Ansicht

Das folgende Beispiel zeigt eine komplette Aufgabenseite, die alle drei Platzhalter-Ebenen kombiniert: Handlebars-Variablen für dynamische Daten, %%FILE%% für die PDF-Einbettung und data-action-Buttons für die Rückmeldung an den Prozess.

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Freigabe angefordert</title>
</head>
<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; background: #f8fafc;">
  <div style="background: white; border-radius: 12px; padding: 32px; box-shadow: 0 1px 3px rgba(0,0,0,0.1);">

    <h1 style="color: #1e293b; margin-bottom: 8px;">Freigabe angefordert</h1>
    <p style="color: #64748b;">Erstellt am {{currentDate "de-DE" "Europe/Berlin"}}</p>

    <div style="background: #f1f5f9; border-radius: 8px; padding: 16px; margin: 24px 0;">
      <p><strong>Antragsteller:</strong> {{antragsteller}}</p>
      <p><strong>Bestellnummer:</strong> {{bestellnummer}}</p>
      <p><strong>Betrag:</strong> {{currency_eur betrag}}</p>
    </div>

    {{#greaterThan betrag 5000}}
    <div style="background: #fef3c7; border-left: 4px solid #f59e0b; padding: 12px 16px; border-radius: 4px; margin: 16px 0;">
      ⚠️ Beträge über 5.000 € benötigen die Freigabe der Geschäftsleitung.
    </div>
    {{/greaterThan}}

    <h2 style="color: #334155; margin-top: 32px;">Dokument</h2>
    <iframe src="%%FILE:rechnungPdf%%" width="100%" height="500px"
            style="border: 1px solid #e2e8f0; border-radius: 8px;">
    </iframe>

    <div style="display: flex; gap: 12px; margin-top: 32px; justify-content: center;">
      <button data-action="approve"
              style="background: #22c55e; color: white; padding: 14px 32px; border: none; border-radius: 8px; cursor: pointer; font-size: 16px; font-weight: 600;">
        ✅ Genehmigen
      </button>
      <button data-action="reject"
              style="background: #ef4444; color: white; padding: 14px 32px; border: none; border-radius: 8px; cursor: pointer; font-size: 16px; font-weight: 600;">
        ❌ Ablehnen
      </button>
    </div>

  </div>
</body>
</html>

Praxisbeispiel: Ein Lieferant soll eine Bestellung über 7.500 € freigeben. Die Aufgabenseite zeigt den Betrag, einen automatischen Warnhinweis (da > 5.000 €) sowie die eingebettete Rechnung als PDF. Per Klick auf „Genehmigen" oder „Ablehnen" wird das Ergebnis direkt an den Prozess zurückgemeldet.

---

Tipps und Hinweise

Nur Inline-CSS verwenden

Externe Stylesheets werden nicht geladen. Alle Styles müssen direkt im HTML-Element als style-Attribut angegeben werden.

• Die maximale Größe pro Vorlage beträgt 50 KB.
• Die Vorlagen werden sicher in einer Sandbox dargestellt.
• %%FILE:...%%-Variablen setzen voraus, dass die referenzierte Variable im Input-Parameter ein Dateiobjekt enthält (z. B. das Ergebnis einer PDF-Generierung).
• Die Panda-KI im Editor kann beim Erstellen und Gestalten von Templates unterstützen.
• Action-IDs in data-action können im nachfolgenden Gateway ausgewertet werden, um den Prozessfluss zu steuern (z. B. genehmigt → weiter, abgelehnt → Benachrichtigung).
• Vorlagen können direkt im Prozess-Designer bearbeitet und in der Vorschau geprüft werden.