Skip to main content

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 multiple documents
    • When specified, the system will generate a separate document for each row in the datagrid
    • In the template, you can reference datagrid fields using datagrid.fieldName syntax
    • Useful for generating multiple similar documents from tabular data

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

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.

HTML Template Placeholders​

In HTML templates, use square brackets to define placeholders:

  • Basic Placeholders

    • Use [field_name] to insert values from the initial submission form
    • Use [forms.N.field_name] to insert values from supplementary forms (e.g., [forms.2.comments])
    • Use [user-name] for the submitter's name
    • Use [workflow-name] for the workflow name
    • Use [submission-url] for a link to the submission

  • Date Placeholders

    • Use [YYYY] for the current 4-digit year
    • Use [YY] for the current 2-digit year
    • Use [MM] for the current month (01-12)
    • Use [M] for the current month (1-12)
    • Use [D] for the current day of month

  • Datagrid Placeholders

    • For main form datagrids: [datagrid_name.field_name] (comma-separated list of values)
    • When using datagrid looping: [datagrid.field_name] (current row value)

Word Document Template Placeholders​

For Word document (.docx) templates, placeholders use a specific format:

  1. Text Placeholders

    • Use the format ${field_name} with curly braces and dollar sign
    • For supplementary forms: ${forms.N.field_name} (e.g., ${forms.2.comments})
    • For system values: ${user-name}, ${workflow-name}, etc.
    • For date values: ${YYYY}, ${MM}, ${D}, etc.
    • For datagrid values when looping: ${datagrid.field_name}

  2. Image Placeholders

    • Use the same format with curly braces: ${signature_field}
    • The system automatically detects if the value is an image (starts with 'data:image')
    • Images are inserted with a standard width of 400 pixels

  3. Creating Placeholders in Word

    • Type the placeholder with the ${...} format directly in the document where you want the value to appear
    • You can format the placeholder text (font, size, color, etc.) to control how the inserted value will appear
    • For repeating values, use the same placeholder name in multiple locations

  4. Special Considerations

    • Word templates are converted to PDF using LibreOffice
    • All placeholders must exactly match the field names in your forms (case-sensitive)
    • HTML formatting in field values will be escaped when inserted into Word documents
    • For complex formatting, use Word's native formatting features in the template

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
  • 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.