StartAssetBundleImportJob DescribeAssetBundleImportJob ListAssetBundleImportJobs Examples

Asset bundle import operations

Use asset bundle import operations to import Amazon QuickSight assets from an QuickSight bundle file that's generated by an earlier export job. The following statements apply to asset bundle import operations.

You can only import QuickSight JSON bundles with the QuickSight asset bundle APIs. CloudFormation JSON files can only be imported using the AWS CloudFormation console or APIs. Both QuickSight JSON and CloudFormation JSON files support property value overrides. If you want to generate a QuickSight JSON file, property overrides are specified when you use an import API call. If you want to generate a CloudFormation JSON file, property overrides are configured with the cloud-formation-override-property-configuration parameter when you create or update the CloudFormation stack. You can import files that were created from your account, or you can import asset bundle files that were generated from other QuickSight accounts. When you create a new import job, you can choose to provide overrides when you configure the import job.
The asset bundle import operations only support .qs format zip files. The .qs format file that contains the asset bundle that you want to import is in an Amazon S3 bucket or in a BASE64 encoded file that you can add to the import job directly. The S3 bucket exists in the same AWS account as your QuickSight account.
All import jobs run asynchronously after they are started. Poll the status of an import job with a DescribeAssetBundleImportJob API call to know the current status of the job. If an asset bundle import job fails, you can choose to have all assets that were successfully imported during the failed job rollback. Information about the error that caused the job to fail is returned in the job description of a DescribeAssetBundleImportJob API call.
All of an imported assets' dependencies must be present for an asset import job to succeed. You can include all dependencies of the asset when you export it. Alternatively, you can configure all dependencies in the QuickSight account that you want to move the asset into. For example, to import a dashboard, the dataset, data source, and theme that the dashboard uses must exist in the account that you're importing the asset into. The caller must have permissions to describe, create, and update all QuickSight resources located in the asset that you want to import.
After an import job succeeds, grant permissions to all users or user groups that need to access the newly created resource. If you want to override the properties of the QUICKSIGHT JSON format export, provide the new values when you start an import job. If you want to override properties in a CLOUDFORMATION JSON format export, provide the property names to override when you start an export job. Then and add the new values when the stack is created in the CloudFormation console or with the AWS CloudFormation APIs.

Permissions are not propagated through the asset bundles. You can update asset permissions with an UpdateDashboardPermissions API call.

Use the following sections to learn more about the asset bundle import API operations.

StartAssetBundleImportJob

Import jobs are configured with the StartAssetBundleImportJobRequest object.

Import jobs are identified by an AssetBundleImportJobId that you provide when you create the new import job. This ID is unique while the job is running. After the job is completed, you can reuse this ID for another job.

Provide an Amazon S3 uri or a base64-encoded ZIP file to the request. If you use an Amazon S3 uri, the caller must have GetObject permissions. All assets contained in the file are imported into the target account.

You can choose to configure override values to be applied to specific assets when they are imported. All imported data sources must have credential overrides. You can store asset credentials in AWS Secrets Manager or you can set a username and password directly into an override. If you use Secrets Manager, provide the secret ARN in the data source override. The caller must have GetSecretValue and DescribeSecret permissions to configure the Secrets Manager secret to the override.

All import jobs run asynchronously after they are started. Poll the status of an export job with a DescribeAssetBundleImportJob call to know the current status of the job. Callers must have read and write permissions for all of the resource types that are exported, including the optional dependencies that are included in the export job.

When an asset import job fails, you can choose to have all assets that were successfully imported during the failed job roll back automatically. If you don't choose to roll back the assets, successfully imported assets will still exist in the account that they are imported to. Information about the error that caused the job to fail is returned in the job description of a DescribeAssetBundleImportJob API call.

For more information about the StartAssetBundleImportJob operation, see StartAssetBundleImportJob in the Amazon QuickSight API Reference.

VPC overrides

When you make a StartAssetBundleImportJob API call, provide an override parameter for the VPC connection that's configured to your QuickSight account. You can find the OverrideParameters value in the asset bundle file that was created when the asset was exported. The following example shows an OverrideParameters structure that uses the PrefixForAllResources value.


"OverrideParameters": {
  "VPCConnections": [
    {
        "VPCConnectionId": "<PrefixForAllResources<VPCConnectionId in asset bundle file" 
        "DnsResolvers": [ "string" ],
        "Name": "string", 
        "RoleArn": "string", 
        "SecurityGroupIds": [ "string" ], 
        "SubnetIds": [ "string" ]

     }
  ]
 }

For more information about setting up a VPC connection in QuickSight, see Configuring the VPC connection with the QuickSight CLI.

Permissions

The following statements apply to asset bundle import permissions.

Asset bundle import operations support up to 64 principals.
The final state of an asset bundle's permissions are determined by the following.
- If the OverridePermissions parameter is provided in the input, all existing permissions are replaced by the permissions that are specified in the OverridePermissions parameter.
- If the asset bundle was exported with permissions, all existing permissions are replaced by the permissions that are in the exported asset bundle's file.
- If neither of the above conditions are met, no changes are made to the asset's permissions.
If the caller executes an asset bundle import job from a different account than the account that the asset bundle was exported from, there are differences in the the user, group, and namespace principal ARNs. When this happens, provide the correct ARN values in the OverridePermissions parameter.

