Building an App for Mendix Workstation

Last modified: September 9, 2025

Introduction

After you have installed the Workstation Client, you must either build a Mendix application that will send data or commands to your devices, or extend an existing app accordingly. In order to do that, you must download, install, and configure the Mendix Workstation Connector from the Mendix Marketplace.

How the Connection Works

The Workstation Connector must authenticate itself to the Workstation Client so that the Client trusts the app using the Connector and establishes a connection. To achieve this, a key pair has to be generated by the Workstation Connector. The public key must be configured in the corresponding app in the Workstation Management. Workstation Client configuration must be up-to-date so that the public key can be verified.

The Workstation Connector establishes connection with the Device through the Workstation Client when it is needed. The connection is closed when it is not required anymore.

When a client browser or tab instance tries to connect to a device, previously connected browser or tab instances are disconnected from the device.

The Workstation Connector connects with Workstation Client using a local websocket on port 8094. Communication with each configured device uses another websocket on port 8095 for the first device, 8096 for the second, and so on, so that the range of ports used is port 8094 to 8094+n, where n is the number of devices you have. Make sure that the Runtime or Admin port of your local development server in Studio Pro (App Settings > Configurations > Server) is not configured on a port greater or equal to 8094.

Prerequisites

  • Mendix Workstation Client 2.4.0
  • Mendix Studio Pro 9.24.11 or newer

Installing and Configuring the Workstation Connector

