diff --git a/content/en/docs/releasenotes/workstation/_index.md b/content/en/docs/releasenotes/workstation/_index.md index e497733841b..38438b7539f 100644 --- a/content/en/docs/releasenotes/workstation/_index.md +++ b/content/en/docs/releasenotes/workstation/_index.md @@ -148,7 +148,7 @@ For more information, see [Nanoflows](/mendix-workstation/build-app/#javascript- #### New Features -* Enhanced bulk registration process - We have improved the bulk registration experience to make managing multiple workstations even more efficient and intuitive. +* Enhanced bulk registration process - We have improved the bulk registration experience to make managing multiple stations even more efficient and intuitive. * New unassigned stations list - If a newly registered station cannot be automatically matched with a preconfigured station, it now appears in the new **Unassigned Stations** list. Before you can edit these unassigned stations, you must first either accept or manually assign them, giving you better control over station assignments. * Code snippet copier - To simplify the registration process from the terminal, we have added a convenient code snippet copier, making the process quicker and less prone to errors. @@ -194,7 +194,7 @@ For more information, see [Nanoflows](/mendix-workstation/build-app/#javascript- #### New Features -* Automatic suffixing for duplicate workstations - To make managing your workstations even smoother, we have implemented automatic suffixing for imported workstations that have duplicate names. This helps prevent naming conflicts and keeps your environment tidy. +* Automatic suffixing for duplicate stations - To make managing your stations even smoother, we have implemented automatic suffixing for imported stations that have duplicate names. This helps prevent naming conflicts and keeps your environment tidy. * Feedback module replaced by the new Forum Space - We have removed the Feedback function in the Workstation Management. Don't worry, your voice is still incredibly important to us! Please share your questions, ideas, and feedback in the new dedicated [Mendix Forum Space for Mendix Workstation](https://community.mendix.com/link/spaces/mendix-workstation-client). This change will help us centralize discussions and provide better support. * Special characters in Workspace names - You can now use special characters in your Workspace names, giving you more flexibility and personalization. * Unique auto-accepted computer names - We have added a uniqueness validation to the **Auto-Accepted Computer Name** field used for bulk registration. This ensures that each computer name is distinct, preventing potential conflicts during the registration process. diff --git a/content/en/docs/workstation/_index.md b/content/en/docs/workstation/_index.md index 6f02bbf3f6f..556e5236240 100644 --- a/content/en/docs/workstation/_index.md +++ b/content/en/docs/workstation/_index.md @@ -11,31 +11,20 @@ cascade: ## Introduction -Mendix Workstation is designed to help you build smarter, faster, and more operator-friendly applications for shop floor 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 helps you build applications for shop floor operators. It enables Mendix applications to directly interact with peripheral devices on a local workstation, without relying on 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, smart card 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 allows Mendix apps to communicate in near real-time with devices like printers, barcode scanners, smart card readers, and industrial scales. This setup 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. -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 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 equipment in a controlled and secure manner. -## Licensing Mendix Workstation - -Mendix Workstation is [Limited Availability](/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 Mendix Workstation into production, contact your CSM to see what arrangements are possible. Without a license you can use Mendix Workstation for development, but workspaces are individual and cannot be shared. - -The following functionalities are only available with a license: - -* [Bulk import of stations](/mendix-workstation/import-export/) -* [Bulk registration of Workstation Clients](/mendix-workstation/register/) -* [Inviting users](/mendix-workstation/build-app/#invite-users) - -## Features of Mendix Workstation +## Capabilities Overview Mendix Workstation has the following features: -* Direct local device access - Mendix Workstation 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. +* Enables Mendix applications to communicate with local devices without routing through a central server, network overload, or any additional intermediate systems. +* Uses Mendix nanoflows to handle interactions with the local PC, such as sending and receiving on-event messages. * Supports multiple interfaces: * PCSC (smart card Reader) - APDU protocol @@ -46,18 +35,9 @@ Mendix Workstation has the following features: * Can emulate and simulate interfaces. -## Benefits of Using Mendix Workstation +### Use Cases -* 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. - -## Use Cases - -Mendix Workstation can be used to create apps that handle use cases such as the following: +You can use Mendix Workstation to create apps that handle use cases such as the following: * Printing labels on an industrial thermal label printer (for example, a Zebra printer) * Badge operators with an NFC smart card reader and PC/SC specification @@ -65,39 +45,35 @@ Mendix Workstation can be used to create apps that handle use cases such as the * Weighing materials with an industrial scale (for example, a Mettler Toledo SICS-compatible scale) * Connected smart tools (for example, screwdrivers with torque control) -## Components of Mendix Workstation - -Mendix Workstation consists of the following components: - -* [Workstation Management](https://workstation.home.mendix.com/) - Allows centralized configuration. -* [Workstation Client](https://marketplace.mendix.com/link/component/247448) - Allows real-time communication with local hardware. -* [Workstation Connector](https://marketplace.mendix.com/link/component/247460) - Allows app integration. +### Benefits -Together, these components enable Mendix applications to securely and efficiently integrate with local devices, bridging the gap between digital workflows and physical operations. +Using Mendix Workstation offers the following benefits for your organization: -### Architecture Diagram - -{{< figure src="/attachments/workstation/WorkstationDiagram.png" class="no-border" >}} +* It improves operator user experience and efficiency by enabling Mendix applications to directly interact with devices on a local workstation. +* It allows for the renovation of home-grown applications and gaining control over legacy systems by providing a modern platform for Mendix applications to connect directly to existing devices. +* It helps keep core systems clean by allowing Mendix applications to communicate with devices without routing through any additional intermediate systems. +* It enables the creation of apps adapted to the operator's job with the exact devices they use, instead of forcing the operator to adapt their job to generic software limitations. +* It gives you the means to compose new forms of user experience tailored to manufacturing processes, equipment and environment, so that your applications can seamlessly integrate with new physical tools and processes on the shop floor. +* It facilitates expansion to adjacent users and domains and helps cross boundaries between silos by enabling deployment across multiple environments and sites. -### Workstation Management (Mendix Service) +## Key Components -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. - -This makes it easier to manage a large, diverse fleet of devices without the need for manual setup or on-site support. +Mendix Workstation consists of the following components: -### Workstation Client (Native Application) +* [Workstation Management](/mendix-workstation/management/) - Allows centralized configuration. +* [Workstation Client](/mendix-workstation/client/) - Allows real-time communication with local hardware. +* [Workstation Connector](/mendix-workstation/connector/) - Allows app integration. -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. +{{< figure src="/attachments/workstation/WorkstationDiagram.png" class="no-border" >}} -### Workstation Connector (Mendix Module) +## Licensing Mendix Workstation -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. +Mendix Workstation is [Limited Availability](/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 Mendix Workstation into production, contact your CSM to see what arrangements are possible. Without a license you can use Mendix Workstation for development, but workspaces are individual and cannot be shared. -The connector handles the following tasks: +The following functionalities are only available with a license: -* Retrieving local station configuration (name and device list) -* Connecting and disconnecting devices -* Exchanging messages with devices -* Subscribing for triggering app logic on event when receiving messages from a device +* [Bulk import of stations](/mendix-workstation/import-export/) +* [Bulk registration of Workstation Clients](/mendix-workstation/register/) +* [Inviting users](/mendix-workstation/build-app/#invite-users) ## Read More diff --git a/content/en/docs/workstation/management/_index.md b/content/en/docs/workstation/management/_index.md new file mode 100644 index 00000000000..de55a939ae1 --- /dev/null +++ b/content/en/docs/workstation/management/_index.md @@ -0,0 +1,25 @@ +--- +title: "Mendix Workstation Management" +linktitle: "Workstation Management" +url: /mendix-workstation/management/ +description: "Provides an overview of Mendix Workstation Management." +no_list: false +description_list: true +weight: 30 +--- + +## Introduction + +[Workstation Management](https://workstation.home.mendix.com/) is a tool for overseeing and optimizing Mendix Workstation deployments across your organization. Tailored for central IT and application support teams, this Mendix Platform service offers a centralized interface to streamline the configuration, monitoring, and troubleshooting of all Workstation Clients and their connected devices. + +This document provides an overview of every facet of Workstation Management, so that you can discover how to perform initial setup, manage user access and roles, configure various device types with precise control, and implement robust monitoring and logging strategies. By mastering these functionalities, you can ensure seamless operation, enhance efficiency, and provide reliable support for your Mendix Workstation ecosystem, regardless of its scale or geographical distribution. + +## Basic Concepts + +For more information about the terms used in this document, such as *station* or *device*, refer to the [Mendix Workstation glossary](/mendix-workstation/glossary/). + +## Users + +Workstation Management is used by central IT and application support teams. + +## Read More diff --git a/content/en/docs/workstation/management/wks-management-admin.md b/content/en/docs/workstation/management/wks-management-admin.md new file mode 100644 index 00000000000..f74c39e716b --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-admin.md @@ -0,0 +1,113 @@ +--- +title: "Managing Stations" +linktitle: "Stations" +url: /mendix-workstation/management-stations/ +description: "Describes the administration of stations in Mendix Workstation Management." +weight: 50 +--- + +## Introduction + +The **Stations** page displays a comprehensive overview of all your configured stations. This page provides quick insights into the status of each station and offers various actions for creation, management, and bulk operations. + +{{< figure src="/attachments/workstation/wks-stations1.png" class="no-border" >}} + +## Station Status Indicators + +The overview page displays the current status of each station, helping you quickly identify any issues or pending actions: + +* **No computer registered** - The station has been created in Workstation Management, but no physical computer running the Workstation Client has been linked to it yet. +* **Computer registered** - A Workstation Client on a physical computer is successfully registered and actively linked to this station. +* **Client's config is out of sync** - The configuration defined in Workstation Management for this station has changed, but the Workstation Client on the registered computer has not yet received or applied these updates. This can happen if auto-refresh is disabled or if there's a temporary connectivity issue. +* **Unknown computer** - The Workstation Client on the registered computer is reporting an unrecognized identifier, or there's an issue with its registration. +Error while registering: An error occurred during the attempt to register a Workstation Client to this station. Further investigation (for example, checking client logs) may be required. + +## Creating a New Station + +To create a new station, choose one of the following options, depending on your deployment scenario. + +### Creating a Station from Scratch + +To create a station from scratch, perform the following steps: + +1. Click **Create Station**. +2. Provide a unique **Station Name**. + + The name is a mandatory identifier for your station. + +3. Optional: Add a station group to organize your stations (for example, by location, department, or function). +4. Optional: Specify an **Auto-Accepted Computer Name**. + + If provided, during a bulk registration process, any Workstation Client reporting this computer name are automatically mapped and registered to this specific station, streamlining large-scale deployments. + +### Creating a Station from Clipboard + +If you have previously copied the configuration of an existing station (for example, from another workspace or for duplication purposes), you can use the **Create Station from Clipboard** option to paste and create a new station based on that data. + +### Create Station from File + +This option allows you to import a station's configuration from a previously exported file. This is particularly useful for migrating or replicating single station configurations. + +## Exporting and Importing Stations + +Workstation Management provides robust features for managing stations in bulk, facilitating migration, backup, and replication tasks. + +* **Export Stations** - Export all stations in the current workspace, or select specific stations from the overview list to export only those you need. +* **Import Stations** - When importing stations from a file, you have fine-grained control over how duplicates are handled: + + * **Ignore** - If a station with the same identifier already exists, the imported station will be skipped. + * **Duplicate** - A new station will be created, even if one with the same identifier already exists, resulting in a duplicate entry. + * **Replace** - The existing station with the matching identifier will be completely overwritten by the imported station's data. + * **Merge** - The imported station's data will be intelligently merged with the existing station's configuration, updating fields where there are differences. + +The import process allows you to specify what information to include: + +* **Include Apps** - Specify whether to include the associated Mendix applications configured for the imported stations. +* **Include Devices** - Specify whether to include the device configurations linked to the imported stations. + +## Bulk Registration Tokens + +For large-scale deployments, administrators can generate bulk registration tokens to simplify the process of linking multiple Workstation Clients to stations without manual intervention for each client. + +### Generating a Token + +Specify a valid time period for the token, after which it will automatically expire. +Upon generation, the system provides the registration command for the terminal, which can be used to register Workstation Clients. + +### Managing Tokens + +You can revoke an active bulk registration token at any time, immediately invalidating it and preventing further registrations using that token. + +## Station Detail Page + +Once a station is created, clicking on the arrow in the **Stations Overview** page will take you to the **Station Detail** page. This page is your central hub for viewing and configuring all specific settings and associated devices for that individual station. + +From here, you can perform the following tasks: + +* Change the station name. +* Manually refresh configuration to the client, forcing the Workstation Client on the registered computer to immediately pull the latest settings from Workstation Management. +* Configure advanced settings like **Detect Card Readers** and **Station Developer Mode**. +* Manage and configure all devices associated with this station. + +## Advanced Station Settings + +### Detect Card Readers + +Card readers are handled uniquely within Workstation Management. They are not configured as separate devices in the Devices overview of a Station page. Instead, the Workstation Client automatically detects connected card readers. + +Auto detecting card readers is enabled by default. You can toggle the **Detect Card Readers** setting on the **Station Detail Page** to **Off** if you do not want the Workstation Client to automatically detect smart card readers for this specific station. + +### Station Developer Mode {#developer-mode} + +Developer mode can be configured on a **Station** page by toggling **Enable Developer Mode**. + +When Developer Mode is enabled, users of the Workstation Client have access to: + +* Quit the program from the start menu. +* Unlink the Workstation Client, allowing it to be registered to another station. +* 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. +* Developer tools (accessible by pressing *Ctrl + Shift + I*). + +{{% alert color="info" %}} +For production environments, it is strongly recommended to disable Developer Mode. This prevents Workstation operators from accidentally quitting or unlinking the Workstation Client and restricts access to debugging tools that are not needed in a live operational setting. +{{% /alert %}} \ No newline at end of file diff --git a/content/en/docs/workstation/management/wks-management-apps.md b/content/en/docs/workstation/management/wks-management-apps.md new file mode 100644 index 00000000000..e7b40e5b4e0 --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-apps.md @@ -0,0 +1,41 @@ +--- +title: "Managing Apps" +linktitle: "Apps" +url: /mendix-workstation/management-apps/ +description: "Describes the app management options available in Mendix Workstation Management." +weight: 70 +--- + +## Introduction + +The **Apps** page allows you to manage your apps on a workspace level. + +{{< figure src="/attachments/workstation/wks-apps1.png" class="no-border" >}} + +## Creating Apps + +To add a new app to your workspace, perform the following steps: + +1. Click **Create App**. +2. Specify the following properties: + + * App name - Provide a meaningful name for your app. + * URL - Enter the URL of your app. + * Public Key - Generated by the Workstation Connector. Used to establish a secure connection between the Mendix app and the Workstation Client. + * Enable in station groups - Select one or more station groups that should have access to the app. + * Enable in all stations - Select this checkbox to enable the app for all configured stations. + +## Editing Apps + +You can edit the basic settings for an existing app by performing the following steps: + +1. Click the **three dot** menu by the app which you want to edit. +2. Click **Edit App**. +3. Modify the app name, URL, or Public Key. + +## Managing Apps + +You can manage your apps by changing their group assignments. + +1. Click the **three dot** menu by the app which you want to edit. +2. Click **Manage App**, and then adjust the app's group assignment as needed. diff --git a/content/en/docs/workstation/management/wks-management-devices.md b/content/en/docs/workstation/management/wks-management-devices.md new file mode 100644 index 00000000000..48e75f33b22 --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-devices.md @@ -0,0 +1,165 @@ +--- +title: "Configuring Devices" +linktitle: "Devices" +url: /mendix-workstation/management-devices/ +description: "Describes the available devices and device syntax for Mendix Workstation Management." +weight: 60 +--- + +## Introduction + +This section details how to configure various device types for the current station. For each device type, you will find instructions on how to set it up in the Management UI, along with the specific message syntax required for Mendix applications to communicate with it through the Workstation Client. + +## 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**. + +### Message Syntax {#card-readers} + +This device type requires the following message and response: + +#### Message + +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 + +* `0#` - Card connected +* `1#` - Card disconnected +* `2# Response` - Response from device as raw hexadecimal. +* `3# Error` - Error message from device. + +## File Device + +The File Device allows Mendix applications to interact with the local file system of the computer running the Workstation Client. + +### Configuration in Management UI + +To add a File Device, perform the following steps: + +1. Navigate to the **Devices** section on the **Station Detail** page. +2. Click **Add Device** and select **File Device**. +3. Provide a **Device Name** (for example, *Write files to test folder*). + +### 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, providing cross-platform compatibility. + +#### 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: + +* 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 + +You can grant one or more of the following permissions for the File Device: + +* Subscribe to change events - Allow the Workstation Client to monitor the configured folder for changes. +* Read files - Allow Mendix applications to read the content of files within the allowed folder. +* Write files - Allow Mendix applications to write content to files within the allowed folder. + +### Message Syntax {#file-device} + +Before sending messages to the File Device, review the following points: + +* Path handling - You can provide the paths either as absolute (for example, `/var/log/app.log` or `C:\Data\report.txt`), or as relative paths. Relative paths are always interpreted relative to the allowed folder configured in Workstation Management. +* Delimiter - The `#` character is used as a delimiter within messages. Paths and data may not contain the `#` character. +* Case sensitivity - File and directory paths may be case-sensitive depending on the underlying operating system. For example, Linux paths are typically case-sensitive, while Windows paths are not. + +#### Message + +* `0#Path` - Initiate watching for changes in the specified `Path`. If `Path` is a directory, the device will watch for changes within that directory (creation, deletion, renaming, or modification of files/subdirectories). If `Path` is a file, the device will watch for changes to that specific file (modification, deletion, or renaming). +* `1#Path` - Stop watching for changes in the specified `Path`. +* `2#File path` - Read the content of the file at the specified `File Path`. +* `3#File path#Data#flag` - Write `Data` to the file at the specified `File Path`. The `flag` can be `w` for overwrite, `a` for append If left blank, the value defaults to `w`. + +#### Response + +* `R#Path` - File or directory at the specified `Path` was renamed, created, or deleted. +* `C#Path` - File or directory at the specified `Path` was changed. This is triggered both when a file is modified and when the contents of a directory changes. +* `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. + +### Example Test: Verifying File Device Configuration + +Follow these steps to verify that your File Device configuration is working correctly: + +1. Create a new Workspace in the Workstation Management. +2. Create a new Station. +3. Add a `File Device` with the following configuration to this Station: + + * **Device Name** - A meaningful name, for example, *Write files to test folder*. + * **Allowed Folder** - For example, on a Windows computer you can use a path like `C:\MyTestFolder`. Ensure this folder exists on the computer where the Workstation Client will run. + * **Allow writing files** - Select **Yes**. + * Use the default values for everything else. + +4. Register the Station to your computer (assuming the Workstation Client is installed there). +5. In your Workspace, navigate to **Test Your Station** and click **Test** by 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 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*. + +## Bluetooth Devices + +Bluetooth Low Energy (BLE) devices using the ATT protocol can be integrated with Mendix Workstation. + +### Configuration in Management UI + +To add a Bluetooth Device, perform the following steps: + +1. Navigate to the **Devices** section on the **Station Detail** page. +2. Click **Add Device** and select **Bluetooth Device**. +3. Enter the exact device name as it is displayed in your operating system's device manager. + +### Message Syntax + +This device type requires the following message and response: + +#### 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`. + +### Response + +* `CharacteristicUUID#Response` + +## Printers + +You can integrate your Workstations with printer devices. + +### Configuration in Management UI + +To add a printer device, perform the following steps: + +1. Navigate to the **Devices** section on the **Station Detail** page. +2. Click **Add Device** and select **Printer**. +3. Enter the exact device name as it is displayed in your operating system's device manager. + +### Message Syntax + +This device type requires the following message and response: + +#### Message + +A print command, for example, `P#TESTHELLO#RAW#aGVsbG8=`. + +#### Response + +The output of the print command, for example, `hello` in a *TESTHELLO.prn* file. \ No newline at end of file diff --git a/content/en/docs/workstation/management/wks-management-settings.md b/content/en/docs/workstation/management/wks-management-settings.md new file mode 100644 index 00000000000..01bc5322bc0 --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-settings.md @@ -0,0 +1,56 @@ +--- +title: "Configuring Settings" +linktitle: "Settings" +url: /mendix-workstation/management-settings/ +description: "Describes the settings available in Mendix Workstation Management." +weight: 80 +--- + +## Introduction + +Navigate to the **Settings** page in a workspace to configure settings that are applied to all stations in that workspace. + +## Log Settings + +Log settings are available in Workstation Management at **Settings > 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. + +{{< figure src="/attachments/workstation/wks-settings1.png" class="no-border" >}} + +### 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. + +By default, the unregistered Workstation Client is set to the **Debug** log level. After the client is registered, the log level as configured in the Workspace settings is applied. + +## 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. + +## Client's Auto-Refresh {#auto-refresh} + +Auto-refresh settings are available in Workstation Management at **Settings > Client's Auto-Refresh**. + +{{< figure src="/attachments/workstation/wks-settings2.png" class="no-border" >}} + +By default, the Workstation Client operates in auto-refresh mode. That is, any changes made to the configuration in Workstation Management are immediately reflected in the Client. + +To change this behavior, set the **Auto-Refresh Mode** toggle to **Off**. You can then force the configuration to refresh by clicking **Refresh on Computer** in Workstation Management, or by clicking **Refresh** in the Workstation Client. + +The **Check Interval** setting is only available when the auto-refresh mode is enabled. It specifies how often a Workstation Client that is disconnected due to a web socket failure should automatically refresh its configuration by polling Workstation Management. By default, this happens every 60 minutes. + +## Local Device Testing + +Local device testing settings are available in Workstation Management at **Settings > Local Device Testing**. + +{{< figure src="/attachments/workstation/wks-settings3.png" class="no-border" >}} + +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 setting, toggle it off. \ No newline at end of file diff --git a/content/en/docs/workstation/management/wks-management-team.md b/content/en/docs/workstation/management/wks-management-team.md new file mode 100644 index 00000000000..1cbd3c0c87f --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-team.md @@ -0,0 +1,69 @@ +--- +title: "Managing the Team" +linktitle: "Team" +url: /mendix-workstation/management-team/ +description: "Describes the team management options available in Mendix Workstation Management." +weight: 90 +--- + +## Introduction + +{{% alert color="info" %}} +Collaborating with other users in a workspace requires a Workstation license. +{{% /alert %}} + +On the **Team** page, you can invite and manage members of a workspace. Only users who have signed into Workstation Management can be invited by email. + +{{< figure src="/attachments/workstation/wks-team1.png" class="no-border" >}} + +You can assign the following roles to your users: + +* Owner - The owner has full rights to manage the workspace. They can perform the following tasks: + + * Reading and editing configurations + * Managing the team + * Registering and deregistering computers to and from stations + * Refreshing computer configurations + * Managing workspace settings + * Deleting a workspace or transfering 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. + + * Viewing bulk registration tokens + * Copying existing bulk registration tokens + * Creating new bulk registration tokens + * Modifying bulk registration tokens + * Revoking bulk registration tokens + * Exporting and importing stations (single and in bulk) + * Linking imported stations to existing workspace apps + * Creating apps during station import. + +* 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 perform the following tasks: + + * Viewing and editing station configurations + * Registering and deregistering computers to and from stations + * Refreshing computer configurations + * Viewing bulk registration tokens + * Copying existing bulk registration tokens + * Creating new bulk registration tokens + * Modifying bulk registration tokens + * Revoking bulk registration tokens + * Exporting and importing stations (single and in bulk) + * Linking imported stations to existing workspace apps. + +* Computer admin - Computer admins can perform the following tasks: + + * Viewing configurations without editing them + * Registering and deregistering computers to and from stations + * Refreshing computer configurations + * Viewing bulk registration tokens + * Copying existing bulk registration tokens + * Exporting stations (single and in bulk). + +* View only - This role can perform the following tasks: + + * Viewing configurations without editing them + * Exporting stations (single and in bulk). + +All members except for the workspace owner can leave a workspace. \ No newline at end of file diff --git a/content/en/docs/workstation/management/wks-management.md b/content/en/docs/workstation/management/wks-management.md new file mode 100644 index 00000000000..714331c7366 --- /dev/null +++ b/content/en/docs/workstation/management/wks-management.md @@ -0,0 +1,32 @@ +--- +title: "Configuring Mendix Workstation Management" +linktitle: "Configuration" +url: /mendix-workstation/management-config/ +description: "Describes the initial configuration of Mendix Workstation Management." +weight: 40 +--- + +## Introduction + +To start using Mendix Workstation, you must first create a workspace and a station by performing the following steps: + +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**. + + {{< figure src="/attachments/workstation/wks-install1.png" class="no-border" >}} + +3. Enter a name for your new workspace, and then click **Create Workspace**. + + {{< figure src="/attachments/workstation/wks-install2.png" class="no-border" >}} + +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" >}} + +5. Enter a name for the station, and then click **Create Station**. + + {{< figure src="/attachments/workstation/wks-install4.png" class="no-border" >}} + +6. Optional: If you do not want Workstation Management to detect smart card readers, in **Station** view, set the **Detect Card Readers** toggle to **Off**. + + {{< figure src="/attachments/workstation/wks-install16.png" class="no-border" >}} \ No newline at end of file diff --git a/content/en/docs/workstation/troubleshooting/_index.md b/content/en/docs/workstation/troubleshooting/_index.md new file mode 100644 index 00000000000..00d2443dd39 --- /dev/null +++ b/content/en/docs/workstation/troubleshooting/_index.md @@ -0,0 +1,14 @@ +--- +title: "Troubleshooting Mendix Workstation" +linktitle: "Troubleshooting" +url: /mendix-workstation/troubleshooting/ +description: "Describes how to solve potential issues with Mendix Workstation." +no_list: false +description_list: true +weight: 20 +--- + +## Introduction + +If you encounter any issues with your Workstation Management, Connector, or Client, use the following troubleshooting tips to help you solve them. + diff --git a/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md new file mode 100644 index 00000000000..6e65eeda6b7 --- /dev/null +++ b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md @@ -0,0 +1,89 @@ +--- +title: "Troubleshooting the Workstation Client" +linktitle: "Workstation Client" +url: /mendix-workstation/troubleshooting-workstation-client/ +description: "Describes how to solve potential issues with the Workstation Client." +weight: 40 +--- + +## Introduction + +This document provides troubleshooting instructions for some potential issues related to the Workstation 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. + +Log files are also available by day in the Client's app data folder. On Windows, press **Win + R** and enter: + +* 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 + +The Client shows an error like the following: *Registration token could not be parsed. Please enter another token!* + +### Cause + +You entered a registration token with an invalid format. + +### Solution + +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 + +The Client shows an error like the following: *Registration token denied by Workstation Management. Please use another token*. + +### Cause + +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 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. + +## 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. \ No newline at end of file diff --git a/content/en/docs/workstation/troubleshooting/wks-troubleshooting-connector.md b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-connector.md new file mode 100644 index 00000000000..b766be3fdb3 --- /dev/null +++ b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-connector.md @@ -0,0 +1,51 @@ +--- +title: "Troubleshooting the Workstation Connector" +linktitle: "Workstation Connector" +url: /mendix-workstation/troubleshooting-workstation-connector/ +description: "Describes how to solve potential issues with the Workstation Connector." +weight: 50 +--- + +## Introduction + +This document provides troubleshooting instructions for some potential issues related to the Workstation Connector. + +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 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 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 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 + +This is a warning log for the Mendix runtime on the **StationConnector - GetWebsocketSession** log node. + +### Cause + +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 + +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 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 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 + +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. diff --git a/content/en/docs/workstation/troubleshooting/wks-troubleshooting-mgmt.md b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-mgmt.md new file mode 100644 index 00000000000..dd2a21b3982 --- /dev/null +++ b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-mgmt.md @@ -0,0 +1,25 @@ +--- +title: "Troubleshooting Workstation Management" +linktitle: "Workstation Management" +url: /mendix-workstation/troubleshooting-workstation-management/ +description: "Describes how to solve potential issues with Workstation Management." +weight: 30 +--- + +## Introduction + +This document provides troubleshooting instructions for some potential issues related to 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. + +### Solution + +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. + +Contact Mendix Support to transfer workspace ownership. \ No newline at end of file diff --git a/content/en/docs/workstation/wks-client-OLD.md b/content/en/docs/workstation/wks-client-OLD.md new file mode 100644 index 00000000000..d793a6038d1 --- /dev/null +++ b/content/en/docs/workstation/wks-client-OLD.md @@ -0,0 +1,138 @@ +--- +title: "Mendix Workstation Management" +linktitle: "Workstation Management" +url: /mendix-workstation/management/ +description: "Describes how to set up and administer Mendix Workstation Management." +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. + +### 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](https://marketplace.mendix.com/link/component/247460) from the Mendix Marketplace. +3. Configure the station in Workstation Management by performing the following steps: + + 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](/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. + 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](https://workstation.home.mendix.com/) 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](/mendix-workstation/installation/#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 Java actions are essential for establishing connections, sending or receiving messages, and managing device interactions: + +* **GetStation** - Retrieves the computer information connected to the Client. +* **SendMessage** - Sends data or commands to the connected device. For more information about the supported message syntax, see [Message Syntax for File, Smart Card, and Bluetooth Devices](/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** - End the subscription to device messages or errors. +* **UnsubscribeByContext** - End all subscriptions related to a context object. +* **UnsubscribeByDevice** - End all subscriptions related to a specific device. +* **DisconnectDevice** - Unsubscribe and completely disconnect from a specific device. + +These nanoflows and actions serve as the core building blocks for integrating devices into your Mendix applications and tailoring the functionality to your specific requirements. + +### Understanding the Domain Model + +The domain model contains the following entities: + +* **Station** - Includes the station name, computer name, the workspace name and the client version (non-persistent entities). +* **Device** - A list of devices associated with the station; includes device names and properties required to achieve a connection (non-persistent entities). +* **AppKeyPair** - A persistent entity to store the app's key pair. The public key needs to be entered in the corresponding app in the Workstation Management. + +### Using the Nanoflows and Actions + +The following section provides more information about using the nanoflows and Java actions in your Mendix application. + +#### GetStation + +Call `GetStation` to retrieve configuration of the current Client computer by using the Workstation Client. `GetStation` can be used multiple times, but it queries the Workstation Client only the first time. The following calls return the current object loaded in the session. If connection with Workstation Client does not work, `GetStation` returns an empty object. + +#### SendMessage + +Call `SendMessage` to send a message to a device. `SendMessage` includes the option to wait for the response of the device in the current nanoflow. + +#### SubscribeToMessages + +Call `SubscribeToMessages` to trigger a nanoflow when a message is received from a device. `SubscribeToMessages` 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: + +* `Device` (object) +* `Message` (String) +* `Context object` (same as the name used when subscribing) + +#### SubscribeToErrors + +Call `SubscribeToErrors` to trigger a nanoflow on device connection error. + +The callback nanoflow must have the following parameters: + +* `Device` (object) +* `ErrorMessage` (String) +* `ErrorCode` (Integer) +* `Context object` (same as the name used when subscribing) + +#### Unsubscribe + +Call `Unsubscribe` to end a subscription. + +#### UnsubscribeByContext + +Call `UnsubscribeByContext` to end all subscriptions related to a context object. + +## 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](/mendix-workstation/troubleshooting/). diff --git a/content/en/docs/workstation/wks-client.md b/content/en/docs/workstation/wks-client.md new file mode 100644 index 00000000000..736af127db7 --- /dev/null +++ b/content/en/docs/workstation/wks-client.md @@ -0,0 +1,15 @@ +--- +title: "Mendix Workstation Client" +linktitle: "Workstation Client" +url: /mendix-workstation/client/ +description: "Describes how to set up and administer the Mendix Workstation Client." +weight: 30 +--- + +## Introduction + +Installed on each local workstation, the [Workstation Client](https://marketplace.mendix.com/link/component/247448) 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. + +### Users + +Workstation Client is used by central IT, support teams, operators, and supervisors. \ No newline at end of file diff --git a/content/en/docs/workstation/wks-connector.md b/content/en/docs/workstation/wks-connector.md new file mode 100644 index 00000000000..cb03cd64b9e --- /dev/null +++ b/content/en/docs/workstation/wks-connector.md @@ -0,0 +1,22 @@ +--- +title: "Mendix Workstation Connector" +linktitle: "Workstation Connector" +url: /mendix-workstation/connector/ +description: "Describes how to set up and administer Mendix Workstation Connector." +weight: 30 +--- + +## Introduction + +The [Workstation Connector](https://marketplace.mendix.com/link/component/247460) is a 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. + +The connector handles the following tasks: + +* Retrieving local station configuration (name and device list) +* Connecting and disconnecting devices +* Exchanging messages with devices +* Subscribing for triggering app logic on event when receiving messages from a device + +### Users + +The Workstation Connector is used by Mendix developers. \ No newline at end of file diff --git a/content/en/docs/workstation/wks-glossary.md b/content/en/docs/workstation/wks-glossary.md new file mode 100644 index 00000000000..ef45bdcfcdd --- /dev/null +++ b/content/en/docs/workstation/wks-glossary.md @@ -0,0 +1,45 @@ +--- +title: "Mendix Workstation Glossary" +linktitle: "Glossary" +url: /mendix-workstation/glossary/ +description: "Presents and explains several concepts related to Mendix Workstation." +weight: 50 +--- + +## Introduction + +Refer to this glossary for an explanation of commonly used terms related to Mendix Workstation. + +## Concepts + +### Mendix Workstation + +A set of tools and components within Mendix for creating intelligent, efficient, and user-friendly applications for shop floor operators, enabling Mendix cloud applications to interact directly with peripheral devices on a local workstation. + +### Workstation Management + +A Mendix Platform application that offers a centralized interface for configuring, monitoring, and maintaining the lifecycle of workstation clients. It's used by central IT and application support teams to configure clients, register computers, configure and assign devices, and group them into workspaces. + +### Workstation Connector + +A component downloaded from the Mendix Marketplace within Mendix Studio Pro to enable app integration and allow a Mendix application to send and receive data or commands to and from devices. + +### Client + +The Mendix Workstation Client acts as a bridge between the Mendix app and local hardware. The goal of the Workstation Client is to establish a secure and reliable connection between the Mendix Application Client and the hardware, peripherals, or local data sources attached to that workstation. + +### Device + +A device represents a physical device on the shop floor. This can include printers, barcode scanners, smart card readers, industrial scales, and others. + +### Registration Token + +A registration token is used to register a computer in Workstation Management. + +### Station + +A station represents a computer on the shop floor. It can connect to one or more apps or devices. + +### Workspace + +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. diff --git a/content/en/docs/workstation/wks-installation.md b/content/en/docs/workstation/wks-installation.md index 22050bb4f2c..82dde301638 100644 --- a/content/en/docs/workstation/wks-installation.md +++ b/content/en/docs/workstation/wks-installation.md @@ -8,10 +8,6 @@ weight: 20 ## Introduction -This document outlines the installation and basic configuration of Mendix Workstation. It provides a quick-start guide for initial setup, followed by detailed instructions on advanced configurations for workspaces and stations. - -## Quick Start Guide - This guide helps you configure and test a minimum working version of Mendix Workstation. By following these steps, you will complete the following: * Create a basic configuration within Workstation Management. @@ -21,7 +17,7 @@ This guide helps you configure and test a minimum working version of Mendix Work ### Creating a Workspace and Station -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. +To create a workspace and a station, perform the following steps: 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**. @@ -155,169 +151,4 @@ Different device types have different requirements for the message syntax. For m ### Quitting the Workstation Client -The Workstation Client runs automatically at system startup. 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](#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 - -Log settings are available in Workstation Management at **Settings > 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. - -By default, the unregistered Workstation Client is set to the Debug log level. After the client is registered, the log level as configured in the Workspace settings is applied. - -#### 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. - -#### Client's Auto-Refresh {#auto-refresh} - -Auto-refresh settings are available in Workstation Management at **Settings > Client's Auto-Refresh**. - -By default, the Workstation Client operates in auto-refresh mode. That is, any changes made to the configuration in Workstation Management are immediately reflected in the Client. - -To change this behavior, set the **Auto-Refresh Mode** toggle to **Off**. You can then force the configuration to refresh by clicking **Refresh on Computer** in Workstation Management, or by clicking **Refresh** in the Workstation Client. - -The **Check Interval** setting is only available when the auto-refresh mode is enabled. It specifies how often a Workstation Client that is disconnected due to a web socket failure should automatically refresh its configuration by polling Workstation Management. By default, this happens every 60 minutes. - -#### Local Device Testing - -Local device testing settings are available in Workstation Management at **Settings > 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 setting, toggle it off. - -### Workspace Team and Collaboration {#collaboration} - -{{% alert color="info" %}} -Collaborating with other users in a workspace requires a Workstation license. -{{% /alert %}} - -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 perform the following tasks: - - * Reading and editing configurations - * Managing the team - * Registering and deregistering computers to and from stations - * Refreshing computer configurations - * Managing workspace settings - * Deleting a workspace or transfering 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. - - * Viewing bulk registration tokens - * Copying existing bulk registration tokens - * Creating new bulk registration tokens - * Modifying bulk registration tokens - * Revoking bulk registration tokens - * Exporting and importing stations (single and in bulk) - * Linking imported stations to existing workspace apps - * Creating apps during station import. - -* 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 perform the following tasks: - - * Viewing and editing station configurations - * Registering and deregistering computers to and from stations - * Refreshing computer configurations - * Viewing bulk registration tokens - * Copying existing bulk registration tokens - * Creating new bulk registration tokens - * Modifying bulk registration tokens - * Revoking bulk registration tokens - * Exporting and importing stations (single and in bulk) - * Linking imported stations to existing workspace apps. - -* Computer admin - Computer admins can perform the following tasks: - - * Viewing configurations without editing them - * Registering and deregistering computers to and from stations - * Refreshing computer configurations - * Viewing bulk registration tokens - * Copying existing bulk registration tokens - * Exporting stations (single and in bulk). - -* View only - This role can perform the following tasks: - - * Viewing configurations without editing them - * Exporting stations (single and in bulk). - -All members except for the Workspace owner can leave a workspace. - -### Advanced Station Settings - -#### Station Developer Mode {#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 - -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 +The Workstation Client runs automatically at system startup. 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](#developer-mode) is enabled. Alternatively, the Workstation Client process can always be stopped via Windows Task Manager. \ 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 deleted file mode 100644 index e562a594f07..00000000000 --- a/content/en/docs/workstation/wks-message-syntax.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Message Syntax for File, Smart Card, and Bluetooth Devices" -linktitle: "Device Syntax" -url: /mendix-workstation/device-syntax/ -description: "Provides information about the message syntax required for different device types." -weight: 40 ---- - -## Introduction - -To enable Mendix Workstation 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. - -## Bluetooth {#bluetooth} - -This device type requires the following message and response: - -### 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`. - -### Response - -* `CharacteristicUUID#Response` - -## File Device {#file-device} - -This device type requires the following message and response: - -### Important Considerations - -Before sending messages to the File Device, review the following points: - -* Path handling - You can provide the paths either as absolute (for example, `/var/log/app.log` or `C:\Data\report.txt`), or as relative paths. Relative paths are always interpreted relative to the allowed folder configured in Workstation Management. -* Delimiter - The `#` character is used as a delimiter within messages. Paths and data may not contain the `#` character. -* Case sensitivity - File and directory paths may be case-sensitive depending on the underlying operating system. For example, Linux paths are typically case-sensitive, while Windows paths are not. -  - -### Message - -* `0#Path` - Initiate watching for changes in the specified `Path`. If `Path` is a directory, the device will watch for changes within that directory (creation, deletion, renaming, or modification of files/subdirectories). If `Path` is a file, the device will watch for changes to that specific file (modification, deletion, or renaming). -* `1#Path` - Stop watching for changes in the specified `Path`. -* `2#File path` - Read the content of the file at the specified `File Path`. -* `3#File path#Data#flag` - Write `Data` to the file at the specified `File Path`. The `flag` can be `w` for overwrite, `a` for append If left blank, the value defaults to `w`. - -### Response - -* `R#Path` - File or directory at the specified `Path` was renamed, created, or deleted. -* `C#Path` - File or directory at the specified `Path` was changed. This is triggered both when a file is modified and when the contents of a directory changes. -* `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. - -### Example Test - -The section below shows a sample test that you can run to verify the configuration. - -1. Create a new Workspace in the Workstation Management. -2. Create a new Station. -3. Add a `File Device` with the following configuration to this Station: - * **Device Name** - *Write files to test folder* - * **Allowed Folder** - For example, on a Windows computer you can use a path like `C:\MyTestFolder` - * **Allow writing files** - **Yes** - * Use the default values for everything else -4. Register the Station to your computer (assuming the Workstation Client is installed there). -5. In your Workspace, navigate to **Test Your Station** and click **Test** by 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 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*. - -## Card Readers {#card-readers} - -This device type requires the following message and response: - -### Message - -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 - -* `0#` - Card connected -* `1#` - Card disconnected -* `2# Response` - Response from device as raw hexadecimal. -* `3# Error` - Error message from device. diff --git a/content/en/docs/workstation/wks-prerequisites.md b/content/en/docs/workstation/wks-prerequisites.md index 9c26101aa86..085dec79434 100644 --- a/content/en/docs/workstation/wks-prerequisites.md +++ b/content/en/docs/workstation/wks-prerequisites.md @@ -2,34 +2,30 @@ title: "Getting Started with Mendix Workstation" linktitle: "Getting Started" url: /mendix-workstation/prerequisites/ -description: "Documents the requirements for Mendix Workstation." +description: "Documents the requirements for Mendix Workstation, as well as a step-by-step walkthrough through a simple installation and configuration process." weight: 10 --- ## Introduction -This document presents the system requirements for Mendix Workstation. +Use this guide to help you get started with Mendix Workstation. Review the system, access, and network prerequisites, and then follow a step-by-step walkthrough to help you set up and test the connection. -## Workstation Client Download Links +## Prerequisites -Mendix Workstation can be downloaded from the Mendix Marketplace: +Before you get started with Mendix Workstation, ensure that you fulfill the following prerequisites. -* [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) - -## System Requirements +### 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 -## Access Requirements +### Access Requirements * A Mendix account * Access to Mendix Workstation Management for configuration -## Network Configuration +### Network Configuration Before implementing Mendix Workstation, perform the following steps: @@ -63,6 +59,157 @@ Before connecting devices with Mendix Workstation perform the following steps: * 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. +## Workstation Client Download Links + +Mendix Workstation 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) + +This guide helps you configure and test a minimum working version of Mendix Workstation. 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 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**. + + {{< figure src="/attachments/workstation/wks-install1.png" class="no-border" >}} + +3. Enter a name for your new workspace, and then click **Create Workspace**. + + {{< figure src="/attachments/workstation/wks-install2.png" class="no-border" >}} + +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" >}} + +5. Enter a name for the station, and then click **Create Station**. + + {{< figure src="/attachments/workstation/wks-install4.png" class="no-border" >}} + +6. Optional: If you do not want Workstation Management to detect smart card readers, in **Station** view, set the **Detect Card Readers** toggle to **Off**. + + {{< figure src="/attachments/workstation/wks-install16.png" class="no-border" >}} + +### 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 the station that you created, and click **Register Computer**. + + {{< figure src="/attachments/workstation/wks-install5.png" class="no-border" >}} + +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". 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. + + {{< figure src="/attachments/workstation/wks-install6.png" class="no-border" >}} + +3. Perform one of the following actions: + + * 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 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, put the portable client in a new folder (for example, in your Documents folder), and then click the .exe file to run the client. + + * For Linux: + * Download the [Linux](https://marketplace.mendix.com/link/component/247459) version of the Client + * Run the following command to install: `sudo apt install ./MendixWorkstation_X.X.X.X_arm64.deb` (replace *X.X.X.X* with the actual version and build number of the downloaded .deb package) + * Install card reader dependencies: `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 (for raw network packet access): `sudo capsh --user=$(whoami) --iab="^cap_net_raw" -- -c "'/opt/Mendix Workstation/Mendix Workstation'"` + +### 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 associated with your station in the overview, and then select **Register computer**. +3. Click **Copy** to copy the registration token to your clipboard. + + {{< figure src="/attachments/workstation/wks-install7.png" class="no-border" >}} + +4. Open the Workstation Client and paste the copied registration token into the **Enter your registration token** field. +5. Click **Register computer**. + + {{< figure src="/attachments/workstation/wks-install8.png" class="no-border" >}} + +6. In Workstation Management, in the **Computer Registration** dialog, click **Done**. + + {{< figure src="/attachments/workstation/wks-install9.png" class="no-border" >}} + +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 + +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 + +1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/). +2. In the **Station** page, click **Add Device**. +3. Select **TCP/IP Server** as the **Device Type**, and then click **Next**. +4. In the **Device Name** field, enter **Test Server** +5. In the **Device Class** field, select or create a class (for example, *Virtual*), and then click **Next**. +6. In the **Port** field, leave the default value of **1705**, and click **Next**. +7. In the **Messages** dialog, leave all values as default, and click **Add Device**. + + {{< figure src="/attachments/workstation/wks-install12.png" class="no-border" >}} + +The emulated device, a local TCP/IP server listening on port 1705, is added to the **Devices** list in the **Station** page. + + {{< figure src="/attachments/workstation/wks-install13.png" class="no-border" >}} + +#### Creating a TCP/IP Client + +1. Go to [Mendix Workstation Management](https://workstation.home.mendix.com/). +2. In the **Station** page, click **Add Device**. +3. Select **TCP/IP Client** as the **Device Type**, and then click **Next**. +4. In the **Device Name** field, enter **Test Client**, and then click **Next**. +5. In the **Device Class** field, select or create a class (for example, *Virtual*), and then click **Next**. +6. In the **Host** and **Port** fields, leave the default value of **localhost** and **1705**, and click **Next**. + + {{< figure src="/attachments/workstation/wks-install14.png" class="no-border" >}} + +7. In the **Messages** dialog, leave all values as default, and click **Add Device**. + +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 + +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. This includes detected smart card readers available on your computer if you did not disable detecting card readers as described [in step 6](/mendix-workstation/installation/#creating-a-workspace-and-station). + +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. +5. In the left tab, click on the client device (**Test Client**). +6. In the right tab, click on the server device (**Test Server**). +7. In the left tab, on the **Test Client** device, enter a test message, and then click **Send Message**. In the other tab, on the **Test Server**, the sent message appears in the **Last message received** field. +8. In the same way, send a message from the **Test Server** to the **Test Client** device. + +{{% alert color="info" %}} +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 + +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](#developer-mode) is enabled. Alternatively, the Workstation Client process can always be stopped via Windows Task Manager. + ## Best Practices for Working with Mendix Workstation As you begin your work with Mendix Workstation, keep in mind the following best practices to help you. @@ -73,7 +220,7 @@ For more information, see [Security Best Practices for Mendix Workstation](/mend ### Performance Optimization -* Ensure workstations meet the recommended hardware specifications. +* Ensure stations meet the recommended hardware specifications. * Minimize background processes to improve performance. * When building app logic reusing the Connectors nanoflows, minimize the amount of microflow calls and [other actions](/refguide/nanoflows/#logic-where-no-connection-is-needed) that require a server connection. One key benefit of Mendix Workstation is client-sided data processing. Every call to the Mendix runtime adds an performance overhead. diff --git a/content/en/docs/workstation/wks-troubleshooting.md b/content/en/docs/workstation/wks-troubleshooting.md deleted file mode 100644 index 372aba5b7cd..00000000000 --- a/content/en/docs/workstation/wks-troubleshooting.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "Troubleshooting Mendix Workstation" -linktitle: "Troubleshooting" -url: /mendix-workstation/troubleshooting/ -description: "Describes how to solve potential issues with Mendix Workstation." -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. - -## 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. - -#### Solution - -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. - -Contact Mendix Support to transfer workspace ownership. - -## Workstation 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. - -Log files are also available by day in the Client's app data folder. On Windows, press **Win + R** and enter: - -* 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 - -The Client shows an error like the following: *Registration token could not be parsed. Please enter another token!* - -#### Cause - -You entered a registration token with an invalid format. - -#### Solution - -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 - -The Client shows an error like the following: *Registration token denied by Workstation Management. Please use another token*. - -#### Cause - -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 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. - -### 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 - -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 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 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 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 - -This is a warning log for the Mendix runtime on the **StationConnector - GetWebsocketSession** log node. - -#### Cause - -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 - -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 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 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 - -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. diff --git a/static/attachments/workstation/wks-apps1.png b/static/attachments/workstation/wks-apps1.png new file mode 100644 index 00000000000..07f0b1c2a46 Binary files /dev/null and b/static/attachments/workstation/wks-apps1.png differ diff --git a/static/attachments/workstation/wks-settings1.png b/static/attachments/workstation/wks-settings1.png new file mode 100644 index 00000000000..c239398772e Binary files /dev/null and b/static/attachments/workstation/wks-settings1.png differ diff --git a/static/attachments/workstation/wks-settings2.png b/static/attachments/workstation/wks-settings2.png new file mode 100644 index 00000000000..ec94f48427d Binary files /dev/null and b/static/attachments/workstation/wks-settings2.png differ diff --git a/static/attachments/workstation/wks-settings3.png b/static/attachments/workstation/wks-settings3.png new file mode 100644 index 00000000000..4b0425298b7 Binary files /dev/null and b/static/attachments/workstation/wks-settings3.png differ diff --git a/static/attachments/workstation/wks-stations1.png b/static/attachments/workstation/wks-stations1.png new file mode 100644 index 00000000000..fbd321da051 Binary files /dev/null and b/static/attachments/workstation/wks-stations1.png differ diff --git a/static/attachments/workstation/wks-team1.png b/static/attachments/workstation/wks-team1.png new file mode 100644 index 00000000000..af38c0a82f5 Binary files /dev/null and b/static/attachments/workstation/wks-team1.png differ