Invoking services of an external system is easily configured in Bizagi through the WS Connector.
The WS Connector supports standard SOAP and RESTful services, and features a graphical mapping that allows for inputs and outputs to be handled without the need of programming.
Overriding the graphical mapping in the WS Connector is also supported when there's the need to use custom XSLT transformations.
For more information, refer to Invoking external services from Bizagi.
For sophisticated scenarios in which configuring web service invocation is not possible through the WS Connector either with graphical mapping or custom XSLT files, you may choose to:
•Rely on the Component library feature to develop your own client that invokes a web service (preferred option).
For more information, refer to the Component library.
•Invoke a web service from a business rule in Bizagi, by making use of the Web service element inside business rules (deprecated, preserved mainly for backwards compatibility).
Still in this cases, it is best for maintainability and recommended in terms of best practices, to rely on the Component library feature.
Note that If the input or output parameters involved the web services you will be invoking, involve complex XML elements (not primary data types such as int), then you may rely on methods of Bizagi rules API that handle XMLs and information in Bizagi.
For more information about this API, refer to XML Helper for interfaces.
When are the alternatives above valid?
Sophisticated scenarios that are not possible through the use of the WS Connector are:
•Where web services are built complying to standards not supported by the WS Connector.
Recall that the WS Connector supports a comprehensive set of standards involving SOAP 1.1 and 1.2, WSDL 1.0 and a broad amount of aspects in extensions such as WS-Security or others.
In such cases, you would use the Component library feature (not the rules' Web service element), since the WS Connector supports a broader set of standards than the ones supported by the Web service element.
•Where you need to invoke a web service while iterating over a collection.
This means that the web service to invoke does not receive a array of items, but information for a single element instead (and you would invoke the service multiple times).
Regardless of these alternatives, note that the Web service element inside of business rules has certain restrictions, some which involve support only to SOAP 1.1 (limited support too) without elements such as the xs:choice (https://www.w3schools.com/xml/el_choice.asp). Therefore, it is recommended to use the WS Connector instead.
Using the Web service element
To create a Web service from a business rule, include a Web service element and configure the invocation.
In the next example, a Web Service has a web method that receives and returns simple data types (such as integer, string, Boolean, etc.):
We will use a Vacation Request Process. This Process will invoke a SOAP Web service at the very beginning to verify (look-up) the number of available vacation days for the employee requesting vacations.
The Web service will return a number for this request (integer).
While invoking the business rule, we can manipulate the response before updating it into our data model.
For this example, the following steps are carried out:
1. Create a new business rule to invoke the Web service.
To do this, go to fourth step of the Process Wizard, Business Rules and select Activity Actions:
2. Click the Activity which will include this expression. Create or edit the rule.
After defining the Name, Display Name and Description properties, create a variable for this invocation (to store the response result) by right-clicking on the green Start button and selecting Variable Declaration.
3. Click on Add to create a new variable and select the integer type column (int).
Give it a Name and click Ok.
Notice you may set a default initial value. Click Ok.
4. Right-click the vertical line of the rule and select Add Web Service.
5. Right-click the Web service element and selecting its Properties: This will launch a wizard that will guide through the Web service invocation.
6. Enter the URL location of the Web service.
The first step in the Configuration wizard is to locate your Web service.
In our example, we enter http://www.bizagi.com/ESB/ESBServices.asmx
You may use UDDI for its location resolution.
7. Select the Web method from the methods provided by the selected Web service. Click Next.
8. Set the values of the input parameters.
Note that Bizagi will automatically detect if the chosen method expects input parameters, and in addition will detect their associated data type.
Within the next window, select the parameter to define its value, and click the Set Value button.
In this example, our method receives as input a single parameter of type String.
You may enter the value for this parameter, or choose from a previously set variable.
In this example we use a XPath expression to set the value, since we require the requester of the vacation request (which can be directly reference by using the case's creator information).
Click OK and then on Next.
9. Select the variable in which the response result will be stored.
In our example, this will be the tempResponse variable we created in step 3.
Click on Next to finish the configuration.
10. Include any required or additional manipulation for the result.
We may now continue editing the rule so that any other manipulation is done directly on the tempResponse variable which is temporarily storing the Web service result.
For instance, we may choose to include an inner expression element to add, subtract, round, amongst other calculations on that information.
To edit the scripting of this expression, double-click the expression:
11. Finally, assign the newly calculated information to the data model of the Process.
To do this, we include an assignment element:
Right-click the Assignment element, and selecting its Properties:
12. Set the variable to an attribute in our data model.
In this example, we will assign the tempResponse final value to an attribute value in our Process data model called DaysAvailable:
Notice this attribute belongs to the VacationRequest entity.
To assign tempResponse, we select Expression and directly type the variable's name:
Click on OK to save the business rule.