Presenting the Mendix Platform SDK and Model API

on October 13, 2015

Share:

One of the most exciting features of Mendix 6 is undoubtedly the Mendix Model API and Platform SDK. With the TypeScript- and JavaScript-based SDK, we now provide access to the inner workings of every Mendix app through an API that enables you to automate any tedious or error-prone task. That includes:

  • ‘Reads’ from the app model, e.g. analyzing the quality of your app model, or generating a high-level diagram to document your app.
  • ‘Writes’ to your app model, from creating a new entity in your domain model or adding an activity to an existing microflow, to generating complete new Mendix apps based on legacy code bases.

In short, we are opening up Mendix app models so that you can do anything you want with them.

Use cases

Generating app models & scripting model changes

Perhaps the most exciting use case for our developers is the possibility to update models of existing apps and create new apps from scratch! Here is a code example that uses the SDK to generate three entities with associations in a domain model:

function create(domainModel: domainmodels.DomainModel) {
	let customer = createEntity(domainModel, customerEntityName);
	addAutoNumberAttribute(customer, customerNumberAttributeName, '1');
	addStringAttribute(customer, 'FirstName');
	addDateTimeAttribute(customer, 'SignupDate');
	addStringAttribute(customer, 'LastName');
	addStringAttribute(customer, 'Email');
	addStringAttribute(customer, 'Address');
	let invoice = createEntity(domainModel, invoiceEntityName);
	addAutoNumberAttribute(invoice, invoiceNumberAttributeName, '1');
	addDateTimeAttribute(invoice, invoiceTimestampAttributeName);
	let invoiceLine = createEntity(domainModel, invoiceLineEntityName);
	addStringAttribute(invoiceLine, invoiceLineProductAttributeName);
	addIntegerAttribute(invoiceLine, 'Quantity');
	associate(domainModel, invoice, customer, 'Invoices');
	associate(domainModel, invoiceLine, invoice, 'Lines');
}

Because we provide access to the entire app model, it is possible to change every aspect of your Mendix app with the Mendix Platform SDK. And this access enables you to create tools to transform existing legacy code bases into modern Mendix apps. If you build a parser for your language of choice, you can use the SDK to generate an entire Mendix app from the original source code.

Export

Another use case of the SDK is the ability to export your entire app model. You have access to every model element: pages, microflows, entities, web services, etc. This makes it possible to take your app model and generate new representations—for instance, Java methods for the microflows in your model. This feature removes any vendor lock-in worries you might have about our platform, in the event that you would ever want to move away from Mendix to another technology!

Analysis

If you are looking to improve your existing app models, it can be hard to figure out where to start. Especially if you join a project where you need to work on an existing app, it is a lot of work to get a feeling for where the complexity of an app can be found. Because Mendix app models are now completely open and accessible, you can also analyze them. This makes it possible to do automated model quality analysis. Code quality analysis tools have become common in traditional programming languages such as Java and .NET. It is now possible to create a similar analysis tool for Mendix app models.

You can simply start creating reports of the volume of your microflows: count the number of activities in your microflows and order the microflows by size. The biggest microflows could be a good starting point for further investigation into the app. The following code snippet demonstrates how you could count the number of activities in a microflow:

function calculateMicroflowVolume(microflow: microflows.Microflow): number {
	return microflow.objectCollection.objects.length;
}

An alternative would be to compare the complexity of the microflows in your app. You could calculate it with the following code example:

function calcuateMicroflowComplexity(microflow: microflows.Microflow): number {
	return CalculateComplexity(microflow.objectCollection.objects, microflow.flows);
}
function CalculateComplexity(objects: IList<microflows.MicroflowObject>,
	flows: IList<microflows.Flow>): number {
	var complexity = 1;
	objects.forEach(object => {
		if (object instanceof microflows.ExclusiveMerge) {
			var numberOfIncoming = flows.filter(flow => flow.destination.id == object.id).length;
			complexity += numberOfIncoming - 1;
		}
		if (object instanceof microflows.LoopedActivity) {
			complexity += CalculateComplexity(object.objectCollection.objects, flows);
		}
	});
	return complexity;
}

