AuraQ has vast experience helping organisations find the gaps that can be filled to enhance their business. This could be to improve efficiency, integrate legacy systems or deliver new portals and strategic applications to create competitive advantage. Contact us to request a free, no obligation Gap Analysis.
31st Aug 2017
Integrating Mendix with Carrier API
As commerce is increasingly moving from the high street to the Internet, the reliance on postal and carrier services is growing. When you order a product from a website they will be responsible for packing up your order and sending it to you, typically sending your parcel via one of the many available carriers. In many cases the company you’ve just bought from won’t be logging onto a carrier website to manually produce a postage label or go to the post office to send out their orders. Instead they’ll have automated their release method by making use of an API (Application Programming Interface) to print labels in their distribution centre or warehouse.
The use of RESTful APIs has been previously covered elsewhere in this blog when discussing the use of APIs with dropbox (http://www.auraq.com/2017/01/09/an-example-of-using-restful-services-in-mendix-with-the-dropbox-api/). As each carrier runs their business in a different fashion, they all use different methodologies in the design of their APIs. However, they often follow similar design patterns. In this blog, we’ll take a look at some of the considerations involved when integrating Mendix with a carrier or postal API.
The two basic elements of using a carrier API are sending requests, which are validated on the server-side, and receiving a response. Under some circumstances the response will then be used as part of a further request as part of validation in a two-stage process. Ultimately, it is a matter of calibrating your data in accordance with the specifications for the carrier. To ensure the highest success rate, it is best to validate your data before sending it to the carrier rather than relying on the error messages.
APIs are typically defined using .wsdl (Web Services Description Language) files. These .wsdl files can be used in Mendix to create a consumed web service and also create XML (eXtensible Markup Language) export and import mappings for the Requests and Responses to the API. A consumed web service is an external service used by the app, but published web services can also be produced to expose parts of a Mendix app to the outside world.
Creating a consumed web service using a .wsdl allows for an endpoint to be determined and also provides a list of allowed operations. The .wsdl can be set in the consumed web service using either a URL or a file. The endpoint can be set using a constant which allows for changes between pointing at a test and live endpoint when changing through environments. The endpoint can also be overwritten, if need be, when the web service is called. In order to use the web services provided within the .wsdl file we need to pass in suitable data such as an XML string to form a SOAP (Simple Object Access Protocol) request. To produce an XML string or to read in a returned XML string we can use export or import mappings.
There are two available options for creating an export mapping and three for an import mapping. An xsd (XML Schema Definition) can be used or a web service operation can be used for an export mapping. These two options and additionally a JSON structure can be used for an import mapping. These definitions will typically contain information as to which elements are required and which elements are “optional”. The “optional” elements can be chosen by the developer. In many cases the “optional” elements will be required when making certain types of call. So, reading and understanding the API documentation is required when setting up the mapping. The mapping activity requires a top-level parameter entity which should be mapped to the top-most .wsdl schema object. The lower level schema objects can be mapped to entities which have an association with the parameter entity or by using a microflow to retrieve specific entity information.
Figure 1: Export mapping for producing XML. The greyed-out tick boxes are the required fields and the other tick boxes are “optional” fields.
Figure 2: Example Export mapping. The Request is populated using an association and the RequestOption is populated using a microflow.
When calling a web service XML export mapping can either be built into the call or the XML string can be produced by a mapping prior to the web service call. The security header information can also be defined in the web service call itself. The advantage of passing in an XML string is that several different mappings can be produced to return different XML strings which can be passed to a single consumed web service so that consistent handling of the data is applied to each of the different mappings.
An example of why several mappings can be required is for cases where different requirements are in place for carriers depending on which countries a package is being sent to. For example, if an order is being sent outside of the UK (from within the UK) it may require a value of the items being shipped included for customs purposes. So, a different mapping can be used for UK orders which does not include this value and the finalised XML can be passed to the web service for processing.
Validation will be performed on the server side based on the data which has been passed to it. Depending on whether the call was successful or not data (typically information about the consignment, tracking numbers or label information) will be returned or an error will be returned. Import mappings are then used to interpret the response from the API. The import mapping works in a similar fashion to the export mapping except that the XML is now being mapped onto an entity structure.
If an error occurs within the response from the call this is stored in Mendix within the message attribute of the $latesterror object. It is highly advisable to log these messages and the call made to the API either to a log entity or directly to the console. By logging the response, you can determine what has caused the issue. It is worth noting that if an error is returned from a web service this still counts as a successful call to the API so any handling of the error must be done after the web service call using the response. If handling is required for situations where the API is currently unavailable, then custom error handling must be added to the web service call action.
When an API returns a label, it will typically be encoded as 64-bit string. The image file can be retrieved by decoding the 64-bit string directly into a file using a Mendix CommunityCommons java action (Base64DecodeToFile). This file can then be printed out and used to send your parcel.
In this blog, we’ve looked over some of the basic architecture of how carrier services work using a set of requests and responses. We’ve also seen several of the neat actions contained within Mendix which help to accelerate the process such as the import/export mappings and consumed web services. These actions allow for concentration of the developers to be focussed more on how to implement the requirements of the carrier than how to set up the calls to the API which results in more rapid development.
Related Blogs
Drag