App Custom Settings

IBM Data Shift provides various customizable configurations through custom user level settings.

Configuration Keys by Category

Device Management & Startup Checks

skipMDMCheck
- Description: defines whether or not to check the device's management state and if it's enrolled in a recognised environment. More information on how to define "recognised environments" here.
- Possible values: true / false
- Default Value: false.
mdmEnvironments
- Description: array of "environment" objects used by the app to recognize the machine's MDM environment.
- Possible values: array of dictionaries, each with the following structure
```
{ 
   name : String (required), 
   serverURL : String (required),
   reconPolicyID : String (optional, required if "skipJamfRecon" is set to "false" and "jamfReconMethod" is set to "selfServicePolicy")
}
```
- Default Value: set in the AppContext.swift file in the fallbackMdmEnvironments variable.
enrollmentRedirectionLink
- Description: the link where the app redirects the user if skipMDMCheck is set to false and no recognized MDM environment are found on the device.
- Possible values: String
- Example: https://www.someorg.com/enrolldoc
- Default Value: set in the AppContext.swift file in the fallbackEnrollmentRedirectionLink variable.

Post-Migration Steps

skipAppleIDCheck
- Description: determines whether or not to display the post-migration phase for Apple ID login verification.
- Possible values: true / false
- Default Value: false.
skipJamfRecon
- Description: specifies whether or not to perform an inventory update to Jamf Pro.
- Possible values: true / false
- Default Value: false.
jamfReconMethod (Mandatory if skipJamfRecon is set to false)
- Description: specifies what method to use to run the Jamf inventory update.
- Possible values:
  - direct -> The app runs sudo jamf recon command. The app will ask for the user Mac password.
  - selfServicePolicy -> Run a self service policy using deeplinks. The policy takes care of running the recon. The app tracks the recon in background. (More information on how to define the correct policy id here)
- Default Value: selfServicePolicy
storePath
- Description: the path to the Jamf self service.
- Possible values: String
- Example: /Applications/SelfService.app
- Default Value: value of the self_service_app_path set in the com.jamfsoftware.jamf domain, if available. Alternatively, the value set in the AppContext.swift file in the fallbackStorePath variable.

Migration Behavior

duplicateFilesHandlingPolicy
- Description: defines how to handle duplicate files on the target device.
- Possible values:
  - ignore -> Doesn't save the old file on the destination device.
  - move -> Move the file already available on the destination device to a backup folder on the Desktop called "Migration.Backup"
  - overwrite -> Overwrite the file already available on the destination device
- Default Value: overwrite.
backupPath
- Description: the user relative path to the migration backup folder. This folder is used to store the duplicate files found on the new device if the duplicateFilesHandlingPolicy value is set to move.
- Possible values: String
- Default Value: /Desktop/Migration.Backup or the value set in the AppContext.swift file in the fallbackBackupPath variable if defined.
excludedPathsList
- Description: represent a list of user's folder relative paths that needs to be excluded from the migration. Supports dynamic flags like $HOMEFOLDER and $APPFOLDER for flexible path definitions.
- Possible values: [ String ] (Array of String values)
- Supported Flags:
  - $HOMEFOLDER - Expands to the user's home directory
  - $APPFOLDER - Expands to the application's folder path
- Default Value: set in the AppContext.swift file in the defaultUrlExclusionList variable.
allowedPathsList
- Description: represent a list of user's folder relative paths that needs to be explicitely included in the migration. Supports dynamic flags like $HOMEFOLDER and $APPFOLDER for flexible path definitions.
- Possible values: [ String ] (Array of String values)
- Supported Flags:
  - $HOMEFOLDER - Expands to the user's home directory
  - $APPFOLDER - Expands to the application's folder path
- Default Value: set in the AppContext.swift file in the defaultExplicitAllowList variable.
excludedFileExtensions
- Description: represent a list of file extensions that needs to be ignored and so excluded from the migration.
- Possible values: [ String ] (Array of String values)
- Default Value: set in the AppContext.swift file in the defaultExcludedFileExtensions variable.
excludedFilePrefixes
- Description: represent a list of file name prefixes that need to be ignored and excluded from the migration.
- Possible values: [ String ] (Array of String values)
- Default Value: set in the AppContext.swift file in the defaultExcludedFilePrefixes variable.
  - Default includes: ["MigrationReport_", "~", ".DS_Store", ".localized"]
- Example:
```
<key>excludedFilePrefixes</key>
<array>
    <string>temp_</string>
    <string>cache_</string>
    <string>.</string>
</array>
```
- Use Case: Exclude temporary files, cache files, or hidden files based on naming patterns.

Feature Specific Customization

generateReport
- Description: Flag that specifies whether the app should generate a migration report on the desktop of the source device.
- Possible values: true / false
- Default Value: false

User Interface Customization

