Overview
Bizagi offers a Web service connector (which is part of its Integration layer) promoting easy configuration to invoke external Web services.
This connector supports both invoking standard SOAP Web services and REST services.
In this article we will focus on describing integration with external SOAP Web services.
For integration with external REST services, refer to Invoking REST services.
The following image illustrates this concept:
The information exchange between Bizagi and the external system is done through standard XMLs.
In this way, the integration is independent from the platforms or technologies involved, and the programming language used in the services implementation.
|
Bizagi has integration with IBM WebSphere Enterprise Service Bus based on the consumption of web service via SOAP, the exposed services with IBM WebSphere Enterprise Service Bus must have HTTP endpoints, the services with JMS endpoints are not supported |
What you need to do in Bizagi
To set the configuration for a SOAP web service, the following steps are followed:
1. Resolve Web Service URL
2. Define Input Parameters
3. Define Output Parameters
4. Configure Error Handling
At the first step, called Resolve Web Service URL, you may choose: if the service to invoke is a SOAP Web service or a RESTful service.
For steps 2 and 3 you may define if you will be using the graphical mapping features or the advanced options to include custom transformation files.
In this article we will illustrate how to use Bizagi's interfaces wizard with its graphical mapping options to invoke a SOAP Web service.
Example
In the following example, we will reference the Vacation Leave Request Process, in which an employee starts a vacation request and consult the number of days available for his vacations.
This sample Process is available for download from Bizagi's free Process templates at the Process Xchange.
For this configuration, go to the sixth step of the Process wizard and click the Define interfaces option.
Once your see the Define Integration interfaces view of the Process, click the automatic task where the external web service will be invoked.
Notice that when a Process is opened in this view (through the Integrate step), only the automatic (Service) Tasks are highlighted (enabled).
In the image below, the automatic Task chosen for our example is Verify Available Vacation Days, in which Bizagi will obtain from another system, the number of available vacation days for that employee.
When clicking on the automatic task, the interfaces wizard will be launched presenting the steps to configure the invocation (as described below).
Resolve Web Service URL
In this first step, select SOAP as the Service type for this invocation.
Then type the Web service's URL, and click the Go button.
In this example, the following URL is used: http://www.bizagi.com/ESB/ESBServices.asmx?wsdl
The system will search for and refresh a list of available Web methods for that Web service (from the read WSDL descriptor file). (3)
Select the port under you wish to configure to use the service (usually a SOAP1.2 based one, if that service supports this protocol):
These ports listed in the drop-down will match those specified by the service (4), as long as this service specifies them for SOAP use:
Then, select the Web method to be used and give an Interface Name to this configuration.
Click on Next.
Define Input Parameters
In the Data to Send step, the interfaces wizard will present the data model pertaining to the current Process (as a Bizagi Data table at the left), and the structured information expected by that given Web service method (as another table at the right).
The Runtime entities information is also available to be mapped, from the simple mapping (advanced mapping is not supported).
For each one of the input parameters needed to establish communication with the external system, the wizard will display the options to map the attribute of the data model using XPath.
This way, the required business information from the data model will be set in the web method's parameters.
For this example, we will map the Applicant's userName to the expected userName parameter of the web service.
Another option for mapping the Applicant in this case could be relying on the Runtime entities information, as shown below. In the example below we map the FullName.
Notice that Runtime entities are displayed at the same level as the Process entity to map input attributes.
Define Output Parameters
In the Response Data step, mapping the result returned by the web service is similarly procedure to setting the input.
With this setting, Bizagi will automatically update the received response back into the Process data model.
In this example, we are mapping the result returned i.e., number of available vacation days, to the NumberOfDaysAvailable attribute.
|
If one or more output values correspond to an identifier of a parametric entity, enable the Business key for the corresponding entity so Bizagi can load the full reference. To do this, refer to Business Keys. |
Configure Error Handling
Bizagi presents an option to configure business error handling.
This is especially useful in following two scenarios: when the response XML contains a Web service business error (for instance, messages such as "Customer's ID does not exist"), or when the modeled Process considers a different workflow transition if an error occurs.
In order to use the error handling, you specify which error message is thrown based on the possible scenarios of the invocation.
For the second scenario mentioned above, where another workflow transition is considered, it is required that the Service Task chosen has an attached Error Event.
In this example, no custom error handling is specified.
To view more information about Error handling options, refer to Interfaces Error handling.
Click on Finish.
At this point, the Verify Available Vacation Days Service Task in the Vacation Request Process has been configured to invoke an external SOAP Web service.
Note that when clicking the Finish button, the interface will be automatically created (or updated) in the Systems module view (Expert View) of your Bizagi project. This means that this interface configuration parameters and authentication options can be reviewed or edited in the Systems module (see the next Additional Considerations section).
Additional Considerations
1. Bizagi will accurately save the configuration for your invocation and mapping even if you change the Web service method afterwards.
This means that if your external Web service changes (i.e., its definition signature has different or new parameters), you will need to consider if reconfiguring the invocation in Bizagi Studio is necessary.
It would still be recommended to examine your Web service's invocation and go over its configuration to review the mapping of new or altered parameters.
Notice you may also choose to manage your Test or Production interfaces (if there are any changes forthcoming to the external systems, such as eventually moving the server hosting the external web service).
2. In case that configuring a Web service through the WS Connector is not possible (throughout the graphical mapping features), then you may choose to do either:
•Perform the Web service invocation from a business rule in which you make use of the methods provided by the XML helper class of Bizagi.
For more information, refer to Methods for interfaces.
•Develop a component for the Web service invocation. This component is built as a class library which is registered in Bizagi through the Component library feature.
For more information, refer to the Component Library.
3. As a best interoperability practice, SOAP Web services' URL should:
•Be set with the ?wsdl termination (i.e http://www.bizagi.com/ESB/ESBServices.asmx?wsdl).
•Should not contain extra blank spaces (after the actual URL).
•Should never be a local physical path to a wsdl, but always an HTTP or HTTPS URL instead.
That is, to make sure that it is properly addressed even when the Web service was not built under .NET technologies.
4. The service port configuration allows you to implicitly choose the most appropriate framework according to the standard supported by that given service (for instance and when choosing a SOAP 1.2 port, the WS connector in a .NET environment will use the svcutil.exe tool instead of wsdl.exe).
Bizagi will automatically suggest the service port to choose, especially when it identifies that one of possible frameworks is not fully compatible with a given standard/port.
5. 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 about this option, refer to the Mapping features and functions.
6. When mapping outputs to the Web service, you have the possibility to include a custom XML transformation file (XSLT). To do this, use the Advanced mapping options accessed when clicking on this icon:
For more information about the advanced options, refer to Advanced mapping.
7. As a good practice and if your web service requires extensive mapping, we recommend you export them for further use.
Last Updated 1/26/2023 4:52:21 PM