DescribeAssetBundleImportJob

Use the DescribeAssetBundleImportJob operation to obtain the current status of an existing export job that's up to 14 days old. You can also use this operation to review a specified job's configuration.

Failed import jobs return error information in their description. Poll this operation until the import job that you want the status of has succeeded or failed.

For more information about the DescribeAssetBundleImportJob operation, see DescribeAssetBundleImportJob in the Amazon QuickSight API Reference.

ListAssetBundleImportJobs

Use the ListAssetBundleImportJobs operation to retrieve a list of all import jobs that were created in the last 14 days. Import jobs are listed in the order that they were started, starting with the most recently started job. If you expect to have multiple lists by this operation, you can choose to specify a maximum page size to be returned and use a pagination token.

For more information about the ListAssetBundleImportJobs operation, see ListAssetBundleImportJobs in the Amazon QuickSight API Reference.

Examples

The following example creates an asset bundle import job for a file that is located in the caller's Amazon S3 bucket.


# upload your bundle to an S3 bucket in your account
aws s3 cp ~/qs-bundle.qs s3://bucket/key/qs-bundle.qs

aws quicksight start-asset-bundle-import-job
  --aws-account-id AWSACCOUNTID \
  --asset-bundle-import-job-id JOBID \
  --asset-bundle-import-source '{"S3Uri": "s3://bucket/key/qs-bundle.qs"}' \
  --failure-action ROLLBACK

# poll job description until status is success (or failed)
aws quicksight describe-asset-bundle-import-job
  --aws-account-id AWSACCOUNTID \
  --asset-bundle-import-job-id JOBID

# grant yourself or others permissions to view/modify the imported resources (for more information, see UpdateDashboardPermissions in the Amazon QuickSight API Reference)

# open your Amazon QuickSight site in your browser and confirm the imported resources (important)

The following example creates an asset bundle import job with a bundle file that's uploaded directly. This example also uses data source credential overrides.


aws quicksight start-asset-bundle-import-job
  --aws-account-id AWSACCOUNTID \
  --asset-bundle-import-job-id JOBID \
  --asset-bundle-import-source-bytes fileb://~/qs-bundle.qs \
  --asset-bundle-import-source-bytes fileb://~/qs-bundle.qs \
  --override-parameters '{"DataSources": [{"DataSourceId": "some-data-source-id", "Credentials": {"CredentialPair": {"Username": "some-username", "Password": "some-password"}}}]}' \
  --failure-action ROLLBACK

# poll job description until status is success (or failed)
aws quicksight describe-asset-bundle-import-job
  --aws-account-id AWSACCOUNTID \
  --asset-bundle-import-job-id JOBID

# grant yourself or others permissions to view/modify the imported resources (for more information, see UpdateDashboardPermissions in the Amazon QuickSight API Reference)

# open your Amazon QuickSight site in your browser and confirm the imported resources (important)

The Override parameters also accept local files, as shown in the example below.


--override-parameters file://import-override-parameter-prod.json \
--override-permissions file://import-override-permission-prod.json \
--override-tags file://import-override-tags-prod.json \

If callers want to assign different permissions to exported assets, they can provide an override object at import. There are two ways that this can be done.

Explicitly specify the resource IDs. If a prefix ID is specified, include the prefix in the resource ID.
Use the wildcard "*" to represent all resources of a specific type in the asset bundle files.

In the example below, all dashboards that are included in the asset bundle file are imported with specified permissions.


