Here is a revised proposal taking into account @tomsmyth's excellent comments:
This is a proposed optional extension to the core OpenRosa standards for OpenRosa-compliant servers to provide client settings. The only component of this extension is a /client-configuration endpoint. A GET request to this endpoint results in a response with a JSON body.
The JSON body contains at most two top-level objects with keys "general" and "admin". Each of these objects has a set of optional properties.
{
"general" : {
"protocol": {"odk_default", "google_sheets", "other"},
...
},
"admin" : {
"admin_pw": String,
...
},
}
The general and admin split is because Collect lets users set an admin password and disable some subset of functionality. Having two separate objects makes it possible to use the same key for the actual setting and whether or not it should be enabled. This also matches the structure of the existing Collect settings QR code. Clients could choose to support some subset of the optional settings keys.
See also Proposal: publish a settings key/value standard.
Similar to the formList endpoint, the standard would leave it up to servers how to generate this settings file. For example, it may be up to a user to log into the server and select from a series of named configurations or a project administrator may impose a configuration on all users collecting data for that project. This will depend on the design of the server.
The standard would leave it up to clients when (if ever) to actually fetch those settings.
Remaining questions:
- Does this make sense for Enketo (@Martijnr) and iXForms (@Xiphware)? For Enketo, I imagine it would be requested when form resources are fetched from the server. I believe iXForms has a required login so that would be a natural time to make the call.
- Is the
general/adminstructure ok even if it sounds like Collect may be the only client that usesadmin? - Is it ok to say all keys are optionally supported by clients? This puts a burden on users of verifying which settings are supported by which clients. It could be confusing if a user sets some keys, uses both Collect and Enketo, and only some subset of keys are honored by each. I'm thinking that we should add that clients must show the user a list of unsupported keys in the configuration.
- Should this spec say anything about whether clients should continue to allow manual changes to settings after having pulled a remote configuration or about periodic polling? Or is this up to each client to define and document?