Skip to main content
Tested · August 2026
Built and run by the FlowX docs team on a live FlowX environment. The process ran end to end through the manual review path: the forms, the KYC verification workflow, and the routing to the review task. The timer escalation and rejection steps were built and validated in the Designer.
In this tutorial, you build a customer onboarding process — a BPMN-driven app that collects personal data through multi-step forms, verifies the customer’s identity via an external KYC API, generates a welcome letter, and routes failed verifications to a manual review queue. What you will build:
  • A multi-step form that collects personal details, address, employment, and document uploads
  • A KYC verification integration that calls an external REST API via an integration workflow
  • An exclusive gateway that routes the process based on verification results
  • A document generation step that produces a personalized welcome letter
  • A manual review task assigned to compliance officers when KYC fails
  • An email notification sent upon successful onboarding
  • A timer boundary event for SLA tracking on the review task
Node types used: User Task, Send Message Task, Receive Message Task, Exclusive Gateway, Timer Boundary Event Patterns demonstrated: Multi-step form collection, REST API integration via workflows, conditional branching, document generation, task assignment, notification sending

Architecture overview

The process follows a collect-verify-decide pattern. Customer data is gathered through a series of user task nodes, sent to a KYC service for verification, and then routed based on the result. The main process orchestrates four form steps, delegates KYC verification to an integration workflow, and uses an exclusive gateway to branch into success or manual review paths.

Prerequisites

Before starting, make sure you have:
  • Access to a FlowX Designer workspace
  • The Documents Plugin deployed and configured (for document generation)
  • The Notifications Plugin deployed and configured (for email sending)
  • A document template named welcomeLetter created in Document Templates (HTML template with placeholders for customer name and date)
  • Familiarity with creating processes, user tasks, and actions in FlowX
HTML template generation is turned off by default on the Documents Plugin. Turn it on for the document-plugin deployment before testing Step 6 — otherwise the welcome letter is never produced and the process stalls at receiveWelcomeLetter.Either variable sets it: HTML_TEMPLATES_ENABLED (referenced directly in the plugin configuration) or FLOWX_HTML_TEMPLATES_ENABLED (the property name flowx.html.templates.enabled in environment-variable form).Default: false
If you do not have a real KYC service available, you can simulate one using a mock REST API endpoint (for example, a simple service that returns PASSED or FAILED based on predefined rules). The integration workflow calls this endpoint the same way it would call a production KYC provider.

Data model

Define the following keys in your process data model. All keys use camelCase and are nested under logical groups.

Step 1: Create the process definition

1

Create a new process

In FlowX Designer, navigate to your project and create a new process definition named customerOnboarding.Set the platform to Web Only (or Omnichannel if you plan to support mobile).
2

Add swimlanes

Create two swimlanes:
  • Customer — for the user-facing form steps
  • BackOffice — for the manual review task (assigned to a compliance role)
This ensures the review task is routed to the right team while the customer interacts with the form steps.
For details on configuring swimlanes and role-based access, see the Swimlanes documentation.

Step 2: Build the data collection forms

Create four User Task nodes in the Customer swimlane, connected in sequence. Each node represents one step of the onboarding form.

User Task 1: Personal information

Node name: personalInfo Open the UI Designer and add a Card with a Form containing these fields: Add a Button labeled Next with an action of type Save Data to persist the form values.

User Task 2: Address details

Node name: addressInfo
Use an enumeration for the country dropdown. Create an enumeration named countries with ISO 3166 country codes and labels.
Add Back and Next buttons. Turn on Can go back? in this node’s settings so the customer can return to the previous step.

User Task 3: Employment and income

Node name: employmentInfo
Use a conditional expression on the Employer and Start Date fields to show them only when employment.status is EMPLOYED or SELF_EMPLOYED.

User Task 4: Document upload

Node name: documentUpload Add a Submit button that triggers the process to move to the KYC verification step.
Uploaded files are stored via the Documents Plugin. Make sure the plugin is configured with an S3-compatible storage backend before testing this step.

Step 3: Set up the KYC verification integration

The KYC check is handled by an integration workflow that calls an external REST API. This keeps the BPMN process clean and the integration logic reusable.

Create the data source

1

Add a RESTful System data source

Navigate to Integrations > Data Sources and create a new data source:
  • Type: RESTful System
  • Name: KYC Provider
  • Code: kycProvider
  • Base URL: https://api.{your-kyc-provider}.com/v1
  • Authorization: Bearer Token (configure the token value using a Configuration Parameter Override so it differs per environment)
2

Define the verification endpoint

Under the data source, add an endpoint:
  • Method: POST
  • Path: /verify
  • Body type: JSON
  • Request body example:
  • Response example:

Create the integration workflow

1

Create the workflow

Navigate to Integrations > Workflows and create a new workflow named kycVerification.Give the Start node an INPUT data slice declaring five STRING fields: firstName, lastName, dateOfBirth, nationalId, and country. These are the values the process passes in Step 4.
2

