Customize Configuration Workflow for iOS

When the MicroStrategy Mobile app is installed on a mobile device, the configuration preferences in the app, referred to as bundled preferences, are stored on the device in a read-only file. A separate writeable file, referred to as device preferences, is created in the document store on the device. The app uses the device preferences. Device preferences can be updated in a number of ways:

• When a user makes changes to the configuration settings on the device
  User changes are always used to update device preferences.
  
• When the app makes changes programmatically
  Programmatic changes may or may not be used to update device preferences, depending on the code.
  
• When a mobile configuration URL is applied
  New configuration settings from the mobile server are always used to update device preferences.
  
• When the app is updated
  Bundled preferences in the app update may or may not be used to update device preferences, as described below.
  

When the MicroStrategy Mobile app is updated, the values of the following MicroStrategy properties, together with the configuration ID and counter of both sets of preferences, determine whether new bundled preferences are copied to the writeable file in the document store, or the existing device preferences remain in the document store. You set the values of these properties in the mstrcustomizations.plist file.

• UsesBundledPreferences
  A flag that indicates whether to overwrite the device preferences with the bundled preferences, when a new version of the app is installed on the device.
  
  • If this flag is set to NO, the bundled preferences will not be copied to the document store on the device during the first install of the MicroStrategy Mobile app, or be used to overwrite the existing device preferences in subsequent installations.
  • If this flag is set to YES, the values of OverrideExistingPreferences and UpdateExistingPreferences determine whether the bundled preferences are used to overwrite the existing device preferences.

• OverrideExistingPreferences
  A flag that indicates whether to overwrite the device preferences with the bundled preferences, when a new version of the app is installed on the device. This flag takes effect only if:
  • UsesBundledPreferences is set to YES, and
  • The configuration ID of the bundled preferences is different from the configuration ID of the device preferences.

• UpdateExistingPreferences
  A flag that indicates whether to overwrite the device preferences with the bundled preferences, when a new version of the app is installed on the device. This flag takes effect only if:
  • UsesBundledPreferences is set to YES, and
  • The configuration ID of the bundled preferences is the same as the configuration ID of the device preferences, and
  • The configuration counter of the bundled preferences is greater than the configuration counter of the device preferences.

The diagram below illustrates the workflow for determining what will be stored in devices preferences, both during the initial installation of the MicroStrategy Mobile app and when it is updated. Following the diagram, there is a set of tables with expected results for various combinations of the three properties described above.

If UsesBundledPrefrences is set to NO, nothing will be written to the device preferences in the document store on the device when the MicroStrategy Mobile app is updated. The results tables below assume that UsesBundledPrefrences is set to YES and that the other two preferences—OverrideExistingPreferences and UpdateExistingPreferences—have different combinations of values. The examples further assume that the updated MicroStrategy Mobile app has one of the following mobile configurations, with the associated configuration IDs and counter attributes

	Configuration ID	Counter
Config A	ZZZ	1
Config B	ZZZ	2
Config C	XYZ	1

The following tables show what happens to the device preferences when the app is updated with each configuration and the app is restarted, based on the values you assigned to each property.

UsesBundledPreferences = YES

UpdateExistingPreferences = YES

OverrideExistingPreferences = YES

	Device Preferences	Bundled Preferences	Device Preferences after restart
Case 1	A [ZZZ] [1]	B [ZZZ] [2]	B [ZZZ] [2]
Case 2	B [ZZZ] [2]	A [ZZZ] [1]	B [ZZZ] [2]
Case 3	A [ZZZ] [1]	C [XYZ] [1]	C [XYZ] [1]

UsesBundledPreferences = YES

UpdateExistingPreferences = NO

OverrideExistingPreferences = YES

	Device Preferences	Bundled Preferences	Device Preferences after restart
Case 1	A [ZZZ] [1]	B [ZZZ] [2]	A [ZZZ] [1]
Case 2	B [ZZZ] [2]	A [ZZZ] [1]	B [ZZZ] [2]
Case 3	A [ZZZ] [1]	C [XYZ] [1]	C [XYZ] [1]

UsesBundledPreferences = YES

UpdateExistingPreferences = YES

OverrideExistingPreferences = NO

 

	Device Preferences	Bundled Preferences	Device Preferences after restart
Case 1	A [ZZZ] [1]	B [ZZZ] [2]	B [ZZZ] [2]
Case 2	B [ZZZ] [2]	A [ZZZ] [1]	B [ZZZ] [2]
Case 3	A [ZZZ] [1]	C [XYZ] [1]	A [ZZZ] [1]

UsesBundledPreferences = YES

UpdateExistingPreferences = NO

OverrideExistingPreferences = NO

	Device Preferences	Bundled Preferences	Device Preferences after restart
Case 1	A [ZZZ] [1]	B [ZZZ] [2]	A [ZZZ] [1]
Case 2	B [ZZZ] [2]	A [ZZZ] [1]	B [ZZZ] [2]
Case 3	A [ZZZ] [1]	C [XYZ] [1]	A [ZZZ] [1]