How to invoke a REST service from Bizagi
From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
<keywords content="keywords"> restful, rest, restful services, restful service, rest web service, rest web services, rest based, rest service, rest services, web services, google, yahoo, twitter, facebook, google maps, soa, json, amazon, ebay, google maps, rest api </keywords>
|
Applies for the ENTERPRISE .NET and XPRESS editions |
Contents |
How to invoke a REST service from Bizagi
Overview
Bizagi allows invocation of REST services available in the web, so that business information is sent from the process, and the response information is automatically updated back into the data model.
REST services are web-based services. The configuration for this type of invocations is done through the same interfaces wizard in Bizagi, in which we can configure any web service invocation.
The following diagram illustrates this concept:
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).
Take into account that Bizagi supports within its interfaces wizard both: invocation of REST services and invocation of SOAP web services. If you wish to view information related to invocation of traditional web services in Bizagi (SOAP), review Web services invocation from Bizagi.
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 one 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 4 possible methods (which are the 4 HTTP methods) to consume their exposed resources: Get, Post, Put, and Delete. Each method to serve each posible action for the resource in matter (to read, create, update or delete).
The table below clarifies on the method for these possibilities:
| Action | HTTP Method |
|
Create |
PUT |
|
Read |
GET |
|
Update |
POST |
|
Delete |
DELETE |
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.
Prerequisites
Take into account 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 previously consult the documentation of the published REST service to invoke, in order to acknowledge what are the parameters expected by the service (inputs), and how is the response sructured as sent by the service (output).
REST services APIs present both: this type of information, and their corresponding examples to consume their resources according to the 4 different HTTP methods: Get, Post, Put and Delete.
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 may use Bizagi's interfaces wizard to define: which information is sent from Bizagi, and how the received information is updated into the process.
In a brief summary, 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 information for the service.
4. Mapping the response information returned by the service.
5. Configuring optional error handling.
Example
In the following example, we will illustrate how to invoke a REST service from the Google Maps API directly from our Bizagi process.
As described previously in this article, as a prerequisite we need to first understand how is a Google Maps REST service invocation structured.
This information is looked up at the source web site: developers.google.com/maps/documentation/geocoding/.
For this specific example, we will use the Geocoding API and its service to send an address, and obtain its latitud and longitude coordenates.
We will also use an available REST service which returns the response information in a XML structure (notice that these services are often provided in both XML and JSON formats).
REST services invocation from Bizagi's interfaces wizard in its 9.1.9 version, support XML-formatted responses (not JSON-formatted responses).
Our REST service invocation will be illustrated in a "Create Vendor" process in Bizagi:
In this sample process, our data model is as shown:
Notice that this example uses a Google's REST service invocation. Therefore and to see it working, it is required that the BPM Server has internet access. Additional browser settings configuration may be required to allow the browser to show the map (include google maps as a secure site).
Creating an interface invocation
Our first step is to create an interface invocation in our "Consult geocode location" service task.
This is done by going to the Process Wizard step #6 ("Integrate") option and into "Define integration interfaces":
In this view, we click on the "Consult geocode location" service task to create the interface invocation.
Specifying the service's type, URL and method
Now we must specify that this configuration invokes a REST-type service, and specify as well its location URL, method and parameters.
In the appearing interface window, we select "REST" as the service type:
From the information presented at the Google Maps API webpage, we specify its location URL separated into: the Base URL and the Service URL.
|
Note: The Base URL and Service URL are also specified at the REST service's documentation. Notice that the Base URL is the prefix URL in which no invocation parameters are specified yet. The Service URL does usually contain query parameters, which values should vary per invocation. |
This example's Base URL is: http://maps.googleapis.com/maps/api/geocode/xml?.
This example's Service URL is: address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true
Notice that the Service URL above, already includes a static sample address ("1600+Amphitheatre+Parkway,+Mountain+View,+CA"). In our process, we will dynamically send this information from the "Street Address" attribute in the data model.
Therefore and in order to define that the address parameter is to be dynamically mapped, we define any variables as necessary, inside the service URL by using the "{", "}" characters.
Our final Service URL is: address={Value1}&sensor=true
Notice that this method we are invoking is a "GET" method (just to consult information), and that it also returns the information in a XML structure.
We name our interface and click on "Next".
Mapping all input information for the service
Next, we will map the information to be sent through the variables defined previously.
To do this, we locate our "Street Address" attribute in Bizagi's process data model (the table at the left), and click on it.
Once selected, we click on the "Value1" variable in the Query_Params table to the right. This way, we map and specify the information which is to be sent to this invocation:
|
Note: Notice we are done configuring the input information for the REST invocation in this example because we are using a "GET" HTTP method. |
We click on "Next".
Mapping the response information returned by the service
Now we will specify how to store the response information to attributes in our Bizagi process' data model.
For this, we will need to include the REST service's response structure in the Response Data.
Remember that this invocation expects an XML-formatted response, and that this response structure is consulted at the REST service API's webpage. Based on this, we go to developers.google.com/maps/documentation/geocoding/?hl=en#XML, and copy the presented sample XML text into an .xml file.
We right-click the table at the left and input its response structure. This may be done manually (by adding nodes), or in an automatic manner by loading the structure from a physical XSD or XML file.
In this example, we choose the "Load Sample XML" import option to load the XML structure from the saved .xml file (locating the .xml file previously saved):
Once we have the XML structure in our Google Maps Response data table, we proceed to map the latitude ("lat") and longitude ("lng") incoming values to our attributes in Bizagi.
To map these values, remember that you may either: click first on the source attribute and then on the target attribute, or also drag and drop a connection from the source to the target.
In the end, the mapped response information for our example will look like:
We click on "Next".
Configuring optional error handling
Finally and for this example, no error handling validation is needed:
We click on "Finish".
Result
Now we can run our "Create Vendor process", and test the invocation result in the work portal.
To do this, run the process from the "Run" button in the quick access options:
In our workportal, we create a new "Create Vendor" case and input the vendor's address in our "Register Vendor information" activity. For this REST service example, all words which make up the address are separated by the "+" character:
After Google Map's REST service invocation, we will obtain the latitude and longitude coordenates for the Vendor's address:
At this point we have invoked a REST service from Bizagi!
Advanced and related
You may extend this how-to based on a Google Maps APIs invocation, so that instead of showing the latitude and longitude coordenate values, you show the exact location in a Google Map directly embedded Bizagi.
This extended approach involves using userfields in your process forms. Learn how to embed a dynamic google map in Bizagi.
Related Articles
- Further information about REST mapping options.
- SOAP Web services invocation.
- how to embed a dynamic google map in Bizagi.
- View considerations for REST services invocations
<comments/>