Add a REST API Call node

Add a REST API Call node connected to the Start node. Configure it to use the kycProvider data source and the /verify endpoint.Map the input variables to the request body:
3

Add a Script node to unwrap the response

A REST node does not put the HTTP body directly on its response key. It wraps it, so kycResponse looks like this:
Add a Script node after the REST API Call, routed on its SUCCESS output, to lift the provider’s fields to the top level:
4

Add an End Flow node

Add an End Flow node after the Script node and give it an OUTPUT data slice declaring status, score, reasons, and verificationId.The output slice is the workflow’s contract: it returns exactly the fields you declare, and drops everything else that accumulated during the run. That is what makes kycResult.status readable in Step 4.
Do not return the raw response with an End Flow payload of {"output": ${kycResponse}}. That hands the BPMN process the entire HTTP envelope — headers and cookies included — and pushes the values you want down to kycResult.output.data.status instead of kycResult.status.
Wrap placeholders in quotes in the REST request body: write "${firstName}", with the quotes. An unquoted ${firstName} is substituted as a bare token rather than a JSON string, producing an invalid body like {"firstName": Jane}. Many endpoints still answer 200 to that while silently parsing nothing, so every node reports success and the workflow returns empty values.
For a detailed guide on building integration workflows, see the Integration Designer documentation.

Step 4: Trigger KYC from the BPMN process

Back in the customerOnboarding process, add a Send Message Task and a Receive Message Task after the documentUpload user task.
The mappings below use the data mapping modals, the default. If you turn on Legacy Mapping, the Start Integration Workflow action takes a JSON input body and the Receive Message Task’s data stream takes a single Key Name instead. See Legacy mapping vs data mappers.

Send Message Task: Start KYC check

Node name: sendKycRequest Add an action:
  • Action type: Start Integration Workflow
  • Workflow: kycVerification
  • Trigger: Automatic
  • Mandatory: Yes
