Skip to main content

Workflow: Document Type

A Document Type workflow is a special workflow type that defines the process for generating a document such as a PDF, Excel, or CSV. It can be used to generate various document types, such as invoices, purchase orders, and more.

When to Use a Document Type Workflow​

  • To generate PDFs or other file formats for business transactions
  • To automate the creation of standardized documents (e.g., invoices, quotes, certificates)
  • To ensure all relevant data fields are present in the final output

Outputs​

A Workflow Document Type must provide the following outputs:

  • file: Binary data of the generated document. (Required)
  • fileName: Name of the generated document file. (Required)
  • fileDisposition: Attachment disposition of the generated document file (attachment, inline, etc.). (Optional)
    • If no value is provided, it defaults to "attachment".
  • metadata: Structured key-value data used by the template to render dynamic text and persisted for subsequent regeneration cycles. (Optional)

Metadata Lifecycle​

Document workflows support a metadata lifecycle that enables UI-driven text overrides and persistence between generations:

  1. Load source data: Fetch domain data (e.g., Customer, Order) from the database using Query tasks.
  2. Build metadata: Use Utilities/SetVariable@1 to compose the metadata object from loaded data and apply any UI edits (e.g., customer name, address blocks, labels, notes).
  3. Render: Pass the metadata to the template engine within the Document/Render task's data property to produce the document (PDF/XLSX/CSV/... ).
  4. Return: Return the generated file and, if used, the metadata to the caller.

The metadata can be persisted externally (e.g., in the calling application or database) between regeneration cycles, allowing users to modify specific fields via UI before re-generating the document.

Tags​

A Workflow Document Type must have the following tags:

  • invoice: Indicates that the document can be used to generate an invoice document.

  • purchaseOrder: Indicates that the document can be used to generate a purchase order document.

  • quote: Indicates that the document can be used to generate a quote document.

  • parcel: Indicates that the document can be used to generate a parcel document.

  • warehouseReceipt: Indicates that the document can be used to generate a warehouse receipt document.

  • airShipment: Indicates that the document can be used to generate an air shipment document.

  • oceanShipment: Indicates that the document can be used to generate an ocean shipment document.

  • pdf: Indicates that the document is a PDF.

  • html: Indicates that the document is an HTML document.

  • csv: Indicates that the document is a CSV document.

  • xlsx: Indicates that the document is an Excel document.

  • docx: Indicates that the document is a Word document.

  • txt: Indicates that the document is a text document.

  • json: Indicates that the document is a JSON document.

Example​

workflow:
  name: "Documents / Invoice"
  workflowId: "2e28201d-704e-40b1-8568-7a87d198e255"
  isActive: true
  workflowType: "Document"
  executionMode: "Sync" # Document workflows can only be executed in Sync mode
  version: "1.0"
  tags:
    - "invoice"
    - "pdf"

variables:
  - name: "fileName"
    value: "invoice.pdf"
  - name: "organizationId"
    value: 123 # Example usage, set or update as needed

inputs:
  - name: "orderId"
    type: "number"
    props:
      visible: false
  - name: "customerId"
    type: "number"
    props:
      visible: false

outputs:
  - name: "file"
    mapping: "generateDocument.invoice.document" # Binary data of the generated document
  - name: "fileName"
    mapping: "fileName" # Name of the generated document file
  - name: "fileDisposition"
    mapping: "attachment" # Defaults to "attachment" if not specified
  - name: "metadata" # Optional: include when UI-editable metadata is used
    mapping: "metadata"

triggers:
  - type: "Manual" # Document workflows can only be triggered manually
    displayName: "Generate Invoice PDF"
    entityName: "Order"

activities:
  - name: data
    steps:
      - task: "Query/GraphQL"
        name: "getOrder"
        inputs:
          query: |
            query($orderId: Int!, $organizationId: Int!) {
              order(orderId: $orderId, organizationId: $organizationId) {
                ...OrderFields
              }
            }
          variables:
            orderId: "{{ orderId }}"
            organizationId: "{{ organizationId }}"
        outputs:
          - name: "order"
            mapping: "order"

      - task: "Query/GraphQL"
        name: "getCustomer"
        inputs:
          query: |
            query($customerId: Int!, $organizationId: Int!) {
              customer(customerId: $customerId, organizationId: $organizationId) {
                customerId
                name
                billingAddress
              }
            }
          variables:
            customerId: "{{ customerId }}"
            organizationId: "{{ organizationId }}"
        outputs:
          - name: "customer"
            mapping: "customer"

  - name: metadata
    steps:
      - task: "Utilities/SetVariable@1"
        name: "buildMetadata"
        inputs:
          name: "metadata"
          value:
            customerId: "{{ data.getCustomer.customer.customerId }}"
            customerName: "{{ data.getCustomer.customer.name }}"
            billToAddress: "{{ data.getCustomer.customer.billingAddress }}"
            notes: "Please call before delivery"

  - name: generateDocument
    steps:
      - task: "Document/Render"
        name: "invoice"
        inputs:
          template:
            engine: "handlebars"
            recipe: "chrome-pdf"
            content:
              $raw: | # Raw template content to skip workflow template lookup
                <html>
                  <head>
                    <title>Invoice</title>
                  </head>
                  <body>
                    <h1>Invoice</h1>
                    <h3>Bill To</h3>
                    <p>{{ meta.customerName }}</p>
                    <p>{{ meta.billToAddress }}</p>
                    <hr />
                    <p>Order Id: {{ order.orderId }}</p>
                    <p>Order Date: {{ order.orderDate }}</p>
                    <p>Order Total: {{ order.orderTotal }}</p>
                    <p><em>{{ meta.notes }}</em></p>
                  </body>
                </html>
          data:
            order: "{{ data.getOrder.order }}"
            meta: "{{ metadata }}"
        outputs:
          - name: "file"
            mapping: "document" # Binary data of the generated document

Best Practices​

  • Schema versioning: Add a metaVersion field in metadata; when templates change, migrate or default missing fields.
  • Field minimization: Include only fields required for rendering; avoid duplicating large source objects in metadata.
  • PII handling: Do not include sensitive information in metadata unless necessary; apply encryption where required.
  • UI validation: Validate and sanitize user-edited metadata in the calling application before passing to the workflow.
  • Default values: Always provide sensible defaults in the metadata composition step to ensure graceful rendering even if some fields are empty.
  • Auditability: Optionally track updatedBy and updatedAt fields in metadata for traceability of UI edits.
  • Recipe selection: Use chrome-pdf for modern HTML/CSS rendering; use pdf (phantom-pdf) for legacy templates.