To install and configure the Workstation Connector, perform the following steps:

  1. Open Mendix Studio Pro and create a new app using a blank or starter template.

    The starter template is suitable for new users who want a good starting point. Alternatively, you can also add the connector to an existing app.

  2. If you did not use the starter template, download the Mendix Workstation Connector.

  3. Configure the application in Workstation Management by performing the following steps:

    1. Navigate to the Workspaces page in the Workstation Management (default home page).
    2. Click Create Workspace or click on an existing Workspace in the overview.
    3. Click Create Station.
    4. Give the station an identifying name, and optionally select or create a group to categorize it, such as Assembly.
    5. Add your devices in the Devices section.
    6. Register your computer by clicking Register Computer.
    7. Click Download to navigate to the Workstation Client listing in the marketplace, download the Client installer for Windows, install, and launch it.
    8. Copy and paste the registration token into the Workstation Client registration field.

  4. Set up the private key by performing the following steps:

    1. In your app add the microflow ASU_AppKeyPair_Initialize as an after startup microflow and add the page AppKeyPair_ShowPublicKey to your navigation or link to it from a button for an admin role.
    2. Run the app.
    3. Navigate to the page you added in step 1 and copy the shown public key. If there is no key shown click Regenerate KeyPair.
    4. On the Apps page in your workspace in the Workstation Management, click Create App.
    5. Paste the copied public key into the Public Key field.
    6. In the station configuration, enable your newly created application (for example, http://localhost:8080, which is the default when running an app locally).
    7. Refresh the Workstation Client.

Managing Apps

The app that you created in the previous section is available on the Apps page that you can access through the left navigation menu. To enable or disable the app for all your stations or groups of stations, click the icon in the right column of the app list, and then click Manage App.

Managing Users

To invite users to your Workstation, click Team in the left navigation menu, and then click Invite Team Member. You can grant your users one of the following predefined roles:

  • Owner - The owner has full rights to manage the workspace. They can read and edit configurations, invite members, manage security, register computers, and manage workspace settings. They can also delete a workspace or give it to a new owner.
  • Workspace admin - The workspace admin can manage the workspace in the same way as the owner, but they cannot delete workspaces or change their ownership.
  • Station admin - Station admins can view and edit station configuration. They can also register computers to the workstation. They cannot manage any other settings.
  • Computer admin - Computer admins can view the configuration without editing it. They can also register new computers.
  • View only - This role grants access to viewing the configuration.

To change a user's role, or remove them from the workspace, click the three dot icon in the right column of the user list (prerequisite: Owner or Workspace admin role).

Getting Started with Custom Logic for Device Interaction

Now that you are ready to start using Mendix Workstation, you can implement your own custom logic for interacting with devices. The following nanoflows and Java actions are essential for establishing connections, sending or receiving messages, and managing device interactions:

  • GetStation - Retrieves the computer information connected to the Client.
  • SendMessage - Sends data or commands to the connected device. For more information about the supported message syntax, see Message Syntax for File, Smart Card, and Bluetooth Devices.
  • SubscribeToMessages - Subscribe a nanoflow to be called when the device is sending a message.
  • SubscribeToErrors - Subscribe a nanoflow to be called on device connection errors.
  • Unsubscribe - End the subscription to device messages or errors.
  • UnsubscribeByContext - End all subscriptions related to a context object.
  • UnsubscribeByDevice - End all subscriptions related to a specific device.
  • DisconnectDevice - Unsubscribe and completely disconnect from a specific device.

These nanoflows and actions serve as the core building blocks for integrating devices into your Mendix applications and tailoring the functionality to your specific requirements.

Understanding the Domain Model

The domain model contains the following entities:

  • Station - Includes the station name, computer name, the workspace name and the client version (non-persistent entities).
  • Device - A list of devices associated with the station; includes device names and properties required to achieve a connection (non-persistent entities).
  • AppKeyPair - A persistent entity to store the app's key pair. The public key needs to be entered in the corresponding app in the Workstation Management.

Using the Nanoflows and Actions

The following section provides more information about using the nanoflows and Java actions in your Mendix application.

GetStation

Call GetStation to retrieve configuration of the current Client computer. GetStation can be used multiple times, but it queries the Workstation Client only the first time. The following calls return the current object loaded in the session. If connection with Workstation Client does not work, GetStation returns an empty object.

SendMessage

Call SendMessage to send a message to a device. SendMessage includes the option to wait for the response of the device in the current nanoflow.

SubscribeToMessages

Call SubscribeToMessages to trigger a nanoflow when a message is received from a device. SubscribeToMessages includes the option to configure a context object to be passed to the callback nanoflow each time a message is received.

The callback nanoflow must have the following parameters:

  • Device (object)
  • Message (String)
  • Context object (same as the name used when subscribing)

SubscribeToErrors

Call SubscribeToErrors to trigger a nanoflow on device connection error.

The callback nanoflow must have the following parameters:

  • Device (object)
  • ErrorMessage (String)
  • ErrorCode (Integer)
  • Context object (same as the name used when subscribing)

Unsubscribe

Call Unsubscribe to end a subscription.

UnsubscribeByContext

Call UnsubscribeByContext to end all subscriptions related to a context object.

Creating a File Device in Workstation Management

Allowed Folder Configuration

The Allowed Folder feature supports flexible path configuration through environment variables, providing cross-platform compatibility for both Windows and Unix-based systems. This functionality allows administrators to define the allowed folder where the Workstation Client is allowed to perform actions.

Environment Variable Support

The system accepts environment variables in the allowed folder configuration within the Workstation Management interface. Notably, both Windows and Unix syntax formats are supported on all platforms, meaning you can use Windows-style environment variables on Unix systems and vice versa.

Supported Path Formats

Windows and Unix style paths can be used independently from the operating system the Workstation Client is running on. The following examples demonstrate the various syntax options available:

Basic Examples
  • Windows-style with backslash: %AppData%\test
  • Windows-style with forward slash: %AppData%/test
  • Unix-style with backslash: $EnvVar\test
  • Unix-style with forward slash: $EnvVar/test

Allowed Actions

The administrator can choose to allow either one or a combination of the following permissions: subscribe to change events, read files and write files.

Error Logs

Logs for the Workstation Management, Client, and Connector are available in case of issues. For more information about accessing the logs, see Troubleshooting Mendix Workstation.