Skip to content

Commit 122a6a4

Browse files
katarzyna-koltun-mxkatarzyna-koltun-mx
authored
Merge pull request #11515 from mendix/kk-wks-connector
Workstation Connector updates
2 parents 71a4390 + 6e05b02 commit 122a6a4

7 files changed

Lines changed: 263 additions & 204 deletions

File tree

‎content/en/docs/releasenotes/workstation/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ If more than one station is found for a given computer name during bulk registra
185185
* Manage events in a nanoflow with the new `SubscribeToObjectChanges` and `WaitForObjectChanges` nanoflow actions.
186186
* Benefit from easier configuration of common use cases with the new `ConnectDevice`, `SendDeviceMessage` and `WaitForDeviceMessage` nanoflow actions.
187187

188-
For more information, see [Nanoflows](/mendix-workstation/connector/#javascript-actions) and [Widgets](/mendix-workstation/connector/#widgets).
188+
For more information, see [Nanoflows](/mendix-workstation/build-app/#javascript-actions) and [Widgets](/mendix-workstation/build-app/#widgets).
189189

190190
#### Improvements
191191

‎content/en/docs/workstation/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,6 @@ The following functionalities are only available with a license:
7474

7575
* [Bulk import of stations](/mendix-workstation/import-export/)
7676
* [Bulk registration of Workstation Clients](/mendix-workstation/register/)
77-
* [Inviting users](/mendix-workstation/connector/#invite-users)
77+
* [Inviting users](/mendix-workstation/configure-connector/#invite-users)
7878

7979
## Read More

‎content/en/docs/workstation/connector/_index.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Mendix Workstation Connector"
3+
linktitle: "Workstation Connector"
4+
url: /mendix-workstation/connector/
5+
description: Provides an overview of the Mendix Workstation Connector."
6+
weight: 13
7+
no_list: false
8+
description_list: true
9+
---
10+
11+
## Introduction
12+
13+
The Workstation Connector 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.
14+
15+
The connector handles the following tasks:
16+
17+
* Retrieving local station configuration (name and device list)
18+
* Connecting and disconnecting devices
19+
* Exchanging messages with devices
20+
* Subscribing for triggering app logic on event when receiving messages from a device
21+
22+
## Basic Concepts
23+
24+
For more information about the terms used in this document, such as *station* or *device*, refer to the [Mendix Workstation glossary](/mendix-workstation/glossary/).
25+
26+
## Users
27+
28+
Workstation Client is used by central IT, support teams, operators, and supervisors.
29+
30+
## Accessing the Workstation Connector
31+
32+
The Workstation Connector is available for download from the Mendix Marketplace. For more information, see [Installing and Configuring the Workstation Connector](/mendix-workstation/install-connector/#install-connector).
33+
34+
## Read More

‎content/en/docs/workstation/connector/wks-connector-configure.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "Integrating with Mendix Studio Pro"
3+
url: /mendix-workstation/configure-connector/
4+
description: "Describes how to configure a Mendix app for Workstation Connector."
5+
weight: 202
6+
---
7+
8+
## Introduction
9+
10+
After importing the Workstation Connector into your app, you must configure your app as allowed.
11+
12+
## Configuring the App
13+
14+
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.
15+
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.
16+
3. Run the app.
17+
4. Log in as an Administrator, navigate to the page you added in step 2 and copy the shown public key.
18+
5. Go back to the [Workstation Management](https://workstation.home.mendix.com/) and navigate to your workspace.
19+
6. Go to the **Apps** page in your workspace and click **Create App**.
20+
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.
21+
8. Perform one of the following actions:
22+
* To enable the app for all stations, select **Enable in all stations**
23+
* 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.
24+
9. Refresh the Workstation Client.
25+
10. Optional: To recreate the key pair, additionally assign the module role **StationConnector.SecurityAdministrator** to your Administrator role.
26+
27+
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.
28+
29+
## Managing Apps
30+
31+
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**.
32+
33+
## Managing Users {#invite-users}
34+
35+
{{% alert color="info" %}}
36+
This feature is only available to licensed Mendix Workstation users. For more information about obtaining a Workstation license, see [Mendix Workstation](/mendix-workstation/).
37+
{{% /alert %}}
38+
39+
You can invite other Workstation Management users to your workspace to share configurations and collaborate. This feature requires a Workstation license.
40+
41+
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/).
42+
43+
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.

‎content/en/docs/workstation/connector/wks-connector-develop-app.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: "Developing Workstation-Enabled Applications"
3+
url: /mendix-workstation/build-app/
4+
description: "Describes the key concepts and best practices to consider when building an app to work with Mendix Workstation."
5+
weight: 25
6+
---
7+
8+
## Introduction
9+
10+
To start using Mendix Workstation, implement your own custom logic for interacting with devices. The following nanoflows and actions serve as the core building blocks for integrating devices into your Mendix applications and tailoring the functionality to your specific requirements.
11+
12+
## Prerequisites
13+
14+
To help you develop your application, familiarize yourself with the [Mendix Studio Pro Guide](/refguide/), especially the following topics:
15+
16+
* [Studio Pro Overview](/refguide/studio-pro-overview/)
17+
* [Data in the Domain Model](/refguide/domain-model/)
18+
* [Pages](/refguide/pages/)
19+
* [Microflows and Nanoflows](/refguide/microflows-and-nanoflows/)
20+
* [Development Best Practices](/refguide/dev-best-practices/)
21+
22+
## Understanding the Domain Model
23+
24+
The Workstation domain model contains the following entities:
25+
26+
* **Station** - A non-persistent entity representing the Workstation Client configuration.
27+
* **Device** - A non-persistent entity representing a connectable peripheral device. Includes the name, class and state (Available, Connected, or Error). Specialize this to maintain your device specific state.
28+
* **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.
29+
30+
## Using the Nanoflows and Actions {#javascript-actions}
31+
32+
The following section provides more information about using the Workstation nanoflows and Java actions in your Mendix application.
33+
34+
#### SendDeviceRequest
35+
36+
Call `SendDeviceRequest` to send a message to a device and return the response or error. Requires Workstation Client 4.0 or later, and a device that supports requests. For more information about the supported message syntax, see [Configuring Devices](/mendix-workstation/management-devices/). This action has the following parameters:
37+
38+
* `device`
39+
* `message`
40+
41+
### SendDeviceMessage
42+
43+
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:
44+
45+
* `device`
46+
* `message`
47+
48+
Responses are passed through message callbacks. For more information, see `GetCreateDevice` (`onMessage`), `WaitForDeviceMessage`, and `SubscribeToDeviceMessages`.
49+
50+
### WaitForDeviceMessage
51+
52+
Call `WaitForDeviceMessage` to wait for a message from the connected device for the duration of the specified timeout period. This action has the following parameters:
53+
54+
* `device`
55+
* `timeout`
56+
57+
### WaitForObjectChange
58+
59+
Call `WaitForObjectChange` to wait for changes in the attributes of the specified object for the duration of the specified timeout period. This action has the following parameters:
60+
61+
* `objectToObserve`
62+
* `attributes`
63+
* `timeout`
64+
65+
### GetCreateDevice
66+
67+
Call this nanoflow to create and configure a device, and define the actions that should happen on connection, disconnection, or messages from the device. This action has the following parameters:
68+
69+
* `name`
70+
* `class`
71+
* `initialize`
72+
* `createDevice`
73+
* `entity`
74+
* `onConnect`
75+
* `onMessage`
76+
* `onDisconnect`
77+
78+
### ConnectDevice
79+
80+
Call this action to connect to a specific device.
81+
82+
### DisconnectDevice
83+
84+
Call this action to disconnect from a specific device.
85+
86+
### Initialize
87+
88+
This action sets up communication with the Workstation Client. It should be automatically called through the `initialize` parameter of `GetStation` or `GetCreateDevice`.
89+
90+
### GetStation
91+
92+
Call `GetStation` to retrieve the current Workstation Client configuration and devices. This action creates and returns a station object with a linked device object per peripheral.
93+
94+
To interact with a specific device, it is better to use `GetCreateDevice` instead. `GetCreateDevice` has a more convenient API, allows specialization, and does not create station and device objects which may not be needed.
95+
96+
### SubscribeToObjectChanges
97+
98+
Call `SubscribeToObjectChanges` to trigger a nanoflow when the specified object changes. This action has the following parameters:
99+
100+
* `objectToObserve`
101+
* `attributes`
102+
* `callback`
103+
* `applicationContext`
104+
105+
### SubscribeToDeviceMessages
106+
107+
Call `SubscribeToDeviceMessages` to trigger a nanoflow when a message is received from a device. This action has the following parameters:
108+
109+
* `device`
110+
* `callback`
111+
* `applicationContext`
112+
113+
### SubscribeToDeviceErrors
114+
115+
Call `SubscribeToDeviceErrors` to trigger a nanoflow on device connection error. This action has the following parameters:
116+
117+
* `device`
118+
* `callback`
119+
* `applicationContext`
120+
121+
### Unsubscribe
122+
123+
Call `Unsubscribe` to end a subscription.
124+
125+
### Private Nanoflows
126+
127+
`CreateStation`, `CommitStation`, `CreateDevice`, and `CommitDevice` are private nanoflows, required be compatible with [strict mode](/refguide/strict-mode/).
128+
129+
## Widgets {#widgets}
130+
131+
The following widgets allow you to specify when to execute an action:
132+
133+
* **On Load/Unload** - Execute the action when the widget is first rendered, or when it is removed (unloaded).
134+
* **On Change** - Execute the action when the specified attribute changes.
135+
* **On Equal** - Execute the action when an attribute is equal to the specified expression.
136+
* **On True** - Execute the action when the specified expression is true.
137+
138+
## Error Logs
139+
140+
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/).
141+
142+
## Deploying Your Application
143+
144+
There are multiple ways to deploy a Mendix application. You can deploy to your local machine for development and testing. You can deploy to Mendix Cloud, which is the default location for both free and licensed apps. You can also deploy to SAP Business Technology (SAP BTP) Platform, Kubernetes and Cloud Foundry-based platforms, Docker containers, Azure, or to a server you configured yourself. For more information, see [Deploying Apps](/deployment/).

‎content/en/docs/workstation/connector/wks-connector.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Installing the Workstation Connector"
3+
url: /mendix-workstation/install-connector/
4+
description: "Describes how to install the Mendix Workstation Connector."
5+
weight: 20
6+
---
7+
8+
## Introduction
9+
10+
After you have [installed the Workstation Client](/mendix-workstation/install-client/), you must either build a Mendix application that will send data or commands to your devices, or extend an existing app accordingly. In order to do that, you must download, install, and configure the [Mendix Workstation Connector](https://marketplace.mendix.com/link/component/247460) from the Mendix Marketplace.
11+
12+
### How the Connection Works
13+
14+
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, you must generate a key pair in the Workstation Connector, and then configure the public key in the corresponding app in the Workstation Management. Workstation Client configuration must be up-to-date, so that the public key can be verified.
15+
16+
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.
17+
18+
When a client browser or tab instance tries to connect to a device, previously connected browser or tab instances are disconnected from the device.
19+
20+
Since version 4.0, the Workstation Connector connects with Workstation Client using a single persistent WebSocket for all device communication.
21+
22+
## Prerequisites
23+
24+
* Mendix Workstation 3.0.0 or newer
25+
* Mendix Studio Pro 9.24.11 or newer
26+
27+
## Installing the Workstation Connector {#install-connector}
28+
29+
To install and configure the Workstation Connector, perform the following steps:
30+
31+
1. Open an existing app to extend with Workstation functionality in Mendix Studio Pro, or create a new app.
32+
2. Import the [Mendix Workstation Connector](https://marketplace.mendix.com/link/component/247460) from the Mendix Marketplace.
33+
34+
For more information, see [How to Use Marketplace Content](/appstore/use-content/)
35+
36+
3. Register one or more Workstation Clients.
37+
38+
For more information, see [Registering Workstation Clients](/mendix-workstation/register/).
39+
40+
4. Configure your application. For more information, see [Integrating with Mendix Studio Pro](/mendix-workstation/configure-connector/).

0 commit comments

Comments
 (0)