This how-to explains how to consume a (third-party) web service with which you can integrate your Mendix application and reuse functionality and data from other applications. Web services are the preferred way of integrating a Mendix application with external systems. They can be used to retrieve data, send updates, and perform operations. In Mendix, calling a web service is something you do in a microflow using the call web service action.
This how-to will teach you how to do the following:
- Import a web service using the wizard and directly
- Configure a web service call
2 Importing a Web Service Using the Wizard
This section will describe the powerful wizard that enables integrating—in just a few clicks—the creation of an imported web service, the related data entities, the XML-mapping, and a microflow to trigger the web service.
2.1 The Configuration
To import a web service using the wizard, follow these steps:
Open your domain model and click Import web service/XML file in the toolbar.
This will open a straightforward wizard dialog that guides you through importing the result of a web service (or an XML file). As a result, it will generate the following items:
- Domain model entities to store the results
- An XML-to-domain mapping that maps the incoming XML to Mendix objects
- An imported web service (or XML schema) document
- A microflow that calls the web service (or imports an XML file) (optional)
On the Import Web Service or XML Scheme dialog box, select Web service operation and click Next:
On the Import Web Service dialog box, select Create new imported web service and click Next.
For WSDL source in the Web service Description section of the New Web Service Operation dialog box, select the WSDL to be used for this imported web service. You can either use a URL (for example, http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL) or load a file from your computer.
Click Next to fetch the services and operations in the WSDL.
This will bring up the Select Ports pop-up window asking you to select a web service port. Click OK to select the default. Studio Pro now imports the operations.
On the New Web Service Operation dialog box, you can now review the services and operations available to the imported web service. Select a web service operation and click Next.
On the Select Elements dialog box, you can optionally select the elements to map as return values of the web service, and then click Next.
The final step in this wizard provides you with the options to add icons to the generated entities and to create a microflow in which the imported web service is called:
Click Finish to create the web service.
2.1 The Outcome
When finished the wizard will add to your model based on the options selected:
- The imported service
- An XML to domain mapping
- A microflow in which the web service operation is called
- Domain model entities (by default, Studio Pro creates non-persistable entities)
3 Importing a Web Service Directly
An alternative to using the wizard described above is to import a web service document directly into your project. For more information, see Consumed Web Services in the Studio Pro Guide.
To import a web service directly, follow these steps:
- Right-click a module and select Add Other > Consumed web service.
- Add a name for the new consumed web service.
In the Consumed Web Service wizard, on the General tab, enter the WSDL to be used for this imported web service. You can use a URL or load a File from your computer.
Click Import to fetch the services and operations in the WSDL.
Review the Services and Operations available to the imported web service:
You can also describe the design purpose of the web service on the Documentation tab.
4 Configuring the Web Service Call
To configure the web service call, follow these steps:
If you did not use the web service wizard and/or did not use the option within the wizard to automatically create a microflow, you have to create a microflow that will call the imported web service:
Make sure the microflow either creates the variables required as arguments for the web service call or has those passed to it.
If you are creating your own microflow, add the call web service activity to the microflow. For details on how to add activities to microflows, see Activities in the Studio Pro Guide.
Double-click the activity to open the Call Web Service properties editor and in the Operation section, click Select… for Operation.
This opens the Select Web Service Operation dialog box, where you can choose the operation for this web service call:
On the SOAP Request Body tab of the Call Web Service properties editor, you can configure the SOAP body, which contains the parameters needed to execute the web service request. The Simple, Export Mapping, and Custom options enable choosing the type of SOAP body to use. Click Edit value to change the domain-to-XML mapping or the variables from the microflow used as input arguments.
Use the Simple option if the imported web service requires only primitive arguments:
Use the Export mappings for each request parameter or Export mapping for the entire request options if the domain model entities need to be mapped to XML elements
Use the Custom option for the definition of a custom XML body with parameters:
On the HTTP Headers tab in the Call Web Service properties editor, you can enter authentication information using the Edit button if the Mendix Runtime should use this before calling the web service:
On the SOAP Response tab of the Call Web Service properties editor, you can configure the handling of the return from the web service call:
If the return is a complex XML structure, you can select the Mapping and use an XML-to-domain mapping to map the XML elements to the domain model entities:
If the return is a primitive, you can store it in a variable that you can name in the Store in variable field:
If you want to ignore the return, select the Ignore option
Your imported web service is now ready to be used in your application.