Calling SOAP web services from Flowable processes
A process often has to call a SOAP service that other systems still depend on, such as a core system of record, a payment or claims service, or a partner interface that cannot be changed. In a Flowable BPMN model, the supported approach is the Web Service task. The Flowable BPMN docs describe it with an IO specification and data input and output associations, which map process variables into the arguments of a web service operation and map the response back into variables for later steps. That mapping is the part your team will spend the most time on, because a WSDL can expose many operations, nested complex types and optional elements, and each one must be fed from data the process actually holds. Keep the design to this documented method, and confirm the exact WSDL import behavior, generated artifacts and required libraries against the Flowable docs for the version you plan to run, since these details change between major releases.
Before building, decide which SOAP operations the process needs and who owns the contract. Ask the service owner for the WSDL version that is live in production, the WS-Security or transport requirements, the expected fault structure, and the timeout and retry behavior the provider supports. Then write down the input and output variables for each call, including types and whether a null value is valid. Test the mapping against recorded request and response messages from a non-production endpoint before the process model depends on it. For legacy services, also plan for faults: a SOAP fault is a valid response that the model must route, not a generic failure. Confirm how the engine surfaces faults and whether a boundary error event or an error handler in your Java code will catch them.
A Web Service task is not always the right tool. If the target offers a plain REST interface, the Http task described in its own topic is usually lighter to configure and test. If the call needs custom logic such as building messages from several data sources, handling retries with business rules, or reusing an existing client library, a Java delegate may be simpler and easier to unit test. Those choices also affect who maintains the integration, so involve the team that will carry the SOAP client dependencies after go-live. Whichever you choose, add a test that replays the call against a stub or a sandbox endpoint in your continuous integration pipeline, so that a provider WSDL change is detected before a production process instance fails at that step.
What the Flowable web service task needs before you model a call
A SOAP call from a BPMN model depends on decisions made outside the diagram: which engine version you run, which Java and Spring stack it sits on, and what the service expects on the wire. Settle these items with the service owner and your platform team first, because they decide the build, the test plan and the upgrade work.
Engine version and Java baseline
Confirm which Flowable engine version you run and the Java, Spring and Jakarta baseline it requires before you add a web service task. Flowable 7.0.0 moved to Java 17, Spring Boot 3 and Jakarta EE, so a platform still on older Java or Java EE APIs needs its own upgrade plan. Check the Flowable release notes for your version rather than assuming the task behaves the same across releases.
Spring Boot 3 upgrade plan
Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3. If your services run on Spring Boot 3, plan the upgrade of the application and its starters before you move the engine. Also check the Jackson default, since 8.0.0 uses Jackson 3 with a Jackson 2 compatibility layer, which affects how SOAP-related payloads and custom code serialize.
WSDL and operations inventory
Obtain the WSDL the provider publishes and list the operations your process needs, along with their input and output messages. The Flowable web service task imports WSDL definitions, so the imported types decide which process variables you map. Ask the provider whether the WSDL is stable, versioned and reachable from a test environment, and whether any operations are deprecated.
Endpoint and network path
Record the endpoint URL for each environment and the network route from the engine's host to it, including proxies, firewalls, DNS entries and egress rules in your cloud or data center. Confirm which nodes of a clustered engine must reach the service, since the async executor may run the call on any node. Ask the provider for the timeout and connection limits they enforce.
Authentication and certificates
Find out how the service authenticates callers, whether through WS-Security headers, basic credentials, mutual TLS client certificates or a token. Confirm which certificate authority signs the server certificate, how client certificates are issued and renewed, and where the engine host stores trust stores and keys. Plan credential storage and rotation before the model is built, so secrets stay out of the BPMN file.
Test access and ownership
Agree who owns the service contract, who can grant test access and what sandbox data the provider allows. Legacy SOAP services often have few test environments, so confirm whether a stub or recorded responses can stand in during development. Name a contact for incidents and schema changes, because a changed WSDL can break a deployed process model.
When the web service task beats an HTTP task or a Java delegate
When the legacy service publishes a WSDL with typed request and response messages, the Flowable web service task is the closest fit. The task works from imported service definitions, so the operation, its message types and its inputs are visible in the model and can be mapped to process variables through data input and output associations. The modeler sees what the service expects, and a change in the contract surfaces during model review rather than at runtime.
- Contract in the model: the imported WSDL defines the operation and types, which keeps the call readable for analysts and reviewers.
- Explicit data mapping: input and output associations move values between process variables and the operation, so the mapping is documented in one place.
- Build effort: the team imports and validates the WSDL first, then builds mappings for each operation, which is front-loaded work.
- Maintenance: when the provider publishes a new WSDL version, the model, imports and mappings must be re-imported and retested together.
Before committing, confirm the WSDL version, the binding style and the operations you need against the Flowable BPMN constructs documentation for your engine version.
When the service exposes a plain HTTP endpoint with a simple payload, the Flowable Http task is usually the lighter option. It needs no imported contract, and the request and response are configured directly in the model. For teams that only call REST endpoints or simple XML over HTTP, this keeps the model smaller and easier for application developers to change without SOAP tooling.
- Lower setup cost: there is no WSDL import step, so the first working call takes less effort.
- Direct configuration: URL, method, headers and body are set on the task, which suits a small number of calls.
- Shared skills: most Java and integration engineers already know HTTP client settings, timeouts and error handling.
- Limits: the model does not check the message against a contract, so schema validation moves into your tests or into the provider's gateway.
For the REST path, including client configuration, timeouts and request mapping, read the Flowable HTTP task topic in this group.
Some SOAP integrations need handling that the task configuration does not express cleanly: custom WS-Security header construction, unusual transport settings, or message assembly that depends on several process variables and business rules. In these cases a Java delegate often gives the team more control, because the code can build the envelope, select keys and handle faults explicitly. The trade-off is that the logic moves out of the model and into code the modeler cannot read.
- Full control: the delegate builds and parses messages, applies security headers and handles faults in ordinary Java.
- Higher build effort: the team writes, tests and packages the delegate and its dependencies, and manages the client library and its versions.
- Hidden behavior: the call is less visible in the BPMN model, so the model documentation must point to the delegate.
- Security review: keys, certificates and credential handling live in code, which the security team will need to review.
Ask the security and integration teams which WS-Security profile and transport rules the provider requires before choosing this path, and confirm them against the provider's own documentation.
The mechanism should be chosen per operation, not per project, and recorded so later changes do not drift. A single process can call a WSDL-defined operation through the web service task, a REST endpoint through the Http task and a complex security flow through a delegate. The team that maintains the model needs to know which mechanism each call uses and why, because the verification steps differ for each.
- Per-operation decision: record the mechanism, owner and reason next to each service call in the model documentation.
- Consistent naming: use a shared convention so reviewers can find SOAP calls quickly.
- Testing differs: the web service task needs contract-aware tests, the Http task needs endpoint and mapping tests, and the delegate needs unit tests with a stubbed provider.
- Ownership: agree who updates the model when the provider changes its contract or endpoint.
Before a go-live, confirm with the provider's team which mechanism they support for test environments and who receives notice of contract changes.
Configuring the web service task step by step
This sequence takes a team from a legacy WSDL to a BPMN web service task that maps process variables into a SOAP operation and handles faults, verified first against a stub service in a test environment. Each step ends with a check you can run before any production endpoint is involved.
Confirm the WSDL and the target operation
Obtain the WSDL from the service owner and confirm which binding, operation and message types the process will call. Record the operation name, its input and output message structure, and the documented fault messages, since these become the names your model must reference. Ask the service owner whether a test or stub endpoint exists for the same WSDL. Done when you have a written operation contract that the process team and the service owner both accept.
Import the WSDL into the model
Import or reference the WSDL definition so the Web Service task can resolve the operation from the modeling tool or the deployed project. Check the import against the Flowable BPMN constructs documentation for how the web service task references its service definition and operation, and confirm each element and attribute name there rather than copying names from older examples. Done when the model validates and the task shows the operation you recorded in step one.
Define the IO specification and associations
Add an IO specification to the web service task and map each process variable to a data input and each response element to a data output association. Keep variable names stable and typed, and separate request-only values from values the process must keep afterward. Check the mapping against the operation contract: every required request element should have a source, and every output you need should have a target variable. Done when a dry review of the mapping shows no unmapped required inputs.
Set the endpoint and timeouts
Configure the endpoint address per environment, not hard-coded in the model, so the same definition can point at a stub in test and the production service later. Set connection and response timeouts in agreement with the service owner, and record where the values live so operations can change them. Confirm that the engine's async and retry behavior works with your timeouts by reading the Flowable advanced documentation on the async executor. Done when the endpoint for the test environment is externalized and documented.
Handle the fault path
Model the failure route explicitly: attach a boundary error event to the web service task for the SOAP faults the contract documents, and route it to a compensating or manual-review path. Decide which faults are retryable and which should stop the instance, and make sure the process records enough variable context to diagnose the failure later. Verify the error event names against the BPMN constructs documentation. Done when each documented fault has a defined route in the model.
Deploy to a test environment with a stub service
Deploy the process definition to a test engine and point the endpoint at a stub service that returns the documented success and fault responses. Start one instance with representative variables, then start instances that trigger each fault. Check that the output variables carry the expected values and that each fault takes its intended route. Done when a successful run and each fault run complete as designed, and the results are kept with the model version.
Test the legacy call against the real endpoint
Once the stub runs are clean, point a controlled test instance at the actual SOAP endpoint in a non-production environment and confirm with the service owner which test data is safe to send. Compare the response structure with the stub you built, since real services often return optional elements or namespaces the stub omitted. Update the stub and the mapping where they differ, then rerun the stub suite. Done when a live test call completes and the stub matches the observed response.
Mapping WSDL operation inputs and outputs to process variables
This table maps each WSDL element in a SOAP operation to a process variable, showing direction, whether the element is required, and who confirms the value. Use it as a worksheet with the service owner before building the Web Service task, because type conversions and optional elements decide how the model behaves at runtime.
| WSDL element | Data type and direction | Process variable name | Required or optional and owner |
|---|---|---|---|
| Operation request elements | Complex type from the imported WSDL, input | Input variables set before the task, such as customerId | Required elements: owner of the service confirms each one |
| Optional request elements | Simple types such as string or date, input | Variables that may be null, such as middleName | Optional: service owner states the default sent when absent |
| Date and number conversions | xs:date, xs:dateTime, decimal, input and output | Typed variables with format agreed in the model | Service owner and process owner agree the format before build |
| Response elements | Complex type or simple type, output | Output variables mapped from the response, such as accountStatus | Service owner confirms which elements are always populated |
| Repeating response elements | Sequence or list of complex types, output | Collection variable, such as transactions | Service owner confirms maximum count and empty-list behavior |
| SOAP faults | Fault detail element, output | Fault variable or error event code, such as faultCode | Service owner lists all fault codes and the boundary error mapping |
| Header elements | SOAP header values, input or output | Separate variable, such as correlationId | Integration owner confirms whether headers are required |
| Namespace and WSDL version | Namespace and operation name from the imported definition | Recorded in the model notes, not a variable | Integration owner confirms the WSDL version in use |
Securing SOAP calls made from the process engine
A SOAP call from a Flowable process carries the same risks as any outbound integration, plus WSDL-driven contracts and message-level security that many legacy services still require. The cards below cover the controls to design before the first service task is deployed, and each one should be confirmed against the service's own security specification and the Flowable configuration docs.
Endpoint transport encryption and trust
Confirm that the WSDL address and the operation endpoint use TLS, and that the engine's trust store contains only the certificate authorities or pinned certificates the service owner has approved. Check whether the service presents a certificate chain that the JVM can validate, and whether the endpoint address in the imported WSDL differs from the one your environment must use. Ask the service owner for certificate rotation dates and who is notified when they change.
Service credentials outside process variables
Keep service usernames, passwords and keystore passwords out of process variables, BPMN XML and deployment packages. Process variables are stored in the database, appear in history and can surface in monitoring tools, so a credential placed there is exposed to everyone who can read history. Inject secrets at runtime from your secrets manager or from externally managed configuration, and confirm with the platform team how rotation reaches running engines.
Least-privilege service accounts
Create a dedicated account for each SOAP service, granted only the operations the process calls. A shared account used by several models makes it hard to trace which process made a call and widens the blast radius of a leaked password. Ask the service owner to confirm which operations the account can invoke, whether it can be restricted by source address, and how the account is disabled when a process is retired.
Log and history minimization
Request and response payloads from SOAP calls often contain personal data, account numbers or session tokens. Decide which values the data input and output associations copy into process variables, and avoid mapping sensitive fields that the process never needs. Review engine logging levels so that request bodies, SOAP envelopes and failed-call details are not written to application logs, and confirm the retention period that applies to history tables with your compliance owner.
WS-Security and message-level settings
Some legacy services require WS-Security headers, such as username tokens, timestamps, signatures or encryption of the message body. Identify these requirements from the service's security specification before modeling the task, because they change the request construction and the clock tolerance between systems. Test them against the service's test environment and confirm which settings the Flowable web service task supports directly and which need custom code.
Timeouts and failure exposure
A slow or unreachable SOAP endpoint can hold a job open and retry with the same request, which can duplicate a business action such as a payment or a booking. Define timeouts on the call, decide which faults are safe to retry, and agree with the service owner whether the operation is idempotent. Failed-job messages should be reviewed so that they do not reveal internal endpoint details to users of the workflow interface.
Testing legacy SOAP calls before go-live
Test the SOAP call against a stub endpoint generated from the WSDL before the legacy service is ever reached from a test environment. A stub that answers with recorded responses lets the team exercise the Web Service task, its IO specification and its data input and output associations without depending on a system the team does not control. Replay representative request and response messages captured from the legacy system, including unusual but valid records such as empty optional elements, long text fields and the character encodings the legacy side actually sends. For each replay, check that the output associations write the expected values into the process variables named in the model, and that the variables keep their types when later gateways and expressions read them. Confirm with the legacy team which WSDL version and binding are live in production, because a stub built from an older contract will pass tests that fail at go-live.
Test the happy path, the fault path and the timeout path as three separate cases, because the engine handles each differently. For the fault path, configure the stub to return a SOAP fault and verify that the boundary event or retry configuration in the model fires as designed, and that the process variables set on failure hold the fault details your operations team needs. For timeouts, delay the stub response beyond the client timeout you configured and confirm that the call fails cleanly rather than leaving the instance waiting indefinitely. Check that retries do not repeat a non-idempotent operation such as a payment or booking, and confirm with the legacy owner whether the operation is safe to repeat before you enable automatic retries.
Include an outage scenario in the test plan: stop the stub while process instances are waiting at the service task and confirm what happens when the service returns. Start several instances, take the endpoint down, let jobs fail, then restore the endpoint and check that the async executor retries the failed jobs and that each instance completes once. Record how long failed jobs stay visible to operators and who is alerted. Ask the legacy team for their maintenance windows and expected outage behavior, and agree on the process owner's response when an outage lasts longer than the retry schedule. Run this test with production-like data volumes, since large payloads and many concurrent instances often expose problems that single-instance tests miss.
Troubleshooting SOAP calls in Flowable processes
This table pairs each common SOAP failure in a Flowable process with its likely cause and the setup or mapping step to check first. Read it from the symptom down, starting with the step that changed most recently, such as the WSDL import or the data associations. Most failures trace back to a mismatch between the imported contract and the variables the model passes in and out.
| Symptom | Likely cause | Fix and first check |
|---|---|---|
| Definition fails to deploy after a WSDL change | Regenerated or changed WSDL types no longer match the imported service definition or the model's operation references | Re-import the WSDL, confirm the operation and message names in the BPMN service task, then redeploy in a test environment before promoting |
| Output variables stay empty | Data output association points to a variable name that differs from the one downstream expressions read, or the response element path does not match the WSDL | Compare the association target with the expressions that read it, then check the response structure against the operation's output message |
| Service rejects the request envelope or namespace | Input mapping builds elements in the wrong namespace or omits required wrapper elements defined in the WSDL | Check the target namespace and element qualification in the WSDL, then inspect the generated request XML in a test call against the provider's test endpoint |
| Timeouts occur under load | Default client timeouts are too short for the provider, or the calling thread waits on a slow backend with no retry or async boundary | Confirm the provider's expected response times with its owner, set explicit connection and read timeouts, and consider an asynchronous step for slow operations |
| TLS or certificate errors appear | Provider certificate chain is missing from the Java truststore, hostname checks fail, or the client certificate is not configured | Import the full chain into the truststore used by the Flowable runtime, verify the hostname in the WSDL endpoint, and test the handshake from the same host |
| Faults are swallowed by the process | The task completes normally on a SOAP fault because no boundary error event or fault check routes the failure | Map the fault to a boundary error event or an explicit check after the task, and confirm the error reaches the operations log for support |
What a Flowable SOAP integration costs and asks of your team
What drives the cost of a Flowable SOAP integration?
The main driver is how much of the service contract your process actually needs to touch. Cost rises with the number of operations, the complexity of the request and response types in the WSDL, how many fault cases the process must handle, and how many environments the calls must work in. Security requirements such as WS-Security headers, mutual TLS or certificate handling add design and testing effort. Each of these is a component of the written scope, so ask any provider to price them separately. Recurring costs are usually limited to keeping the integration working when the upstream service changes, which is a separate support or maintenance decision.
How long does it take to model and test one SOAP operation?
Duration depends on the operation's shape more than on the BPMN itself. A simple request with a flat response and one happy path is mostly mapping and a test run. Effort grows when the response is nested, when faults must route to different process paths, or when the service only exists in a test environment that is not yet stable. No researched figure is supplied here, so ask for a duration per operation in the quote, and ask what is assumed about the test endpoint's availability. Your team should also confirm whether the timeline includes a round of testing against the real service owner's environment.
What must our internal team provide before the work starts?
Gather the inputs that define the contract and the access needed to test it. The usual list includes:
- The WSDL files and any imported schemas, with the version the production service runs
- A test or staging endpoint that behaves like production, including its authentication settings
- Client certificates, keystores, truststores and the rules for storing them
- Named contacts for the service owner and the team that operates the endpoint
- Sample request and response messages for each operation in scope
- Known fault codes and how the service reports business errors
Missing items usually show up as delays in the middle of the build, so list them in the statement of work.
Can our own team build a Flowable SOAP integration without outside help?
Yes, if your engineers already work with Flowable and with SOAP tooling, and have time to own the work. The Flowable web service task uses imported WSDL definitions and data input and output associations, so the BPMN side is manageable for a team that knows the engine. The harder parts are usually the security configuration, the fault handling and the test strategy for a legacy endpoint. Decide early who will maintain the integration after go-live. If that owner is not identified, a partner can plan the handover, but the decision on internal capacity remains yours.
How does the work change as the number of operations and fault cases grows?
Effort grows roughly with the number of distinct operations, and faster with the number of distinct fault paths. Each additional operation adds its own mapping, test data and error handling. Each fault case adds a branch in the process model that someone must design, test and explain to operations staff. Reuse helps: shared variable naming, a common error pattern and reusable test fixtures reduce the work for later operations. Ask any provider how they will group operations and whether they will keep a fault catalogue that your support team can read.
When is a SOAP call better handled by an HTTP task or a Java delegate?
Choose the web service task when the upstream service is a SOAP contract that must stay as defined in its WSDL. If the service exposes a REST interface, the Http task is usually simpler to build and test. A Java delegate suits logic that needs custom code, such as unusual security handling or transformations that are awkward in BPMN. Whichever you choose, decide it before modeling starts, because changing the approach later means reworking the process models and test suites. The page on the HTTP task covers the REST alternative in more detail.
What recurring work comes after go-live for a SOAP integration?
Plan for three recurring activities: monitoring failed calls, updating the integration when the service publishes a new WSDL version, and renewing certificates or credentials. Each has an owner and a cost in people's time. Ask whether the quote includes post-go-live support, what response you can expect for a broken integration, and how long the test endpoint will stay available. Retainer support is available as a separate arrangement, and its scope should be written down with the same care as the build.
How DeployOpen scopes and delivers Flowable SOAP integrations
DeployOpen plans, builds, tests and documents Flowable process integrations that call SOAP services, inside your own infrastructure. Each engagement starts from a written scope that settles which WSDL definitions, operations and variable mappings are in play before any model is changed.
How we scope
- Inventory the WSDL files, operations, bindings and endpoints that the process models will call, and who owns each service
- Agree in writing which data input and output associations map to which process variables, including fault handling expectations
- Decide with you whether a web service task, an HTTP task or a Java delegate fits each call, and record the reasons
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
How we build
- Import the WSDL definitions into the Flowable project and model each web service task with its IO specification and mappings
- Build the surrounding delegates, configuration and test harness that your Flowable version and runtime require
- Test each call against a stub or test endpoint for the legacy service, covering normal responses, faults and timeouts
- Confirm the behavior against the Flowable version you run, since the supported stack and APIs differ between major releases
How we hand over
- Deliver the process models, configuration, test suite and a runbook describing endpoints, credentials and failure handling
- Document each service contract, its mapping and the owner to contact when a SOAP endpoint or WSDL changes
- Walk your engineers through the build and run a knowledge transfer session on testing legacy service calls
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover
- Retainers can cover re-testing of SOAP calls when a Flowable release or a legacy service version changes
- Confirm with us during scoping which operational checks, monitoring and escalation paths you need after go-live
