Building an App for Mendix Workstation

Last modified: April 23, 2026

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 3.0.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 an existing app to extend with Workstation functionality in Mendix Studio Pro, or create a new app.

  2. Import the Mendix Workstation Connector from the Mendix Marketplace.

  3. Register one or more Workstation Clients. For more information, see Registering Workstation Clients.

  4. Configure your app as an allowed app by performing the following steps:

    1. In your app go to App Security and assign the module role StationConnector.Administrator to the Administrator user role.
    2. In your app add the page StationConnector_Security to your navigation or link to it from an Open page button. Alternatively, place the snippet SNIPPET_StationAdminPage on a page available to the Adminstrator user role.
    3. Run the app.
    4. Log in as an Administrator, navigate to the page you added in step 2 and copy the shown public key.
    5. Go back to the Workstation Management and navigate to the workspace you created in step 3.2.
    6. Go to the Apps page in your workspace and click Create App.
    7. Enter your app's URL (for example, http://localhost:8080, which is the default when running an app locally) and paste the copied public key into the Public Key field.
    8. Perform one of the following actions:
      • To enable the app for all stations, select Enable in all stations
      • To enable it for a specific station, go to Stations and navigate to your station. You will find the created app under the Apps section. Here you can enable the application just for this station by pressing the toggle.
    9. Refresh the Workstation Client.
    10. Optional: To recreate the key pair, additionally assign the module role StationConnector.SecurityAdministrator to your Administrator role. This adds a Regenerate KeyPair button to the StationConnector_Security page. Use caution when using this button in a production scenario to avoid the need to reconfigure the app in the Management, and refresh all Workstation Clients.

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

You can invite other Workstation Management users to your workspace to share configurations and collaborate. This feature requires a Workstation license.

To invite a user, click Team in the left navigation menu, then click Invite Team Member. Enter the user's email address and select a role. For more information about the available roles, see Workspace Team and Collaboration.

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. This action requires the 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 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 - A non-persistent entity representing the Workstation Client configuration.
  • Device - A non-persistent entity representing a connectable peripheral device. Includes the name, class and state (Available, Connected, or Error). Specialize this to maintain your device specific state.
  • 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.

SendDeviceMessage

Call SendDeviceMessage to send a message to a device. For more information about the supported message syntax, see Message Syntax for File, Smart Card, and Bluetooth Devices. This action has the following parameters:

  • device
  • message

WaitForDeviceMessage

Call WaitForDeviceMessage to wait for a message from the connected device for the duration of the specified timeout period. This action has the following parameters:

  • device
  • timeout

WaitForObjectChange

Call WaitForObjectChange to wait for changes in the attributes of the specified object for the duration of the specified timeout period. This action has the following parameters:

  • objectToObserve
  • attributes
  • timeout

GetCreateDevice

Call this nanoflow to create and configure a device, and define the actions that should happen on connection, disconnection, or messages from the device. This action has the following parameters:

  • name
  • class
  • initialize
  • createDevice
  • entity
  • onConnect
  • onMessage
  • onDisconnect

ConnectDevice

Call this action to connect to a specific device.

DisconnectDevice

Call this action to disconnect from a specific device.

Initialize

This action sets up communication with the Workstation Client. It should be automatically called through the initialize parameter of GetStation or GetCreateDevice.

GetStation

Call GetStation to retrieve the current Workstation Client configuration and devices. This action creates and returns a station object with a linked device object per peripheral.

To interact with a specific device, it is better to use GetCreateDevice instead. GetCreateDevice has a more convenient API, allows specialization, and does not create station and device objects which may not be needed.

SubscribeToObjectChanges

Call SubscribeToObjectChanges to trigger a nanoflow when the specified object changes. This action has the following parameters:

  • objectToObserve
  • attributes
  • callback
  • applicationContext

SubscribeToDeviceMessages

Call SubscribeToDeviceMessages to trigger a nanoflow when a message is received from a device. This action has the following parameters:

  • device
  • callback
  • applicationContext

SubscribeToDeviceErrors

Call SubscribeToDeviceErrors to trigger a nanoflow on device connection error. This action has the following parameters:

  • device
  • callback
  • applicationContext

Unsubscribe

Call Unsubscribe to end a subscription.

Private Nanoflows

CreateStation, CommitStation, CreateDevice, and CommitDevice are private nanoflows, required be compatible with strict mode.

Widgets

The following widgets allow you to specify when to execute an action:

  • On Load/Unload - Execute the action when the widget is first rendered, or when it is removed (unloaded).
  • On Change - Execute the action when the specified attribute changes.
  • On Equal - Execute the action when an attribute is equal to the specified expression.
  • On True - Execute the action when the specified expression is true.

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.