// import-override-permission-prod.json
{
    "DataSources": [
        {
            "DataSourceIds": ["DATASOURCEID"],
            "Permissions": {
                "Principals": ["arn:aws:quicksight:REGION:AWSACCOUNTID:user/default/USERIR"],
                "Actions": [
                    "quicksight:UpdateDataSourcePermissions",
                    "quicksight:DescribeDataSourcePermissions",
                    "quicksight:PassDataSource",
                    "quicksight:DescribeDataSource",
                    "quicksight:DeleteDataSource",
                    "quicksight:UpdateDataSource"
                ]
            }
        }
    ],
    "DataSets": [
        {
            "DataSetIds": ["DATASETID"],
            "Permissions": {
                "Principals": ["arn:aws:quicksight:REGION:AWSACCOUNTID:user/default/USERIR"],
                "Actions": [
                    "quicksight:DeleteDataSet",
                    "quicksight:UpdateDataSetPermissions",
                    "quicksight:PutDataSetRefreshProperties",
                    "quicksight:CreateRefreshSchedule",
                    "quicksight:CancelIngestion",
                    "quicksight:PassDataSet",
                    "quicksight:ListRefreshSchedules",
                    "quicksight:UpdateRefreshSchedule",
                    "quicksight:DeleteRefreshSchedule",
                    "quicksight:DescribeDataSetRefreshProperties",
                    "quicksight:DescribeDataSet",
                    "quicksight:CreateIngestion",
                    "quicksight:DescribeRefreshSchedule",
                    "quicksight:ListIngestions",
                    "quicksight:DescribeDataSetPermissions",
                    "quicksight:UpdateDataSet",
                    "quicksight:DeleteDataSetRefreshProperties",
                    "quicksight:DescribeIngestion"
                ]
            }
        }
    ],
    "Themes": [
        {
            "ThemeIds": ["THEMEID"],
            "Permissions": {
                "Principals": ["arn:aws:quicksight:REGION:AWSACCOUNTID:user/default/USERIR"],
                "Actions": [
                    "quicksight:ListThemeVersions",
                    "quicksight:UpdateThemeAlias",
                    "quicksight:DescribeThemeAlias",
                    "quicksight:UpdateThemePermissions",
                    "quicksight:DeleteThemeAlias",
                    "quicksight:DeleteTheme",
                    "quicksight:ListThemeAliases",
                    "quicksight:DescribeTheme",
                    "quicksight:CreateThemeAlias",
                    "quicksight:UpdateTheme",
                    "quicksight:DescribeThemePermissions"
                ]
            }
        }
    ],
    "Analyses": [
        {
            "AnalysisIds": ["ANALYSISIDS"],
            "Permissions": {
                "Principals": ["arn:aws:quicksight:REGION:AWSACCOUNTID:user/default/USERIR"],
                "Actions": [
                    "quicksight:RestoreAnalysis",
                    "quicksight:UpdateAnalysisPermissions",
                    "quicksight:DeleteAnalysis",
                    "quicksight:DescribeAnalysisPermissions",
                    "quicksight:QueryAnalysis",
                    "quicksight:DescribeAnalysis",
                    "quicksight:UpdateAnalysis"
                ]
            }
        }
    ],
    "Dashboards": [
        {
            "DashboardIds": ["*"],
            "Permissions": {
                "Principals": ["arn:aws:quicksight:REGION:AWSACCOUNTID:user/default/USERIR"],
                "Actions": [
                    "quicksight:DescribeDashboard",
                    "quicksight:ListDashboardVersions",
                    "quicksight:UpdateDashboardPermissions",
                    "quicksight:QueryDashboard",
                    "quicksight:UpdateDashboard",
                    "quicksight:DeleteDashboard",
                    "quicksight:DescribeDashboardPermissions",
                    "quicksight:UpdateDashboardPublishedVersion",
                    "quicksight:UpdateDashboardLinks"
                ]
            }
        }
    ]
}

If callers want to assign different tags to imported assets, they can provide an override object at import. There are two ways that this can be done.

Explicitly specify the resource IDs. If a prefix ID is specified, include the prefix in the resource ID.
Use the wildcard "*" to represent all resources of a specific type in the asset bundle files.

In the example below, all dashboards that are included in the asset bundle file are imported with specified tags.


// import-override-tags-prod.json

{
    "DataSources": [
        {
            "DataSourceIds": ["DATASOURCEID"],
            "Tags": [
                {
                    "Key": "tagkey_datasource",
                    "Value": "tagvalue_datasource"
                },
                {
                    "Key": "tagkey2_datasource",
                    "Value": "tagvalue2_datasource"
                }
            ]
        }
    ],
    "DataSets": [
        {
            "DataSetIds": ["*"],
            "Tags": [
                {
                    "Key": "tagkey_dataset",
                    "Value": "tagvalue_dataset"
                },
                {
                    "Key": "tagkey2_dataset",
                    "Value": "tagvalue2_dataset"
                }
            ]
        }
    ],
    "Themes": [
        {
            "ThemeIds": ["*"],
            "Tags": [
                {
                    "Key": "tagkey_theme",
                    "Value": "tagvalue_theme"
                },
                {
                    "Key": "tagkey2_theme",
                    "Value": "tagvalue2_theme"
                }
            ]
        }
    ],
    "Analyses": [
        {
            "AnalysisIds": ["*"],
            "Tags": [
                {
                    "Key": "tagkey_analysis",
                    "Value": "tagvalue_analysis"
                },
                {
                    "Key": "tagkey2_analysis",
                    "Value": "tagvalue2_analysis"
                }
            ]
        }
    ],
    "Dashboards": [
        {
            "DashboardIds": ["*"],
            "Tags": [
                {
                    "Key": "tagkey_dashboard",
                    "Value": "tagvalue_dashboard"
                },
                {
                    "Key": "tagkey2_dashboard",
                    "Value": "tagvalue2_dashboard"
                }
            ]
        }
    ]
}

If you want to import an asset bundle file with Strict mode, use the OverrideValidationStrategy parameter and set StrictModeForAllResources to True. The following example calls the StartAssetBundleImportJob API with Strict mode.


aws quicksight start-asset-bundle-import-job
--aws-account-id AWSACCOUNTID \
--asset-bundle-import-job-id JOBID \
--asset-bundle-import-source-bytes fileb://~/qs-bundle.qs \
--override-validation-strategy '{"StrictModeForAllResources":true}'

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Asset bundle export operations

Dashboard operations