Example Using the Wizard to Invoke Webservices
From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
<keywords content="keywords"> webservice, webservices, web services, complex webservice, complex web service, web service complex data types, webservice complex data types, XML, XSD, XSLT, interface, interfaces, WebService, Webservice, Web Service, WebServices, Webservices, Web Services, parameter mapping </keywords>
Contents |
Example Using the Wizard to Invoke Webservices
Bizagi offers a module to allow the agile configuration and implementation of an interface that communicates with external applications. This module offers one or several public methods, which can be invoked by the authorized users for these applications or external systems. This information can be transformed or modified so that both systems (Bizagi and the external system) understand the exchanged data.The definition of interfaces is performed in the sixth step in the Process Wizard, where the interaction with other systems using web services is configured.
The following example shows the configuration of an interface which verifies if the potential client of a bank is included in any black list. The verification is done in an external system that already exists in the bank.
The first step in order to configure the parameters to invoke the Web Service from Bizagi is to select the Service Task called "Verify in Black List" to open the Interface Wizard.
|
Note: For this shown configuration in the interfaces wizard, we first select SOAP as the service type:
|
Then in the wizard, type the URL to the web service and click on Go.
All available methods in that web service are shown with its respective input and output parameters. Select the method of the Web Service that is going to be invoked.
Once a method is selected, the Interface Name is set to the same method name. If the method is changed the name will also be changed (is possible to type a different name from the one proposed after the method is selected). The System is also selected by default. It is possible to select another existing System or to type a different name to create a new one. When finished click the Next button.
The second step is to map the input parameters. In the default view, a table with the Bizagi data model is shown on the left side and on the right side there is a table with the structure of the message the web service expects.
For Bizagi to be able to show this structure it is necessary that the web service has completely described the data types, used in its request and response messages, in its WSDL. In this way it is possible to relate the data in Bizagi with data in the web service without writing a XSL transformation. An example of such web service is similar to the one used in this example. When queried in a web browser, it looks like this:
|
Note: If the web service used in an interface does not have the description of the data types, read here how to configure an interface using the Advanced options. |
Using the wizard it is possible to have one-to-one relationships. Assign the simple data type parameters of the web services an attribute to the same data type in Bizagi. As seen from the picture above, the web service needs to receive two strings, DocumentType and DocumentNumber. These parameters are going to be matched to the client’s DocumentNumber and DocumentType. Do this by clicking on the arrow beside DocumentNumber in Bizagi Data table, and drag the line that appears to the arrow beside the corresponding parameter in the web service.
The same is done for DocumentType, just that the attribute to do the mapping will be the Code belonging to DocumentType. After this, click the Next button.
The following window is very similar, but is used to map the response from the web service to attributes in Bizagi so the information is saved for a case. For this reason, now the web service table is on the left and the table with Bizagi Data is on the right.
In both this window and the previous one, there is an option to maximize the window, on the upper right corner. Maximizing this window will allow inclusion of special mapping features and functions, and use of other available quick-configuration options such as: Map all, Unmap all, Undo and Redo.
The response from the web service is mapped to Bizagi data in the same way as before, clicking on a left arrow and dragging the line to an arrow on the right. Here, the Boolean parameter Exist is mapped to the Boolean attribute BlackListReported; DocumentNumber to DocumentNumber; DocumentType to Code belonging to DocumentType; and ListCode to Code belonging to ListRejectionsApplicant which is an attribute in the Collection ApplicantsRejections. This last mapping will create a new record in the Collection.
Click on the same button, used to maximize the window, to restore it to its normal size, and click on Next to continue with the interface configuration.
On the last step it is the error handling of the interface. Here, assuming that the Service Task does not has an Error Event attached, in the Error Invoking Web Service action select Throw Exception. This means that if there is a communication error with the web service, or any other uncontrolled error occurs, the error is reported so the process stops until this error can be solved by the administrator.
The Response errors section is to be used when the web service returns controlled errors. On Response XPath write the complete XPath of the element that should be checked for an error value in the web service response.
Then click on Add error validation; select the Operator (different than or equal to) and the Value that indicates an error. For this error validation also select an Action, like the one before; and finally the Error message, which can also be a parameter of the web service response.
To save this configuration click on Finish.
Web Service Configuration (Advanced)
There may be some scenarios in which custom options and advanced transformations will be required. For this, the wizard's options may not fullfill these requirements.
Some of these scenarios involve when:
- The web service does not have a complete definition of the data types used on its messages in the WSDL.
- Either the request or response message of the web service requires a sophisticated transformation, in which it is necessary to use elements like: if, choose, call-template, param or attribute; or any other XSLT advanced function.
- The response from the web service will be used to update information of a Collection in Bizagi.
- The web service is used to generate a PDF file.
For any of the previous cases, you may use the Advanced options to invoke web services.
Related Articles
- Special web services mapping features and functions.
- Advanced options to invoke web services.
- Web services in Bizagi.
<comments />
