The App Config community (appconfig.org) is formed to standardize the way devices and applications can be managed in enterprise environments. It makes possible for companies to manage their (large) fleet of devices and the applications that run on them in a centralized fashion using any of the MDM/EMM solutions that are part of the community. Apps that are manageable this way define a schema that contains the configurable properties and appear in the Managed Google Play Store (also called Google Play for Work Store). This Managed Google Play Store is only accessible by users of registered Organizations. All apps can be accessed through it from the normal Google Play Store but there are ones that are only visible in this specialized Store. Android devices that want to use managed apps in compliance with app config need to be set up with Android Work Profile enabled and apps need to be installed through the Managed Google Play Store (there is no way to configure apps that are installed using another method). An Organization in the Managed Google Play Store can be bound to a third party MDM/EMM solution and apps that are distributed to the devices managed by the MDM/EMM need to be first approved by the Organization's admin to appear in the Play Store app on the device. They can be installed as a mandatory app (so that they are installed automatically) or optional (the user of the phone can choose to install it).
Cognex provides support for App Config standard with it's MX-series devices and compatible apps starting with remote Firmware Update and Config Upload for MX Terminals through the MX Connect application. With the App Configuration capability (see Terminology and Definitions) the MDM administrator can specify which Firmware and Config should be applied to a device or group of devices. When these are specified MX Connect will apply the Firmware Update and/or Config Upload after it is synchronized to the Android device and when it is connected to the MX Terminal (see steps below).
The following terms are used throughout this document:
Register an Organization in the Managed Google Play Store (Google Play for Work Store) using Google's Managed Enterprise Enrollment page and create a binding between it and the MDM/EMM solution you use
To register your organization, start from the MDM/EMM you are using and start adding the binding. You will need at least one Google Account that is registered to Manage your business (not a personal account).
Please note, that one Organization can only be bound to one MDM/EMM at a time.
You need to search for MX Connect and before you can successfully add it to the Application Catalog Rule, you need to Approve it.
You need to start with Adding a new app to Mobile Iron App Catalog from Google Play (or alternatively you can log in directly to the Managed Google Play Store and Approve MX Connect from there).
You need to search for MX Connect and before you can successfully add it to the App Catalog, you need to Approve it
You can distribute the app during the Add steps (in that case you do not need to do Step 4) and add a Managed Configuration to it too (in that case you do not need Step 5 either), but you can also do it later in separate steps.
Once the MX Connect App shows up in the Catalog, you need to Distribute it to the Users or User Groups that needs to use it.
When the values set using App Configuration / Managed Configuration gets synced to an Android device and the Firmware URI is changed, it will be automatically installed to the MX Terminal by MX Connect. If the MX Terminal is connected when the new values are received, the installation will begin right away and if not, it will be done upon next connection. Please note that you cannot use the MX Terminal unti the Firmware update is done.
When the values set using App Configuration / Managed Configuration gets synced to an Android device, it will be automatically installed to the MX Terminal by MX Connect if the actual file is different than the last installed one, or if Always apply config was set. If the MX Terminal is connected when the new values are received, the installation will begin right away and if not, it will be done upon next connection. Please note that you cannot use the MX Terminal unti the Config upload is done, but it usually just takes a couple of seconds.
The main features of the MX Connect application are:
In the UPDATES section of the main screen the app shows the configured firmware and MX configuration. If these configurations are installed properly, a checkmark is displayed in the rows, respectively. Although the configuration XML sent by the MDM contains URLs, MX Connect only displays the last component of these URLs. Use file names in the URLs that reflect the version of their content.
Check the log to review the history of the attached MX mobile terminal. You can check what configuration the app received, and if the updating processes were successful.
Tap the row in the history list and check the disclosed page for more detailed information on a particular event.
The following terms are used throughout this document:
Configure Apple Push Notification Service on your MDM
Follow the instructions to enable your MDM to communicate with mobile phones via Apple's Push Notification Service.
Make your iOS device supervised
Make your iOS device supervised by using the Apple Configurator desktop application on a Mac or by using Apple's DEP program. This is a precondition so that MDM can have more control over the mobile phone (e.g. launch and application in single app mode which is required for MX Connect updating workflow).
Enroll the mobile phone to the MDM.
User-Initiated Enrollment for Mobile Devices
You can combine supervising and enrolling by using a supervising identity.
For more information about device enrollment, refer to Enrollment of Mobile Devices.
Install MX Connect app with your MDM system from the App Store.
Add MX Connect to JAMF by an App Store URL.
Set the distribution method to "Install Automatically" to let JAMF deploy it without user interaction.
To learn more about app distribution in JAMF, read the App Distribution document.
To install MX Connect app first you have to create an Application Catalog Rule.
In the app catalog rule you have to add MX Connect app by any of the possible options. Most likely you will select the App Store Applications option.
To force installing to devices set the Application Type field to Mandatory.
Click Add button.
Select MX Connect published by Cognex Corporation:
Save and assign to user group where MX mobile terminals are used. Set all other assignment properties according to your need and finally publish your changes.
Create a Single App Mode Configuration Profile for MX Connect.
Launch the application by putting it to Single App Mode (SAM). To let your MDM put the application to SAM, create a configuration profile in your MDM that is sent out to devices in the right time. If a device receives a Single-App-Mode configuration profile for MX Connect app, the iOS device launches the app and keeps it on screen until the MDM system revokes the configuration profile.
You can create a Single-App-Mode configuration profile at Mobile Devices or Configuration Profiles.
You can create a Single-App-Mode configuration profile at Profiles / Add.
You can create a Single-App-Mode configuration profile at Configurations.
Create a new configuration and select the Single App Mode type.
To associate the MX Connect app configure the restriction by selection your hosted MX Connect app.
Please note that this is only a preparation step so please leave "Enable this configuration" option unchecked:
Create an Autonomous Single App Mode Configuration Profile for MX Connect.
Autonomous Single App Mode (ASAM) is a very similar functionality to Single-App-Mode. ASAM lets the MX Connect app to lock to the iOS device's screen and unlock when it is no longer needed.
MX Connect needs this to autonomously lock to the screen during downloading and installing update files to prevent the phone's user to navigate away during installation.
To let MX Connect use ASAM, create a configuration profile with MX Connect app's bundle ID, com.cognex.MXConnect, in your MDM and issue it to all your iOS devices.
Select Restrictions to create an Autonomous Single App Mode configuration profile.
Select the Applications tab and MX Connect's bundle ID: com.cognex.MXConnect
Select Restrictions to create an Autonomous Single App Mode configuration profile.
Select the Applications tab and add MX Connect's bundle ID (com.cognex.MXConnect) to the list.
In the configuration section you have to add MX Connect to the appropriate field.
To send ASAM configuration to a particular device click on Push button on the device's Configuration tab.
Prepare a server to access firmware and configuration update files by URL.
During a firmware or configuration update MDM sends only the URLs of the update files to the MX Connect app, which downloads the update files using these URLs. Make sure that your update files are accessible by a URL, and set up a server to accomplish this requirement, if necessary. You can use Cognex' firmware storage to distribute upgrades. For more detail, refer to the FAQ
Install MX Connect app (with your MDM system) on mobile devices.
If the MX Connect app is already installed on all iOS devices managed, skip this step (otherwise check Preparation step 4).
Once you have added MX Connect to your JAMF instance, apply two settings to automatically install to you device.
App install is automatic:
Add your iOS device to the app's scope:
Once you have added MX Connect to your SOTI instance, apply two settings to automatically install to you device.
Installing the app is automatic:
Add your iOS device to the app's scope:
Launch MX Connect. To launch MX Connect, send a Single App Mode configuration profile to the iOS devices.
To launch MX Connect, put it to Single-App-Mode by adding your device to the SAM configuration profile's scope.
To launch MX Connect, put your device to Single-App-Mode by adding it to the SAM configuration profile's scope.
Please note that you have to uncheck this option after the installation process to terminate the Single App Mode.
Send updates to the MX mobile terminal.
To send firmware or MX configuration updates, compose an XML text containing the URLs of the update files. The XML has to be provided to your MDM, which sends it to each MX Connect instance. MX Connect starts the update process upon receiving the XML configuration.
The XML composed is not a command but a configuration. The XML resides at MX Connect until the next XML configuration overwrites it. MX Connect will try to install the firmware and configuration using the defined URLs each time when the application starts. Firmware update is performed once and MX Connect checks whether the installed firmware matches with the firmware available on the MX mobile terminal. MX configuration update is performed multiple times when the application is opened, which takes only a few seconds.
To send new updates to MX Connect, edit the App Configuration text at MX Connect's page. Use the proper form of the XML to perform a successful update.
To send new updates to MX Connect, edit the App Configuration text at MX Connect app's "Application Catalog Rule". Use the proper form of the XML to perform a successful update.
Click on Add button and create a new configuration as indicated below.
Select the actual MX Connect assignment and edit Application configuration. Turn on Send configuration setting.
Depending from MDM you have to enter an XML as configuration or you can add key-value pairs as a configuration or you can pick your preferred method.
<dict>
<key>firmwareURL</key>
<string>https://myserver.com/firmwares/firmware_file_name</string>
<key>configurationURL</key>
<string>https://myserver.com/configs/config_file_name</string>
</dict>
Key | Type | Value |
---|---|---|
firmwareURL | string | https://myserver.com/firmwares/firmware_file_name |
configurationURL | string | https://myserver.com/firmwares/firmware_file_name |
Revoke Single App Mode from MX Connect to remove devices from SAM.
A company owning and operating many Cognex Mobile Terminals may want to remotely collect up-to-date information about battery level, battery health, installed firmware, etc. An iOS application using the cmbSDK framework can report status information of the attached Mobile Terminal to an MDM instance. Cognex mobile apps (MX Connect, Cognex Quick Setup...) can be also configured to report MX data.
Any iOS application is capable of reporting Mobile Terminal status information if it embeds and uses the cmbSDK framework.
1. Update cmbSDK framework in your app to use at least 2.4.0 version.
2. Configure reporting for the app in your MDM.
Reporting is done by an iOS application towards an MDM instance. The app has to be managed by the MDM instance and can only report to that MDM instance. There are a few configuration options the MDM administrator has to properly set to let the reporting feature work for a certain application. These settings are done by creating a proper Managed App Configuration including key-value pairs as the configuration of reporting. Please refer to your MDM's administration guide to learn how to edit Managed App Configuration of a managed mobile app.
As described above the MDM's administrator has to compose a Managed App Configuration to define settings of the reporting. This Managed App Configuration is sent to the mobile app by the MDM to let the app process it and behave accordingly. Please note that providing a proper Managed App Configuration is mandatory to enable the reporting. Without that the cmbSDK (in the app) won't start reporting.
The mandatory configuration fields are the following.
Key | Type | Description |
---|---|---|
mxReportingEnabled | Bool | It has to be set to true to enable reporting. |
mxReportingURL | String | This URL has to point to your MDM instance including port number if necessary. |
mxReportingIntervalMinutes | Integer | Reporting frequency in minutes, minimum value is 1. |
mdmType | String | The type of your MDM. Possible values: "AirWatch", "Jamf", "MobileIronCloudV1", "SOTI" |
mdmDeviceID | String |
This field is a technical field that has to be set with a constant depending on your MDM type. SOTI: %DeviceIdentifier% Jamf: $JSSID MobileIron: ${devicePK} Workspace ONE / Airwatch: {DeviceSerialNumber} |
It is possible to turn on/off the reporting from the source code of your application by changing MDMReportingEnabled property of your CDMDataManSystem instance. Please note that the default value is false for MDMReportingEnabled. Please be aware that the mandatory fields still needs to be configured in MDM.
For cmbSDK connecting to your MDM instance will most likely require authentication credentials. Beside the mandatory configuration fields you also have to provide these in the Managed App Configuration as indicated in the following table.
Key | Type | SOTI | Jamf | MobileIron | Airwatch | Description |
---|---|---|---|---|---|---|
mdmReportingClientID | String | x | Application needs to be added as API client and generate this ID | |||
mdmReportingClientSecret | String | x | Application needs to be added as API client and generate this secret | |||
mdmReportingPassword | String | x | x | x | x | Password |
mdmReportingUsername | String | x | x | x | x | User name |
mdmTenantCode |
String | x | The key value is available in the system settings when REST API access is enabled. |
Please note that you have to provide a registered user's credentials that has the right to use the MDM's API for reporting. Refer to your MDM's administrator guide to learn more.
If you don't want to provide authentication credentials via Managed App Config for some reason these can be set by the cmbSDK's API from your app's code. It gives you full flexibility to retrieve authentication credentials in the way your company's policy requires. To do so you have to set the defaultMDMAuthCredentials property of CDMDataManSystem class.
var authCredentials: MDMAuthCredentials = MDMAuthCredentials()
authCredentials.username = "usr"
authCredentials.password = "pwd"
authCredentials.clientID = "myClientID"
authCredentials.clientSecret = "myClientSecret"
self.dataManSystem.defaultMDMAuthCredentials = authCredentials
self.dataManSystem.MDMReportingEnabled = true // if you want to start reporting
MDMAuthCredentials *authCredentials = [MDMAuthCredentials new];
authCredentials.username = "usr";
authCredentials.password = "pwd";
authCredentials.clientID = "myClientID";
authCredentials.clientSecret = "myClientSecret";
self.dataManSystem.defaultMDMAuthCredentials = authCredentials;
self.dataManSystem.MDMReportingEnabled = true; // if you want to start reporting
Please note that if you set authentication credentials both in the Managed App Config and via defaultMDMAuthCredentials property the fields in the Managed App Config will overwrite the fields in the defaultMDMAuthCredentials property per field basis. This precedence allows your MDM administrator to make some fix/change without rebuilding and deploying your application.
The following data of the attached Mobile Terminal is collected:
Attribute name | Type | Format | Description |
---|---|---|---|
MX Device Variant | Text | MX-1XXX VARIANT | Example MX-1502 ER is shown for extended range MX-1502 mobile terminals |
MX Device Name | Text | MX-1XXX-YYYYYY names are used by default, but it may be different according to configuration | |
MX Serial Number | Text | 14 character | |
MX Pistol Grip Battery Level | Number | X | -1 means no battery is available |
MX Flat Battery Level | Number | ||
MX Pistol Grip Battery Health | Number | ||
MX Flat Battery Health | Number | ||
MX Firmware Version | Text | A.B.C_D | Example: 5.7.9_sr3 |
MX Status Date | Date | Depends from you MDM local settings | Contains the timestamp (in case of SOTI only date) for the last report. |
MX Status Timestamp | Text | YYYY-MM-DD HH:MM:SS (24H) | Contains the exact timestamp for the last report. Available only on SOTI. |
The reported data fields appear as custom/extension attributes in MDM.
These custom attributes are global attributes. These are assigned to all enrolled devices in case of Jamf and SOTI and are assigned only to the devices that have reported data in the case of Airwatch. By default the custom attributes are not present in an MDM instance, the properly configured mobile app creates the custom attributes automatically via the MDM's API and neither the app developer nor the MDM administrator has to take care of it.
Preparing custom/extension attributes to require two steps: