This how-to describes how you can use the available Mendix APIs with any mainline orchestrators (Jenkins, Visual Studio Team Services, etc.) to build a simple CICD pipeline.
This is not meant to be a step-by-step guide. It will simply show you which APIs to use and provide some examples on how to use them. The tool used in the examples is postman.
Before starting this how-to, make sure you are familiar with the following:
- Using REST services
- Unit Testing (only if used in your application)
- Application Test Suite (only if used in your application)
3 The Pipeline
3.1 API Rights and Keys
3.1.1 User API Key
To get access to the Mendix Cloud environments, an authorized user is needed when executing the APIs. With Mendix APIs, API keys are used to achieve this. To create a Mendix API key, follow the steps in Authentication.
3.1.2 Mendix API Rights
To be able to use the Mendix APIs to access your environment, you will need to grant API rights to the user that is going to be used to access the APIs. To grant API rights to that user, open your app in the Developer Portal, then go to Security > Node Permissions, and check the API RIGHTS option for the user you created an API key for in the previous step.
3.2 Building the Deployment Package
3.2.1 Getting the Latest Revision
To get the latest revision, use the Retrieve Branch API call to get the
LatestRevisionNumber from the output.
An example of how to do this call is below. Be aware that
<AppId> is not a GUID, but the actual name of the cloud node. In the example below, the
After getting the version you want to build the package for, you need to build the package. To do this, use the Start Building a Deployment Package API call.
This is a POST call, so you will need to pass the relevant fields in the body (follow the link above to know what to use).
Before proceeding to the next step, you need to wait for the build of the deployment package to be successful. To do this, use the Retrieve Package API call. This scenario needs to use the
PackageId (output from the previous call) and check if the status is
Succeeded (the other possible statuses are Queued, Building, Uploading, and Failed).
3.3 Deploying to the Next Environment
After building the deployment package, you can now deploy the new package to the next (Test, Acceptance, etc.) environment. To do this, use the Deploy API.
3.3.1 Getting the Environment Status
First, you need to check if the environment to which you want to deploy is running. You need to know if you need to stop it before deploying the new deployment package to it. To do this, use the Retrieve Environment API call and check the status.
3.3.2 Stopping the Environment
If the environment is running, you need to stop it. To do this, use the Stop Environment API call.
3.3.3 Deploying/Transporting the Package
To deploy/transport a package to the environment, use the Transporting a Deployment Package to an Environment API call.
For this action, you need the
PackageId from section 3.2.2 Building the Package.
3.3.4 Starting the Environment
After a successful deployment, you must start the environment. To do that, use the Start Environment API call.
Before proceeding to the next steps (although you might not have any, if all you want to automate is the transport to another environment), you must make sure the environment has started. To do that, use the Get Environment Status API call with the
JobId (output of the previous call). The environment will be ready when the status is Started.
3.4 Running Tests
After deploying the package to the environment and starting it, you are ready to run tests. This is not a mandatory step in a CICD pipeline, but it is usually part of it.
The sections below show you how to execute unit and ATS (UI) tests remotely. There can also be other tests (for example, load tests), but these are not covered in this how-to.
3.4.1 Unit Tests
One way of doing unit tests in a Mendix app is by using the Unit Testing module available from the Mendix Marketplace. This module already exposes an API to execute remote calls.
First, you need to start the tests.
When the tests are completed (check the status for when completed is
true), you can see how many tests ran, how long they took to run, how many failed, which ones failed, and what the reasons were for failing.
You can also (manually) create a web service that exposes the standard unit structure from the data available in the Unit Testing module.
3.4.2 Mendix Application Test Suite (ATS) Tests
3.5 Next Steps
If you need to promote to another environment, repeat the steps in Deploying to the Next Environment section.
4 Jenkins/VSTS Examples
The sections below present examples of how to call a Mendix API with Jenkins (using a groovy script) and Visual Studio Team Services (VSTS).
To call a REST service with Jenkins (using a groovy script), install the HTTP Request Plugin. If you also want to bind credentials to variables (see
withCredentials in the code snippet below), install the Credentials Binding Plugin. The
Mendix-ApiKey will be set in a
This code snippet example gets the latest revision number so it can be used when building the deployment package:
To call a REST service with VSTS, use the Invoke REST API task. This should be used in an agentless phase, and you will need to set up a Generic endpoint first. The
Mendix-ApiKey will go in the Headers section. You can set Success criteria (under the Advanced section) to define what makes the task successful.
The example below checks the status of the acceptance environment. The task will be successful if the environment is running.