Step 5: Verify that Your Uploaded Catalog Has No Errors
After you upload your catalog file, Amazon posts a report to your catalog bucket indicating success or failure for the import of your catalog data each time that you upload a new catalog file. Review this report to ensure there are no errors with your catalog. If there are errors, you need to interpret the messages contained in the ingestion report and troubleshoot your catalog file.
- Receiving and Understanding the Catalog Ingestion Report
- Retrieving Your Ingestion Report
- What's In the Ingestion Report?
- Acting on the Ingestion Report
- Ingestion Reports FAQ
- Next Steps
Receiving and Understanding the Catalog Ingestion Report
After you've uploaded your catalog data to the Amazon Simple Storage Service (S3) bucket for integration into the Amazon catalog, the catalog integration system generates an ingestion report within four hours to tell you whether the catalog file could be used. The report gives an overall success or failure status, identifies any problems found in the file, and provides details about each problem.
Retrieving Your Ingestion Report
The ingestion report, named report.html, is an HTML file placed in the same S3 bucket as your uploaded catalog file. You can opt to receive an email telling you that the new report is ready, providing a basic summary of its contents and giving you a command with which you can download the full report.
How to Receive Ingestion Status Notification Emails
To receive your ingestion report summary emails, ask your Amazon sales representative to add you to the distribution list for your catalog.
Success and failure emails are sent separately, so if you want to receive both, ask to be included on both lists. A report is generated once per upload or when the ingestion status changes.
How to Use the Information in the Email
The email that you receive provides the ingestion's success or failure status. If the ingestion fails, the errors are listed in the full report (rather than in the email). The email also contains an Amazon Web Services (AWS) command to retrieve the full report.
To use the AWS command to retrieve the report, you must first install the Amazon Web Services Command Line Interface (CLI) tool, after which you can use AWS commands in a normal command or terminal window. This ensures that your proprietary catalog information remains protected, because only someone with access rights to your S3 bucket can retrieve the report using that command.
Here's an example of the AWS command to retrieve the report. Copy the line from the email and paste it into your command or terminal window.
aws s3api get-object --bucket cdf-test --key reports/report.html --version-id FciuqMvVh2oWFv726L6Ytf8ECLbO6Kj0 report.html
When run successfully, this command downloads the report to your current folder. The downloaded file has the name report.html. (If you're curious about what that command is doing, see the AWS CLI Command Reference get-object page.)
In addition to the AWS CLI command, the email will also contain a link to access the report directly. This link is valid for 7 days. Note that anyone with this link can access the full report, so be aware of this when forwarding the email.
What's In the Ingestion Report?
The ingestion report has three sections:
- The summary, including the success or failure status
- Errors, warnings, and suggestions
- Counts of catalog entries added, removed, updated, or unchanged.
The Summary
Here is an example of the summary section of an ingestion report:
The summary includes a unique ID given to each ingestion attempt, the catalog that was used, when the ingestion attempt was made, and the result. There are two possible results:
-
Success: No errors were found in the catalog, although there still may be actionable warnings and suggestions. The catalog information was integrated into Amazon's catalog.
Note: You should still look at the Counts section to ensure that the results are as you expected. For instance, you could accidentally delete a big portion of your catalog and still have a successful ingestion as long as there are no errors in what remains. Only by reading beyond the Success glyph to notice that the number of entries removed was unexpectedly high would you suspect that something wasn't right. -
Failure: Errors prevented the catalog from being used. Your last successfully ingested catalog remains the active catalog. The Errors, Warnings, and Suggestions section of the report will give you specific information about what went wrong.
The ingestion in the example above failed due to nine errors. Many warnings and suggestions were also generated, but messages in these categories generally do not trigger a failure (image-related warnings and suggestions are the exception). Counts for added, removed, and updated are all 0 because the ingestion failed and the uploaded catalog was not used. The unchanged count of 0 indicates that there is no previous catalog to change.
Clicking on any of those boxes takes you to that section of the report.
Errors, Warnings, and Suggestions
This portion of the report is where you'll find the information that you'll need to fix any problems. You can view the report information by expanding some of the sections:
- Clicking the Details button for a section expands that section to list its individual messages. At the end of each message is the number of entries that generated it.
- Clicking the plus sign next to each message displays the IDs of the works that generated the message, and in some cases, an additional message with more details. Here's an example with two expanded errors:
Issues found in the Errors section cause an ingestion to fail; warnings and suggestions generally do not. Therefore, a successful ingestion report can still contain plenty of warnings and suggestions that you should examine.
Counts
The last section in the report provides specifics on the changes to your catalog due to the ingestion. Clicking the Details button in each category again shows the IDs of the works in each. If you have a list of expected changes, you can compare it against these lists as a final check.
If the ingestion failed, then the uploaded catalog was not used so the Added, Removed, and Updated values will be 0. The Unchanged value shows the number of catalog entries in your last successfully ingested catalog.
If the ingestion was successful, the Added, Removed, Updated, and Unchanged numbers should reflect your expected results. As mentioned above, the counts in this section can indicate that there's a problem with your catalog even when the ingestion is successful by all other measures.
Acting on the Ingestion Report
What you do next depends on the ingestion status.
- Success: As long as the counts of pages added, removed, updated, and unchanged are as you expected, there is no further action required. However, consider addressing any warnings and suggestions. See Catalog Ingestion Report Messages for an explanation and course of action for each.
- Failure: Refer to Catalog Ingestion Report Messages for an explanation and course of action for each entry in the Error section. If you still have trouble understanding what needs to be done or how to do it, contact your Amazon Business Developer Manager.
Ingestion Reports FAQ
- Q: What is an ingestion report?
- A: This report tells you whether your catalog was successfully ingested into Amazon, and if not, why. After you upload your latest catalog, a new copy of the report is added to your S3 bucket as report.html, normally within four hours. You can use this report to troubleshoot issues in your catalog file. It contains the ingestion success or failure status plus any errors, warnings, and suggestions.
- Q: How do I know if my uploaded catalog file was ingested into the system?
- A: You can receive the ingestion results through an opt-in email, which also includes a link to download the full report.
- Q: How do I get added to the email distribution list for my catalog's ingestion results?
- A: Send mail to p11-catalog-subscriptions@amazon.com asking to be added. Because the success and failure mail reports are separate email lists, ask to be added to both lists.
- Q: My catalog ingestion failed. What do I do next?
- A: Look at your ingestion report for the specific errors that caused the failure. Explanations and follow-up instructions for each error are given in the ingestion report documentation. If necessary, your Amazon Business Development Manager can help you work through problems with your catalog. See Catalog Ingestion Report Messages.
Next Steps
Continue on to the next step: Step 6: Update your Catalog at Regular Intervals.
Last updated: Jan 27, 2021