Overview
Bizagi provides a Web services connector as part of its integration layer, enabling the easy configuration of external web service invocations.
This connector supports both standard SOAP web services and REST services.
This article focuses on integrating with external SOAP web services. For information about integrating with REST services, see Invoking REST services.
The following image illustrates this concept:
The exchange of information between Bizagi and the external system is performed through standard XML messages. This approach makes the integration independent of the platforms, technologies, and programming languages used to implement the service.
|
Bizagi supports integration with IBM WebSphere Enterprise Service Bus through SOAP web service consumption. The services exposed by IBM WebSphere Enterprise Service Bus must provide HTTP endpoints. Services exposed through JMS endpoints are not supported. |
What you need to do in Bizagi
To configure a SOAP web service invocation, complete the following steps:
1.Resolve Web Service URL
2.Define Input Parameters
3.Define Output Parameters
4.Configure Error Handling
In the first step, select whether the service to invoke is a SOAP web service or a RESTful service.
In steps 2 and 3, you can choose between graphical mapping and advanced mapping options, including custom transformation files.
This article demonstrates how to use the Interfaces Wizard with the graphical mapping option to invoke a SOAP web service.
Example
The following example uses the Vacation Leave Request process, in which an employee submits a vacation request and checks the number of vacation days available.
This sample process is available through Bizagi's free process templates in Process Xchange.
To begin the configuration, go to Step 6 of the Process Wizard, Integrate, and select Define integration interfaces.
In the Define integration interfaces view, select the Service Task where the external web service will be invoked.
Notice that when a process is opened from the Integrate step, only automatic tasks (Service Tasks) are enabled for configuration.
In the following example, the selected task is Verify Available Vacation Days. During this activity, Bizagi retrieves the employee's available vacation days from an external system.
When you select the Service Task, the Interfaces Wizard opens and displays the steps required to configure the invocation.
Resolve Web Service URL
In this step, select SOAP as the Service Type.
Enter the web service URL and click Go.
In this example, the following URL is used:
http://www.bizagi.com/ESB/ESBServices.asmx?wsdl
Bizagi reads the WSDL and retrieves the available web methods for the service. (3)
Next, select the service port you want to use, typically the SOAP 1.2 port if the service supports it.
The ports displayed in the list correspond to those defined by the web service (4).
Select the web method to invoke and provide a name for the interface configuration.
Click Next.
Define Input Parameters
In the Data to Send step, the wizard displays:
•The process data model on the left.
•The structure expected by the selected web method on the right.
Runtime entity information is also available for mapping when using simple mapping. Advanced mapping does not support Runtime entities.
For each input parameter required by the service, the wizard allows you to map information from the process data model using XPath expressions.
This mapping defines which business data Bizagi sends to the external service.
In this example, the Applicant's userName is mapped to the corresponding userName parameter expected by the web service.
Alternatively, you can use information from Runtime entities. In the following example, the fullName attribute is mapped.
Notice that Runtime entities are displayed at the same hierarchical level as the Process entity.
Define Output Parameters
In the Response Data step, configure the mapping for the data returned by the web service in a similar way.
With this configuration, Bizagi automatically stores the response in the process data model.
In this example, the value returned by the service, representing the number of available vacation days, is mapped to the NumberOfDaysAvailable attribute.
|
If one or more output values correspond to the identifier of a Parameter entity, configure the appropriate Business Key so Bizagi can load the complete entity reference. For more information, see Business Keys. |
Configure Error Handling
Bizagi provides options to configure business error handling.
This functionality is especially useful in the following scenarios:
•The service returns a business error in the response XML, such as "Customer ID does not exist".
•The process must follow a different workflow path when an error occurs.
To use error handling, define the error message that should be generated for each possible invocation scenario.
For workflow branching based on errors, the selected Service Task must include an attached Error Event.
In this example, no custom error handling is configured.
For more information, see Interfaces Error handling.
Click Finish.
At this point, the Verify Available Vacation Days Service Task has been configured to invoke an external SOAP web service.
When you click Finish, Bizagi automatically creates or updates the interface in the External Systems module (Expert view) of your project. This allows you to review and modify interface settings, including authentication options, directly from the module.
Considerations
1.Changes to the web service
Bizagi preserves your invocation and mapping configuration even if the selected web method changes later.
However, if the external web service definition changes and introduces modified or additional parameters, review the interface configuration and update the mappings as needed.
You can also manage different configurations for Test and Production environments if external service endpoints change over time.
2.Alternative integration options
If a web service cannot be configured through the Web services connector using graphical mapping, you can use one of the following alternatives:
•Invoke the web service through a business rule by using methods provided by Bizagi's XML Helper class. For more information, see Methods for interfaces.
•Develop a custom component as a class library and register it through the Component Library.
3.SOAP web service URL recommendations
For best interoperability, SOAP web service URLs should:
•End with ?wsdl (for example, http://www.bizagi.com/ESB/ESBServices.asmx?wsdl).
•Not contain trailing blank spaces.
•Always use an HTTP or HTTPS URL.
•Never reference a local physical WSDL file.
These recommendations help ensure compatibility, especially with services developed using technologies other than .NET.
The selected service port determines the framework used by the connector.
For example, when a SOAP 1.2 port is selected in a .NET environment, the Web services connector uses svcutil.exe instead of wsdl.exe.
Bizagi automatically recommends the most appropriate port whenever compatibility considerations exist.
5.Advanced graphical mapping features
When working with output mappings, you can maximize the mapping window to access additional mapping functions and transformation features.
You may use the special mapping features and functions available to manipulate output parameters through a graphical view by maximizing this window.
For more information, see Mapping features and functions.
When mapping web service outputs, you can include a custom XML transformation file (XSLT).
To do this, use the Advanced mapping option available through the corresponding icon:
7.Export mappings
As a best practice, if your web service requires extensive mapping configurations, export and save those mappings for future reuse.
Last Updated 8/27/2026 3:23:57 PM