Document

The Document task is a powerful component in OSPROV's workflow builder that enables automated document generation within your workflows. It allows you to create customized documents based on submission data, such as contracts, certificates, reports, or letters, without requiring manual document preparation.

Purpose

The Document task is designed to:

• Generate documents automatically during workflow execution
• Create customized documents using submission data
• Produce standardized outputs like contracts, certificates, or reports
• Support both HTML-based and Word template-based document generation
• Apply watermarks to documents when needed
• Distribute generated documents via email notifications

Prerequisites

Before you can use a Document task in your workflow, you need to create a document template:

1. Navigate to Documents in the admin menu
2. Click Create New Document
3. You can create a document template in two ways:
   • Enter HTML content directly in the template field
   • Upload a Word document (.docx) template file
4. Save and publish your document template so it becomes available for use in workflows

Adding a Document Task to Your Workflow

Basic Setup

1. In the Workflow Builder, drag the Document task from the task palette onto the canvas
2. Click on the Document task to open its configuration panel
3. Configure the following required settings:
   • Document: Select the document template you want to use from the dropdown menu
   • Title for process: Enter a descriptive title that will appear in the submission history
   • Label for status: (Optional) Override the default status label

Document Selection

The document selection determines what template will be used for generation:

• Select from available document templates in your organization
• Each template contains predefined content with placeholders
• The selected document will be populated with data from the workflow submission
• The generated document is stored with the submission and available for download

Document Filename

• Document filename: Specify a custom filename for the generated document
  • If not specified, the document template name will be used
  • You can use placeholders like [field_name] to include submission data in the filename
  • The system will automatically append a unique ID to ensure uniqueness
  • Special characters and spaces will be replaced with hyphens

Advanced Settings

Datagrid Looping

• Datagrid to loop on: Specify a datagrid field to generate one document per row
  • In the template, reference the current row's fields using ${datagrid.columnKey} (Word) or [datagrid.columnKey] (HTML)

Known issue

The datagrid loop feature has a known code issue and may not generate documents correctly. Email notifications also do not fire for loop-generated documents. Do not use this in production without thorough testing. For most cases, the comma-separated approach (without looping) is more reliable.

Watermarking

• Document Watermark: Specify text to be used as a watermark on the generated document
  • The watermark will appear diagonally across each page
  • You can use placeholders like [field_name] in the watermark text
  • Useful for marking documents as drafts, confidential, or with other statuses

Notification Settings

• Send document as notification: When checked, sends an email notification with the generated document
  • Email Template: Select the email template to use for the notification
  • Sent to which Roles: Select which roles should receive the notification
  • Other Recipients: Additional email addresses to notify (comma-separated)
  • Useful for distributing documents to stakeholders automatically

Visibility Settings

• Hide from submission history: When checked, prevents this document task from appearing in the submission history
  • Useful for keeping the submission history focused on user actions
  • The document is still generated, but the task isn't visible in the history
  • Helps reduce clutter in complex workflows with many tasks

How Document Tasks Work

When a workflow reaches a Document task:

1. The system loads the selected document template
2. If it's an HTML template:
   • Placeholders in the template are replaced with actual submission data
   • The HTML is converted to a PDF document
3. If it's a Word template:
   • Placeholders in the template are replaced with actual submission data
   • The document is converted to PDF using LibreOffice
   • If a watermark is specified, it's applied during conversion
4. If datagrid looping is enabled:
   • A separate document is generated for each row in the specified datagrid
5. The document is stored with the workflow submission
6. If configured, notifications are sent with the document attached
7. The workflow automatically proceeds to the next task

Unlike action tasks (Approve, Review, Process), Document tasks:

• Do not appear in users' task lists
• Do not require any user action to complete
• Execute automatically and immediately
• Create persistent documents that remain available after the workflow completes

note

If document generation fails, the workflow continues. The task is marked as failure in the submission history, but no one is blocked and no task is waiting. Check the submission history for the error message.

Document Placeholders

Document templates use placeholders to insert dynamic content. The placeholder format depends on whether you're using HTML templates or Word document templates.

Placeholder Reference

The following placeholders are available in both HTML and Word templates. Use [placeholder] syntax in HTML templates and ${placeholder} syntax in Word templates — except for the Document Filename and Watermark fields, which always use [placeholder] regardless of template type.

Filename and Watermark always use [key]

Even if you are using a Word template, the Document Filename and Watermark fields use square bracket syntax: [fieldKey]. Only the document body itself uses ${fieldKey} for Word. Mixing up the syntax in these fields means the placeholder will appear as literal text in the output.

