If your app requires configuration, you will want it to be remotely configurable via HP Command Center (HPCC).
To enable remote configuration via HPCC, you must provide a special app configuration template (also known as a MOC file) as part of your app submission on the HP App Center. In turn, the MOC file allows HPCC users to generate app configurations (also known as CFG files) and remotely deploy them to your app running on HP devices.
The MOCTool (available on the Downloads page) makes it easy to create and verify a MOC file for your application, generate multiple valid CFG file variations, and test the remote configuration feature with your app while installed on HP device or simulator.
MOC file
A Manifest of Configuration (MOC) file is a file in XML format and has an extension as “.moc”. The purpose of a MOC file is to describe your application’s configuration parameters, including how those parameters should be presented to users within HPCC’s user interface in a well-structured, editable format. The MOC file schema (.xsd) and several examples are included in the MOCTool package (available on the Downloads page).
A MOC file includes following information:
- Hierarchy of configurable options (“frames”, “fidgets”, “sets”)
- List of all possible values for each option (“items”)
- Default values
- Dependencies between various options
- Error messages to be displayed for invalid input
- Localized strings for all options and errors
CFG file
A Configuration (CFG) file is a special file in JSON format and has an extension as “.cfg”. The purpose of a CFG file is to store a specific application's configuration in readable, standard format for data transmission. Unlike MOC files, a CFG file stores currently selected values for all options. The format is used for application data exchange in both directions: to read an app’s current configuration and to write a new one.
Note: To support remote configuration, you must modify your app to consume configurations in the CFG file format.
MOCTool
To facilitate development and testing of remote configuration for your app, you will use the MOCTool. For details on installation and usage see the User Guide in the MOCTool package (available on the Downloads page).
The MOC tool:
- Validates your MOC file as you create it
- Lets you view and interact with the UI exactly as an user will use it on HPCC
- Lets you create many CFG file variations for testing your app
- Lets you write and read CFG files to your installed app (on an HP device or simulator)
The Remote Configuration Process End to End
To enable remote configuration via HPCC for your app, HP recommends you follow this process:
- Review the MOC file specification, to understand its features and limitations. For example, which data types are supported and which are not supported.
- Design and implement app configuration in your app that conforms to the JSON format and MOC file limitations (see the configSample in the SDK).
- Using an XML editor or text editor, construct a MOC file. (If your editor supports XML schema validation, validate your MOC file against the schema.)
- Load the MOC file into The MOCTool. If it reports errors or warnings, fix those errors and warnings in the editor and reload the MOC file.
- Using The MOCTool’s UI preview (this is how your MOC will be displayed in HPCC), test the UI defined by your MOC. Check the layout. Check dependencies between options. Make changes in the editor and reload as necessary.
- Using The MOCTool, create various configurations and deploy them to your app running on a device or simulator. Be sure to test “corner cases”. Make changes to your MOC and/or your app as needed to make sure all possible configurations are handled appropriately. (Note: You can save these CFG files for future app regression testing.)
- Once you are happy with your app and your MOC file, upload both to the HP App Center. When your app is published, the existence of a MOC file will automatically enable remote app configuration via HPCC.
Note: Your MOC file can be updated even after your app has been published.
Caution: Only one MOC file is allowed per app, no matter how many versions of the app have been published. Therefore, you should either require app updates or make sure all versions of your app are able to handle configurations that might be created with future/modified MOC files.
Caution: It may sometimes be necessary to include sensitive information in an app’s configuration (passwords, etc.). Such information should always be implemented as “write-only”. In other words, when your app receives a configuration containing a password (or other sensitive information), it should remove the password immediately, store it securely (e.g. use EncryptedSharedPreferences), and overwrite the configuration omitting the password. That way, when the configuration is retrieved from the device the password is not present.