Integration has always been an important part of application development. But the topic hasn’t taken much of the spotlight in the marketplace for developing apps until now. The maturation in cloud native and “as a service” software options have increased the need for APIs that connect disparate applications together to exchange data, trigger events and orchestrate workflow processes.
At Mendix, we’ve made investments in the platform to make it easy to connect applications and services with each other in a variety of ways, most recently with REST. And while REST has become a standard for building APIs and web-services for applications to talk, it’s important to recognize other web service protocols. Standardized frameworks and APIs remain valid options depending on the problem you’re trying to solve. Let’s spend some time identifying the use cases where Mendix plays a role in integration, the guiding principles for building integrations with Mendix, and how the platform solves integration challenges to enable your enterprise.
Identify the Use Case for Integrations
Mendix offers a variety of protocols, frameworks, and APIs for integrating systems to Mendix applications and between disparate software solutions. But before you pick a technology to use for an integration, identifying the use case will help inform the decision you will make. Let’s go through the most common integration use cases and the technologies used to satisfy them.
Extending legacy systems
A common use case for Mendix is to build modern UIs and mobile apps on top of legacy systems. You still see a lot of SOAP-based web services when connecting to legacy systems. Mendix’s web-service support will allow you to use these systems quickly from your Mendix application because of the extensive support for mapping complex XML messages to Mendix entities.
It’s also common to build apps directly on top of legacy databases, or even custom protocols. Mendix offers a Database Connector to run SQL queries directly on existing databases. For custom protocols, you can use the Connector Kit to easily provide access from Mendix applications.
Using third party services
Increasingly, software components and functionality are offered as a service. All the large cloud vendors offer many interesting services, from text to image recognition, from address validation to complete business process automation. The majority of these use REST as the technology to expose these services, although some SOAP technology is still being used.
Expose APIs
Many companies participate in digital ecosystems. APIs to expose data, algorithms, transactions and business processes play a crucial part in this goal. APIs enable an independent group of enterprises, people and things to collaborate on a standardized digital platform. REST is the main way to implement these APIs.
Using Microservices architectures to build complex solutions
To achieve speed and agility in your software development process, separating your solutions into small components that can be developed and operated by small autonomous DevOps teams has become essential.
Sharing data and logic between multiple apps often takes significant effort to implement. Mendix helps you by generating most of the required APIs based on your microflows and domain model entities.
For microservices, decoupling your components using a message bus or iPaaS, will bring additional benefits like improved uptime and scalability. Mendix works well with most commercial messaging products. Modern iPaaS platforms offer publish and subscribe functionality based on REST protocols. Real-time push-based messaging is usually provided through REST webhooks.
Microservices best practices promote the concept of smart end-points and dumb pipes. In practice, this means that your message bus is only responsible for transporting messages between apps. The apps themselves need to be able to translate a message into any format they need. Mendix’s Import- and Export-mappings enable you to easily define in a visual way how to convert message formats from one app to another.
Backend system for bespoke frontend – and mobile – applications
Developers of mobile apps usually need a backend to store their data and integrate with backend systems. Using Mendix’s ability to generate Rest APIs for domain models, you can have a backend for your mobile application in 5 minutes. No need to spend a lot of time building a backend, and no need to learn another backend language (and database technology) just to store your mobile data.
Mendix is not limited to just storing data for your applications. Because of its strong support for logic and integration, we see customers using Mendix as a Digital Integration Hub. The Mendix-based backend retrieves data from other backend applications and services, handling data transformation and validation.
And best of all, creating administrative web pages to manage your back office processes is a piece of cake with Mendix. Building these back office webpages usually takes a lot more effort with specialized mBaaS solutions.
Guiding principles
As mentioned above, one major goal of our integration facilities is to connect to external systems. We aim to make this as simple and productive as possible. However, when dealing with external systems, productivity is not enough. Control, agility, and collaboration are important aspects to consider. Here’s how that is handled in the Mendix platform.
Control
When dealing with systems not under your control, having control over integration details can be very important. You need to be able to adjust to the other side, as these are not always implemented correctly according to spec, or they may be old systems, using old practices.
This means you need a simple and flexible way to convert messages between external systems and your Mendix application.
In Mendix this is handled with mappings. You can define import mappings to convert received messages into Mendix objects. When sending objects to external systems, you can convert them using export mappings. This will work both for XML messages as well as for JSON messages. Mappings are reusable, meaning that you can use them for Web Services, Rest services and for connector kit integrations as well.
The following screenshot shows an import mapping where an XML or JSON message containing orders and order lines will be converted into Order and OrderLine objects. 
Speed
Speed is not just about raw productivity, but also about easily being able to change your applications. When external systems depend on your services, or vice-versa, being able to modify your application without impacting external dependencies is critical. Two important tools will help you here: versioning of APIs and explicit contracts about the messages exchanged.
To ensure the messages you exchange remains the same, you can define these messages using message definitions. Depending on the use case, this can be done using an xml-schema, a json structure, or a message definition started from one of your domain model entities. When you make changes to your mappings, that aren’t compatible with your message definitions, you will see a consistency check.
The following screenshot shows a message definition started from an entity. If you have associated entities, you can include these to define the aggregate message, e.g., orders with order lines.
Versioning is built into Rest publish. You can specify a version for your API, and make it part of your endpoint address. When you need to provide an API with different behavior you provide a new version simply by copying the original definition and changing the version number. This allows you to run two versions side-by-side until everyone has migrated to the new version.
Collaboration
Integration usually requires collaboration with other people, both inside your organization and outside as well. We aim to make this as easy as possible, for example by providing visual mappings to define how to convert external data to internal data. The visual nature of these mappings enables you to collaborate on them with anybody in your organization, even non-technical people.
Another tool that facilitates collaboration is the automatically generated documentation and contracts for your services, so others can easily understand and use them. Every REST API you implement will automatically include an OpenAPI document, describing all the resources and methods provided by your API. If you include documentation and example values in your message definition, as shown in the previous section, these will also be included in your OpenAPI documentation. This will make it very easy for your user to start using your API.
Similarly, every web service built with Mendix generates a WSDL based documentation page.
Tools
Now that we’ve looked at the main use cases for integration and reviewed the guiding principles for building integrations, let’s go through the main tools for implementing these in Mendix. Here’s the list:
- Web services – Mendix provides out of the box support for publishing and consuming SOAP-based web services.
- Rest services – REST publish and consume for Microflows and entities.
- oData – Publishing entities for use in BI and data analytics tools based on the OData standard.
- Connector Kit – Integration through custom Java logic.
- Connectors – Custom integrations using the Connector Kit available through the App Store.
Web services
Mendix supports both publishing and consuming web services:
- You can publish microflows as web service operations.
- You can consume web services by importing their WSDL contract.
Creating a web service is as easy as selecting “Publish as web service operation…” in the microflow editor. When you turn any a microflow into a web-service operation, any input parameters and the microflow return value will automatically be converted into input and output messages for the operation.
You have full control over the message, you can select which attributes to include, and what names to use, as illustrated in the following screenshot. This enables you to ensure the contract with the outside world is stable, while you can still make changes to your application. And speaking of contract, using this information is enough to generate both the WSDL and the documentation automatically.
When you have a WSDL, either from a Mendix application or from a 3rd party application, you can easily import it into your Mendix App. All you have to do is create a new “Consumed Web Service” document, specify the location of your WSDL, and you’re good to go.
You can call any operation in the consumed web service by using the Call Web service activity in a microflow. When calling an external web service you can use import and export mappings to ensure your domain models are easily converted to and from any messages you need to exchange with the service.
Import and export mappings offer a powerful way to convert external data to Mendix objects and vice-versa. Some of the features it supports:
- Automatically detects and creates associations between objects.
- Support for inheritance and other complex xml types.
- Can generate the required domain model entities from the WSDL or XML schema.
- Can be used to create new objects or object existing objects.
- You can use microflows to convert attributes.
- You can specify which attributes in the message should be treated as key attributes.
- Support for complex XML schema definitions like the Acord standard.
These mappings can be reused for Xml and Json and for Webservices, Rest and Connectors.
REST services
We are very proud of what you can do in Mendix with REST publish. With the most recent productivity improvements, we can now safely say that Mendix is the easiest and most productive way to create APIs.
Just in this months release we’ve added:
- Generate full Rest API for an entity from the domain model.
- Generate full Rest API by dragging an entity from the Connector.
- Generate default message definition for an entity by dragging it from the Connector to a message definition.
- Generate default mappings from a message definition.
With these productivity improvements, you can now create a REST API for your domain model in literally seconds, as illustrated below.
Most newer services are using REST instead of web services these days. Using REST requires a small shift in the design of your services. Web services are about calling and providing access to remote logic. In REST, you design a data model that can be used by external apps. Objects in your domain model are called resources. The operations on your resources are standardized:
- Read or find one or more existing resources (GET)
- Create a new resource (POST)
- Change an existing resource (PUT)
- Delete an existing resource (DELETE)
You will also see this approach in contracts for REST services like Swagger and OpenApi: first, the resources will be listed, and then the operations on these resources.
The Mendix REST publish functionality follows the approach used by OpenApi where you define your resources first, and then the operation on those resources. You have full control of your REST API because you define the resources, the messages exchanged, and the microflows that implement the operations.
Alternatively, you can let Mendix handle all of this automatically. Just expose your entity from your domain model, or drag an entity on the resources section of a publish REST document, and everything required will be generated for you, including security. All the security rules you define on your entities are automatically used by your REST API.
Whether you want full control of the API you implement, or you just want to generate a backend for your mobile application in 5 minutes, Mendix can do it.
Looking at the implementation of your REST operations, you can use any microflow as the implementation of a REST operation. Mendix will automatically detect the parameters you need and any objects that need an import or export mapping. This can be specified in the Operation dialog. You can also use send and receive binary data or file document, for example, if you want to provide an operation to retrieve a pdf document.
The following screenshots use the optional httpResponse parameter which you can use to override Http status code or status message. If required, you can also specify that you want access to the http request, for example, to determine the value of http header values.
As already shown earlier in the post, Mendix will automatically provide an OpenAPI contract and documentation page for every Rest service you create. If you provide example values in your message definitions, users of your Rest service literally only have to push “Execute” to see the result of calling your service. We can’t make it any easier than this.
Calling a REST service is also simple. First, you define what the external resources you are going to use look like by creating a message definition. The easiest way is usually to create a JSON structure by copying and pasting an example JSON message. Mendix will automatically determine the structure of your message and the applicable attribute types, as illustrated below.
Next, define mappings to import and export data to the external Rest service. This is similar to the example above. One feature not yet mentioned is that you can generate Domain model entities in case you do not already have the appropriate entities. This is probably the case when you have defined a message based on some example JSON.
Finally, use the “Call Rest” activity in microflows to call the REST API. This is simply a case of providing the url of the API, and in the request and response tabs, you can define which mappings you want to use.
oData
Mendix currently provides oData in the modeler as an integration facility for a specific use case: providing Mendix app data for analytics. Next to this, Mendix also provides SAP integration based on oData, but this is based on Connector Kit technology, as described in the next section.
OData provides a similar interface which you may expect from a database. It has insert, select, update, delete functionality on resource. OData achieves this by standardizing a data language on top of Rest. The benefit of this is that all client tools understand up front how to work with the data you expose.
The data analytics tools that support OData range from Microsoft Excel to Tableau, to ETL tools, to basic query tools like LINQPad, and even to statistical analytics tools like R. This means that you can expose your data from Mendix once, and all these tools can directly work with the data within your App.
To expose your Mendix data through OData, select “Expose as OData resource…” on your entity in a Domain model.
Next, you will be able to specify which attributes you want to expose. You can also specify who can access this data. Of course, all entity access rules specified on your domain model entities still apply when retrieving data through OData.
You can now open the exposed entity directly in a tool like Microsoft Excel or PowerBI and always have up-to-date information from a Mendix application.
Find more information on Mendix OData support and how to use R to gain insight from the data in your Mendix apps.
Connector Kit
In case one of the out-of-the-box integration facilities doesn’t fit your need, you can use the Mendix Connector Kit to implement a custom integration. The Connector Kit enables you to implement custom Microflow Activities using the Mendix Java API. You can re-use most 3rd party java libraries, to provide any integration you need. The Microflow activities you implement will be completely integrated into the Toolbox, so any Mendix developer can use them without Java knowledge.
To create a custom integration with Java, create a custom Java action. A java source file will be generated for your Java action. Here you can provide your Java implementation, or call into existing Java libraries. To ease the use of your customer microflow activity by other developers, you can define how your activity will show up in the microflow editor toolbox, as illustrated below.
Users of your custom integration will now see the activity show up in the Microflow toolbox, like any other microflow activity.
If you want other projects to also benefit from your custom integration, you can publish the source module to the Mendix Appstore.
Find more information on the Mendix Connector Kit:
- https://docs.mendix.com/howto/extensibility/howto-connector-kit
- https://www.mendix.com/blog/introducing-mendix-connector-kit/
- https://www.mendix.com/blog/writing-code-in-a-low-code-world/
- https://apidocs.mendix.com/7/runtime/
Connectors
A large number of these custom Connector Kit based integrations already exist in the Mendix Appstore.
SAP OData connector
The SAP oData connectors enable you to easily build Mendix applications on top of SAP. The OData model creator will generate a Mendix domain model based on what you have exposed in your SAP API Hub, so any customizations to your SAP APIs will also be included in your Mendix Application.
Appstore links:
- https://appstore.home.mendix.com/link/app/74525/Mendix/SAP-OData-Connector
- https://appstore.home.mendix.com/link/app/105622/Mendix/SAP-OData-Model-Creator
Database connector
Using the database connector you can execute SQL queries and Stored Procedure calls on existing databases. The connector will execute the query and convert the retrieved data into Mendix objects. The Appstore also contains an Oracle connector with support for Oracle specific extensions like pl/sql procedures, ref cursors and user defined types.
Appstore link:
- https://appstore.home.mendix.com/link/app/2888/Mendix/Database-Connector
- https://appstore.home.mendix.com/link/app/8683/Mendix/Oracle-Connector-(Beta)
Apache Kafka connector
Apache Kafka is a distributed streaming platform, specifically targeted at high volume exchange of messages between different applications, and processing of for example IoT sensor data. Using the Kafka connector Mendix Apps can send and receive messages through Kafka.
Machine learning and cognitive connectors
There are a number of connectors in the Mendix Appstore that allow you to use machine learning for specific purposes. Some examples include identification of images and text, automated conversions with chatbots and detection of emotion in text.
Redis connector
Redis is an in-memory database which can be useful when building a distributed multi-instance application. Redis can be used as a data cache and message broker.
Appstore link:
IOT connectors
Next to the Kafka connector mentioned earlier, there are some other connectors that can also be used with IoT data:
- MQTT client: https://appstore.home.mendix.com/link/app/3066/Mendix/MQTT-Client
- AWS IoT connector: https://appstore.home.mendix.com/link/app/2868/Mendix/AWS-IoT-Connector
- KPN Lora connector: https://appstore.home.mendix.com/link/app/2747/First-Consulting/KPN-LoRa-Connector
As the demand for applications grow, the need to connect them to each other will grow to support the diversity of use cases the applications will need to satisfy. Mendix offers flexible integration options tied to guiding principles that make creating new connections easy to build, manage, and expose to the variety of systems and services within your organization. Providing developers with the right tools and options to help them build integrations gives them the flexibility they need to create and connect apps with speed, collaboration, and control.