Placeholder	What you get
fieldKey	Value of any main form field
user-name	Submitter's full name
workflow-name	The workflow's name
submission-url	Link to the submission
submissionId	Submission reference, e.g. SUB-0001
submittedBy	Username of who submitted
submittedOn	Date and time (d/m/Y g:i:s format)
submittedOn|date	Date only (d/m/Y)
submittedOn|time	Time only (HH:MM:SS, 24-hour)
forms.2.fieldKey	Field from the 2nd supplementary form
forms.2.submittedBy	Who submitted the 2nd supplementary form
forms.2.submittedOn|date	Date the 2nd supplementary form was submitted
datagridKey.columnKey	All values in that datagrid column, comma-separated
YYYY	Current 4-digit year
YY	Current 2-digit year
MM	Current month (01–12)
M	Current month (1–12)
D	Current day of month

HTML Template Placeholders

Use [placeholder] syntax. Example:

<p>Dear [user-name],</p>
<p>Reference: [submissionId] — submitted on [submittedOn|date].</p>
<p>Items requested: [items.itemName]</p>

Word Template Placeholders

Use ${placeholder} syntax in the .docx file body. Example:

Dear ${user-name},

Reference: ${submissionId} — submitted on ${submittedOn|date}.

Signatures — if a placeholder resolves to a base64 image value (e.g. a Signature field), OSPROV automatically inserts it as an image at 400px wide. No special syntax is needed beyond using the correct field key.

Rich text fields — if a field contains HTML (e.g. from a rich text area), OSPROV automatically converts it to Word formatting when inserted into a Word template. Supported: headings, paragraphs, bold/italic/underline, bullet and numbered lists, basic tables. Inline styles such as colour and font size are stripped.

Datagrid without loop — referencing ${datagridKey.columnKey} gives a comma-separated list of all values in that column across all rows. Individual rows cannot be targeted separately without using the loop feature.

Creating placeholders in Word — type the ${...} placeholder directly in the document where you want the value to appear. You can apply Word formatting (font, size, colour) to the placeholder text to control how the inserted value looks.

Example of a Word document template with placeholders:

Dear ${user-name},

Thank you for your submission regarding ${forms.1.subject}.

Project Details:
- Project Name: ${project_name}
- Start Date: ${start_date}
- Budget: ${budget}

Approved by:
${signature_field}

Date: ${YYYY}-${MM}-${D}

These placeholders are automatically replaced with actual data when the document is generated.

Use Cases

Contract Generation

Automate contract creation:

• Generate employment contracts with employee details
• Create vendor agreements with negotiated terms
• Produce service agreements with specific service details
• Generate lease agreements with property and tenant information

Certificate Production

Automate certificate generation:

• Create training completion certificates
• Generate compliance certificates
• Produce award certificates
• Create membership certificates

Report Generation

Automate report creation:

• Generate inspection reports with findings
• Create audit reports with observations
• Produce performance evaluation reports
• Generate incident reports with details

Multi-Document Generation

Generate multiple related documents:

• Create individual receipts for each line item
• Generate separate certificates for each participant
• Produce individual letters for multiple recipients
• Create separate agreements for each service

Best Practices

1. Template design: Create clear, well-formatted document templates with appropriate placeholders
2. Testing: Test document generation with various data scenarios to ensure proper formatting
3. Fallback values: Include default or fallback text for optional fields that might be empty
4. Strategic placement: Position document tasks after all necessary data has been collected
5. Notifications: Configure appropriate notifications to distribute documents to stakeholders
6. Document naming: Use clear naming conventions for document templates and filenames
7. Watermarks: Use watermarks for draft documents or to indicate document status

Troubleshooting

Document Not Generating

If documents aren't being generated:

• Verify that the document template exists and is correctly configured
• Check that placeholders in the template match field names in your forms
• Ensure the document template has been published
• Check the system logs for any errors during document generation
• For Word templates, ensure LibreOffice is properly installed and configured

Missing or Incorrect Data in Documents

If documents contain missing or incorrect data:

• Verify that the referenced fields exist in the submission data
• Check that placeholders are correctly formatted (e.g., [field_name])
• Ensure that supplementary form references use the correct form number
• Test the document template with sample data to identify issues

Notification Issues

If document notifications aren't being sent:

• Verify that the "Send document as notification" option is checked
• Check that the email template exists and is correctly configured
• Ensure recipient information is correctly specified
• Check the system logs for any email sending errors

Watermark Issues

If watermarks aren't appearing on documents:

• Verify that the watermark text is correctly specified
• Check that LibreOffice is properly configured to support watermarks
• Ensure the document conversion process is working correctly
• Test with simple watermark text first, then add placeholders

Related Features

• Document Template Management: Create and manage document templates in the admin interface
• Email Templates: Set up templates for document notifications
• Transform Tasks: Prepare data before document generation
• Submission Documents: View and download generated documents from the submission history

Summary

The Document task is a powerful component in OSPROV's workflow builder that enables automated document generation without requiring manual preparation. By strategically placing document tasks in your workflows, you can create standardized, data-driven documents that are consistent, accurate, and automatically distributed to stakeholders.

Unlike action tasks that require user interaction, document tasks execute automatically and create persistent documents that remain available after the workflow completes. This makes them ideal for contract generation, certificate production, report creation, and multi-document generation throughout your business processes.