Implement a Simple CI/CD Pipeline with Mendix APIs

Last modified: August 19, 2024

Introduction

This how-to describes how to use the available Mendix APIs with any mainline orchestrators (Jenkins, Visual Studio Team Services, etc.) to build a simple CI/CD pipeline.

This is not meant to be a step-by-step guide. Its purpose is to indicate which APIs to use and to provide some examples of how to use them. The tool used in the examples is Postman.

Prerequisites

Before starting this how-to, make sure you are familiar with the following:

Building The Pipeline

The basic process for building a CI/CD pipeline is described below. The process involves setting up API keys and rights, building the deployment package, and deploying to the next environment. In most cases, it also involves running tests once the package is deployed and the environment is restarted.

Setting Up API Keys and Rights

User API Key

For access to Mendix Cloud environments, an authorized user is needed when executing the APIs. With Mendix APIs, this is achieved via API keys. To create a Mendix API key and set the required authentication headers, follow the steps in Authentication.

Mendix API Rights

To be able to use the Mendix APIs to access your environment, the user who is going to access the APIs needs API rights.

To grant API rights, open your app in Apps, then go to the Permissions tab of the app’s Environments page and select the API Rights option for the user for whom you created an API key in the User API Key step, above. For more details on how to configure permissions, see Node Permissions.

Building the Deployment Package

To build the deployment package, use the Team Server API and the Build API. In this example, a package will be built for the latest revision, but you can use whatever version you wish.

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 <AppId> is ukservices.

Building the Package

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 (as described in Start Building a Deployment Package).

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).

Deploying to the Next Environment

After building the deployment package, you can deploy the new package to the next environment (such as Test or Acceptance). To do this, use the Deploy API.

Getting the Environment Status

First, check if the environment to which you want to deploy is running. To do this, use the Retrieve Environment API call and check the status.

Stopping the Environment

If the environment is running, you need to stop it before deploying the new deployment package to it. To do this, use the Stop Environment API call.

Deploying/Transporting the Package

To deploy/transport a package to the environment, use the Transport a Deployment Package to an Environment API call.

For this action, you need the PackageId from the Building the Package section.

Starting the Environment

After a successful deployment, the next step is starting the environment. Use the Start Environment API call to do this.

Before proceeding to any next steps, confirm that the environment has started. To do that, use the Get Environment Status API call with the JobId (output of the previous call). The environment is ready when the status is Started.

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 CI/CD 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.

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, 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 for failure were.

Mendix Application Test Suite (ATS) Tests

ATS has its own API for CI/CD. To use this ATS API, follow the steps in the ATS and CI/CD section of How to Use ATS in Combination with CI/CD.

Next Steps

If you need to promote to another environment, repeat the steps in the Deploying to the Next Environment section.

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).

Jenkins

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-Username and Mendix-ApiKey will be set in a customHeaders array.

This code snippet example gets the latest revision number so it can be used when building the deployment package:

VSTS

To call a REST service with VSTS, use the Invoke REST API task. Use it in an agentless phase, and set up a Generic endpoint first. The Mendix-Username and Mendix-ApiKey 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 succeed if the environment is running.