​

I. My Workflows

1. Log in and navigate to the “Workflows” builder section from the sidebar.

2. Click the”Ellipsis” icon.

• Activate/Inactivate: Toggle a workflow’s status using the activate/inactive button.

• Execution history: Click the “Execution History” button to view the workflow execution history records.

• Delete: Click the “Delete” button to delete the workflow.

• The interface tracks the number of workflows created based on your subscription.
• For example, as shown here, you can have 10 workflows active at a time.

​

Sort:

​

Creating Workflows

1. Start from Scratch: Open the workflow canvas, click “Add a node,” and build a custom flow by dragging and connecting nodes.

2. After creating the workflow, click “Test Workflow.”

3. Click “Save and Publish” to create the new workflow.

4. Click the “Revision History” to view the changes in the workflow.

5. Click the “Execution History” to view the workflow executions.

6. Click the “Export Workflow” to transfer the workflow to another system.

7. Click the “Settings” to modify the preferences.

8. Adjust the values and click “Save.” The concurrency limit specifies the exact number of simultaneous executions allowed. Any additional executions will be paused until the current ones are completed. For instance, if 100 records are triggered for workflow execution and the concurrency limit is set to 1, 99 records will wait until the single active execution finishes.

9. Click “Delete Workflow” to delete the workflow.        

​

II. Templates

• Use Prebuilt Templates: Navigate to “Templates,” select a template (e.g., “Job to Invoice”), and edit it on the canvas.

• Import Workflows: Use the “Import Workflow” option to upload a previously exported .json file and adjust as needed.

1. Access the Import Option: Navigate to the “Workflows” section in your Zuper instance. Look for the “Import Workflow” option, which allows you to upload a JSON file. This option is typically found in the workflow management area of the Zuper interface.
2. Upload the JSON File: Select the “Import Workflow” option, and a file browser window will appear. Select the previously exported .json file containing the workflow you want to import. Ensure the file was exported from Zuper, as only Zuper-exported workflows are compatible.
3. Adjust the Workflow: Once the file is uploaded, the workflow will appear in your Zuper workflows list. Open the imported workflow to customize it as needed. This may involve updating configurations, adjusting settings, or modifying the workflow logic to suit your requirements.

• Only workflows exported from Zuper can be imported.
• If you encounter issues during the import process, ensure the JSON file is valid and properly formatted. You may need to check Zuper’s documentation or contact their support for assistance if the file fails to import.

• Add the missing variables.

• Navigate to the Workflows section in the sidebar. Click the Templates to view the available options. Use the search bar or sort by name to find a specific template.

• Click any of the templates to use them for workflow creation. Then, Click “Use this template” to create the workflow.

​

III. Execution History

• Filters: Use dropdowns to filter by Workflow, All Status, Triggered Date, and Mode. Check the “Flagged” box to view only flagged items.
• Search: Enter a Workflow Name in the search bar to quickly find specific executions.
• Columns:
  • Execution ID: Unique identifier for each execution.
  • Workflow Name: Name of the executed workflow.
  • Triggered at: Time when the workflow was initiated.
  • Executed at: Time when the workflow was processed.
  • Status: Indicates success (green), failure (red), in progress (yellow), or queued (gray).
  • Time Taken: Duration of the execution, with warnings for failures.
• Total Executions: Displays the number of executions for the current month, along with the remaining quota.
• Pagination: Navigate through pages using the controls at the bottom.

• Success: Workflow completed without issues (green checkmark).
• Failed: Workflow encountered an error (red “X” with warning icon).
• In Progress: The Workflow is currently running.
• Queued: The Workflow is waiting to be processed.

• Created Time: The timestamp when the workflow is queued or initiated in the system. This may be slightly later than the Triggered Time due to system processing or queueing delays.
• Triggered Time: The timestamp when the trigger condition is met (e.g., when a “Job Created” event occurs or a webhook is received).
• Why It’s Helpful:
  • Troubleshooting: A large gap between Triggered Time and Created Time may indicate system latency or resource issues.
  • Audit Accuracy: Triggered Time confirms when the event occurred, while Created Time shows when the system began processing.
  • Performance Optimization: Monitoring this gap helps improve workflow efficiency, especially for time-sensitive tasks.
  • Compliance: Precise Triggered Times align executions with external events or schedules for auditing purposes.

​

Triggers and Events

​

Types of Triggers

• Webhook Trigger: Initiates a workflow when an external system sends a request to a configured URL endpoint. Configure the endpoint in the node settings for real-time data integration.

​

Advanced Settings:

​

What is a Webhook?

​

Setting Up a Webhook Trigger

