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

Android project
  • Your app source should be Gradle-based and must build successfully before you start the migration process (./gradlew clean build).
  • gradlew must be executable.
  • Android SDK 31 or later, discoverable through ANDROID_HOME or ANDROID_SDK_ROOT.
  • JDK 17 or later.

AI coding agent
  • Cursor, Kiro, Codex, or an equivalent agent with file read, file write, shell execution, and network access 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.

Access to the BlackBerry Maven repository

The migration process requires network access to the BlackBerry Maven repository during the first prompt (00pre-bootstrap.md). If access cannot be established through your network, the toolkit stops all processes. The toolkit does not support an offline mode.

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 00pre-bootstrap.md, you will be asked to provide these values. They are collected and written to dynamics-migration-tool/output/bootstrap.json. Prompt 02-create-settings-json.md reads the values from that file and does not prompt for them again.

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 in the project root is recommended, but not required. When Git is present, the prompt 00pre-bootstrap.md captures a fingerprint, checks the working tree state, and creates a backup branch.

Grant required permissions to your AI coding agent
The prompt 00pre-bootstrap.md will verify that your agent has the necessary permissions to execute the migration process, and will stop the process if the permissions are not granted. 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
  • Enable network access (required to access the BlackBerry Maven repository)
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, manifest, resource, 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.

Deferral

The migration process will generate a bootstrap.json file in the output repository. In bootstrap.json, you can add domains to deferredDomains[] with developerSignedOff: true. The agent must not edit deferrals. Non-waivable domains include authorization, policy management, secure clipboard, transport hardening, and externalStorage.

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:
  • Jetpack DataStore
  • Room without the BlackBerry Dynamics bridge; use SupportSQLiteOpenHelper.Factory in prompt 04-sqlite-migrate-to-secure-sql.md
  • WorkManager using secure APIs before authorization
  • Firebase/Google APIs on sensitive enterprise data
  • Deep links or App Links for enterprise data

For more information about software requirements and Android feature support by the BlackBerry Dynamics SDK, see the BlackBerry Dynamics SDK Development Guide.