Based on these two examples, you can imagine that the SDK makes it possible to do all kinds of analysis on Mendix app models.

How does it work?

You can look at the Platform SDK and Model API as an alternative perspective on our existing Team Server repository in which we host your Mendix app models. The Platform SDK allows you to take a specific project, branch and revision, and make it available as an Online Working Copy – essentially the equivalent of a local Team Server working copy, but in the cloud. You can then access the app model to analyze it, make changes, and generate new elements. And finally, once you have applied all the changes you want to make, you can commit those changes back to the Team Server.

The following code snippet demonstrates how you would open your project, change the name of MyFirstModule.Customer to MyFirstModule.Client and commit the changes back to the Team Server:

project.createOnlineWorkingCopy()
	.then(workingCopy => {
		let customerEntity = workingCopy.model()
			.findEntityByQualifiedName('MyFirstModule.Customer');
		customerEntity.name = 'Client';
		return workingCopy;
	})
	.then(workingCopy => workingCopy.commit());

And these illustrations are of course just start. Stay tuned for future blog posts in which we will dive into the details of specific example scripts!

Background on our Model API implementation

More and more of the Mendix app platform services we provide are centered on the app model. At the basis of those services, we have a single specification of the Mendix app metamodel – i.e. the description of what you can define in your app model. This helps ensure that we have a consistent, formal definition of what a Mendix app is across all of our services. We have extensive reference documentation of the metamodel, and will be releasing it as part of the Platform SDK beta release. To give you an idea of how extensive that documentation is, here is a sneak peek into the structure of a microflow retrieve activity:

Model API Platform SDK

In the above diagram, you can identify the Retrieve action that you can define in the Business Modeler as activity in a microflow. You can see the two types of sources from which you can choose (database or association), and the other configurable items, such as the XPath constraint, or the sort order. And this is the actual level at which you can get access to your app model!

The beta label

We are initially releasing the Mendix Platform SDK and Model API as beta, but that does not mean that the quality of the SDK is not production-level. We already use the Mendix Platform SDK ourselves in several of the services that we provide, such as the Mendix Business Modeler and Mendix Model Share. And of course, our own R&D team and Expert Services consultants are already using the Mendix Platform SDK on a daily basis.

The beta label indicates that the APIs have not been completely stabilized yet. Someone once made the remark to me that, like diamonds, APIs are forever. And we want to do them right. So we want to improve the APIs after initially opening them up. Therefore, we currently have a closed and later an open beta program, so that we can improve based on the feedback we get back from our developer community – from you!

Conclusion

This blog post demonstrates the basics of the Mendix Platform SDK. I hope you can imagine that the possibilities are endless – generating new apps, scripting updates of existing apps, analyzing your app models, etc. By opening up our platform, we want to enable our community of developers to take full advantage of Mendix. We think that the only limit to what you can do using the Mendix Model API and Platform SDK should be your imagination! 😉

Get started with the Mendix SDK with the SDK documentation available on the Mendix Developer website.

Subscribe to Our Blog

Receive Mendix platform tips, tricks, and other resources straight to your inbox every two weeks.

RSS Feed of the Mendix Blog

About David Hartveld

Having graduated just a few years ago as MSc in Computer Science from Delft University of Technology, David is always pushing the boundaries of what is possible with the Mendix app platform. He started at Mendix as software engineer in the Platform Portal team, straight from school. He has now taken on the role of Product Manager of the Platform Portal. In that role, he brings his pragmatic approach to building software to the development of the parts of the platform he is responsible for. Besides work, David is a baseball enthusiast and amateur player. He lives in the center of Rotterdam, just an always inspiring bike ride through the breathing heart of the city away from the Mendix office.

| Twitter