External User Task

Overview

The External User Task allows tasks to be assigned to people outside of Pantarey – without requiring a user account. External recipients receive a secure link and can grant approvals, review documents, fill out forms, or interact with individually designed pages.

This makes it possible to integrate approval and coordination workflows with customers, suppliers, or partners directly into an automated process – fully traceable and without manual effort.

Why this is useful

External people can be included in the process directly, without a Pantarey account and without manual overhead. This speeds up coordination and eliminates media breaks.

When to Use the External User Task

Use Case	Description
External approvals	A customer or manager approves an order with a single click.
Document review	An invoice or contract is provided for review as a PDF.
Forms for external people	Data is collected from external people (e.g., contact details, feedback).
Customer interaction	Custom pages for order confirmations, status queries, or feedback.

Configuration in the Process Designer

The External User Task is added as an activity in the Process Designer. The following settings are available in the properties panel:

Recipient: Email address of the external person (can be dynamically populated from process data).
Notification channel: Selection of the delivery method (see below).
HTML templates: Three individually designable pages (task page, success page, already-completed page).
Input parameters: Data made available as placeholders in the templates.

A wizard guides through the configuration step by step.

Notification Channels

The external person is notified via one of the following channels:

Channel	Description
Email (internal)	Sent via the built-in Pantarey email infrastructure.
SMTP	Sent via a custom mail server (SMTP configuration required).
Office 365	Sent via Microsoft Graph (Microsoft 365 integration required).
Microsoft Teams	Notification via a Teams message containing the task link.

Dynamic Values in Notification Fields

All input fields of the notification configuration – recipient, sender, subject, email body, Teams message, and all credentials (SMTP, Office 365, Teams) – can be filled dynamically from process data.

The Pantarey placeholder syntax with round brackets is used for this:

$(path.to.field)

Do not confuse with Handlebars

Notification fields use only the $(…) syntax, not Handlebars ({{…}}). Handlebars is applied only to the HTML templates (task, success, already-completed pages) and to the subject and email body.

Data access

Resolution runs against a combined scope of the input parameter root and the business payload under data:

Fields placed directly on the root of the input parameter are accessible via the short form: $(recipient).
Fields from the business payload are addressed via their path: $(customer.email).
On a name collision the input parameter root wins.

Recommended pattern

Keep the business payload under data and put meta fields (recipient, sender, credentials) explicitly on the root:

{
  "data": $,
  "recipient": customer.email,
  "senderAddress": "noreply@company.com"
}

In the properties panel of the external user task, enter:

Field	Value
Recipient	`$(recipient)`
Sender	`$(senderAddress)`
Subject	`Approval for $(customer.name)`

Further use cases

Tenant-specific SMTP credentials per process instance: $(smtpHost), $(smtpUser), $(smtpPass).
Recipient from a list in the business payload: $(customer.email) (short form of $(data.customer.email), as long as customer does not also exist on the root).
Multi-step approvals with different senders per step – the value is set in the inputParameter of the corresponding activity.

Multiple Recipients (CC/BCC)

For the SMTP and Office 365 channels, the "Change dispatch channel" dialog offers the optional fields CC and BCC alongside the recipient field. This allows additional addressees to be included in copy or blind copy without chaining multiple activities.

Only SMTP and Office 365

The internal Pantarey channel does not support CC and BCC. The fields are not shown in the dialog and would be discarded on send. Microsoft Teams does not send email at all — it delivers a chat message.

What can be entered in the fields

All three fields (recipient, CC, BCC) accept the same input formats:

A single address

text alice@company.com
Multiple addresses, separated by comma or semicolon

text alice@company.com, manager@company.com; archive@company.com
Placeholders (resolved from the input parameters, see Data access)

text $(email)
Multiple placeholders combined

text $(manager), $(deputy)
Placeholders mixed with fixed addresses

text $(email), archive@company.com

Placeholders pointing to list fields

If a placeholder points to an array in the input parameters, the whole array is used. This allows a complete recipient list to be driven by the process payload.

Example — inputParameter (JSONata):

{
  "data": $,
  "mainRecipient": order.owner.email,
  "ccList": order.participants.email
}

Resulting input parameter:

{
  "mainRecipient": "alice@company.com",
  "ccList": ["manager@company.com", "archive@company.com"]
}

Entries in the dialog:

Field	Value
Recipient	`$(mainRecipient)`
CC	`$(ccList)`
BCC	`$(ccList), compliance@company.com`

Behavior notes

CC and BCC may stay empty – that is not an error. Only the recipient field must resolve to at least one valid address.
Within a single field, duplicate addresses are removed automatically.
Across fields, no deduplication is applied: if a person appears both in the recipient and CC field, they will receive the email twice.
Placeholder paths are case-sensitive. $(email) and $(Email) are different paths.
Email addresses are normalized to lowercase internally.

Typical error messages

The task fails with an error if the recipient fields cannot be resolved cleanly. The messages come from the system in English and look like this:

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

The placeholder path does not exist in the input parameters. Typical cause: a typo in the path or a different field name in the payload.

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

The path exists but the value is null or undefined. Often happens when a field was not set in a previous step.

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

A token is not a valid email address. Typical cause: a name or a number was placed into the payload instead of an address.

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

The recipient field is empty after resolution. Occurs, for example, when $(email) points solely to an empty string or an empty array.

If a resolved value contains curly braces ({ or }), the dispatch is also aborted. This indicates that a whole object was written into the placeholder instead of an address — typically a path like $(customer) instead of $(customer.email).