Map the workflow’s input parameters:
Select each source path from the autocomplete list that opens when you type ${. A path you type out in full and don’t select is saved as a static text value, so the workflow receives the literal ${customer.firstName} text instead of the name.

Receive Message Task: Receive KYC result

Node name: receiveKycResult Add a data stream with Source set to Workflow and select kycVerification. In the Output Mapping of its End Flow node, map status, score, reasons, and verificationId to the fields of the same name under kycResult. Click Confirm, then save the node. Subsequent nodes can read kycResult.status, kycResult.score, kycResult.reasons, and kycResult.verificationId.
With Legacy Mapping turned on, the action’s JSON input body is:
On the Receive Message Task, set the data stream’s Key Name to kycResult.
The process waits at the Receive Message Task until the integration workflow completes and returns its output. For details on this pattern, see Start Integration Workflow Action.

Step 5: Add the KYC decision gateway

Add an Exclusive Gateway node after the receiveKycResult node. Node name: kycDecision Configure two outgoing branches: Gateway conditions read process data through input, the same way business rules do.
Using the default branch for the failure path ensures that any unexpected status value (not just FAILED) is routed to human review rather than slipping through.
For details on configuring exclusive gateways, see the Exclusive Gateway Node documentation.

Step 6: Build the success path

The success path generates a welcome letter and sends a confirmation email.

Generate the welcome letter

Add a Send Message Task and Receive Message Task pair for document generation.

Send Message Task: Generate welcome letter

Node name: sendGenerateWelcomeLetter Add a Kafka Send Action with:
  • Topics: ai.flowx.plugin.document.trigger.generate.html.v1
  • Message:
The templateName must match a document template you created in Document Templates. In the template’s HTML, bind each value with a Thymeleaf attribute, for example <span th:text="${customerName}"></span> and <span th:text="${currentDate}"></span>. A {{customerName}} placeholder is not substituted and prints as literal text. For details, see Managing HTML templates and Generating documents from templates.
${...} placeholders in message payloads reference existing process data only — the engine does not evaluate functions or expressions inside them. Set onboarding.currentDate before sendGenerateWelcomeLetter: add a Service Task named setCurrentDate in front of it, with a Business Rule action that writes today’s date:

Receive Message Task: Receive letter result

Node name: receiveWelcomeLetter Add a data stream with Source set to Custom Topic, then set:
  • Topic Name: use the value from KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT, configured on the document-plugin deployment (default: ai.flowx.engine.receive.plugin.document.generate.html.results.v1)
  • Key Name: generatedDocs.welcomeLetter

Send the confirmation email

Add another Send Message Task and Receive Message Task pair for notification.

Send Message Task: Send email

Node name: sendEmailNotification Add a Kafka Send Action with:
  • Topics: ai.flowx.plugin.notification.trigger.send.notification.v1
  • Message:
Create the onboardingComplete notification template in the Notifications Plugin before testing. For configuration details, see the Notifications Plugin documentation.

Receive Message Task: Receive email confirmation

Node name: receiveEmailConfirmation Add a data stream with Source set to Custom Topic, then set:
  • Topic Name: use the value from KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT, configured on the notification-plugin deployment (default: ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1)
  • Key Name: notificationResult
After this node, add an End Event node to close the success path.

Step 7: Build the manual review path

When KYC fails or returns a REVIEW status, the process routes to a human reviewer.

User Task: Manual review

Node name: manualReview Place this node in the BackOffice swimlane. Open the UI Designer and create a review interface: Add two buttons:
  • Approve — sets reviewDecision to APPROVED and advances
  • Reject — sets reviewDecision to REJECTED and advances
Enable Update task management on this node so the task appears in the Task Manager inbox for compliance officers. Assign the node to a swimlane with the appropriate role (for example, COMPLIANCE_REVIEWER).

Timer boundary event: SLA escalation

Attach a Timer Boundary Event to the manualReview node to enforce a 48-hour SLA.
  • Timer type: Duration
  • Duration: PT48H (ISO 8601 format — 48 hours)
  • Interrupting: No (non-interrupting — the review can still complete after escalation)
Connect the timer to a Send Message Task that sends an escalation notification:
For details on timer configuration, see Timer Boundary Event and Timer Expressions.

Review decision gateway

Add a second Exclusive Gateway after the manualReview node. Node name: reviewDecisionGateway For the Approved branch, connect to the same document generation and email notification nodes used in the success path (or duplicate them if your process layout requires separate paths). For the Rejected branch, add an End Event node labeled endRejected.

Step 8: Add a business rule for risk scoring (optional)

You can enrich the KYC response with custom logic before the gateway evaluates it. A Receive Message Task does not take actions, so add a Service Task named normalizeKycResult between receiveKycResult and kycDecision, and give it a Business Rule action. Action type: Business Rule Language: JavaScript
Always put an object on the top-level key, as above. A dotted key like output.put("kycResult.status", ...) creates a flat key literally named kycResult.status instead of updating the nested value, so gateway conditions and ${kycResult.status} placeholders would silently keep reading the old value. Objects put this way are deep-merged into the existing key.
Business rules execute synchronously within the process engine. Use them for lightweight data transformations and decision logic. For details, see Business Rule Action.

Step 9: Configure stages for Task Manager

Define stages to track progress in the Task Manager: Enable Update task management on the first user task node (personalInfo) and the manual review node (manualReview) so that process instances appear in the Task Manager with their current stage.

Testing

1

Test the happy path (KYC passes)

Start a new process instance and fill in all four form steps with valid data. Use a national ID that your mock KYC service recognizes as valid.Verify:
  • The KYC integration workflow completes and returns status: PASSED
  • The welcome letter is generated (check the document storage)
  • The confirmation email is sent to the customer email address
  • The process ends at the success End Event
2

Test the manual review path (KYC fails)

Start a new instance with data that triggers a FAILED or REVIEW KYC status.Verify:
  • The process routes to the manualReview user task
  • The task appears in the Task Manager for the BackOffice swimlane
  • Approving the review generates the welcome letter and sends the email
  • Rejecting the review ends the process at the rejection End Event
3

Test SLA escalation

Start a manual review scenario and let the 48-hour timer expire (for testing, temporarily change the duration to PT1M — one minute).Verify:
  • The escalation email is sent to the configured manager address
  • The review task remains active (non-interrupting timer)
  • The reviewer can still approve or reject after escalation
4

Test form navigation

Verify that the Back button on each form step returns the user to the previous step without losing entered data.Verify that required field validations prevent advancing to the next step when fields are empty.

What you learned

In this tutorial, you built a complete customer onboarding process that demonstrates several core FlowX capabilities:
  • Multi-step forms — using sequential User Task nodes with form components to collect structured data across multiple screens
  • Integration workflows — delegating external API calls (KYC verification) to reusable integration workflows triggered via the Start Integration Workflow action
  • Conditional routing — using Exclusive Gateway nodes with JavaScript conditions to branch process logic based on data values
  • Document generation — using the Documents Plugin with Kafka Send/Receive Message Tasks to generate documents from HTML templates
  • Notifications — using the Notifications Plugin to send email confirmations
  • Task assignment — using swimlanes and the Task Management plugin to route manual review tasks to specific roles
  • SLA tracking — using Timer Boundary Events to enforce and escalate overdue tasks
  • Business rules — using JavaScript business rules to enrich and transform data within the process

Next steps

Process definitions

Deep-dive into process configuration options

Integration Designer

Build more integration workflows for external systems

Task Management

Configure task routing and assignment rules

Mortgage advisor chatbot

Build a conversational AI app as a companion to this BPMN tutorial
Last modified on November 18, 2026