Creating and running the Amazon Cognito user pool import job
This section describes how to create and run the user pool import job by using the Amazon Cognito console and the AWS Command Line Interface.
Importing users from a .csv file (console)
The following procedure describes how to import the users from the
.csv
file.
To import users from the .csv file (console)
-
Choose Create import job.
-
Enter a Job name. Job names can contain uppercase and lowercase letters (a-z, A-Z), numbers (0-9), and the following special characters: + = , . @ and -.
-
If this is your first time creating a user import job, the AWS Management Console will automatically create an IAM role for you. Otherwise, choose an existing role from the IAM Role list, or let the AWS Management Console create a new role for you.
-
Choose Upload CSV and select the
.csv
file to import users from. -
Choose Create job.
-
To start the job, choose Start.
Importing users (AWS CLI)
The following CLI commands are available for importing users into a user pool:
-
create-user-import-job
-
get-csv-header
-
describe-user-import-job
-
list-user-import-jobs
-
start-user-import-job
-
stop-user-import-job
To get the list of command line options for these commands, use the help
command line option. For example:
aws cognito-idp get-csv-header help
Creating a user import job
After you create your .csv
file, create a user import job by
running the following CLI command, where JOB_NAME
is the name
you're choosing for the job, USER_POOL_ID
is the user pool ID for
the user pool into which the new users will be added, and
ROLE_ARN
is the role ARN you received in Creating the
CloudWatch Logs IAM role (AWS CLI, API):
aws cognito-idp create-user-import-job --job-name "
JOB_NAME
" --user-pool-id "USER_POOL_ID
" --cloud-watch-logs-role-arn "ROLE_ARN
"
The PRE_SIGNED_URL
returned in the response is valid for 15
minutes. After that time, it will expire and you must create a new user import job to get a
new URL.
Example Sample response:
{ "UserImportJob": { "Status": "Created", "SkippedUsers": 0, "UserPoolId": "
USER_POOL_ID
", "ImportedUsers": 0, "JobName": "JOB_NAME
", "JobId": "JOB_ID
", "PreSignedUrl": "PRE_SIGNED_URL
", "CloudWatchLogsRoleArn": "ROLE_ARN
", "FailedUsers": 0, "CreationDate": 1470957431.965 } }
Status values for a user import job
In the responses to your user import commands, you'll see one of the following
Status
values:
-
Created
- The job was created but not started. -
Pending
- A transition state. You have started the job, but it has not begun importing users yet. -
InProgress
- The job has started, and users are being imported. -
Stopping
- You have stopped the job, but the job has not stopped importing users yet. -
Stopped
- You have stopped the job, and the job has stopped importing users. -
Succeeded
- The job has completed successfully. -
Failed
- The job has stopped due to an error. -
Expired
- You created a job, but did not start the job within 24-48 hours. All data associated with the job was deleted, and the job can't be started.
Uploading the .csv file
Use the following curl
command to upload the .csv file containing your user
data to the presigned URL that you obtained from the response of the
create-user-import-job
command.
curl -v -T "
PATH_TO_CSV_FILE
" -H "x-amz-server-side-encryption:aws:kms" "PRE_SIGNED_URL
"
In the output of this command, look for the phrase "We are completely uploaded and
fine"
. This phrase indicates that the file was uploaded successfully.
Describing a user import job
To get a description of your user import job, use the following command, where
USER_POOL_ID
is your user pool ID, and
JOB_ID
is the job ID that was returned when you created the
user import job.
aws cognito-idp describe-user-import-job --user-pool-id "
USER_POOL_ID
" --job-id "JOB_ID
"
Example Sample response:
{ "UserImportJob": { "Status": "Created", "SkippedUsers": 0, "UserPoolId": "
USER_POOL_ID
", "ImportedUsers": 0, "JobName": "JOB_NAME
", "JobId": "JOB_ID
", "PreSignedUrl": "PRE_SIGNED_URL
", "CloudWatchLogsRoleArn":"ROLE_ARN
", "FailedUsers": 0, "CreationDate": 1470957431.965 } }
In the preceding sample output, the PRE_SIGNED_URL
is the URL
that you uploaded the .csv
file to. The
ROLE_ARN
is the CloudWatch Logs role ARN that you received when you
created the role.
Listing your user import jobs
To list your user import jobs, use the following command:
aws cognito-idp list-user-import-jobs --user-pool-id "
USER_POOL_ID
" --max-results 2
Example Sample response:
{ "UserImportJobs": [ { "Status": "Created", "SkippedUsers": 0, "UserPoolId": "
USER_POOL_ID
", "ImportedUsers": 0, "JobName": "JOB_NAME
", "JobId": "JOB_ID
", "PreSignedUrl":"PRE_SIGNED_URL
", "CloudWatchLogsRoleArn":"ROLE_ARN
", "FailedUsers": 0, "CreationDate": 1470957431.965 }, { "CompletionDate": 1470954227.701, "StartDate": 1470954226.086, "Status": "Failed", "UserPoolId": "USER_POOL_ID
", "ImportedUsers": 0, "SkippedUsers": 0, "JobName": "JOB_NAME
", "CompletionMessage": "Too many users have failed or been skipped during the import.", "JobId": "JOB_ID
", "PreSignedUrl":"PRE_SIGNED_URL
", "CloudWatchLogsRoleArn":"ROLE_ARN
", "FailedUsers": 5, "CreationDate": 1470953929.313 } ], "PaginationToken": "PAGINATION_TOKEN
" }
Jobs are listed in chronological order from last created to first created. The
PAGINATION_TOKEN
string after the second job indicates that
there are additional results for this list command. To list the additional results, use the
--pagination-token
option as follows:
aws cognito-idp list-user-import-jobs --user-pool-id "
USER_POOL_ID
" --max-results 10 --pagination-token "PAGINATION_TOKEN
"
Starting a user import job
To start a user import job, use the following command:
aws cognito-idp start-user-import-job --user-pool-id "
USER_POOL_ID
" --job-id "JOB_ID
"
Only one import job can be active at a time per account.
Example Sample response:
{ "UserImportJob": { "Status": "Pending", "StartDate": 1470957851.483, "UserPoolId": "
USER_POOL_ID
", "ImportedUsers": 0, "SkippedUsers": 0, "JobName": "JOB_NAME
", "JobId": "JOB_ID
", "PreSignedUrl":"PRE_SIGNED_URL
", "CloudWatchLogsRoleArn": "ROLE_ARN
", "FailedUsers": 0, "CreationDate": 1470957431.965 } }
Stopping a user import job
To stop a user import job while it is in progress, use the following command. After you stop the job, it cannot be restarted.
aws cognito-idp stop-user-import-job --user-pool-id "
USER_POOL_ID
" --job-id "JOB_ID
"
Example Sample response:
{ "UserImportJob": { "CompletionDate": 1470958050.571, "StartDate": 1470958047.797, "Status": "Stopped", "UserPoolId": "
USER_POOL_ID
", "ImportedUsers": 0, "SkippedUsers": 0, "JobName": "JOB_NAME
", "CompletionMessage": "The Import Job was stopped by the developer.", "JobId": "JOB_ID
", "PreSignedUrl":"PRE_SIGNED_URL
", "CloudWatchLogsRoleArn": "ROLE_ARN
", "FailedUsers": 0, "CreationDate": 1470957972.387 } }