The Three HTML Templates

Each External User Task provides three individually designable HTML pages:

Task Page (Page Template)

The main page displayed to the external person. It presents information, embeds documents, and provides action buttons (e.g., Approve/Reject).

Success Page (Success Template)

Displayed after the task has been completed successfully – for example, after clicking "Approve". Typically contains a confirmation or thank-you message.

Already Completed Page (Completed Template)

Displayed when the external person opens the link again and the task has already been completed. This prevents the task from being processed twice.

Placeholders and Template Syntax

The HTML templates support three types of placeholders that are automatically replaced when the page is rendered:

Layer	Syntax	Purpose
Handlebars variables	`{{variableName}}`	Dynamic data from the input parameters
System placeholders	`%%PLACEHOLDER%%`	System-provided values (URLs, files)
Action buttons	`data-action="..."`	Actions reported back to the process

Handlebars Variables

The templates use Handlebars as the template engine. All variables from the activity's input parameters are available in the templates.

Simple Variables

<p>Dear {{customerName}},</p>
<p>Your order no. {{orderNumber}} has been received.</p>

Nested Objects (Dot Notation)

Values from nested objects are accessed using dot notation:

<p>Invoice recipient: {{invoice.recipient.name}}</p>
<p>Amount: {{invoice.amount}}</p>

HTML Output Without Escaping (Triple-Stache)

By default, special characters are escaped. Triple curly braces output the value as raw HTML:

<div>{{{formattedText}}}</div>

Conditional Display

{{#ifEquals status "urgent"}}
  <div style="color: red; font-weight: bold;">⚠️ Urgent approval required!</div>
{{/ifEquals}}

{{#greaterThan amount 5000}}
  <p>Note: Amounts over €5,000 require management approval.</p>
{{/greaterThan}}

Available Handlebars Helpers

All available helpers for dates, numbers, conditions, text, QR codes, and more are documented in the Handlebars Helpers Reference.

Quick example – QR code for bank transfer data:

<img src="{{{qrCode (buildString "BCD\n001\n1\nSCT\n" bic "\n" recipientName "\n" iban "\nEUR" amount "\n\n\nInvoice " invoiceNumber)}}}" width="200" />

System Placeholders

System placeholders are marked with double percent signs (%%...%%) and are automatically replaced by the system. They are independent of Handlebars.

`%%EXTERNAL_URL%%` — Link to the Task Page

Contains the unique URL to the external task page. Typically used in the notification email:

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

`%%FILE:variableName%%` — Secure File URL

Generates a secure proxy URL to a file referenced in the input parameters. Documents can be embedded or provided for download.

Display PDF in an iFrame:

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

Embed an image:

<img src="%%FILE:productImage%%" alt="Product photo" style="max-width: 400px;" />

Download link:

<a href="%%FILE:contractDocument%%">Download contract</a>

Dot notation is supported to access nested file objects:

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

Prerequisite for %%FILE%%

The referenced variable must be a file object containing referenceId and contentType in the input parameters. This is typically the result of a file upload or a PDF generation in a previous process step.

Action Buttons

Buttons with the data-action HTML attribute are automatically converted into forms that report the chosen action back to the process. The action ID (e.g., approve, reject) is passed as the result to the subsequent process flow and can be used in a gateway to determine the next steps.

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

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

Action IDs are freely definable and can be named as needed (e.g., approve, reject, request_info, escalate).

Complete Example — Approval with PDF View

The following example shows a complete task page combining all three placeholder layers: Handlebars variables for dynamic data, %%FILE%% for PDF embedding, and data-action buttons for reporting the decision back to the process.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Approval Requested</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;">Approval Requested</h1>
    <p style="color: #64748b;">Created on {{currentDate "en-US" "Europe/Berlin"}}</p>

    <div style="background: #f1f5f9; border-radius: 8px; padding: 16px; margin: 24px 0;">
      <p><strong>Requester:</strong> {{requester}}</p>
      <p><strong>Order number:</strong> {{orderNumber}}</p>
      <p><strong>Amount:</strong> {{currency_eur amount}}</p>
    </div>

    {{#greaterThan amount 5000}}
    <div style="background: #fef3c7; border-left: 4px solid #f59e0b; padding: 12px 16px; border-radius: 4px; margin: 16px 0;">
      ⚠️ Amounts over €5,000 require management approval.
    </div>
    {{/greaterThan}}

    <h2 style="color: #334155; margin-top: 32px;">Document</h2>
    <iframe src="%%FILE:invoicePdf%%" 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;">
        ✅ Approve
      </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;">
        ❌ Reject
      </button>
    </div>

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

Practical example: A supplier is asked to approve an order for €7,500. The task page shows the amount, an automatic warning notice (since > €5,000), and the embedded invoice as a PDF. By clicking "Approve" or "Reject", the result is reported directly back to the process.

Tips and Notes

Use inline CSS only

External stylesheets are not loaded. All styles must be specified directly on the HTML element using the style attribute.

The maximum size per template is 50 KB.
Templates are securely rendered in a sandbox.
%%FILE:...%% variables require the referenced variable to be a file object in the input parameters (e.g., the result of a PDF generation).
The Panda AI in the editor can assist with creating and designing templates.
Action IDs in data-action can be evaluated in the subsequent gateway to control the process flow (e.g., approved → continue, rejected → notification).
Templates can be edited and previewed directly in the Process Designer.