BlackBerry Dynamics SDK migration toolkit: Prerequisites and considerations

Before you use the migration toolkit, verify that your development environment meets the following requirements:

Item

Description

iOS project
  • Your app source must build successfully before you start the migration process. For a .xcworkspace project (CocoaPods or a multi-project workspace), run xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Debug -destination 'generic/platform=iOS Simulator' build. For a .xcodeproj-only project, run xcodebuild -project YourApp.xcodeproj -scheme YourApp -configuration Debug -destination 'generic/platform=iOS Simulator' build.
  • Xcode 15 or 16, with command-line tools installed.
  • iOS deployment target 17.0 or later.
  • CocoaPods, if your project uses CocoaPods integration.

AI coding agent
  • Cursor, Kiro, Codex, GitHub Copilot, or an equivalent agent with file read, file write, and shell execution capabilities.
  • If your agent does not auto-load steering files (for example, GitHub Copilot), run setup with --agent generic and paste steering and prompt files for each migration step. For more information, see Prepare your migration environment.

BlackBerry Dynamics entitlements

You must define a BlackBerry Dynamics entitlement ID (GDApplicationID) and entitlement version (GDApplicationVersion). For more information, see Using an entitlement ID and version to uniquely identify a BlackBerry Dynamics app.

When your AI coding agent runs prompt 02-configure-info-plist.md, it stops and asks you for these values and your app setup type. The agent registers required BlackBerry Dynamics URL schemes with the native bundle identifier, not GDApplicationID.

After the app is converted to a BlackBerry Dynamics app, your organization's BlackBerry UEM administrator must register the entitlement ID and entitlement version of the app with UEM to deploy the app to users. For more information, see Add an internal BlackBerry Dynamics app entitlement.

Git repository

A Git repository with a pre-migration baseline commit is required before source changes begin. Git must be installed locally. No remote repository, GitHub account, or network access is required for the baseline.

If your working copy is not already a Git repository, prompt 00pre-bootstrap.md asks for consent to initialize Git, exclude toolkit artifacts, and create a pre-migration baseline commit. If Git identity is not configured, set user.name and user.email locally or globally before you continue.

Grant required permissions to your AI coding agent
The migration process requires that your agent can read and write project files and execute shell commands. You must grant the following permissions manually before you start the migration process (permission names may vary depending on your chosen agent):
  • Enable file read/write
  • Enable shell command execution
If you are using Cursor, grant the following permissions:
  • Auto-Run Mode (Ask Every Time, Run in Sandbox, or Run Everything)
  • Auto-Run Network Access (sandbox.json Only, sandbox.json + Defaults, or Allow All)

For the actual migration run, provide the agent with full access to the target project outside the sandbox so that it can apply required code, build, Info.plist, and validation updates directly. Sandbox-restricted execution is suitable for analysis-only runs, but it may prevent the agent from completing project-wide changes. Enable full access in a trusted local development environment, and review the generated migration report and code diff before you commit changes.

Web browser

You require a web browser to view the visual migration report that the toolkit creates (migration-report-viewer.html).

Unsupported features

The migration toolkit does not support the following:
  • SwiftData (@Model, ModelContainer, ModelContext)
  • App Extensions (WidgetKit, SiriKit, Share Extensions, and similar)
  • Bitcode
  • App Clips
  • CloudKit and iCloud for sensitive data
  • SFSafariViewController for enterprise use cases
  • Certain WKWebView features (for example, WKDownload, WKFindConfiguration, non-pageWorld content worlds)
  • Flutter hybrids; the 00pre and 00 prompts detect and stop the code migration for Flutter-based apps

Unsupported features are listed in the unsupportedFeatures section of the migration report. For more information about software requirements and iOS feature support by the BlackBerry Dynamics SDK, see the BlackBerry Dynamics SDK Development Guide.