Example for data collection methods

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Integrate > Application integration > Web services connector > Invoking REST services >

Example for data collection methods

The following example gives a brief description of how to use GET and DELETE methods through the invocation of a REST service from the Google Maps API directly in our Bizagi Process. The consumption of the service will be explained with XML and JSON data.

 

As described previously in Invoking REST services, as a prerequisite we need to first understand the structure of the Google Maps REST service invocation.

 

This information is looked up at the source web site: developers.google.com/maps/documentation/geocoding/.

 

 

InvokingREST01_Geocoding

 

 

In this specific example, we will use the Geocoding API exposed through a Web service to send an address, and obtain the corresponding latitude and longitude coordinates.

 

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).

 

We will illustrate how to invoke a REST service, using the Create Vendor Process in Bizagi:

InvokingREST02_createvendor

 

 

In this sample Process, our data model is as shown:

 

InvokingREST03_datamodel

 

 

Notice that this example uses Google's REST service invocation (an external Web service). For this reason the Bizagi Server must have 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:

 

InvokingREST04_Step6

 

 

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:

 

REST00

 

 

From the information presented at the Google Maps API web page, we specify its location URL separated into: the Base URL and the Service URL.

 

note_pin

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 usually contains query parameters, in which values should vary per invocation.

Recall that this URL should not contain extra blank spaces.

 

This example's Base URL for XML content-tpye is: http://maps.googleapis.com/maps/api/geocode/xml?

This example's Base URL for JSON content-tpye is: http://maps.googleapis.com/maps/api/geocode/json?

This example's service-part of the URL is ("Service URL"): 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

 

REST02

 

 

Notice that this method we are invoking is a GET method (just to consult information), and that it also returns the information in an XML or JSON 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 QueryParams table to the right. This way, we map and specify the information which is to be sent to this invocation:

 

REST03

 

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.

 

This example is oriented to XML-formatted or JSON-formatted response.

The chosen response structure is consulted at the REST service API's web page. Based on this, if the invocation expects an XML-formatted, then we go to developers.google.com/maps/documentation/geocoding/?hl=en#XML, otherwise, we go to developers.google.com/maps/documentation/geocoding/?hl=en#JSON,

Copy the presented sample text into an file with the respective extension (.xml or .json).

 

XML Format

 

InvokingREST10_input13

 

JSON Format

 

InvokingREST10_input13_json

 

note_pin

For JSON Format, the Content Type needs to be set in the Interface properties located in Expert > External systems > Default (or other name), Interfaces > your interface name.

 

InvokingREST10_output_json

 

Right-click the table at the left and enter the response structure.

This may be done manually (by adding nodes), or in an automatic manner by loading the structure from a physical XSD, XML or JSON file.

Click for more information about REST configuration options.

 

In this example, we choose the Import option to load the structure from the saved file (locating the copied structure previously saved):

 

For the XML file, we chose Load Sample XML

 

REST04_xml

 

For the JSON file, we chose Load Sample Json

 

REST04_json

 

Once we have the XML/JSON 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 (Response Data) and then on the target attribute (Bizagi Data), or also drag and drop a connection from the source to the target.

 

In the end, the mapped response information for our example will be as follows:

 

REST05

 

Click Next.

 

note_pin

When mapping outputs to Bizagi, 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:

 

REST03_output_Advanced

 

For more information about the advanced options, refer to Advanced mapping.

 

 

Configuring optional error handling

Lastly, no error handling validation is needed for this example.

To view more information about error handling options, refer to Interfaces Error handling.

 

REST08

 

 

Click Finish.

 

 

Execution

Run the Create Vendor Process, and test the invocation result in the Work Portal.

 

To do this, click the Run button in the Home tab:

 

ComponentLibrary_Run

 

In the Work Portal, we create a new Create Vendor case and enter the vendor's address in the "Register Vendor information" Task field.

For this REST service example, all text which make up the address are separated by the "+" character:

 

REST06

 

After Google Map's REST service invocation, we will obtain the latitude and longitude coordinates for the Vendor's address:

 

REST07