diff --git a/content/en/docs/workstation/_index.md b/content/en/docs/workstation/_index.md index 0212e33e214..79128d2b933 100644 --- a/content/en/docs/workstation/_index.md +++ b/content/en/docs/workstation/_index.md @@ -2,7 +2,7 @@ title: "Mendix Workstation" url: /mendix-workstation/ description: "Presents documentation on configuring and using Mendix Workstation." -weight: 46 +weight: 42 no_list: false description_list: true cascade: @@ -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 - -* 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 +### 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,47 @@ 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 +### Benefits -Mendix Workstation consists of the following components: +Using Mendix Workstation offers the following benefits for your organization: -* [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. +* 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. -Together, these components enable Mendix applications to securely and efficiently integrate with local devices, bridging the gap between digital workflows and physical operations. +## Key Components -### Architecture Diagram +Mendix Workstation consists of the following components: -{{< figure src="/attachments/workstation/WorkstationDiagram.png" class="no-border" >}} +* [Workstation Management](/mendix-workstation/management/) - Allows centralized configuration. +* Workstation Client - Allows real-time communication with local hardware. -### Workstation Management (Mendix Service) + 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. -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. +* Workstation Connector - Allows app integration. -This makes it easier to manage a large, diverse fleet of devices without the need for manual setup or on-site support. + 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. -### Workstation Client (Native Application) + The connector handles the following tasks: -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. + * 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 -### Workstation Connector (Mendix Module) +{{< figure src="/attachments/workstation/WorkstationDiagram.png" class="no-border" >}} -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. +## Licensing Mendix Workstation -The connector handles the following tasks: +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. -* 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 +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) ## 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..e9c7512dcdc --- /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. + +### Developer Mode {#developer-mode} + +Developer mode can be configured on the **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..678c9ce630d --- /dev/null +++ b/content/en/docs/workstation/management/wks-management-devices.md @@ -0,0 +1,180 @@ +--- +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 unselecting **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 + +* `P#PrintJobDocName#Format#DataPayloadInBase64` - Submit a print job. +* `S` - Get printer status and queued jobs. +* `C#JobId` - Cancel print job. + +#### Response + +* `P#DocName#JobId` - Print job accepted by OS print interface. +* `S#State#StateReason1,...#NumJobs#JobId1:JobName1:JobState1,...` - Printer state and job list summary. +* `E#ErrorMessage` - Error. + +#### Example + +The sample print command `P#TESTHELLO#RAW#aGVsbG8=` contains the following elements: + +1. `P (command prefix)` - Tells the Workstation Client that the incoming instruction is a Print command. +2. Separator +3. `TESTHELLOFILE` (file name) - Name assigned to the print job. The client uses this to create the temporary file (for example, `TESTHELLOFILE.prn`) before sending it to the printer spooler. +4. Separator +5. `RAW` (format type) - Tells the Workstation Client that the following data is a Raw Printer Command (such as ZPL for Zebra printers, EPL, or PCL) rather than a standard document like a PDF or a Word file. Printing in RAW bypasses the standard printer drivers' formatting. It sends the exact code the printer needs to generate labels, barcodes, or specific layouts. +6. `aGVsbG8=` (payload) - A data string encoded to Base64. Base64 decoded, it translates to the text `hello`. If you are testing this and the printer is not reacting, verify that the string you are encoding in Base64 matches the specific language your printer speaks. For example, a Zebra printer cannot process a plain text `hello` unless it is wrapped in ZPL commands like `^XA^FO50,50^A0N,50,50^FDhello^FS^XZ`). 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..8f45eb640b5 --- /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 (for more information, see [Troubleshooting the 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/wks-troubleshooting-client.md b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md index e04c884abfd..c477cccc29f 100644 --- a/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md +++ b/content/en/docs/workstation/troubleshooting/wks-troubleshooting-client.md @@ -28,7 +28,7 @@ On Linux, the *Mendix Workstation/logs* folder is located at either `$XDG_CONFIG ### Diagnostics -When [Developer Mode](/mendix-workstation/installation/#developer-mode) is enabled, the Client also shows a **Diagnostics** page. This page displays information about the available devices, credentials, station configuration, system info, and log levels, which you can use to help you troubleshoot any issues. +When [Developer Mode](/mendix-workstation/management-stations/#developer-mode) is enabled, the Client also shows a **Diagnostics** page. This page displays information about the available devices, credentials, station configuration, system info, and log levels, which you can use to help you troubleshoot any issues. ## Registration Token Could Not Be Parsed diff --git a/content/en/docs/workstation/wks-batch-registration.md b/content/en/docs/workstation/wks-batch-registration.md index ee49563403e..4ec3c04f8cc 100644 --- a/content/en/docs/workstation/wks-batch-registration.md +++ b/content/en/docs/workstation/wks-batch-registration.md @@ -14,7 +14,7 @@ The registration process is a necessary first step when enabling this crucial fu Mendix Workstation supports both individual registration of local Workstation clients, and bulk rollouts for large production environments. {{% alert color="info" %}} -After a Workstation Client is registered, any changes that you make in Workstation Management (such as adding new devices, or setting the **Detect Card Readers** toggle to **Off**) will be immediately synchronized with the Client. To change this behavior, see [Client's Auto-Refresh](/mendix-workstation/installation/#auto-refresh). +After a Workstation Client is registered, any changes that you make in Workstation Management (such as adding new devices, or setting the **Detect Card Readers** toggle to **Off**) will be immediately synchronized with the Client. To change this behavior, see [Client's Auto-Refresh](/mendix-workstation/management-settings/#auto-refresh). {{% /alert %}} ## Registering a Single Workstation Client diff --git a/content/en/docs/workstation/wks-build-app.md b/content/en/docs/workstation/wks-build-app.md index 4331084a08a..b6f8a84cdfa 100644 --- a/content/en/docs/workstation/wks-build-app.md +++ b/content/en/docs/workstation/wks-build-app.md @@ -59,7 +59,7 @@ This feature is only available to licensed Mendix Workstation users. For more in 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 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 [Managing the Team](/mendix-workstation/management-team/). 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. @@ -81,7 +81,7 @@ The following section provides more information about using the nanoflows and Ja #### SendDeviceMessage -Call `SendDeviceMessage` to send a message to a device. For more information about the supported message syntax, see [Message Syntax for File, Smart Card, and Bluetooth Devices](/mendix-workstation/device-syntax/). This action has the following parameters: +Call `SendDeviceMessage` to send a message to a device. For more information about the supported message syntax, see [Configuring Devices](/mendix-workstation/management-devices/). This action has the following parameters: * `device` * `message` 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-import.md b/content/en/docs/workstation/wks-import.md index ad559dc40cb..395349ab386 100644 --- a/content/en/docs/workstation/wks-import.md +++ b/content/en/docs/workstation/wks-import.md @@ -12,7 +12,7 @@ You can manage and share station and workspace data across various workspaces an ### Workspace Roles and Permissions -Different user roles are granted various levels of access to import and export tasks. For more information, see [Workspace Team and Collaboration](/mendix-workstation/installation/#collaboration). +Different user roles are granted various levels of access to import and export tasks. For more information, see [Managing the Team](/mendix-workstation/management-team/). ## Importing and Exporting Stations in Bulk diff --git a/content/en/docs/workstation/wks-installation.md b/content/en/docs/workstation/wks-installation.md index 8ad17467dd6..2e3d5da4447 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,14 +17,16 @@ 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**. {{< figure src="/attachments/workstation/wks-install1.png" class="no-border" >}} -3. Enter a name for your new workspace, and then click **Create Workspace**. +3. Enter a name for your new workspace, specify the environment type (**Test**, **Acceptance** or **Production**), and then click **Create Workspace**. + + Workspaces created with the Test environment type have [Developer Mode](/mendix-workstation/management-stations/#developer-mode) for their stations enabled by default. Changing the environment type after creation does not disable or enable Developer Mode. {{< figure src="/attachments/workstation/wks-install2.png" class="no-border" >}} @@ -96,7 +94,7 @@ The **Stations** page now shows your station's status as **Computer Registered** {{< figure src="/attachments/workstation/wks-install10.png" class="no-border" >}} -Any changes that you make in Workstation Management (such as adding new devices, or setting the **Detect Card Readers** toggle to **Off**) will be immediately synchronized with the Workstation Client. To change this behavior, see [Client's Auto-Refresh](#auto-refresh). +Any changes that you make in Workstation Management (such as adding new devices, or setting the **Detect Card Readers** toggle to **Off**) will be immediately synchronized with the Workstation Client. To change this behavior, see [Client's Auto-Refresh](/mendix-workstation/management-settings/#auto-refresh). ### Configuring and Testing Virtual Devices @@ -150,174 +148,9 @@ After configuring the server and client pair, test their connectivity by perform 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/). +Different device types have different requirements for the message syntax. For more information, see [Configuring Devices](/mendix-workstation/management-devices/). {{% /alert %}} ### 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 (for more information, see [Troubleshooting the 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. +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](/mendix-workstation/management-stations/#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 8cfe5f42e00..00000000000 --- a/content/en/docs/workstation/wks-message-syntax.md +++ /dev/null @@ -1,88 +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..c52b4045e48 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 [Configuring Devices](/mendix-workstation/management-devices/). +{{% /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](/mendix-workstation/management-stations/#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/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