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 (supports {{SECRET_NAME}} placeholders)
   • Method: GET, POST, PUT, PATCH, or DELETE (GET and DELETE send no body)
   • Headers: Optional HTTP headers, one per line (Header-Name: value)
   • Payload: One of three payload modes (below)

Payload Modes

Full payload (default): Sends the complete submission in a fixed structure — submission ID, form ID, account ID, all field responses under data, and a timestamp. Existing webhooks keep this behaviour.

Select fields: Choose exactly which form fields to include, optionally rename their keys to match the receiving system, and toggle each metadata field (submission ID, form ID, account ID, timestamp) individually. Values keep their native types. Each selected field can also carry a condition so it is only included when the submission matches (e.g. only send overtime_hours when hours exceed a threshold).

Custom template: Write the exact JSON body using {{field_name}} placeholders for form fields and _-prefixed system variables:

{
  "employee": { "name": "{{worker_name}}" },
  "timesheet": { "hours": {{hours_worked}}, "date": "{{shift_date}}" },
  "source": "assignar-pay",
  "submitted_at": "{{_timestamp}}"
}

Placeholders inside quotes become text; standalone placeholders keep their native JSON type (numbers stay numbers, arrays stay arrays). Unresolved variables become null. Available system variables: _submissionId, _formId, _accountId, _timestamp, _formTitle, _submissionVersion, _submittedBy, _triggerEvent. The editor validates the template as JSON and offers a variable picker.

Previewing and Testing

• Preview payload shows the exact JSON the webhook would send, built from your latest submission (or sample values when the form has none). Secrets are never resolved in previews.
• Send test fires a real request at the configured endpoint — with secrets resolved and signing applied — so you can verify the integration end to end before enabling the workflow.

Webhook Templates and Presets

Use the Templates menu on a webhook step to save the current configuration (URL, method, payload settings, headers) as a reusable account-wide template, or apply a saved template / built-in preset. With a connected Assignar integration, presets for common Assignar API calls are available out of the box. Templates store secret references only — never secret values.

Authentication with Secrets

Store sensitive credentials securely:

1. Open the form's "Secrets" tab
2. Add a new secret (e.g., WEBHOOK_API_KEY) — local to the form or global to the account
3. Reference it in the webhook URL or headers: Authorization: Bearer {{WEBHOOK_API_KEY}}

Resolution priority is local form secrets, then global form secrets, then integration secrets.

Integration Secrets

With a connected integration (e.g. Assignar), virtual secrets become available without storing anything yourself:

For example, a webhook calling the Assignar API directly:

URL:     {{ASSIGNAR_API_URL}}/timesheets
Method:  POST
Headers: Authorization: Bearer {{ASSIGNAR_TOKEN}}

Tokens are cached for the duration of a workflow run, refreshed automatically when expired, and never written to logs. The form's Secrets tab lists available integration secrets and offers a "Test resolution" health check. If a step references integration secrets from a disconnected integration, the editor shows a warning.

Payload Signing (HMAC)

Enable Sign payload on a webhook step to let receivers verify authenticity. Each request then carries:

• X-Webhook-Timestamp: the send time in milliseconds
• X-Webhook-Signature: sha256=<hex> — an HMAC-SHA256 over timestamp.body, keyed by a form secret you choose

Receivers recompute the HMAC with the shared secret and compare; the timestamp guards against replay.

Common Webhook Integrations

• Slack notifications
• Microsoft Teams alerts
• Assignar API (via integration secrets)
• 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 the form's "Workflows" tab
2. Open the actions menu on a workflow and select "View runs"
3. Expand a run to see per-step details:
   • When the workflow ran, its trigger and duration
   • Each step's result (success/failure) and error messages
   • Webhook delivery logs: HTTP status, response time, the response body, and which secrets resolved (values are never logged)

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