Workflows

What This Feature Does

Workflows automate actions that happen when forms are submitted. Instead of manually sending notifications or updating systems, workflows do this automatically. You can send emails, post data to external systems via webhooks, and trigger actions based on specific conditions.

Workflow Components

Every workflow has three parts:

1. Trigger: What starts the workflow (e.g., form submission)
2. Conditions: Optional rules that must be met (e.g., status = "Urgent")
3. Actions: What happens when triggered (e.g., send email)

Creating a Workflow

Setting Up Your First Workflow

1. Navigate to "Forms" in the left sidebar
2. Select the form you want to automate
3. Click the "Workflows" tab
4. Click "Create Workflow"
5. Name your workflow (e.g., "Notify manager on submission")

Configuring the Trigger

1. In the workflow editor, find the "Trigger" section
2. Select when the workflow should run:
   • On Submission: When a new form is submitted
   • On Update: When a submission is edited
   • On Status Change: When submission status changes
   • On Assignment: When submission is assigned
3. Save your trigger configuration

Adding Conditions

Conditions make workflows run only when specific criteria are met.

Adding a Condition

1. In the workflow editor, find the "Conditions" section
2. Click "Add Condition"
3. Configure the condition:
   • Field: Select which form field to check
   • Operator: Choose comparison (equals, contains, greater than, etc.)
   • Value: Enter the value to compare against
4. Add multiple conditions if needed

Condition Operators

AND vs OR Conditions

AND (All must be true):

• Priority equals "High" AND
• Location equals "Main Site"
• Both conditions must match

OR (Any can be true):

• Priority equals "High" OR
• Priority equals "Critical"
• Either condition triggers the workflow

Email Notifications

Send automatic email notifications when forms are submitted.

Creating an Email Action

1. In the workflow editor, find the "Actions" section
2. Click "Add Action"
3. Select "Send Email"
4. Configure the email:
   • To: Recipients (fixed emails or from form fields)
   • Subject: Email subject line
   • Body: Email content

Dynamic Email Content

Use field placeholders to include submission data in emails:

Syntax: {{field_name}}

Example Subject:

New Safety Report: {{location}} - {{date}}

Example Body:

A new safety inspection has been submitted.

Location: {{location}}
Inspector: {{inspector_name}}
Date: {{inspection_date}}
Status: {{overall_status}}

Issues Found: {{issues_description}}

Please review this submission in Assignar Pay.

Recipient Options

Fixed Recipients:

• Enter email addresses directly
• Separate multiple emails with commas

Dynamic Recipients:

• Use {{email_field}} to send to email addresses from form fields
• Use {{assigned_to.email}} to email the assigned user

Role-Based Recipients:

• Send to all users with a specific role
• Send to project managers, supervisors, etc.

Email Best Practices

• Keep subjects clear and informative
• Include key details in the body
• Provide a link back to the submission
• Test with your own email first

Webhook Actions

Send form data to external systems via HTTP webhooks.

Creating a Webhook Action

1. In the workflow editor, add a new action
2. Select "Send Webhook"
3. Configure the webhook:
   • URL: The endpoint to send data to
   • Method: POST, PUT, or PATCH
   • Headers: Optional HTTP headers
   • Payload: Data to send

Webhook Payload

Default Payload: Includes all form fields and submission metadata.

Custom Payload: Define exactly what data to send using JSON format with placeholders:

{
  "event": "form_submitted",
  "form_name": "{{_form_name}}",
  "submitted_by": "{{_submitted_by}}",
  "data": {
    "location": "{{location}}",
    "status": "{{status}}",
    "description": "{{description}}"
  }
}

Authentication

For secured webhooks, add authentication headers:

API Key:

Header: X-API-Key
Value: your-api-key-here

Bearer Token:

Header: Authorization
Value: Bearer your-token-here

Using Secrets for Credentials

Store sensitive credentials securely:

1. Navigate to form settings
2. Go to "Secrets" section
3. Add a new secret (e.g., WEBHOOK_API_KEY)
4. Reference in webhook headers: {{secrets.WEBHOOK_API_KEY}}

See Permissions for more on secrets management.

Common Webhook Integrations

• Slack notifications
• Microsoft Teams alerts
• Custom APIs
• Data warehouses
• Third-party project management tools

