diff --git a/content/en/docs/workstation/_index.md b/content/en/docs/workstation/_index.md index 0a960fe3224..b77ed89191f 100644 --- a/content/en/docs/workstation/_index.md +++ b/content/en/docs/workstation/_index.md @@ -9,54 +9,56 @@ cascade: - content_type: "Mendix Workstation" --- {{% alert color="info" %}} -Mendix Workstation Client is [Limited Availability](https://docs.mendix.com/releasenotes/release-status/#limited-availability) for production use. Support is provided according to your Mendix SLA if you purchased a Workstation license. If you want to take the Mendix Workstation Client into production, contact your CSM to see what arrangements are possible. Without a license you can use the Mendix Workstation Client for development, but workspaces are individual and cannot be shared. +Mendix Workstation Client is [Limited Availability](https://docs.mendix.com/releasenotes/release-status/#limited-availability) for production use. Support is provided according to your Mendix SLA if you have purchased a Workstation license. If you want to use Mendix Workstation Client in production, contact your Customer Success Manager (CSM) to discuss available options. Without a license, you can use Mendix Workstation Client for development purposes only; however, workspaces remain individual and cannot be shared. {{% /alert %}} ## Introduction -Mendix Workstation Client is designed to help you build smarter, faster, and more operator-friendly applications for shopfloor operators. It enables Mendix cloud applications to directly interact with peripheral devices on a local workstation, without relying on intermediate servers or heavy network traffic. +Mendix Workstation Client is designed to help you build smarter, faster, and more operator-friendly applications for shop floor operators. It enables Mendix cloud applications to interact directly with peripheral devices on a local workstation, eliminating the need for intermediate servers or heavy network traffic. -By connecting applications directly to the PC's local resources, Workstation allows for near real-time communication with devices like printers, barcode scanners, smartcard readers, and industrial scales, all from within a Mendix app. This setup ensures low-latency performance and reduces infrastructure complexity. +By connecting applications directly to the PC's local resources, Workstation enables near real-time communication with devices such as printers, barcode scanners, smart card readers, and industrial scales—all from within a Mendix app. This architecture ensures low-latency performance and reduces infrastructure complexity. -Workstation is especially valuable in manufacturing and industrial environments where precision, speed, and reliability are key to operator efficiency. +Workstation is especially valuable in manufacturing and industrial environments where precision, speed, and reliability are critical to operator efficiency. -In addition to connectivity features, Workstation supports enterprise-grade deployment of projects across multiple environments and sites. It enables distributed teams to collaborate effectively and centrally manage connections to a wide range of heterogeneous equipment assets in a controlled and secure manner. +In addition to device connectivity, Workstation supports enterprise-grade deployment across multiple environments and sites. It enables distributed teams to collaborate effectively and centrally manage connections to a wide range of heterogeneous equipment in a controlled and secure manner. -## Features of Mendix Workstation Client +## Features -Mendix Workstation Client has the following features: +Mendix Workstation Client provides the following key features: -* Direct local device access - Mendix Workstation Client allows Mendix client applications to send and receive messages directly from the PC's local hardware. -* No server detour - Communication happens between the client app and local devices — without routing through a central server, network overload, or any additional intermediate systems. -* Interactions with the local PC, such as sending and receiving on-event messages, are handled with Mendix nanoflows. -* Supports multiple interfaces: +* **Direct Local Device Access** – Enables Mendix client applications to send and receive messages directly from the PC's local hardware. +* **No Server Intermediary** – Communication occurs directly between the client app and local devices, without routing through a central server or any intermediate systems, avoiding network congestion. +* **Nanoflow Integration** – Interactions with the local PC, such as sending and receiving event-driven messages, are handled through Mendix nanoflows. +* **Multiple Interface Support** – Supports various communication protocols and interfaces: - * PCSC (Smartcard Reader) - APDU protocol - * Serial Port (COM Port) RS232 standard - * TCP-IP (Ethernet) - * Bluetooth LE (BLE) - ATT protocol + * PCSC (Smart Card Reader) – APDU protocol + * Serial Port (COM Port) – RS-232 standard + * TCP/IP (Ethernet) + * Bluetooth LE (BLE) – ATT protocol * File System -* Can emulate and simulate interfaces. +* **Interface Emulation** – Provides the ability to emulate and simulate interfaces for testing purposes. -## Benefits of Using Mendix Workstation Client +## Benefits -* Improve operator user experience and efficiency. -* Renovate home-grown application and get control of legacy systems. -* Keep core systems clean. -* Create apps adapted to the operator's job, instead of forcing the operator to adapt their job to the software. -* Compose new forms of user experience tailored to manufacturing processes, equipment and environment. -* Expand to adjacent users and domains of your core systems and cross boundaries between silos. +Using Mendix Workstation Client provides the following benefits: + +* **Enhanced Operator Experience** – Improves user experience and operational efficiency for shop floor operators. +* **Legacy System Modernization** – Modernizes home-grown applications and provides better control over legacy systems. +* **System Integrity** – Keeps core systems clean and isolated from device-level integrations. +* **Job-Centric Design** – Creates applications adapted to the operator's workflow, rather than forcing operators to adapt their workflow to the software. +* **Tailored User Experience** – Enables new forms of user experience specifically designed for manufacturing processes, equipment, and environments. +* **Extended Reach** – Expands capabilities to adjacent users and domains, breaking down silos between systems. ## Use Cases -Mendix Workstation Client can be used to create apps that handle use cases such as the following: +Mendix Workstation Client supports a variety of manufacturing and industrial scenarios, including: -* Printing labels on an industrial thermal label printer (for example, a Zebra printer) -* Badge operators with an NFC smartcard reader and PC/SC specification -* Scanning and parsing barcodes (for example, GS1 specifications) -* Weighing materials with an industrial scale (for example, a Mettler Toledo SICS-compatible scale) -* Connected smart tools (for example, screwdrivers with torque control) +* **Label Printing** – Print labels on industrial thermal label printers (such as Zebra printers). +* **Operator Authentication** – Authenticate operators using NFC smart card readers with PC/SC specification. +* **Barcode Processing** – Scan and parse barcodes in various formats (such as GS1 specifications). +* **Material Weighing** – Weigh materials using industrial scales (such as Mettler Toledo SICS-compatible scales). +* **Smart Tool Integration** – Integrate connected smart tools (such as torque-controlled screwdrivers). ## Components of Mendix Workstation Client @@ -74,23 +76,29 @@ Together, these components enable Mendix applications to securely and efficientl ### Workstation Management (Mendix Service) -Used by central IT and application support teams. Workstation Management is a Mendix Platform application which provides a centralized interface to configure and monitor all workstations and devices across the organization. Whether managing a few stations or hundreds across multiple global sites, administrators can register computers, assign devices, group them into workspaces, and remotely troubleshoot connection issues. +**Primary Users:** Central IT and application support teams + +Workstation Management is a Mendix Platform service that provides a centralized interface to configure and monitor all workstations and devices across the organization. Whether managing a few stations or hundreds across multiple global sites, administrators can register computers, assign devices, group them into workspaces, and remotely troubleshoot connection issues. -This makes it easier to manage a large, diverse fleet of devices without the need for manual setup or on-site support. +This centralized approach simplifies the management of large, diverse device fleets without requiring manual setup or on-site support. ### Workstation Client (Native Application) -Used by central IT, support teams, operators, and supervisors. Installed on each local workstation, the Workstation Client acts as a bridge between the Mendix client app and local hardware. It handles the traffic between connected devices and the client application using the configurations provided by the Workstation Management. +**Primary Users:** Central IT, support teams, operators, and supervisors + +Installed on each local workstation, the Workstation Client acts as a bridge between the Mendix client app and local hardware. It manages communication between connected devices and the client application using configurations provided by Workstation Management. ### Workstation Connector (Mendix Module) -Used by Mendix developers. The App Connector is a plug-and-play Mendix module that allows developers to connect their apps to local devices using nanoflows. It establishes a connection with the Workstation Client, which acts as the intermediary between the Mendix app and the local devices. Once this connection is established, the module facilitates seamless data exchange by routing messages and events back and forth between the app and the devices. +**Primary Users:** Mendix developers + +The Workstation Connector is a plug-and-play Mendix module that enables developers to connect their applications to local devices using nanoflows. It establishes a connection with the Workstation Client, which serves as the intermediary between the Mendix app and local devices. Once connected, the module facilitates seamless data exchange by routing messages and events between the application and devices. The connector handles the following tasks: -* Retrieving local station configuration (name and device list). -* Connecting and disconnecting devices. -* Exchanging messages with the device. -* Subscribing for triggering app logic on event when receiving messages from the device. +* Retrieving local station configuration (name and device list) +* Connecting and disconnecting devices +* Exchanging messages with devices +* Subscribing to device events to trigger application logic when receiving messages from the device ## Read More diff --git a/content/en/docs/workstation/wks-build-app.md b/content/en/docs/workstation/wks-build-app.md index 8a6ba81e4fb..7f73b63b7d2 100644 --- a/content/en/docs/workstation/wks-build-app.md +++ b/content/en/docs/workstation/wks-build-app.md @@ -8,129 +8,122 @@ weight: 30 ## Introduction -After you have [installed the Workstation Client](/mendix-workstation/installation/), 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](https://marketplace.mendix.com/link/component/247460) from the Mendix Marketplace. +After [installing the Workstation Client](/mendix-workstation/installation/), the next step is to build a Mendix application that can send data or commands to devices, or to extend an existing app accordingly. This guide explains how to install and configure the [Mendix Workstation Connector](https://marketplace.mendix.com/link/component/247460) 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 must authenticate with the Workstation Client, ensuring the Client trusts the application using the Connector and establishes a connection. To accomplish this, the Workstation Connector generates a key pair consisting of a private key and a public key. The public key is then configured in the corresponding app in Workstation Management. The Workstation Client configuration must be current to ensure 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. +The Workstation Connector establishes a connection with devices through the Workstation Client when needed. The connection is closed when it is no longer required. -When a client browser or tab instance tries to connect to a device, previously connected browser or tab instances are disconnected from the device. +When a browser or tab instance attempts to connect to a device, all previously connected browser or tab instances are automatically 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. +The Workstation Connector connects with the Workstation Client using a local WebSocket on port *8094*. Communication with each configured device uses a separate WebSocket on port *8095* for the first device, *8096* for the second, and so on, meaning the port range used is *8094* to *8094+n*, where *n* is the number of devices configured. Ensure that the Runtime or Admin port of your local development server in Studio Pro (**App Settings** > **Configurations** > **Server**) is not configured to use a port greater than or equal to *8094* to avoid conflicting ports. ## Prerequisites -* Mendix Workstation Client 2.4.0 +* Mendix Workstation Client 3.0.0 or newer * 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. +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](https://marketplace.mendix.com/link/component/247460) from the Mendix Marketplace. +3. Configure the station in Workstation Management by performing the following steps: - 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](https://marketplace.mendix.com/link/component/247460). -3. Configure the Station in Workstation Management by performing the following steps: - - 1. Navigate to the **Workspaces** page in the [Workstation Management](https://workstation.home.mendix.com/) (default home page). - 2. Click **Create Workspace** or click on an existing Workspace in the overview. - 4. Click **Create Station**. - 5. Give the station an identifying name, and optionally select or create a group to categorize it, such as *Assembly*. - 6. Add your devices in the **Devices** section. - 7. Register your computer by clicking **Register Computer**. - 8. Click **Download** to navigate to the Workstation Client listing in the marketplace, download the Client installer for Windows, install, and launch it. - 9. Copy and paste the registration token into the [Workstation Client](/mendix-workstation/installation/) registration field. + 1. Navigate to the **Workspaces** page in [Workstation Management](https://workstation.home.mendix.com/). + 2. Click **Create Workspace**, or select an existing workspace from the overview. + 3. Click **Create Station**. + 4. Enter a name for the station and optionally select or create a group to categorize it, such as *Assembly*. + 5. Add devices in the **Devices** section. + 6. Click **Register Computer** to register your computer. + 7. Click **Download** to navigate to the Workstation Client listing in the Marketplace, download the Client installer for Windows, install it, and launch it. + 8. Copy the registration token and paste it into the [Workstation Client](/mendix-workstation/installation/) registration field. 4. Configure your app as an allowed app by performing the following steps: - 1. In your app go to [App Security](https://docs.mendix.com/refguide/app-security/#user-roles) 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. + 1. In your app, go to [App Security](https://docs.mendix.com/refguide/app-security/#user-roles) 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 Administrator user role. 3. Run the app. - 4. Login as an Administrator, navigate to the page you added in step 2 and copy the shown public key. - 6. Go back to the [Workstation Management](https://workstation.home.mendix.com/) and navigate to the workspace you created in step 3.2. - 7. Go to the **Apps** page in your workspace and click **Create App**. - 8. 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. - 9. 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. - 10. Refresh the Workstation Client. - 11. 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. Be mindful when using this button in a production scenario to avoid the need to reconfigure the app in the Management, and refresh all Workstation Clients. + 4. Log in as an Administrator, navigate to the page you added in step 2, and copy the displayed public key. + 5. Return to [Workstation Management](https://workstation.home.mendix.com/) and navigate to the workspace you created above. + 6. Navigate to the **Apps** page in your workspace and click **Create App**. + 7. Enter your app URL (such as `http://localhost:8080`, 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 the app for a specific station, navigate to **Stations** and select your station. The created app appears under the **Apps** section. Enable the application for this station only by toggling it on. + 9. Refresh the Workstation Client. + 10. (Optional) To recreate the key pair, also assign the module role **StationConnector.SecurityAdministrator** to your Administrator role. This action adds a **Regenerate KeyPair** button to the **StationConnector_Security** page. Use caution when regenerating keys in production environments, as this requires reconfiguring the app in Workstation Management and refreshing 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**. +Apps you create appear on the **Apps** page, accessible through the left navigation menu in your workspace. To enable or disable an app for all stations or specific station groups, click the three-dot icon in the right column of the app list, 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: +You can invite other Workstation Management users to your workspace to share configurations and collaborate. This feature requires a Workstation license. -* 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 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. Available roles are described in the [installation guide](/mendix-workstation/installation/#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 (prerequisite: Owner or Workspace admin role). +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 +## Implementing Custom Device Interaction Logic -Now that you are ready to start using Mendix Workstation Client, 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: +Once you have configured Mendix Workstation Client, you can implement custom logic for interacting with devices. The following nanoflows and Java actions are essential for establishing connections, sending and 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](/mendix-workstation/device-syntax/). -* **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. +* **GetStation** – Retrieves information about the computer connected to the Client. +* **SendMessage** – Sends data or commands to a connected device. For more information about supported message syntax, see [Message Syntax for File, Smart Card, and Bluetooth Devices](/mendix-workstation/device-syntax/). +* **SubscribeToMessages** – Subscribes to device messages and triggers a nanoflow when messages are received. +* **SubscribeToErrors** – Subscribes to device connection errors and triggers a nanoflow when errors occur. +* **Unsubscribe** – Ends a subscription to device messages or errors. +* **UnsubscribeByContext** – Ends all subscriptions related to a context object. +* **UnsubscribeByDevice** – Ends all subscriptions related to a specific device. +* **DisconnectDevice** – Unsubscribes and disconnects 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. +These nanoflows and actions serve as the core building blocks for integrating devices into your Mendix applications and tailoring 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. +* **Station** – Contains the station name, computer name, workspace name, and client version (non-persistent entity). +* **Device** – Contains a list of devices associated with the station, including device names and properties required to establish connections (non-persistent entity). +* **AppKeyPair** – Stores the application's key pair (persistent entity). The public key must be configured in the corresponding app in Workstation Management. ### Using the Nanoflows and Actions -The following section provides more information about using the nanoflows and Java actions in your Mendix application. +The following section describes how to use the nanoflows and Java actions. #### 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. +Call `GetStation` to retrieve the configuration of the Client computer via the Workstation Client. `GetStation` can be called multiple times, but it queries the Workstation Client only on the first call. Subsequent calls return the current object loaded in the session. If the connection with the Workstation Client fails, `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. +Call `SendMessage` to send a message to a device. `SendMessage` provides an option to wait for the device's response within 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. +Call `SubscribeToMessages` to trigger a nanoflow when a message is received from a device. `SubscribeToMessages` provides an option to specify a context object that will be passed to the callback nanoflow whenever a message is received. -The callback nanoflow must have the following parameters: +The callback nanoflow must have the following parameters: -* `Device` (object) +* `Device` (Object) * `Message` (String) -* `Context object` (same as the name used when subscribing) +* `Context Object` (same as the name used when subscribing) #### SubscribeToErrors -Call `SubscribeToErrors` to trigger a nanoflow on device connection error. +Call `SubscribeToErrors` to trigger a nanoflow on device connection errors. -The callback nanoflow must have the following parameters: +The callback nanoflow must have the following parameters: -* `Device` (object) +* `Device` (Object) * `ErrorMessage` (String) * `ErrorCode` (Integer) -* `Context object` (same as the name used when subscribing) +* `Context Object` (same as the name used when subscribing) #### Unsubscribe @@ -140,31 +133,6 @@ Call `Unsubscribe` to end a subscription. 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 Client](/mendix-workstation/troubleshooting/). +Log files are available for troubleshooting issues with Workstation Management, the Client, and the Connector. For more information about accessing logs, see [Troubleshooting Mendix Workstation Client](/mendix-workstation/troubleshooting/). diff --git a/content/en/docs/workstation/wks-installation.md b/content/en/docs/workstation/wks-installation.md index 030a0033228..249a981f563 100644 --- a/content/en/docs/workstation/wks-installation.md +++ b/content/en/docs/workstation/wks-installation.md @@ -2,23 +2,26 @@ title: "Installing and Configuring Mendix Workstation Client" linktitle: "Installation and Configuration" url: /mendix-workstation/installation/ -description: "Documents the installation process for Mendix Workstation Client." +description: "Quick start and advanced guide for installing and configuring the Mendix Workstation Client, including setting up workspaces, stations, and devices for initial testing from the Workstation Management." weight: 20 --- ## Introduction -This document provides a quick start guide for installing Mendix Workstation Client, and then configuring its basic settings. Mendix Workstation Client is available for the following operating systems: +This document outlines the installation and basic configuration of the Mendix Workstation Client. It provides a quick-start guide for initial setup, followed by detailed instructions on advanced configurations for workspaces and stations. -* [Microsoft Windows (global installer)](https://marketplace.mendix.com/link/component/247448) -* [Microsoft Windows (portable)](https://marketplace.mendix.com/link/component/247456) -* [Linux ARM 64](https://marketplace.mendix.com/link/component/247459) +## Quick Start Guide -To configure Mendix Workstation Client, perform the following steps: +This guide helps you configure and test a minimum working version of the Mendix Workstation Client. By following these steps, you will complete the following: + +* Create a basic configuration within Workstation Management. +* Set up a pair of virtual TCP/IP Client and Server devices for testing. +* Install the Workstation Client on your computer. +* Verify the connection between your virtual devices directly from Workstation Management. ### Creating a Workspace and Station -A *station* represents a workstation on the shopfloor. It can connect to one or more apps or devices. A *workspace* is a grouping of one or more stations. For example, a workspace may group together all the stations which belong to the same factory or factory line. +A *station* represents a workstation on the shop floor. It can connect to one or more apps or devices. A *workspace* is a grouping of one or more stations. For example, a workspace may group together all the stations which belong to the same factory or factory line. 1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/) and sign in with your Mendix account. 2. In **Workspace Overview**, click **Create Workspace**. @@ -29,27 +32,27 @@ A *station* represents a workstation on the shopfloor. It can connect to one or {{< figure src="/attachments/workstation/wks-install2.png" class="no-border" >}} -3. After the workspace is created, in the **Stations** page, click **Create a New Station**. +4. After the workspace is created, in the **Stations** page, click **Create a New Station**. {{< figure src="/attachments/workstation/wks-install3.png" class="no-border" >}} -4. Enter a name for the station, and then click **Create Station**. +5. Enter a name for the station, and then click **Create Station**. {{< figure src="/attachments/workstation/wks-install4.png" class="no-border" >}} -5. Optional: If you do not want Workstation Management to detect smart card readers, in **Station** view, set the **Detect Card Readers** toggle to **Off**. +6. (Optional) To prevent Workstation Management from detecting smart card readers, set the **Detect Card Readers** toggle to **Off** in the **Station** view. {{< figure src="/attachments/workstation/wks-install16.png" class="no-border" >}} -## Downloading and Running the Workstation Client +### Downloading and Running the Workstation Client The Workstation Client is a connector between the devices and your local PC. You can download and enable the client by performing the following steps: -1. Open a station and click **Register Computer**. +1. Navigate to the **Station** you created above and click **Register Computer**. {{< figure src="/attachments/workstation/wks-install5.png" class="no-border" >}} -2. In the **Computer Registration** dialog, click **Download**. The [Workstation Client](https://marketplace.mendix.com/link/component/247448) page on the Mendix Marketplace opens for the Windows installer. Alternatively, you can find the component on the Mendix Marketplace by searching for "Workstation Client". You can also find the [portable](https://marketplace.mendix.com/link/component/247456) and [Linux](https://marketplace.mendix.com/link/component/247459) version by using the search, or navigate to them through the above links. +2. In the **Computer Registration** dialog, click **Download**. This will open the Mendix Marketplace page for the [Workstation Client Windows Installer](https://marketplace.mendix.com/link/component/247448). Alternatively, you can find the component on the Mendix Marketplace by searching for "Workstation Client". The [portable](https://marketplace.mendix.com/link/component/247456) and [Linux](https://marketplace.mendix.com/link/component/247459) versions are also available by searching the Marketplace or using the direct links provided. {{< figure src="/attachments/workstation/wks-install6.png" class="no-border" >}} @@ -57,23 +60,23 @@ The Workstation Client is a connector between the devices and your local PC. You * For Windows: - * If you have administrator rights for your computer, click **Download** and run the Workstation Client installer in the form of an NSIS installer package. If you get a prompt from Windows Access Control, click **Yes** to allow Workstation Client to be installed; for a silent installation, you can also run the installer as an administrator with the `/S` argument, that is, `MendixWorkstationX.Y.Z.exe /S`. The default installation folder is *C:\Program Files\Mendix Workstation*. The app data folder can be found at *C:\ProgramData\Mendix Workstation*. The client runs automatically after the installation is completed. - * If you do not have administrator rights for your computer, download the [Workstation Client Portable](https://marketplace.mendix.com/link/component/247456) instead. As a best practice, put the portable client in a new folder in your Documents folders, and then click the .exe file to run the client. + * If you have administrator rights for your computer, click **Download** and run the Workstation Client installer in the form of an NSIS installer package. If you get a prompt from Window's User Account Control, click **Yes** to allow Workstation Client to be installed; for a silent installation, you can also run the installer as an administrator with the `/S` argument, that is, `MendixWorkstationX.Y.Z.exe /S`. The default installation folder is *C:\Program Files\Mendix Workstation*. The app data folder can be found at *C:\ProgramData\Mendix Workstation*. The Client runs automatically after the installation is completed. + * If you do not have administrator rights for your computer, download the [Workstation Client Portable](https://marketplace.mendix.com/link/component/247456) instead. As a best practice, create a new folder (e.g., within your Documents directory) for the portable Client, and then run the .exe file from there. * For Linux: - * Download the [Linux](https://marketplace.mendix.com/link/component/247459) version of the Client - * Install: `sudo apt install ./workstation_X.X.X_arm64.deb` - * Install card reader dependencies: `sudo apt install pcscd libcap2-bin` + * Download the [Linux](https://marketplace.mendix.com/link/component/247459) version of the Client. + * Run the following command to install: `sudo apt install ./workstation_X.X.X_arm64.deb` (replace *X.X.X* with the actual version number of the downloaded .deb package). + * Install card reader dependencies with: `sudo apt install pcscd libcap2-bin` * Enable card reader dependencies: `sudo systemctl enable pcscd --now` - * Start the application from the applications menu > Accessories > Mendix Workstation - * Bluetooth support requires starting the application with `CAP_NET_RAW` privilege: `sudo capsh --user=$(whoami) --iab="^cap_net_raw" -- -c "'/opt/Mendix Workstation/Mendix Workstation'"` + * Start the application from the applications menu > Accessories > Mendix Workstation.<> + * Bluetooth support requires starting the application with `CAP_NET_RAW` privilege (for raw network packet access): `sudo capsh --user=$(whoami) --iab="^cap_net_raw" -- -c "'/opt/Mendix Workstation/Mendix Workstation'"` -## Registering your Computer +### Registering your Computer With the Workstation Client running on your computer, you must now register your computer in the Workstation Management. -1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/) and navigate to the **Station Overview** in the workspace which contains the station that you want to register to your computer. -2. Click the menu in the overview and select **Register computer**. +1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/) and navigate to the **Station Overview** within the workspace that contains the station you wish to register. +2. Click the ... (three-dot) menu associated with your station in the overview, and then select **Register computer**. Alternatively, click on the station to navigate to it's detail page and select **Register computer** within the *No computer registered* notification. 3. Click **Copy** to copy the registration token to your clipboard. {{< figure src="/attachments/workstation/wks-install7.png" class="no-border" >}} @@ -91,11 +94,11 @@ The **Stations** page now shows your station's status as **Computer Registered** {{< figure src="/attachments/workstation/wks-install10.png" class="no-border" >}} -## Configuring and Testing Virtual Devices +### Configuring and Testing Virtual Devices After registering your computer, test your connectivity by creating a pair of virtual devices: a TCP/IP server that will emulate a device, and a TCP/IP client that will connect to the emulated device. -### Creating a TCP/IP Server +#### Creating a TCP/IP Server 1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/). 2. In the **Station** page, click **Add Device**. @@ -111,7 +114,7 @@ The emulated device, a local TCP/IP server listening on port 1705, is added to t {{< figure src="/attachments/workstation/wks-install13.png" class="no-border" >}} -### Creating a TCP/IP Client +#### Creating a TCP/IP Client 1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/). 2. In the **Station** page, click **Add Device**. @@ -126,14 +129,14 @@ The emulated device, a local TCP/IP server listening on port 1705, is added to t The device, which will be used to connect to the TCP/IP server running in Workstation Client, is added to the **Devices** list in the **Station** page. -### Testing the Devices +#### Testing the Devices After configuring the server and client pair, test their connectivity by performing the following steps: 1. In the left navigation menu of the current workspace, click **Settings**, and ensure that the **Enable Local Device Testing** toggle is set to **On**. 2. In the left navigation menu, click **Test Your Station**. - The page refreshes and displays a list of all your devices. If you do not want the list to show any smart card readers available on your computer, make sure to set the **Detect Card Readers** toggle to **Off**. + The page refreshes and displays a list of all your devices. This includes detected smart card readers available on your computer if you did not disable detecting card readers as described [above](/mendix-workstation/installation/#creating-a-workspace-and-station) in step 6. 3. In your web browser, duplicate the tab where you have opened the **Test Your Station** page. 4. Arrange the two opened tabs so that you can view the two **Test Your Station** pages side by side. @@ -146,6 +149,112 @@ After configuring the server and client pair, test their connectivity by perform Different device types have different requirements for the message syntax. For more information, see [Message Syntax for File, Smart Card, and Bluetooth Devices](/mendix-workstation/device-syntax/). {{% /alert %}} -## Quitting the Workstation Client +### Quitting the Workstation Client + +The **Close** button closes the Client window but does not terminate the application; it continues to run in the background. To completely quit the Client, right-click its icon in the Windows systray and select **Quit**. This action is only available if [Developer Mode](/mendix-workstation/installation#developer-mode) is enabled. Alternatively, the Workstation Client process can always be stopped via Windows Task Manager. + +## Advanced Configurations + +### Workspace Apps + +It is crucial to configure the Mendix apps that are allowed to connect to the Workstation Client via the Workstation Connector. To do so, apps are managed on a workspace level and can be enabled or disabled for all stations in workspace, by station station groups, or individually per station. + +### Workspace Settings + +Navigate to the **Settings** page in a workspace to configure settings that are applied to all stations in that workspace. + +#### Log Settings + +The Workstation Client always stores logs to the file system it is installed on (c.f. [Troubleshooting - Workstation Client](/mendix-workstation/troubleshooting/#workstation-client)). No logs are send to the Workstation Management. However, you can configure the log level and retention policy of all the Workstation Clients that are registered to stations in the workspace. + +##### Log Level + +Configure the log level of the logs stored by the Workstation Client(s). + +* Info (default): Logs normal operation and key application events. For example, the time when the Client was launched or terminated. +* Warn: Info logs and potential issues or suboptimal conditions. For example, if a request to refresh the Client's configuration timed out. +* Error: Warning logs and visible problem, something is not working as expected. For example, if a port to connect to a device is already in use. +* Debug: Error logs and detailed internal state for developer diagnostics. For example, requests to the Workstation Management, communication with devices. + +#### Retention Policy + +Verbosity and thus log file size increases with each log level. To constrain this, the logs are limited to 10 MB in size and stored for 7 days by default. + +Modify these settings to the needs of your logging policy, especially if you require to keep debug level logs in production for retrospective troubleshooting. + +#### Local Device Testing + +By default, the Workstation Management is pre-configured as an allowed app to connect to the Workstation Client on the **Test your Station** page in a workspace. To disable this, navigate to the tab "Local Device Testing" on the **Settings** page and toggle it off. + + +### Workspace Team and Collaboration + +Note: Collaborating with other users in a workspace requires a Workstation license. + +Invite and manage members of a Workspace on the Team page. Only users who have signed into Workstation Management can be invited via email. One of the following roles can be assigned: + +* Owner - The owner has full rights to manage the workspace. They can read and edit configurations, manage the team, register computers, and manage workspace settings. They can also delete a workspace or transfer ownership to a new owner. By default, the user who created a workspace is assigned the owner role. Contact Mendix Support if a Workspace owner has left the company to transfer the ownership. +* Workspace admin - The workspace admin can manage the workspace in the same way as the owner, but they cannot delete the workspace or change its ownership. +* Station admin - Station admins can view and edit station configurations. They can also register computers to stations. They cannot manage any other settings. +* Computer admin - Computer admins can view configurations without editing them. They can also register computers to stations. +* View only - This role grants access to viewing the configuration but cannot perform any actions. + +All members but the Workspace owner can leave a workspace. + + +### Advanced Station Settings + +#### Station Developer Mode + +Developer mode can be configured on a **Station** page by toggling **Enable Developer Mode**. + +*Developer Mode* is enabled by default for each station. This allows users of the Workstation Client to +* quit the program from the start menu, +* unlink the Workstation Client so that it can be registered to another station, +* gives access to debug level live logs displayed in the **Logs** pane of the Workstation Client even if the workspace's log level is set to a different level, +* give access to developer tools (available by pressing *Ctrl + Shift + I*). + +For production environments, it is recommended to disable *Developer Mode* to prevent Workstation operators from accidentally quitting or unlinking the Workstation Client. + +#### Device Settings + +##### Card Readers + +Card reader devices cannot be configured as separate devices in the **Devices** overview of a **Station** page. Instead, they are automatically detected by the Workstation Client and added to the device list of the Client. + +Auto detecting card readers is enabled by default. This setting can be configured on a **Station** page by toggling **Detect Card Readers**. + +Refer to [Message Syntax - Card Readers](mendix-workstation/device-syntax/#card-readers) for a more in-depth explaination how to communicate with card readers. + +##### File Device + +This section explains the configuration of a file device. Refer to [Message Syntax - File Device](mendix-workstation/device-syntax/#file-device) for a more in-depth explaination how to communicate with file devices. + +###### 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 can perform actions. + +###### Environment Variable Support + +The system accepts environment variables in the allowed folder configuration within the Workstation Management interface. 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 of 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. + +##### Bluetooth Devices + +Simply add Bluetooth LE (BLE) devices that use the ATT protocol by entering the exact device name as displayed in your OS' device manager -The **Close** button closes the Client but does not stop it. The Client continues to run in the background. To quit the Client, right-click on its icon in the Windows systray, and then click **Quit**. +Refer to [Message Syntax - Bluetooth](mendix-workstation/device-syntax/#bluetooth) for a more in-depth explaination how to communicate with bluetooth devices. \ No newline at end of file diff --git a/content/en/docs/workstation/wks-message-syntax.md b/content/en/docs/workstation/wks-message-syntax.md index 39e0b2d7094..8ed1f9600d2 100644 --- a/content/en/docs/workstation/wks-message-syntax.md +++ b/content/en/docs/workstation/wks-message-syntax.md @@ -8,45 +8,45 @@ weight: 40 ## Introduction -To enable Mendix Workstation Client to communicate with your devices, you must ensure that the messages you send have the correct syntax. This syntax varies depending on the type of device. The following sections show the required syntax for file system, smart card, and Bluetooth devices. +For Mendix Workstation Client to communicate with devices, messages must use the correct syntax. This syntax varies depending on the device type. The following sections describe the required syntax for file system, smart card, and Bluetooth devices. ## Bluetooth -This device type requires the following message and response: +This device type uses the following message and response formats: ### Message -* `0#ServiceUUID#CharacteristicUUID` - Subscribe to characteristic `CharacteristicUUID` from service `ServiceUUID`. -* `1#ServiceUUID#CharacteristicUUID` - Unsubscribe from characteristic `CharacteristicUUID` from service `ServiceUUID`. -* `2#ServiceUUID#CharacteristicUUID` - Read characteristic `CharacteristicUUID` from service `ServiceUUID`. -* `3#ServiceUUID#CharacteristicUUID` - Write to characteristic `CharacteristicUUID` from service `ServiceUUID`. +* `0#ServiceUUID#CharacteristicUUID` – Subscribe to characteristic `CharacteristicUUID` from service `ServiceUUID`. +* `1#ServiceUUID#CharacteristicUUID` – Unsubscribe from characteristic `CharacteristicUUID` from service `ServiceUUID`. +* `2#ServiceUUID#CharacteristicUUID` – Read characteristic `CharacteristicUUID` from service `ServiceUUID`. +* `3#ServiceUUID#CharacteristicUUID` – Write to characteristic `CharacteristicUUID` from service `ServiceUUID`. ### Response * `CharacteristicUUID#Response` -## File System +## File Device -This device type requires the following message and response: +This device type uses the following message and response formats:   ### Message -* `0#Directory` - Watch for changes in `Directory`. If `Directory` is a file path, then watch for changes in the file. `Directory` is relative to the folder configured in Workspace management. Environment variables (for example, `%public%`) are supported. -* `1#Directory` - Stop watching for changes in `Directory`.   -* `2#File path` - Read file at `File path`. -* `3#File path#Data#flag` - Write to file at `File path`. The `flag` can be `w` for overwrite, `a` for append If left blank, the value defaults to `w`. +* `0#Directory` – Watch for changes in `Directory`. If `Directory` is a file path, watch for changes in that file. `Directory` is relative to the folder configured in Workstation Management. Environment variables (such as `%public%`) are supported. +* `1#Directory` – Stop watching for changes in `Directory`. +* `2#File path` – Read file at `File path`. +* `3#File path#Data#flag` – Write to file at `File path`. The `flag` can be `w` for overwrite or `a` for append. If left blank, the value defaults to `w`. ### Response -* `R#File name` - `File name` was renamed (also triggered when file is created and deleted) -* `C#File name` - `File name` was changed -* `D#Data` - `Data` from file read -* `E#Error` - `Error` message from operating system -* `S#{0,1,2,3}#directory` - The command `{0,1,2,3}` on `directory` was successful. +* `R#File name` – `File name` was renamed (also triggered when the file is created or deleted). +* `C#File name` – `File name` was changed. +* `D#Data` – `Data` from file read operation. +* `E#Error` – `Error` message from operating system. +* `S#{0,1,2,3}#directory` – The command `{0,1,2,3}` on `directory` was successful. ### Example Test -The section below shows a sample test that you can run to verify the configuration. +The following example demonstrates how to test the file device configuration: 1. Create a new Workspace in the Workstation Management. 2. Create a new Station. @@ -59,18 +59,18 @@ The section below shows a sample test that you can run to verify the configurati 5. In your Workspace, navigate to **Test Your Station** and click on the configured file device. 6. Enter `3#test.txt#Hello from Mendix` in the **Send Message** field, and then press **Send Message**. - The test should show a response like `S#3#C:\MyTestFolder\test.txt` to indicate that the text file *test.txt* was succesfully written to *MyTestFolder*. + The test should show a response like `S#3#C:\MyTestFolder\test.txt` to indicate that the text file *test.txt* was successfully written to *MyTestFolder*. 7. Go to *C:\MyTestFolder* and verify that it contains the text file. 8. Open the test file and verify that it contains the text *Hello from Mendix*. -## Smart Cards +## Card Readers -This device type requires the following message and response: +This device type uses the following message and response formats: ### Message -Send instruction in hexadecimal as a string, for example, *FFCA000000*. The messages exchanged with the smart card are APDU messages. For more information, refer to the documentation of the APDU command for your smart card reader. +Send instruction in hexadecimal as a string, for example `FFCA000000` to read the smart card ID. The messages exchanged with the smart card are APDU messages. For more information, refer to the documentation of the APDU command for your smart card reader. ### Response diff --git a/content/en/docs/workstation/wks-prerequisites.md b/content/en/docs/workstation/wks-prerequisites.md index 40220663c29..4e11ffafe73 100644 --- a/content/en/docs/workstation/wks-prerequisites.md +++ b/content/en/docs/workstation/wks-prerequisites.md @@ -8,46 +8,61 @@ weight: 10 ## Introduction -This document presents the system requirements for Mendix Workstation Client. +This document describes the system requirements for Mendix Workstation Client. ## System Requirements -* Operating System - Windows 10 or Windows 11 (64-bit); Linux ARM64 -* Memory - Minimum 4 GB RAM (8 GB recommended for optimal performance) -* Disk Space - 400 MB of free disk space for installation +* **Operating System** – Windows 10 or Windows 11 (64-bit); Linux ARM64 +* **Memory** – Minimum 4 GB RAM (8 GB recommended for optimal performance) +* **Disk Space** – 400 MB free space for installation + +Mendix Workstation Client can be downloaded from the Mendix Marketplace: + +* [Microsoft Windows (global installer)](https://marketplace.mendix.com/link/component/247448) +* [Microsoft Windows (portable)](https://marketplace.mendix.com/link/component/247456) +* [Linux ARM 64](https://marketplace.mendix.com/link/component/247459) ## Access Requirements * A Mendix account -* Access to the Mendix Workstation Management for configuration +* Access to Mendix Workstation Management for configuration ## Network Configuration Before implementing Mendix Workstation Client, perform the following steps: 1. Ensure that the Workstation user can access the Mendix Cloud. -2. Open the required ports for communication (for example, TCP 443 for HTTPS). -3. Add the Workstation Client to the Allow list for any firewall or antivirus software, if applicable. +2. Open the required ports for communication (such as TCP 443 for HTTPS). +3. Add the Workstation Client to the Allow list for any firewall or antivirus software, as needed. + +### Custom Certificates and Proxy Settings + +The Workstation Client uses the operating system's certificates and proxy environment variables to establish a connection with Workstation Management. In most controlled corporate environments, these settings are preconfigured on employee computers by IT departments. + +To use a custom proxy configuration, you must start the Workstation Client from the command line and set the environment variables as described [here](https://github.com/nodejs/undici/blob/main/docs/docs/api/EnvHttpProxyAgent.md#class-envhttpproxyagent). For example, from the Windows Command Prompt: +``` +set HTTPS_PROXY=[PROXY_IP_ADDRESS] && "C:\Program Files\Mendix Workstation\Mendix Workstation.exe" +``` ## Device Connectivity -Before connecting devices with Mendix Workstation Client perform the following steps: +Before connecting devices to Mendix Workstation Client, complete the following steps: -* Make sure the devices are correctly set up and connected to your computer. -* Verify that the device driver is installed and up to date. -* Take a note of the connection parameters used by the devices: +* Ensure the devices are correctly set up and connected to your computer. +* Verify that device drivers are installed and up to date. +* Note the connection parameters used by the devices: - * For Serial Port connection - baud rate, data bits, parity and stop bits, flow control. - * For TCP/IP connection - IP address and port. + * For Serial Port connection – baud rate, data bits, parity and stop bits, flow control + * For TCP/IP connection – IP address and port -* Obtain the manual and technical documentation for your devices, including chapters describing the communication protocol and how to configure it. -* Test the connection and protocol on your operating system using the tool recommended in the device technical documentation or using common tool such as PuTTY. - * For Serial Port connection - Open the device and test device basic commands. - * For TCP/IP connection - Ping the device to make sure that it is reachable on the network and not blocked by a firewall, and then test the basic device commands. +* Obtain manuals and technical documentation for your devices, including chapters describing the communication protocol and configuration instructions. +* Test the connection and protocol on your operating system using the tool recommended in the device technical documentation or using a common tool such as PuTTY: + * For Serial Port connection – Open the device and test basic device commands + * For TCP/IP connection – Ping the device to verify it is reachable on the network and not blocked by a firewall, then test basic device commands -## Best Practices for Working with Mendix Workstation Client +## Best Practices -As you begin your work with Mendix Workstation Client, keep in mind the following best practices to help you. +When working with Mendix Workstation Client, follow these best practices. ### Security Recommendations diff --git a/content/en/docs/workstation/wks-security.md b/content/en/docs/workstation/wks-security.md index ed0d93ce58f..4df32b44c23 100644 --- a/content/en/docs/workstation/wks-security.md +++ b/content/en/docs/workstation/wks-security.md @@ -8,44 +8,44 @@ weight: 15 ## Introduction -Security is one of the most important aspects of a deployment, because misconfiguration or failing security can have large consequences. The Mendix Workstation Client gives many configuration options for permissions that can have an impact on the security of your deployment. +Security is critical for deployments, as misconfigurations or security failures can have serious consequences. Mendix Workstation Client provides numerous configuration options that can impact the security of your deployment. -This document describes the common aspects you should consider when deploying the Mendix Workstation Client in production. +This document describes the security aspects you should consider when deploying Mendix Workstation Client in production. ## Assignment of Workspace Roles {#workspace-roles} -Workspace roles should be assigned following the principle of least privilege. Always grant users the minimum permissions necessary for them to successfully complete their tasks. You can reassign the roles at any time if responsibilities change. To help maintain a secure deployment, consider the following guidelines: +Workspace roles should be assigned following the principle of least privilege. Always grant users only the minimum permissions necessary to complete their tasks. You can reassign roles at any time if responsibilities change. To maintain a secure deployment, follow these guidelines: -* Assign the View Only role to untrusted users. -* Use caution when granting the Workspace Admin role. - * Workspace Admins can unintentionally disrupt production, for example by deleting an app or modifying its public key. +* Assign the **View Only** role to untrusted workspace users. +* Use caution when granting the **Workspace Admin** role: + * Workspace Admins can unintentionally disrupt production, such as by deleting an app or modifying its public key. * Workspace Admins can allow Workstation Clients to access malicious apps. -* Conduct regular permissions audits to make sure that temporary privilege elevations are reverted once they are no longer necessary. +* Conduct regular permissions audits to ensure that temporary privilege elevations are reverted once they are no longer necessary. -## Station Set Up {#setup-stations} +## Station Setup {#setup-stations} -Setting up stations involves a variety of options, some of which have important security implications. To help ensure a secure deployment, follow these best practices: +Setting up stations involves various options with important security implications. To ensure a secure deployment, follow these best practices: -* Keep stations lean by disabling unused apps and deleting unused devices. - * Any unused device represents a potential attack surface (for example, a forgotten card reader that leaks a token, or a TCP device that exposes a device on the network). - * Any unused but enabled app may gain unintended access to devices that were not meant to be exposed to it. -* Verify that all devices configured on a station are safe for all enabled applications. +* Keep stations lean by disabling unused apps and removing unused devices: + * Any unused device represents a potential attack surface (such as a forgotten card reader that leaks a token, or a TCP device that exposes a device on the network). + * Any enabled but unused app may gain unintended access to devices not intended for that app. +* Verify that all devices configured on a station are safe for all enabled applications: * Devices are shared across all applications in a station. If a device should not be accessible by a particular app, it should not be present on that station. -* Configure File devices carefully. +* Configure File devices carefully: * File devices are powerful and can pose security risks if misconfigured. * Restrict the allowed folder and permissions as much as possible. The Workstation Client enforces these restrictions within the allowed folder and its subfolders. ## Access Restrictions for the Configuration Folder on Microsoft Windows {#config-access} -By default, the Windows global installer for the Workstation Client grants the **BUILTIN\Users** Windows user group read and write access to the *ProgramData/Mendix Workstation* folder. This configuration is safe in most cases. However, for highly sensitive environments, you may want to restrict write access for the built-in Users group, and instead delegate permissions to a different group. +By default, the Windows global installer for the Workstation Client grants the **BUILTIN\Users** Windows user group read and write access to the *ProgramData/Mendix Workstation* folder. This configuration is safe in most cases; however, for highly sensitive environments, you may want to restrict write access for the built-in Users group and delegate permissions to a different group. ### Why Restrict the Users Group? The **BUILTIN\Users** group includes all standard user accounts on the system. Restricting its write access helps prevent the following: -* Compromised accounts modifying configuration files -* Unauthorized users deregistering the station, temporarily halting production +* Compromised accounts from modifying configuration files +* Unauthorized users from deregistering the station, temporarily halting production -By delegating permissions to a more tightly controlled group, you ensure that only authorized accounts have the ability to modify the configuration and to use the Workstation Client. +Delegating permissions to a more tightly controlled group ensures that only authorized accounts can modify the configuration and use the Workstation Client. -To delegate permissions to a custom group, create a new Windows user group and grant it the same permissions to the *C:\ProgramData\Mendix Workstation* folder as are currently held by the Users group. After that, you can remove the Users group or adjust its permissions as needed. For more information about managing groups and permissions, refer to Microsoft Windows documentation. +To delegate permissions to a custom group, create a new Windows user group and grant it the same permissions for the *C:\ProgramData\Mendix Workstation* folder currently held by the Users group. Then you can remove the Users group or adjust its permissions as needed. For more information about managing groups and permissions, refer to the Microsoft Windows documentation. diff --git a/content/en/docs/workstation/wks-troubleshooting.md b/content/en/docs/workstation/wks-troubleshooting.md index 54d59587f5f..5ec6ea13916 100644 --- a/content/en/docs/workstation/wks-troubleshooting.md +++ b/content/en/docs/workstation/wks-troubleshooting.md @@ -8,13 +8,13 @@ weight: 40 ## Introduction -If you encounter any issues with your Workstation Management, Connector, or Client, use the following troubleshooting tips to help you solve them. +If you encounter issues with Workstation Management, the Connector, or the Client, use the following troubleshooting steps to resolve them. ## Workstation Management ### Station Status of Unlinked Workstation Client Is Still "Computer Registered" -This issue might occur if your Workstation Client could not establish a connection to the Workstation Management, for example, because the computer was not connected to a network. +This issue may occur if the Workstation Client cannot establish a connection to Workstation Management, such as when the computer is not connected to a network. #### Solution @@ -22,19 +22,26 @@ Manually unregister the station in Workstation Management. ### Workspace Owner Account Deactivated -The Workspace's owner account has been deactivated and the owner did not transfer the ownership to another Workspace member. +The workspace owner's account has been deactivated, and the owner did not transfer ownership to another workspace member. #### Solution -Raise a ticket to support to transfer Workspace ownership. +Contact Mendix Support to transfer workspace ownership. ## Workstation Client -The Client retains logs for the last eight days. You can access the logs by clicking the **Logs** button on the Client UI, and then optionally selecting the level of logs that you want to see. Opening the client's console through the browser developer tools (**Ctrl + Shift + I**) can also provide additional information about encountered errors in the UI of the Client. +By default, the Client retains logs of up to 10 MB for the past seven days locally on your computer. Access logs by clicking the **Logs** button on the Client UI, then optionally selecting the level of logs you want to see. Opening the Client's console through the browser developer tools (**Ctrl + Shift + I**) can also provide additional information about encountered errors in the UI of the Client. -You can also find log files by day in the Client's app data folder. To do so on Windows, press **Win + R**. If you installed the Client using the installer for all users, enter `%ProgramData%\Mendix Workstation\logs`. If you are using the portable version, enter `%AppData%\Mendix Workstation\logs`. On Linux the Mendix *Workstation/logs* folder is either located at `$XDG_CONFIG_HOME` or `~/.config`. +Log files are also available by day in the Client's app data folder. On Windows, press **Win + R** and enter: -Alternatively, you can start the Workstation Client from Powershell to view logs: `start "C:\Program Files\Mendix Workstation\Mendix Workstation.exe" -ArgumentList "--log-level=debug" -wait`. +* If you installed the Client using the installer for all users: `%ProgramData%\Mendix Workstation\logs` +* If you are using the portable version: `%AppData%\Mendix Workstation\logs` + +On Linux, the *Mendix Workstation/logs* folder is located at either `$XDG_CONFIG_HOME` or `~/.config`. + +**Live logs** are available in two ways: +* Start the Workstation Client. Click the three-dot icon in the top tight, then click **Logs**. Debug level logs are only available in *Developer Mode* +* Start the Workstation Client from PowerShell: `start "C:\Program Files\Mendix Workstation\Mendix Workstation.exe" -ArgumentList "--log-level=debug" -wait`. ### Registration Token Could Not Be Parsed @@ -42,11 +49,11 @@ The Client shows an error like the following: *Registration token could not be p #### Cause -You entered a registration token with an invalid format. +The registration token has an invalid format. #### Solution -Ensure that you copied and pasted the token as displayed by the management and that you did not enter additional characters by accident. Create a new registration token if the issue persists. +Ensure you copied and pasted the token exactly as displayed in Workstation Management without any additional characters. Create a new registration token if the issue persists. ### Registration Token Denied by Workstation Management @@ -54,11 +61,15 @@ The Client shows an error like the following: *Register token denied by Workstat #### Cause -The registration token is no longer valid because it has either expired after one hour, the token was recreated in the Management application (using the **Refresh** button or reopening the registration window) or the token has already been used by another Workstation Client. +The registration token is no longer valid. This can occur if: + +* The token expired after one hour +* The token was recreated in Workstation Management (using the **Refresh** button or reopening the registration window) +* The token has already been used by another Workstation Client #### Solution -If the status of the Station displayed in the Management is still *No computer registered*, regenerate the token and try again. Otherwise, check if the correct computer and Client is registered to that station and unregister it if not. +If the station status in Workstation Management is still *No computer registered*, regenerate the token and try again. Otherwise, verify the correct computer and Client are registered to that station and unregister if not. ### Access Denied by Workstation Management @@ -66,29 +77,65 @@ The Client shows an error like the following: *Station could not be synchronized #### Cause -This error occurs if the credentials provided by the Workstation Client are no longer valid, for example, if it got deregistered in the Management or if the APIKey is expired. +This error occurs when the credentials provided by the Workstation Client are no longer valid, such as when it was deregistered in Workstation Management or the API key has expired. #### Solution -You can continue using the Workstation Client with the current configuration, but it will no longer receive updates. To fix this, press **Unlink** in the Workstation Client and then re-register the workstation. +You can continue using the Workstation Client with the current configuration, but it will no longer receive updates. To resolve this, click **Unlink** in the Workstation Client, then re-register the workstation. + +### HTTPError: Request failed with status code 503 Service Temporarily Unavailable + +The Client shows an error like the following: *Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': HTTPError: Request failed with status code 503 Service Temporarily Unavailable: GET.* + +#### Cause + +Workstation Management is temporarily offline, most likely due to maintenance. + +#### Solution + +Check out the [Mendix Status Page](https://status.mendix.com/) to see if there is a scheduled maintenance for the Workstation Management. If there is no maintenance message and the issue persists after a few minutes, report an incident via the status page. + +### TimeoutError: Request timed out + +The Client shows an error like the following: *Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': TimeoutError: Request timed out: GET [yourStationURL]* + +#### Cause + +The Client request to Workstation Management is not forwarded to the Workstation Management server and times out. This issue may occur if your network traffic is routed through a proxy server, as is common in protected corporate IT environments, and the proxy server is offline. + +#### Solution + +Verify whether your computer's network traffic is routed through a proxy server and configure your proxy settings accordingly. See [Network Configuration](/mendix-workstation/prerequisites/#network-configuration). + +### Workstation Management URL cannot be resolved + +The Client shows an error like the following: *Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': Error: Workstation Management URL cannot be resolved. This might be an DNS issue or the host is offline.* + +#### Cause + +The Client cannot resolve the URL to Workstation Management. This can have several causes, most commonly when the machine running the Workstation Client has no internet connection. + +#### Solution + +First, verify you have a working internet connection. Then verify you can access [Workstation Management](https://workstation.home.mendix.com/) from your browser. If your browser cannot resolve that address, there may be an issue with your DNS server or configuration. On Windows, verify your DNS settings for your Ethernet or wireless LAN adapter using the command prompt and entering `ipconfig`. The command `nslookup www.mendix.com` provides further information about the IP address your DNS server resolved for the Mendix domain. ## Workstation Connector -Logs for the Connector can be found in Studio Pro's console during local development or within the environment logs of your running environment. Since the Connector performs most operations client-sided in nanoflows, you can also inspect the local logs that can be found in the browser console. +Connector logs are available in Studio Pro's console during local development or in the environment logs of your running environment. Since the Connector performs most operations client-side in nanoflows, you can also inspect local logs in the browser console. ### Workstation Client Did Not Respond Within 3 Seconds. Connection Failed. -If the **StationConnector.GetStation** nanoflow fails to connect to your Workstation Client, this error log message is visible in the browser console and in the Studio Pro's Console on the **Client_Nanoflow** log node. +If the **StationConnector.GetStation** nanoflow fails to connect to the Workstation Client, this error appears in the browser console and in Studio Pro's Console on the **Client_Nanoflow** log node. #### Cause -The connection between the Client and the Connector cannot be established either because the Workstation Client cannot be found on the local computer or the current application is not allowed to establish a connection. +The connection between the Client and Connector cannot be established. This occurs either because the Workstation Client cannot be found on the local computer, or because the current application is not allowed to establish a connection. #### Solution -* Verify that the Workstation Client is running and registered on the same computer as the browser that is trying to establish a connection via the StationConnector. -* Verify that the Client is registered in the correct Workspace by comparing the Workspace name and ID displayed in the Client UI with the Workspace in the Management. -* Verify that the application that is attempting a connection is properly configured as an allowed app in the Workspace and on the Station. To do so check that your application, for example, running on `http://localhost:8080`, is added in the **Apps** section of your Workspace. If the app is added, check that the public key of the configured workspace app is up to date with the public key displayed in your app that is using the connector. If not, update the public key value of the workspace app with the latest value displayed in the app. Next, check that the app is also enabled as an allowed app in the Station configuration by going to the respective Station detail page in that workspace. Always press the **Refresh** button in the Workstation Client after applying any changes in the Management. +* Verify the Workstation Client is running and registered on the same computer as the browser attempting to connect via the StationConnector. +* Verify the Client is registered in the correct workspace by comparing the workspace name and ID displayed in the Client UI with the workspace in Workstation Management. +* Verify the application attempting to connect is properly configured as an allowed app in the workspace and on the station. To do so, check that your application (such as `http://localhost:8080`) is added in the **Apps** section of your workspace. If the app is added, verify the public key of the configured workspace app matches the public key displayed in your app using the Connector. If not, update the public key value of the workspace app with the latest value displayed in the app. Next, verify the app is also enabled as an allowed app in the station configuration by navigating to the respective station detail page in that workspace. Always click the **Refresh** button in the Workstation Client after applying any changes in Workstation Management. ### The Client Requested a Session for a Time That Is Ahead of the Server @@ -96,20 +143,20 @@ This is a warning log for the Mendix runtime on the **StationConnector - GetWebs #### Cause -For security reasons, the Connector only allows the time of the computer running the Workstation Client to be 24 hours behind the Mendix runtime server that hosts the app before establishing a session. +For security reasons, the Connector only allows establishing a session when the computer running the Workstation Client has a time within 24 hours of the Mendix runtime server hosting the app. #### Solution -Change the time of the computer running the Workstation Client to be within 24 hours of the Mendix runtime server. If that is not an option, you can customize this yourself in the **StationConnector.GetWebsocketsSession** microflow, but must maintain this setting after updating the module to a newer version. +Set the time on the computer running the Workstation Client to within 24 hours of the Mendix runtime server. If this is not possible, you can customize this behavior in the **StationConnector.GetWebsocketsSession** microflow, but you must maintain this customization when updating the module to a newer version. ### Context Entity Is Not Updated After Sending a Message -The Context Entity on your page is not getting updated after sending a message. More specifically, modifying a context entity shortly after sending a message for the first time does not always work. +The context entity on your page is not updated after sending a message. Specifically, modifying a context entity shortly after sending a message for the first time does not always work. #### Cause -Sending a message for the first time sets the Connected state to true and triggers a commit on the device. This in turn refreshes the device and all data sources that are nested within a device data source. Some of these data sources may create a new blank entity instead of showing the updated entity. +Sending a message for the first time sets the **Connected** state to **true** and triggers a commit on the device. This refreshes the device and all data sources nested within a device data source. Some of these data sources may create a new blank entity instead of displaying the updated entity. #### Solution -Make sure that all data sources nested within a device data source follow a Singleton (also: GetCreate) pattern, where an entity is created if it does not exist and retrieved if it does. +Ensure all data sources nested within a device data source follow a Singleton (also known as GetCreate) pattern, where an entity is created if it does not exist or retrieved if it does.