--- alias: operation-guide-connectiotadministration tags: - connect iot description: "Configure the Connect IoT module to integrate IoT data into your MES system, enabling automation workflows and device connectivity" --- # Connect IoT Administration To use the Connect IoT module in the MES system, you must have an approved license. For more information, see [[user-guide-automation-index]]. ## Activate Entities to be used by IoT At least one entity type must be enabled to be used by Connect IoT workflows. To enable them, in the `Administration/Entity Types/` page, you will need to activate the Connect IoT Enabled checkbox. ![Screenshot showing an administration page for entity types with a highlighted section for enabling entities to be used by IoT workflows.](../images/automation_image2.png) ![Screenshot showing the Administration/Entity Types page with enabled entity types for use by Connect IoT workflows.](../images/automation_image3.png) Enable the `.Connect` feature on the **Security** page to display the **Connect** button for the selected entity, as shown in the image below. ![connect iot entity feature](../images/connect_iot_entity_feature.png) ## Package Repository The Package Repository contains the runtime components used by Connect IoT. ![Screenshot showing a package repository configuration form with fields for business data and IoT settings.](../images/automation_image4.png) To configure the type and location, use the [[user-guide-configuration-index]] page located in `Administration > Configuration`, search for "IoT" and fill out the values for path `/Cmf/System/Configuration/ConnectIoT` according to the following table: | Name | Type | Possible Values | Default Value | Description | | ------------------ | -------- | -------------------- | ------------- | ------------------------------------------------------------ | | RepositoryType | `String` | `NPM`
`Directory` | `NPM` | Type of Package Repository to use:
- `NPM`: NPM server based repository
- `Directory`: Directory-based repository. Must use `.rebuildDatabase.ps1` script supplied in the ISO to generate the database. | | RepositoryLocation | `String` | | | Depending on the `RepositoryType`, fill with:
- `NPM`: Url of the NPM server. Example: `/opt/connectiot`
- `Directory`: Path where the packages were deployed. Must be accessible by MES host and IoT runtime components. Example: `E:\Repository` | | RepositoryToken | `String` | | | If `RepositoryType` is set to `NPM`, enter the Bearer token for authentication, if needed. Example: `VGhpcyBpcyBhIHRlc3Q=` | Table: Connect IoT System Configurations ### Managing Packages in the Repository The [[user-guide-automation-repository-index]] page supports listing and uploading packages natively only when the **Repository Type** is set to `Directory`. When the Repository Type is set to `NPM`, you cannot manage packages directly through the MES UI. Instead, you must manage packages externally using a standard NPM client CLI (for example, `npm publish`) or an NPM server native user interface (such as Nexus, Verdaccio, or Artifactory) to list, upload, and maintain them. ### NPM Registry Compatibility Requirements To ensure full compatibility with MES, the underlying NPM registry or repository manager must support specific standard NPM API behaviors. The host automatically handles discovery and version retrieval by interacting with the registry through the following mechanisms: | Functionality | API Endpoint(s) | Requirement & Behavior | | --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Package Discovery & Search | `GET /v1/search` | When the registry search API returns unscoped names for packages that are actually scoped, the host automatically reconciles them. This ensures scoped packages are discovered and mapped correctly within MES without requiring manual naming overrides. | | Version Retrieval & Fallback Resolution | `GET /{package}/{version}`
`GET /{package}` | If a direct fetch via `GET /{package}/{version}` returns an HTTP `404 Not Found`, the host executes a fallback strategy. It queries the full package metadata via `GET /{package}` and programmatically resolves the required version from the returned `versions` map. | | Tarball Download Redirects | Follows redirect targets | The host supports registries that offload storage by redirecting package requests to external storage endpoints via HTTP `301`, `302`, `307`, or `308`. The host follows the `Location` header to the final endpoint, supporting up to five sequential redirects. | Table: NPM Registry Compatibility Requirements ## Enable Customizations ### Custom Automation Business Scenarios By default, only the automation business scenarios supplied by `Critical Manufacturing` are visible when using the `AutomationBusinessScenario` entity. To allow custom/additional business scenarios packages to be used, use the [[user-guide-configuration-index]] page located in `Administration > Configuration`, search for "IoT" and fill out the values for path `/Cmf/System/Configuration/ConnectIoT` according to the following table: | Name | Type | Possible Values | Default Value | Description | | ------------------------- | -------- | --------------- | --------------------------------------------- | ------------------------------------------------------------ | | BusinessScenarioPackageNameFilter | `String` | | `@criticalmanufacturing/connect-iot-business-scenarios-*` | Filter to use to identify packages that can be used for `AutomationBusinessScenario` entities. Update the value if custom automation business scenarios packages are intended to be used. Use `;` as separator and `*` as wildcard. Example: `@criticalmanufacturing/connect-iot-business-scenarios-*;@customer/connect-iot-business-scenarios-*` | Table: Automation Business Scenarios Packages filter configuration ### Custom Automation Task Library By default, only the task library packages supplied by `Critical Manufacturing` are visible when using the `Automation Task Library` (ATL) entity. To allow custom/additional ATL packages to be used, use the [[user-guide-configuration-index]] page located in `Administration > Configuration`, search for "IoT" and fill out the values for path `/Cmf/System/Configuration/ConnectIoT` according to the following table: | Name | Type | Possible Values | Default Value | Description | | ------------------------- | -------- | --------------- | --------------------------------------------- | ------------------------------------------------------------ | | TasksLibraryPackageNameFilter | `String` | | `@criticalmanufacturing/connect-iot-controller-engine-*` | Filter to use to identify packages that can be used for `Automation Task Libraries` entities. Update the value if custom ATL pacakages are intended to be used. Use `;` as separator and `*` as wildcard. Example: `@criticalmanufacturing/connect-iot-controller-engine-*;@customer/connect-iot-controller-engine-*` | Table: ATL Packages filter configuration ### Custom Protocol Drivers By default, only the protocol drivers supplied by `Critical Manufacturing` are visible when using the `Automation Protocol` entity. To allow custom/additional drivers to be used, use the Configuration page located in `Administration/Configuration`, search for "IoT" and fill out the values for path `/Cmf/System/Configuration/ConnectIoT` according to the following table: | Name | Type | Possible Values | Default Value | Description | | ------------------------- | -------- | --------------- | --------------------------------------------- | ------------------------------------------------------------ | | ProtocolPackageNameFilter | `String` | | `@criticalmanufacturing/connect-iot-driver-*` | Filter to use to identify packages that can be used for `Automation Protocol` entities. Update the value if custom drivers are intended to be used. Use `;` as separator and `*` as wildcard. Example: `@criticalmanufacturing/connect-iot-driver-*;@customer/connect-iot-driver-*` | Table: Protocol Drivers filter configuration ## Additional Configurations In the section `/Cmf/System/Configuration/ConnectIoT` of the [[user-guide-configuration-index]], the additional values can be defined: | Name | Type | Possible Values | Default Value | Description | | --------------------- | ----------------------- | --------------- | ------------------------- | ------------------------------------------------------------ | | ConfigurationTemplate | `Json in string format` | | `` | The configuration template to use within the `Automation Manager` entity. Can be changed in the `Configuration` Wizard. There is only one possible template and will be stored in this configuration entry.
`Note:` Just change the value here if there is a problem with the json. Otherwise, always use the wizard in `Automation Manager`entity. | Table: Connect IoT additional configurations ## Interlocking Timeouts When a **Resource** has an interlocking property enabled, the MES sends a request to the Automation Controller that owns the Resource and waits for the reply before completing the operation. See the [[tutorials-connectiot-mes-interop-scenarios]] for an explanation of how each interlocking scenario works. Each of these calls has its own timeout, defined in the section `/Cmf/System/Configuration/Resource` of the [[user-guide-configuration-index]]. Raise the value for an operation that legitimately takes longer than the default, such as uploading a large recipe body, and lower it when the MES should give up earlier and fail the operation. | Name | Type | Default Value | Description | | ----------------------------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------- | | GetRecipeListTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the list of recipes available at the equipment. | | RecipeBodyDownloadTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for a recipe body downloaded from the equipment. | | RecipeBodyUploadTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the equipment to accept an uploaded recipe body. | | SetupInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Resource begin setup request. | | MaterialDispatchInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Material dispatch request. | | MaterialTrackInInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Material track in request. | | MaterialTrackOutInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Material track out request. | | ContainerDockInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Container dock request. | | ContainerUndockInterlockingTimeOut | `Int32` | `60000` | Time, in milliseconds, that the MES waits for the reply to a Container undock request. | Table: Connect IoT interlocking timeouts When an entry is missing or has no value, the MES uses 60000 milliseconds. !!! warning The timeout on the MES side and the Reply Timeout of the corresponding trigger task in the Automation Workflow are independent. Keep the task Reply Timeout below the MES timeout, so the workflow reports the failure before the MES gives up on the call. ## Access Tokens Each **Automation Manager** signs in to MES with a long-term access token of a user, and its controllers use the same token. Where the token comes from depends on how you deploy the manager. | Deployment | Token | Expiration | Stored in | | ---------- | ----- | ---------- | --------- | | Package created by **Download** (Windows service or console) | Created by **Download** for the user selected in the wizard, named `_` | 1 year. When you run **Download** as an administrator, 10 years, and at least until 2037-12-28. | `system.authentication.settings.accessToken` of `config.json` and `config.full.json` | | Kubernetes, with the Deployment Mode `AutomaticDeploy` | Issued by the Automation Manager Controller for the integration user, named `AMC--` | Requested 30 years ahead | A Kubernetes secret, passed to the container as `APPLICATION_PAT`. See [[user-guide-automation-manager-deploy#deployment-token]]. | | Docker container that you start | An access token that you create for the integration user | The date you choose | The `APPLICATION_PAT` variable. See [[operation-guide-connectiotinstallation-docker]]. | Table: Access token of an Automation Manager per deployment Each **Download** creates a new token and does not revoke the tokens that earlier downloads created. Revoke the tokens that no manager uses. When the token expires or is revoked, every instance on that manager loses MES. The monitor log shows `Error connecting to MES: …` and `Waiting 30s until next attempt` at start, and `Looks like the token has expired and must be renewed!` about once a minute while it runs. To replace the token of a manager created by **Download**: 1. Create a new token for the user: run **Download** again, or create an access token on the **Users** page. See [[user-guide-security-users#creating-access-tokens-for-a-user]]. 2. Set the new token in `system.authentication.settings.accessToken` of the `config.json` of the manager. 3. Restart the manager. The processes read the token only when they start. The manager is the parent process of the monitor and of every controller and driver process, so all its instances restart. Plan a maintenance window. 4. Revoke the old token in the **Access Tokens** sub-section of the user on the **Users** page. See [[user-guide-security-users#revoking-access-tokens-for-a-user]]. For a manager deployed by the Automation Manager Controller, **Undeploy** revokes the token, and the next **Deploy** issues a new one. See [[user-guide-automation-manager-undeploy]]. A manager with the `ClientCredentials` authentication type has no access token: the processes read the client secret from the `SECURITY_PORTAL_CLIENT_SECRET` environment variable. See [[installation-guide-connectiotautomationmanagerconfig#authentication-type-clientcredentials-settings]]. ## Data on the Manager Host An **Automation Manager** keeps stored values, packages, and logs in folders on its host. The default configuration, in the configuration entry `/Cmf/System/Configuration/ConnectIoT/ConfigurationTemplate`, puts them under `/ConnectIoT`, where `` is the temporary folder of the account that runs the manager. A clean-up of that folder, or a container without a volume for it, deletes them. | Data | Configuration key | Default folder | Contents | Back up | | ---- | ----------------- | -------------- | -------- | ------- | | Persistency | `storage.settings.path` | `/ConnectIoT/Persistency` | Values that workflows store as `Persistent`, kept for `retentionTime` (`30d` by default) | Yes | | Package cache | `cache` | `/ConnectIoT/Cache` | One folder per package version that the monitor downloaded | No. The monitor downloads a missing package again from the repository. | | Logs | `dirname` of each `File` transport in `logging` | `/ConnectIoT/Logs` and `/ConnectIoT/Jobs` | Logs of the instances, the manager, the monitor, and the jobs. A new file starts every 10 MB, and files are kept 30 days. | Only when your retention rules require it | | Configuration | None | The manager installation folder | `config.json` with the access token, `config.full.json`, and `config.downloaded.json` | Optional. A new **Download** creates it again, with a new token. | Table: Data that an Automation Manager keeps on its host - Move the persistency out of the temporary folder to a folder that is backed up. Change `storage.settings.path` with [[user-guide-automation-manager-configure]]. For the keys, see [[installation-guide-connectiotautomationmanagerconfig#storage-structure]]. - Stored values stay on the host where the instance ran, in the store of its instance ID. The ASA **Change Automation Manager** action replaces the instance with a new one, with a new ID, on the target manager, so the new instance does not read the values of the old one, even when both managers share the persistency folder. See [[user-guide-automation-scheduled-action-action#what-the-action-costs-at-run-time]]. - For High Availability, put the persistency in a shared folder that every manager node reaches. See [[tutorials-connectiot-deployment#productive-deployment]]. ## Network Connections Open the following connections in every firewall between the manager host, MES, the package repository, and the equipment. The configuration keys are described in [[installation-guide-connectiotautomationmanagerconfig]]. | From | To | Address | Notes | | ---- | -- | ------- | ----- | | Monitor and controller processes | MES | `system.address` and `system.port`, over HTTPS when `system.useSsl` is `true` | Every call to MES. | | Monitor and controller processes | Security Portal | The URL in `system.authentication.settings.openIdConfiguration`, and the token endpoint that it returns | Sign-in with the access token or the client secret. | | Monitor and controller processes | Message bus | The address that MES publishes in `/.well-known/criticalmanufacturing-configuration`, or the one set in `MESSAGEBUS_GATEWAY_ADDRESS`, `MESSAGEBUS_GATEWAY_PORT`, and `MESSAGEBUS_GATEWAY_WS_PROTOCOL` when all three are set | WebSocket connection. | | Monitor | Package repository | `repository.settings.url` for `Npm`, `repository.settings.path` for `Directory` | With the `System` repository type, the monitor downloads the packages through MES and needs no connection to the repository. | | Controller and driver processes | Monitor | `monitorHost` and `monitorPort` (`localhost` and `0` by default) | With `0`, the operating system assigns a free port when the manager starts. | | Controller processes | Driver processes | `hostName` (`localhost` by default) and a port that each driver process opens when it starts | The port changes every time the driver process starts. It crosses the network only when the controller and the driver run on different managers. | | Driver processes | Equipment | The address and port in the communication parameters of the protocol | See the page of each protocol in [[user-guide-automation-protocol-protocols-index]]. | | Equipment or other systems | REST Server driver | `address` and `port` of the driver | The REST Server driver listens for requests. See [[user-guide-driver-restserver]]. | Table: Network connections of an Automation Manager When the `logging` section has an `OTLP` transport, the processes also send telemetry to its `endpoint`.