This is the Mendix client API documentation.

The client API is compatible with both the React and the Dojo client and will replace the previous API which was based on the global mx object.

This documentation is primarily meant to assist the development of JavaScript actions.

Usage

The client API is available as a module in the Mendix client. To use the client API in a JavaScript action, import the module as follows:

import { login } from "mx-api";
import { commit } from "mx-api/data";
import { getUserId } from "mx-api/session";
import { showDialog } from "mx-api/ui";

await login({ username: "demo_user", password: "123456" });
await commit({ objects: [newUser] });
const userId = getUserId();
showDialog({ type: "info", content: `User created` });

Instead of importing the client API methods directly, you can also import the entire module and access the methods through the module object:

import { login, data, ui, session } from "mx-api";

await login({ username: "demo_user", password: "123456" });
await data.commit({ objects: [newUser] });
const userId = session.getUserId();
ui.showDialog({ type: "info", content: `User created` });

Examples

To get started with the client API, you can use the following examples as a reference.

Let's say you have an app where you keep track of pets. The following example demonstrates how to retrieve all pets from the database and create a new pet if none are found in a JavaScript Action.

// This file was generated by Mendix Studio Pro.
//
// WARNING: Only the following code will be retained when actions are regenerated:
// - the import list
// - the code between BEGIN USER CODE and END USER CODE
// - the code between BEGIN EXTRA CODE and END EXTRA CODE
// Other code you write will be lost the next time you deploy the project.
import "mx-global";
import { Big } from "big.js";
import { create, commit, retrieveByEntity } from "mx-api/data";
import { getUserName } from "mx-api/session";
import { showDialog } from "mx-api/ui";

// BEGIN EXTRA CODE
// END EXTRA CODE

/**
 * @returns {Promise.<MxObject[]>}
 */
export async function GetPets() {
    // BEGIN USER CODE
    try {
        // Retrieve all pets
        let pets = await retrieveByEntity({ entity: "MyFirstModule.Pet" });

        // If no pets are found, create a new pet
        if (pets.length === 0) {
            const newPet = await create({ entity: "MyFirstModule.Pet" });
            newPet.set("Name", "Buddy");
            newPet.set("Age", 3);
            await commit({ objects: [newPet] });

            // Retrieve pets again after creating a new one
            pets = await retrieveByEntity({ entity: "MyFirstModule.Pet" });
        }

        // Show a dialog with the current user's name
        const userName = getUserName();
        showDialog({ type: "info", content: `Pets retrieved by ${userName}` });

        return pets;
    } catch (error) {
        showDialog({ type: "error", content: `Something went wrong: ${error.message}` });
    }
    // END USER CODE
}

It is also possible to handle user login and logout in a JavaScript action. The following example demonstrates logging in a user, retrieving and displaying their roles, and confirming before logging them out.

// This file was generated by Mendix Studio Pro.
//
// WARNING: Only the following code will be retained when actions are regenerated:
// - the import list
// - the code between BEGIN USER CODE and END USER CODE
// - the code between BEGIN EXTRA CODE and END EXTRA CODE
// Other code you write will be lost the next time you deploy the project.
import "mx-global";
import { Big } from "big.js";
import { login, logout } from "mx-api";
import { getUserRoleNames } from "mx-api/session";
import { confirmation, showDialog } from "mx-api/ui";

// BEGIN EXTRA CODE
// END EXTRA CODE

/**
 * @param {string} username
 * @param {string} password
 * @returns {Promise.<void>}
 */
export async function UserLoginAndLogout(username, password) {
	// BEGIN USER CODE
    try {
        // Log in the user
        await login({ username, password, useAuthToken: true, reloadOnSuccess: false });

        // Retrieve the user's roles
        const roles = getUserRoleNames();

        // Show a confirmation dialog with the user's roles
        await confirmation({ content: `User roles: ${roles.join(", ")}` });

        // Show a confirmation dialog before logging out
        const confirmed = await confirmation({
            content: "Do you really want to log out?",
            okText: "Yes, I want to log out",
            cancelText: "No, stay logged in",
        });

        if (confirmed) {
            // Log out the user
            await logout();
        } else {
            showDialog({ type: "info", content: "Logout cancelled." });
        }
    } catch (error) {
        showDialog({ type: "error", content: `Something went wrong: ${error.message}` });
    }
	// END USER CODE
}