Multiple Actions

Workflows can have multiple actions that run in sequence or parallel.

Adding Multiple Actions

1. After creating your first action, click "Add Action"
2. Configure the additional action
3. Repeat for all desired actions
4. Actions run in the order listed

Action Order

Actions execute from top to bottom:

1. First action completes
2. Second action starts
3. And so on...

If an action fails, subsequent actions may still run (depending on configuration).

Parallel vs Sequential

Sequential (Default):

• Actions run one after another
• Next action waits for previous to complete

Parallel:

• Actions run simultaneously
• Faster execution for independent actions

Workflow Examples

Example 1: Notify Manager on High Priority Submissions

Trigger: On Submission

Conditions:

• Priority equals "High" OR Priority equals "Critical"

Actions:

1. Send Email to manager@company.com
   • Subject: URGENT: New {{form_name}} requires attention
   • Body: Include submission details

Example 2: Sync to External System

Trigger: On Submission

Conditions: None (all submissions)

Actions:

1. Send Webhook to integration endpoint
   • URL: https://api.external-system.com/submissions
   • Method: POST
   • Include all form data

Example 3: Multi-Step Approval Notification

Trigger: On Status Change

Conditions:

• Status equals "Approved"

Actions:

1. Send Email to submitter ({{submitted_by_email}})
   • Subject: Your {{form_name}} has been approved
2. Send Webhook to project management system
3. Send Email to accounting team

Example 4: Escalation Workflow

Trigger: On Submission

Conditions:

• Issue Type equals "Safety Incident"
• Severity equals "Critical"

Actions:

1. Send Email to safety officer
2. Send Email to site manager
3. Send Webhook to incident tracking system
4. Send SMS notification (via webhook to SMS service)

Testing Workflows

Test Mode

1. In the workflow editor, click "Test"
2. Fill in sample field values
3. Click "Run Test"
4. View results:
   • Conditions evaluated
   • Actions that would run
   • Email preview (not actually sent)
   • Webhook payload preview

Live Testing

1. Enable the workflow
2. Submit a real form that matches your conditions
3. Verify actions completed:
   • Check email inboxes
   • Check webhook endpoints
   • Review workflow execution logs

Viewing Workflow Logs

1. Navigate to form's "Workflows" tab
2. Click on a workflow
3. Select "Execution History"
4. View details:
   • When workflow ran
   • Which conditions matched
   • Action results (success/failure)
   • Error messages if any

Managing Workflows

Enabling/Disabling Workflows

1. Navigate to the workflows list
2. Toggle the "Enabled" switch
3. Disabled workflows don't run but are preserved

Editing Workflows

1. Click on the workflow to edit
2. Make your changes
3. Save the workflow
4. Changes take effect immediately

Duplicating Workflows

1. Click the actions menu on a workflow
2. Select "Duplicate"
3. A copy is created
4. Edit the copy as needed

Deleting Workflows

1. Click the actions menu on a workflow
2. Select "Delete"
3. Confirm deletion
4. Workflow is permanently removed

Troubleshooting

If emails aren't sending

• Verify recipient email addresses are valid
• Check spam/junk folders
• Review workflow conditions
• Check execution logs for errors
• Verify email service is configured

If webhooks are failing

• Check the URL is correct and accessible
• Verify authentication credentials
• Check webhook endpoint logs
• Review payload format
• Test endpoint manually

If conditions aren't matching

• Review condition configuration
• Check field values in submissions
• Test with simplified conditions first
• Use workflow logs to debug

If workflows aren't triggering

• Verify workflow is enabled
• Check the trigger type matches the event
• Review conditions are correctly configured
• Submit a test form to verify

Best Practices

• Start simple: Begin with basic workflows and add complexity
• Test thoroughly: Always test before enabling in production
• Document workflows: Note what each workflow does and why
• Monitor logs: Regularly review execution logs
• Use conditions wisely: Don't over-complicate
• Handle errors gracefully: Plan for webhook failures
• Secure credentials: Use secrets for API keys
• Review periodically: Update workflows as needs change

What's Next

After setting up workflows, you may want to:

• Create Document Templates for automated reports
• Configure Permissions for workflow management
• Review Submissions to see workflow effects
• Set up Views for monitoring workflow results