Exporting catalog data

You can use the HCL Commerce REST API to export catalog data in CSV format. The default data types that you can export are categories or products.

Before you begin

Ensure that the Swagger UI and the REST Discovery API are enabled. For more information, see Enabling and disabling the REST Discovery API.

Procedure

  1. Use the Organization Administration Console to assign the following roles to a HCL Commerce user:
    • Catalog Exporter: The role that allows users to export and download catalog data. This role is typically assigned to category managers, product managers, and site administrators.
    • Registered Customer: The role that allows users to log in to the store and access the catalog export tools in the Swagger UI. This role is necessary if the user password is expired and must be reset by using the storefront.
    For more information, see Selecting roles for a user.
  2. Go to the Aurora starter store and log in to the store by using the HCL Commerce user that contains the Catalog Exporter and Registered Customer roles.
    This step is required so that the catalog export REST services can be used in the Swagger UI.
  3. Open the Swagger UI.

    In the Swagger UI, the catalog_export class is used to export catalog data. Then, the catalog_download class is used to download the exported catalog data.

    1. Open a web browser and go to the following URL: https://localhost/webapp/wcs/stores/servlet/swagger/index.html
  4. Export the catalog data.
    1. Expand the catalog_export class.
    2. Expand the POST /store/{storeId}/catalog_export/{objectType} method path.
    3. Enter the following parameters:
      Parameter Value
      storeId The store identifier to export the catalog data from.

      For example, 10151.

      objectType The type of data to export. Enter either Category or Product. This value is case-sensitive.
      Note: Ensure that you enter a valid value. The catalog_export class does not validate the input. Instead, if you enter an invalid value, errors occur in the proceeding step when you work with the catalog_download class.

      For example, Category.

      body Optional: Enter extra comma-separated values in JSON format that you want to export.
      exportMode
      Indicates whether to export full or delta catalog data. The default value is full.

      If you specify a delta build, the catalog_download class in the proceeding step lets you specify a value for the deleted parameter. This parameter indicates whether the downloaded file contains only deleted objects since the last export.

      CSVColumnList
      A list of CSV columns to export. The default value is all columns.
      catalogId
      The ID of the catalog to export. The default value is the master catalog.
      langId
      The ID of the language to export. The default value is the default store language.
      For example, to scope the catalog export based on the 10001 catalog ID, specify the following JSON in the body:
      
      {
      catalogId : "10001"
      }
      

      For a list of sample optional values that you can input, see Catalog export sample inputs and scenarios.

      In addition to the supported optional values, you can also specify the optional query parameters that are available to all REST services. For a list of all the optional query parameters that can be used with the HCL Commerce REST API, see HCL Commerce REST API.

      For example, the following screen capture shows the Swagger UI with sample catalog export values:
      Swagger UI: catalog_export input
    4. Click Try it out!.
    5. Note the export ID in the response body, as it is used to download the catalog data in the proceeding step.
      For example, the following screen capture shows the Swagger UI with a returned export ID of 10001:
      Swagger UI: catalog_export output
  5. Download the exported catalog data.
    1. Expand the catalog_download class.
    2. Expand the GET /store/{storeId}/catalog_download/byExportId/{exportId} method path.
    3. Enter the following parameters:
      Parameter Value
      storeId The store identifier to download the exported catalog data from. Use the same store ID value that you used in the preceding step.

      For example, 10151.

      exportId The export ID that you noted in the preceding step's response body after you run the catalog export REST service.

      For example, 10001.

      deleted Optional: Indicates whether the downloaded file contains only deleted objects since the last export. This parameter is used when you export delta catalog data. That is, when the exportMode value is set to delta when you export catalog data by using the catalog_export class in the preceding step.

      The default value is false, which indicates that the CSV file contains only the new or updated objects, no deleted objects.

      For example, the following screen capture shows the Swagger UI with sample catalog export values:
      Swagger UI: catalog_download input
    4. Click Try it out!.
    5. The response body contains the exported catalog data in CSV format.
      For example, the following screen capture shows the Swagger UI with the inline response:
      Swagger UI: catalog_download output
    6. Download the CSV file by going to the response request URL in your web browser.
      For example, in this sample, the request response URL is:
      
      https://localhost:443/wcs/resources/store/10151/catalog_download/byExportId/10002
      
      Going to the request URL results in the CSV file download, instead of the inline response in Swagger UI.
      Swagger UI: catalog_download save dialogue

What to do next

If issues occur when you use the catalog export or download services, review the following troubleshoot tips:
  • Ensure that your system has sufficient memory when you run a delta catalog export. Out of memory errors might occur during delta catalog exports, as checking for file differences can potentially be a memory intensive process.
  • Ensure that you enter a valid object type when you run the catalog export service. This value is case-sensitive. The catalog_export class does not validate the input. Instead, if you enter an invalid value, errors occur in when later working with the catalog_download class.
  • Ensure that the catalog export service completes before you call the catalog download service. The catalog download response indicates this if you try to download it too early.
  • Ensure that you are logged in as a user that contains the Catalog Exporter and Registered Customer roles. Otherwise, a NOT_AUTHORIZED_FOR_QUERY error occurs when you work with the catalog export services.
  • If the catalog download response indicates an invalid export ID, it might be due to any of the following reasons:
    • The export ID does not exist. Check that you entered the correct value.
    • The catalog ID might exist but not within the store ID that you requested.
    • The export ID might exist but is expired. This error might occur if a new request of the same kind is issued, making the old one no longer valid.
    • The store does not contain any catalogs.

After you download the exported catalog data in CSV format, you can import it into a third-party application for further processing.