orgName
- Description: the Organization's name used within the text showed in the UI.
- Possible values: String
- Example: Mac@IBM
- Default Value: set in the AppContext.swift file in the fallbackOrgName variable.
networkServiceIdentifier
- Description: the advertised bonjour service identifier.
- Possible values: String
- Example: _migrator
- Default Value: set in the AppContext.swift file in the fallbackNetworkServiceIdentifier variable.
skipMigrationSummary
- Description: Flag that specifies whether the app should skip the Migration Summary/Recap view before starting the migration.
- Possible values: true / false
- Default Value: false
- Use Case: Enable this to streamline the migration process by skipping the confirmation/recap page.
showWelcomePageInfo
- Description: Flag that specifies whether the app should display version, copyright, and privacy information on the Welcome page.
- Possible values: true / false
- Default Value: false
- Use Case: Enable this to show app metadata and legal information on the initial screen.

Terms & Conditions

shouldRequireTAndCAcceptance
- Description: Flag that defines whether the app should require user acceptance of the Terms and Conditions before proceeding with migration.
- Possible values: true / false
- Default Value: false
- Use Case: Enable this when your organization requires explicit user consent before data migration.
termsConditionsURL
- Description: The URL string pointing to the app's terms and conditions document.
- Possible values:
  - Remote URL: https://example.com/terms.html
  - Local file: T&C.pdf (placed in app bundle's Contents/Resources directory)
- Default Value: null
- Note: If using a local file, ensure it's included in the app bundle during build. This link appears in the app's menu bar for easy user access.
privacyPolicyURL
- Description: The URL string pointing to the app's privacy policy. Accessible from the app menu.
- Possible values:
  - Remote URL: http://www.ibm.com/privacy
  - Local file: PrivacyPolicy.pdf (placed in app bundle's Contents/Resources directory)
- Default Value: null
- Note: If using a local file, ensure it's included in the app bundle during build. This link appears in the app's menu bar for easy user access.
thirdPartyNotices
- Description: The URL string pointing to the app's third party notices document. Accessible from the app menu.
- Possible values:
  - Remote URL: https://example.com/notices.html
  - Local file: TPNotices.pdf (placed in app bundle's Contents/Resources directory)
- Default Value: null
- Note: If using a local file, ensure it's included in the app bundle during build. This link appears in the app's menu bar for easy user access.

Custom Page Icons

Administrators can customize the icon displayed on each page of the migration workflow. Icons can be specified as:

Remote URLs (e.g., https://cdn.example.com/icon.png)
Local file paths relative to the user folder (e.g., /Documents/custom-icon.pdf)
Base64 encoded image data

Available Icon Configuration Keys:

welcomePageIcon
- Description: Custom icon for the Welcome/Initial page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
browserPageIcon
- Description: Custom icon for the Browser page (old device selecting new device)
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
serverPageIcon
- Description: Custom icon for the Server page (new device waiting for connection)
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
codeVerificationPageIcon
- Description: Custom icon for the Code Verification page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
setupPageIcon
- Description: Custom icon for the Setup/Migration Options selection page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
recapPageIcon
- Description: Custom icon for the Recap/Summary page (before migration starts)
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
migrationPageIcon
- Description: Custom icon for the Migration in Progress page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
jamfReconPageIcon
- Description: Custom icon for the Jamf Recon/Inventory Update page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
rebootPageIcon
- Description: Custom icon for the Reboot countdown page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon
finalPageIcon
- Description: Custom icon for the Final/Completion page
- Type: String (URL, file path, or base64)
- Default: Uses built-in icon

Example Icon Configuration:

<key>welcomePageIcon</key>
<string>https://cdn.company.com/migration-welcome.png</string>
<key>migrationPageIcon</key>
<string>/Documents/custom-migration-icon.pdf</string>

Configuration Profile Example

To configure these settings via a configuration profile, simply define the values as shown in the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Device Management & Startup Checks -->
    <key>skipMDMCheck</key>
    <false/>
    <key>mdmEnvironments</key>
    <array>
        <dict>
            <key>name</key>
            <string>Production</string>
            <key>serverURL</key>
            <string>https://some.server.url</string>
            <key>reconPolicyID</key>
            <string>000</string>
        </dict>
        <dict>
            <key>name</key>
            <string>QA</string>
            <key>serverURL</key>
            <string>https://some.server.url</string>
            <key>reconPolicyID</key>
            <string>000</string>
        </dict>
    </array>
    <key>enrollmentRedirectionLink</key>
    <string>https://www.some.org.enroll/doc</string>
    
    <!-- Post-Migration Steps -->
    <key>skipAppleIDCheck</key>
    <false/>
    <key>skipJamfRecon</key>
    <false/>
    <key>jamfReconMethod</key>
    <string>selfServicePolicy</string>
    <key>storePath</key>
    <string>/Applications/SelfService.app</string>
    
    <!-- Migration Behavior -->
    <key>duplicateFilesHandlingPolicy</key>
    <string>move</string>
    <key>backupPath</key>
    <string>/Desktop/Migration.Backup</string>
    <key>excludedPathsList</key>
    <array>
        <string>/some/path/1</string>
        <string>/some/path/2</string>
        <string>$HOMEFOLDER/Downloads</string>
        <string>$APPFOLDER/SomeApp.app</string>
    </array>
    <key>allowedPathsList</key>
    <array>
        <string>/Library/Application Support/SomeApp</string>
        <string>/Library/Preferences/com.example.plist</string>
        <string>$HOMEFOLDER/Library/ImportantFiles</string>
    </array>
    <key>excludedFileExtensions</key>
    <array>
        <string>vdi</string>
        <string>tmp</string>
    </array>
    <key>excludedFilePrefixes</key>
    <array>
        <string>temp_</string>
        <string>cache_</string>
    </array>
    
    <!-- User Interface Customization -->
    <key>orgName</key>
    <string>YourOrg</string>
    <key>networkServiceIdentifier</key>
    <string>_migrator_yourorg</string>
    <key>skipMigrationSummary</key>
    <false/>
    <key>showWelcomePageInfo</key>
    <true/>
    
    <!-- Terms & Conditions -->
    <key>shouldRequireTAndCAcceptance</key>
    <true/>
    <key>termsConditionsURL</key>
    <string>https://www.yourorg.com/terms</string>
    <key>privacyPolicyURL</key>
    <string>https://www.yourorg.com/privacy</string>
    <key>thirdPartyNotices</key>
    <string>https://www.yourorg.com/notices</string>
    
    <!-- Custom Page Icons (Optional) -->
    <key>welcomePageIcon</key>
    <string>https://cdn.yourorg.com/welcome-icon.png</string>
    <key>browserPageIcon</key>
    <string>custom-browser-icon.pdf</string>
    <key>serverPageIcon</key>
    <string>custom-server-icon.pdf</string>
    <key>codeVerificationPageIcon</key>
    <string>custom-code-icon.pdf</string>
    <key>setupPageIcon</key>
    <string>custom-setup-icon.pdf</string>
    <key>recapPageIcon</key>
    <string>custom-recap-icon.pdf</string>
    <key>migrationPageIcon</key>
    <string>custom-migration-icon.pdf</string>
    <key>jamfReconPageIcon</key>
    <string>custom-recon-icon.pdf</string>
    <key>rebootPageIcon</key>
    <string>custom-reboot-icon.pdf</string>
    <key>finalPageIcon</key>
    <string>custom-final-icon.pdf</string>
</dict>
</plist>

Afterward, you will need to create a new configuration profile in Jamf Pro (if one has not already been created for configuring PPPC values) and define a new "Application & Custom Settings" payload as shown below:

Usage Notes

Terms & Conditions Configuration

When enabling shouldRequireTAndCAcceptance, ensure that:

The termsConditionsURL points to a valid, accessible document
Users will be required to accept before proceeding with migration
The acceptance is stored locally and persists across app launches

Custom Icons Best Practices

Use PDF format for vector icons that scale well
PNG format is supported for raster images (recommended: 512x512px or higher)
Icons should be clear and recognizable at various sizes
Test icons in both light and dark mode if applicable
Keep file sizes reasonable (< 1MB per icon)

File Exclusion Strategy

The app combines both default exclusions and managed exclusions:

excludedPathsList + default exclusions = final exclusion list
excludedFileExtensions + default extensions = final extension list
excludedFilePrefixes + default prefixes = final prefix list
Use allowedPathsList to explicitly include paths that would otherwise be excluded

Using Dynamic Path Flags

Both excludedPathsList and allowedPathsList support dynamic flags for flexible path definitions:

$HOMEFOLDER: Automatically expands to the user's home directory (e.g., /Users/username)
$APPFOLDER: Automatically expands to the application's folder path

Examples:

$HOMEFOLDER/Downloads → /Users/username/Downloads
$APPFOLDER/Cache → /Applications/YourApp.app/Contents/Cache
$HOMEFOLDER/Library/Caches → /Users/username/Library/Caches

These flags ensure paths work correctly across different user accounts and system configurations without hardcoding specific usernames or paths.

Configuration Profile Deployment

To deploy these settings:

Create a new Configuration Profile in Jamf Pro
Add an "Application & Custom Settings" payload
Set the Preference Domain to your app's bundle identifier
Upload the XML plist with your custom settings
Scope to appropriate devices/users

Home

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

App Custom Settings

Configuration Keys by Category

Device Management & Startup Checks

Post-Migration Steps

Migration Behavior

Feature Specific Customization

User Interface Customization

Terms & Conditions

Custom Page Icons

Configuration Profile Example

Usage Notes

Terms & Conditions Configuration

Custom Icons Best Practices

File Exclusion Strategy

Using Dynamic Path Flags

Configuration Profile Deployment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally