Skip to main content

Tips for Success with Workflow Builder

Before you embed the workflow builder in your application, you'll want to prepare the building blocks that make it easy for your customers to create workflows - without needing technical expertise. This guide walks through the key steps to set up the embedded workflow builder for success.

Build custom components for your API​

Your customers need to interact with your product's data through the workflow builder. Custom components wrap your API into reusable, configurable actions that abstract away technical complexity and present business-friendly operations instead.

When building components:

  • Name actions by business function, not technical implementation. Use "Submit Leave Request" instead of /api/v1/leave-requests.
  • Consolidate multi-step operations into a single action. A "Process Return" step can update inventory, issue a refund, notify the warehouse, and email the customer-all behind the scenes.
  • Include event-based triggers that understand your system. Triggers like "Return Initiated" or "Order Cancelled" are more meaningful to your customers than raw webhook endpoints.
  • Handle validation internally. Components should enforce required fields, data types, and error cases so customers don't have to think about them.

For example, a webhook component might offer a "Return Initiated" trigger that handles subscribing to the right events in your system. When customers add it to a workflow, they select the event from a dropdown-the component handles the rest.

See building custom connectors to get started.

Pre-configure connections​

Connection setup is one of the biggest friction points for new users. Pre-configuring connections to your platform and common third-party systems significantly reduces the time it takes for customers to build their first workflow.

  • Authenticate to your platform once by creating an org-activated customer connection for your API that customers can reuse across all of their workflows. Enable Use for workflows on the connection so it's available without extra setup.
  • Pre-configure common third-party integrations your customers are likely to use, such as Slack, Microsoft Teams, Salesforce, HubSpot, Jira, Google Workspace, and Microsoft 365.
  • Clearly document any permissions or scopes required for each connection.

When customers open the workflow builder, connections are already available in the dropdown. They don't need to supply API keys, complete OAuth flows, or do any manual configuration.

Create workflow templates​

Starting from a blank canvas can be intimidating for non-technical users. Workflow templates provide pre-built starting points that customers can adapt to their specific needs.

When creating templates:

  • Focus on common use cases. Build templates for the workflows your customers need most often.
  • Keep templates complete but easy to follow. Include all the necessary steps while keeping the overall flow understandable at a glance.
  • Name templates by business outcome, not technical implementation. "Return Initiated Workflow" is clearer than "Webhook to API template."
  • Add descriptions so customers understand when to use each template.

Some useful template patterns to start with:

  • Order cancellation - Trigger on cancellation event → validate order fulfillment → process cancellation
  • Return initiated - Trigger on return event → process return → send notification and log status
  • Access request - Submit request → manager approval → security review → grant access

When a customer selects a template, they receive a copy they can customize. Connections are stripped from the template, so they'll configure their own-or use pre-configured connections that are already set to Use for workflows.

See workflow templates for instructions on creating and publishing templates.

Simplify complex logic inside components​

Non-technical users shouldn't need to think about conditional logic, error handling, or data transformation. Build that complexity into your components so customers interact with simple, linear steps.

  • Manage branching and loops internally. Customers shouldn't need to wire up conditionals for common cases-let the component handle them.
  • Use business language in step names. Steps should read like a business process, not code.
  • Pre-fill common configurations so customers can get started without having to configure everything from scratch.
  • Make advanced options available but not required. Power users can access deeper settings if they need them.

A workflow that reads "When a new request arrives → Send notification to manager → When request is approved → Update leave management system" is far easier for a non-technical user to understand and trust.

Embed the workflow builder in your application​

Keeping users in your application creates a seamless experience. When the workflow builder feels like a native feature, customers are more likely to adopt it and build workflows independently.

  • Integrate into your existing navigation. A "Workflows" section in your app's nav feels native.
  • Match your application's branding. Use Prismatic's theming options to align colors, fonts, and styles.
  • Support both templates and blank workflows. Offer starting points for all skill levels.
  • Let customers test within your app. Customers should be able to trigger test events and validate workflows without leaving your interface.

Inside your application, customers can browse the template library, select a starting point, customize stages, connect to their integrations, and deploy-all in one place.

See embedding the workflow builder and theming for implementation details.

White-label the documentation​

Give your customers the documentation they need to be successful with the workflow builder, branded for your product.

Prismatic provides a documentation template you can fork and customize. The embedded-workflow-builder-docs repository contains a complete, white-label docs site you can deploy under your own domain.