Quickstart¶
This page provides a concise end-to-end walkthrough for running a migration. For detailed command options and behavior, see Command Reference.
Prerequisites checklist¶
Before running any commands, confirm the following:
Environment
- Node.js 22 or later is installed:
node --version - AWS CLI is installed and configured:
aws sts get-caller-identity --profile - Single AWS account in an Amazon Connect-supported region
Permissions
- IAM role or profile has the required permissions. See setting up the IAM Role.
Amazon Connect
- An Amazon Connect instance is available, or use the express-setup command to create one.
- Outbound campaigns are enabled on the Connect instance.
- The Amazon Connect instance has a Q_MESSAGE_TEMPLATES knowledge base integration configured (required for template import). This integration is created automatically when outbound campaigns are enabled. If you have not yet enabled outbound campaigns, see Set up Amazon Connect outbound campaigns.
Install the tool¶
- Download the zip archive from the AWS Marketplace portal.
- Extract the zip archive to a local directory.
- Verify the tool runs:
node ./pinpoint-migration-tool.mjs --help
End-to-end migration steps¶
Run commands in the following order. Each step depends on the steps before it completing successfully.
Screenshots in this section are provided for reference only. The exact output displayed may vary depending on your AWS environment, configuration, and tool version.
Placeholders¶
The following placeholders are used in all commands on this page. Replace each one with the value for your environment before running a command.
| Placeholder | Value |
|---|---|
<region> |
Your AWS region, for example us-east-1 |
<profile> |
Your AWS CLI profile name, for example pinpoint-migration |
<pinpoint-app-id> |
Your Pinpoint application ID |
<connect-instance-id> |
Your Amazon Connect instance ID |
Note: These commands must be run from the directory where the zip archive was extracted.
Step 1 — Run the preflight scan¶
Validates your AWS environment. No resources are created or modified.
node ./pinpoint-migration-tool.mjs preflight -r <region> -p <profile> -a <pinpoint-app-id> -c <connect-instance-id>
Review the preflight report. Resolve any blocking issues before continuing.
Step 2 — Deploy bootstrap infrastructure¶
Deploys the CloudFormation stack with resources required by all subsequent commands.
node ./pinpoint-migration-tool.mjs bootstrap -r <region> -p <profile>
Run this command once per migration environment. Re-running updates the existing stack.
Step 3 (optional) — Provision a Connect instance¶
Skip this step if you already have an Amazon Connect instance configured for outbound campaigns. If you use express-setup, complete this step before proceeding to Step 4.
node ./pinpoint-migration-tool.mjs express-setup -r <region> -p <profile>
Step 4 — Migrate endpoints¶
Export Pinpoint endpoints to S3, then ingest them into Amazon Connect Customer Profiles. Endpoint import must complete before template or segment import.
Endpoint export jobs for large datasets can take significant time. The command displays the export job ID immediately. Use --job-id to check status without re-running the full export.
node ./pinpoint-migration-tool.mjs export-endpoints -r <region> -p <profile> -a <pinpoint-app-id>
node ./pinpoint-migration-tool.mjs import-endpoints -r <region> -p <profile> -i <connect-instance-id> -a <pinpoint-app-id>
Step 5 — Migrate templates¶
Export Pinpoint message templates to S3, then recreate them in Amazon Connect.
node ./pinpoint-migration-tool.mjs export-templates -r <region> -p <profile> -a <pinpoint-app-id>
node ./pinpoint-migration-tool.mjs import-templates -r <region> -p <profile> -i <connect-instance-id> -a <pinpoint-app-id>
Step 6 — Migrate segments¶
Export Pinpoint segment definitions to S3, then recreate them in Customer Profiles.
node ./pinpoint-migration-tool.mjs export-segments -r <region> -p <profile> -a <pinpoint-app-id>
node ./pinpoint-migration-tool.mjs import-segments -r <region> -p <profile> -i <connect-instance-id> -a <pinpoint-app-id>
Step 7 — Migrate campaigns¶
Export eligible campaigns to S3, then recreate them as Amazon Connect Outbound Campaigns.
node ./pinpoint-migration-tool.mjs export-campaigns -r <region> -p <profile> -a <pinpoint-app-id>
node ./pinpoint-migration-tool.mjs import-campaigns -r <region> -p <profile> -i <connect-instance-id> -a <pinpoint-app-id>
Step 8 — Migrate journeys¶
Export Pinpoint journeys to S3 as Contact Flow definitions, then import them into Amazon Connect.
node ./pinpoint-migration-tool.mjs export-journeys -r <region> -p <profile> -a <pinpoint-app-id>
node ./pinpoint-migration-tool.mjs import-journeys -r <region> -p <profile> -i <connect-instance-id> -a <pinpoint-app-id>
Step 9 — Review the migration report¶
After migration completes, review the migration report output and the migration state file in S3. See Post-Migration Actions.
Costs and Service Quotas¶
Amazon S3
The tool stages exported Pinpoint data in Amazon S3 during migration. Standard S3 storage charges apply to this data. For most migrations, the staged data is small and costs are typically less than $1.00 USD for the duration of the migration. Actual charges depend on the volume of endpoints being migrated and how long the staged data is retained after the migration completes.
To minimize ongoing charges, delete the S3 bucket or exported files after you have verified the migration results. For current S3 pricing, see Amazon S3 pricing.
Amazon Connect and other AWS services
No additional charges are incurred by running the migration tool itself. Standard service charges for Amazon Connect, Amazon Q in Connect, and Amazon Connect Customer Profiles apply once migrated resources are active and in use. These charges are based on your usage of those services and are not within the scope of this tool.
Service quotas
The tool validates applicable service quotas during the preflight check. If any quotas are insufficient for your migration, the preflight report will indicate which quotas need to be increased and provide guidance on submitting an AWS Support request. The tool will not proceed with migration if required quotas are not met.