1. Access the Workflow: Open the Zuper Workflow Builder and select or create a new workflow.
2. Add a Trigger: Click on the ”+” button and choose “On Webhook” from the trigger options.
3. Configure the Webhook:
   • Trigger Name: Assign a unique name to identify the webhook.
   • Webhook Method: Select the HTTP method (e.g., GET, POST).
   • Webhook URL: Define the URL where the webhook will listen (eg:https://staging-workflow.zuperpro.com/api/gate
   • Advanced Settings: Optionally, set up response settings or headers (e.g., Key: “Authorization”, Value: “Bearer 789”).
4. Save the Draft: Click “Save as Draft” to store your configuration.

​

Responding to Webhook Events

• Response Settings: Configure what happens after the webhook is triggered. For instance, you can set the workflow to notify when it finishes or send an email.
• Error Handling: Define actions for cases of failure, such as retrying the request or notifying the team.

​

Benefits of Using Webhooks

• Real-Time Automation: Instantly trigger workflows based on external events.
• Flexibility: Integrate with a wide range of third-party services.
• Efficiency: Reduce manual intervention by automating responses to specific triggers.

​

Best Practices

• Ensure the webhook URL is secure and accessible.
• Test the workflow using the “Test Until Node” feature to verify functionality.
• Regularly review and update webhook configurations to align with changing requirements.

​

Tips and Tricks:

• x-module: Specifies the module type (e.g., job).
• x-module-uid: Specifies the unique identifier of the record in that module (e.g., abc123 for a job).

• Workflow: WF1, triggered by a webhook.
• Webhook Endpoint: https://zuper.workflow.endpoint/wf1 (referred to as API1).
• Webhook Request Headers:

http

CollapseWrap

Copy

x-module: job

x-module-uid: abc123

• Result:
  • The workflow WF1 is triggered, creating an execution instance (WF1Ex1).
  • This execution is logged and associated with the job record identified by abc123.
  • The association appears in the “associations” section of the job details page for abc123 in the Zuper platform.

1. Purpose: The x-module and x-module-uid headers allow precise linking of webhook-triggered workflow executions to specific records, improving traceability and organization within the platform.
2. Use Case: This is useful for automation scenarios where external systems (e.g., via webhooks) trigger workflows in Zuper, and you want to tie those executions to specific entities like jobs, tasks, or other modules.
3. Display: The association is visible in the side pane of the record’s details page, making it easy to track related workflow executions.

​

Implementation Guidance

​

1. Setting Up the Webhook

• Endpoint Configuration: Ensure the webhook endpoint (e.g., https://zuper.workflow.endpoint/wf1) is correctly configured in the Zuper platform to trigger the desired workflow (WF1).
• Authentication: Verify if the webhook requires authentication (e.g., an API key or token). For example, some platforms require headers like X-Airplane-API-Key for secure webhook execution.docs.airplane.dev
• Headers: Include the x-module and x-module-uid headers in the webhook request. Example:

http

CollapseWrap

Copy

POST https://zuper.workflow.endpoint/wf1

Content-Type: application/json

x-module: job

x-module-uid: abc123

{

  "payload": "your_data_here"

}

​

2. Verifying the Module and UID

• Ensure the x-module value corresponds to a valid module in the Zuper platform (e.g., job, task, etc.).
• Confirm that the x-module-uid (e.g., abc123) exists in the specified module. If the UID is invalid, the system may fail to log the association or return an error.
• If you’re querying module IDs (e.g., for jobs or projects), you might need to use an API (like Linear’s GraphQL API) to retrieve valid UIDs, as shown in the Linear documentation for team or project IDs.docs.trunk.io

​

3. Testing the Webhook

• Test the webhook call using tools like curl or Postman to ensure the headers are correctly processed and the workflow execution is logged.
• Example curl command:

bash

CollapseWrapRun

Copy

curl -X POST https://zuper.workflow.endpoint/wf1 \

-H "Content-Type: application/json" \

-H "x-module: job" \

-H "x-module-uid: abc123" \

-d '{"payload": "test data"}'

• Check the job details page for abc123 in Zuper to confirm the execution appears under “Associations.”

• Invalid Headers: If x-module or x-module-uid is missing or invalid, the system might not associate the execution correctly. Ensure proper error handling in your integration.
• Webhook Verification: Some platforms require webhook verification (e.g., Linear uses a SHA256 HMAC signature in the Linear-Signature header).

​

5. Customization

• If you need to customize the behavior (e.g., how the execution is logged or displayed), check if Zuper supports transformation scripts, like Linear’s webhook transformation feature.
• For example, you could filter executions based on conditions (e.g., only log if the job meets certain criteria) or add additional metadata to the association.

​

Potential Questions and Answers

• What modules are supported for x-module? The specific modules (e.g., job, task, etc.) depend on Zuper’s platform. You’d need to consult Zuper’s documentation or API to confirm supported modules.
• What happens if x-module-uid doesn’t exist? The system might silently fail to log the association or return an error. Test with valid and invalid UIDs to understand the behavior.
• Can multiple executions be associated with one record? Likely yes, as the “associations” section suggests a list. Verify by triggering multiple webhook calls for the same x-module-uid.
• Setup: Copy the unique webhook URL from the node settings, paste it into the external app’s webhook settings, and specify data to send (e.g., via POST requests). Test by sending data from the external app and verifying in the Execution History.
• Zuper Event Triggers: Initiate a workflow based on platform events (e.g., “Job Created,” “Invoice Updated,” etc.). Select the event and define conditions in the node settings.
• Scheduled Trigger: Initiates a workflow on a recurring schedule. Set the schedule in the node for automated, periodic tasks.
  • Schedule Types:
    • Fixed Interval: Runs at regular intervals (e.g., every 15 minutes, hourly, or daily at a specific time like 9 AM IST). Suitable for predictable, recurring tasks.
    • Repeats Every (Cron-Based): Uses cron expressions for precise scheduling (e.g., 0 9 * * _for daily at 9 AM IST or _ /15 * * * * for every 15 minutes). Ideal for complex or custom schedules.
    • A recurring schedule can be daily, weekly, monthly, or yearly. You can specify the schedule by choosing specific days of the week or months and specify the schedule.

• Webhook Trigger: Ideal for external integrations (e.g., syncing with a CRM via API calls).
• Zuper Event Trigger: Best for reacting to internal platform updates (e.g., automating notifications when a job is completed).
• Scheduled Trigger: Perfect for routine tasks (e.g., generating daily reports). Choose fixed intervals for simplicity or cron-based for precision.

• Triggered Time: 10:00:00 AM IST (when the job is created).
• Created Time: 10:00:02 AM IST (when the workflow is queued).
• If the workflow fails (e.g., notification not sent), you can:
  • Flag the execution in the Execution History tab for review.
  • Use filters (e.g., “Failure” status, “Job Created” trigger) to analyze similar issues.
  • Check the gap between Triggered Time and Created Time to identify potential system delays.

​

Execution and Monitoring

• Access: Navigate to the desired workflow and select “Execution History” from the sidebar.
• Details: Logs display timestamps, execution status, and error messages. Use filters (date or status) for efficient analysis.

​

Sidebar Workflow Execution History

• Location: Found in the sidebar under “Execution History.”
• Functionality: Offers a summary of recent workflow runs with links to detailed logs for in-depth review.

​

Version Control and Roll Back

• Version Control: Every save generates a new version. Access “Revision History” to view all versions with their timestamps.
• Roll Back: Choose a previous version and click “Revert” to restore it, ensuring stability after modifications.

​

IV. Variables

​

Using Variables in Workflow Builder

​

Defining Variables

1. Navigate to the Variables tab in the Workflow Builder interface.
2. Click Create a Variable.
3. Provide a name for the variable (e.g., client_id).
4. Assign a value to the variable or link it to a data source (e.g., an API response, database field, or user input).
5. Optionally, enable the Mark as Secret option for sensitive data (see below for details).

• Encrypts the variable’s value in storage and during transit.
• Masks the value in the Workflow Builder interface to prevent accidental exposure.
• Restricts access to authorized users or processes, reducing the risk of data leaks.
• Enhances security by ensuring sensitive data is not logged or displayed in plaintext during workflow execution or debugging.

​

Using Variables in Workflows

• Node configurations: Insert variables into fields like text inputs, API calls, or conditions to dynamically populate values.
• Code nodes: Reference variables in JavaScript code to process or manipulate data.

• In node configurations, select the variable from a dropdown menu or reference it using the format {{VARIABLE.<variable_name>}} in supported fields.
• In code nodes, use the VARIABLE object followed by the variable name to access its value.

1. In the node’s configuration panel, locate the field where the variable is needed (e.g., a URL or payload field).
2. Use the variable picker or type {{VARIABLE.client_id}} to insert the variable’s value dynamically.

javascript

CollapseWrapRun

Copy

let variable_value = VARIABLE.zuperkey; // Access the variable

let result = variable_value.toUpperCase(); // Process the variable

return result; // Return the result for the next node or output

​

Tips for Success

• Test thoroughly: Always test your workflows to ensure variables and expressions are correctly referenced and the return statement provides the expected output.
• Use descriptive variable names: Clear names (e.g., client_id, user_email) improve workflow readability and maintenance.
• Leverage “Mark as Secret” for sensitive data: Always enable this option for variables containing sensitive information to enhance security and compliance.
• Validate data sources: Ensure variables linked to data sources (e.g., APIs, databases) are correctly configured to avoid runtime errors.

​

V. Insights

• Navigate to the “Execution Insights” section from the main dashboard.
• Check the overview for total executions, success/failure rates, and key trends. Use the “Last Days” filter to adjust the time range for data analysis.
• Save or export insights for future reference.

​

Workflow activity in the Job details page

• **Select any of the jobs from the Jobs module and locate “Workflow Activity” under **the right-hand panel of the Jobs details page.
• Purpose: Displays a chronological list of workflow-related events, such as notifications, status updates, and auto-assignments.
• Details Included:
  • Event Type: Identifies the action (e.g., “Notification,” “Job status update,” “Auto assignment”).
  • Timestamp: Shows the exact date and time (e.g., “2025/07/28 07:42 PM”) when the activity occurred.
  • Status: Indicates the outcome (e.g., a green checkmark for completed actions, a red circle with an ”!” for pending or failed actions).
• Example Activities:
  • “Customer Internal Notification” at a specific time.
  • “Job to project” status updates with success indicators.
  • “Workflow-23-June-2025-04-48-16” execution details.
• Functionality: Allows users to monitor automation efficiency, troubleshoot issues, and ensure all workflow steps are executed as intended.