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 REST services (RESTful services as considered Web-based services).
For integration with external SOAP Web services, refer to Invoking SOAP Web services.
Version 11 introduces a powerful feature for B2B integration which considers REST services, known as Bizagi Connectors.
It is strongly recommended for you to use Bizagi Connectors, given that with Connectors you have further extensibility possibilities such as including headers or using OAuth.
For more information about this feature, refer to Bizagi connectors.
RESTful services integration
The following image illustrates how Bizagi easily integrates RESTful services through its Web services connector:
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.
Before moving on in this article, we will briefly list some REST services characteristics, and mention some differences between REST services and traditional web services (SOAP); mainly because both are important and frequently used in applications (one approach doesn't seek to replace the other).
REST services compared to SOAP web services
First of all, it is important to understand that REST services as a concept, was reinforced as the best alternative for consulting information from mobile devices.
According to this idea, through mobile devices it is frequent to want to get online information contained in Web sites in an agile way (such as geographic maps, general Web information, social networks updates, currency exchange rates, weather report, commercial products pricing, etc.). This is why REST services expose information as "resources" to be consumed via HTTP (or HTTPS).
Having said this, REST services design and use have a different approach to that presented by SOAP web services. SOAP web services are meant for a SOA design in internal corporate systems, with the possibility of stronger or additional security measures for their access.
When consuming SOAP or REST, invocation configuration differs as follows:
When invoking a SOAP web service, the system itself can interpret and make use of a previous definition of the Web service (its expected input and output structure). This is described through the WSDL published at the SOAP web service's design and construction.
When invoking a REST service, by default, there is no definition available for this service's input parameters and output structure, that a system can automatically interpret. This task is delegated to the user making the invocation.
About REST services
REST services present four possible methods (which are the four HTTP methods) to consume their exposed resources: Get, Post, Put, and Delete. Each method to serve each possible action for the resource matter (to read, create, update or delete).
The table below clarifies these possibilities:
Take into account that the steps slightly vary according to the chosen interface method in the Bizagi interfaces wizard (according to the chosen HTTP method for the REST service). While using POST or PUT methods (those methods in which information is to be persisted unto the resource), that extra information involved (to create or update), is sent by setting a configuration in an additional step.
These methods above would use Basic authentication.
Bear in mind that because of their nature, REST services are expected to be provided over the Internet, and by Web sites which publish world-wide information.
Therefore, it is required to first consult the documentation of the published REST service to be invoked, in order to ascertain what parameters are expected by the service (input), and how the response is structured as returned by the service (output).
REST services APIs present both the structure of information (input and output), and their corresponding examples to consume the resources according to the four different HTTP methods: Get, Post, Put and Delete.
You may also refer to other advanced configuration options regarding REST services, such as defining the content-type, at REST services configuration.
What you need to do in Bizagi
You may invoke an external system's REST service from any Activity in your Bizagi Process.
To configure this type of invocation, you use Bizagi's interfaces wizard to define: which information is sent from Bizagi, and how the received information is updated into the Process.
In brief, configuring a REST service invocation in Bizagi is done by:
1. Creating an interface invocation.
2. Specifying the service's type, URL and method.
3. Mapping all input parameters of the service (for POST and PUT Methods).
4. Mapping the response of the external service.
5. Configuring optional error handling.
In the following examples, we will illustrate how to invoke a REST services:
•For invocation of methods GET and DELETE, refer to Example for data collection methods.
•For invocation of methods POST and PUT, refer to Example for data placement methods.
Once you complete the previous examples, you will know how to invoke a REST service from Bizagi!
Bizagi will accurately save the configuration for your invocation and mapping even if there is a change in the external Web service method afterwards.
This means that if your external Web service changes (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 current mapping of new or altered parameters.
Notice you may also choose to manage your Test or Production interfaces (should any change be done to the external systems, such as eventually moving the server hosting the external web service).