Promoting Changes & Viewing Jobs

This guide walks you through the process of promoting your configurations, copying configurations from another environment, updating the index, and viewing jobs using the Catalog Management feature.

💡 Prerequisites


Knowledge Prerequisites
We recommend that you read the following guides before starting:

Access Prerequisites
Catalog Management should always be accessed via tools.bloomreach.com and not via tools-staging.bloomreach.com. The only exception to this is if the account is not accessible via tools.bloomreach.com and is accessible via tools-staging.bloomreach.com.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.com. Accessing Catalog Management via tools-staging.bloomreach.com may have edge cases where functionality may not work as it isn't a supported use case.

EU/UK-based Merchants: EU/UK-based merchants should access via tools.bloomreach.co.uk and not via tools-staging.bloomreach.co.uk. The only exception to this is if the account is not accessible via tools.bloomreach.co.uk and is accessible via tools-staging.bloomreach.co.uk.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.co.uk. Accessing Catalog Management via tools-staging.bloomreach.co.uk for a non-staging-only account may have edge cases where functionality may not work as it isn't a supported use case.

📔 Glossary


Feed Job: A feed job modifies all or part of the catalog records. It can be either a Full-feed job or a Delta feed job.
Index Job: An index job informs Bloomreach about the new catalog data for indexing.

Autosuggest Index Job: An Autosuggest Index Job informs Bloomreach about the changes in Autosuggest configurations or rules.

Promotion Process


The configuration changes made to a catalog go through a promotion process. You can start these changes in the staging environment and push them to production. Please note that changes can not be made directly on a production catalog outside of the promotion process.

The promotion process is summarized below:

1. Make Attribute Configuration Changes

Configure the attributes as per your needs. For more details, refer to this guide.

2. Review and save the configuration changes

1999

In this example, we changed the existing configurations of attribute new_field and added a new attribute named demo_field_2

Once a configuration is modified, theReview & Save action will be available. Review & Save action allows you to confirm the difference between what's in production and what's about to be promoted. Using this, you can verify that the changes will turn out as expected. The configuration will be reflected on API endpoints within 1-60 minutes.

👍

Modifying Production configurations

Alternatively, you can make changes directly to the catalog’s Production configuration without going through the process of promoting configurations from Staging.

Nonetheless, it's still recommended to test any changes in the Staging environment. This helps prevent unwanted changes in the Production environment.

3. Update Catalog’s index

522

It is recommended that you update your index immediately after saving your configuration changes. The index update ensures that the configurations available on your APIs are in sync with the data on your catalog's index. You can update the index via:

  • Index update API: You can trigger an Index API call to inform Bloomreach about the new configurations and to index the catalog.
  • Update Catalog Index UI: You can force an index update using the Update Catalog's Index action located in the environment drop-down list. This will create an updated index job and display the newly submitted job's identifier. The status of the job can be viewed under the Jobs tab.
581

Note:If another user changed the configuration before this change, the change will be rejected, and this change must be updated to reflect the new state of configurations.

4. Initiate the promotion

998

You can now start the promotion by selecting the Promote this to Production action in the environment drop-down menu.

On initiating the promotion process, you’ll be able to view all the changes you saved. You may also include/exclude certain changes from being promoted using the checkboxes provided. You can include/exclude changes while copying another catalog's configuration as well.

Copy another catalog's configuration


534

You can use the Copy configuration to this environment action to work with an existing configuration. You may encounter two different scenarios while copying the configurations:

  • Copy from the production version of the catalog into the staging environment: This is useful for resetting your changes in staging back to the known production configuration.
  • If multiple catalogs are in an account, copy a completely different product catalog configuration into the staging environment. It comes in handy when you have multiple languages and, hence, multiple catalogs, but your configurations are similar or nearly identical.

First-time use of configuration on an existing Catalog

If the configuration for the Catalog was generated before the Catalog Management rollout, the attribute configurations may contain reserved attributes. These reserved attributes may not be modified, only removed.

Reserved attributes already have a static configuration in our system, and it is best to remove them from the Catalog configuration completely. Removing a reserved attribute configuration is a no-operation procedure, but we still recommend verifying any configuration change in staging before promoting it to production.

Viewing Catalog Jobs


1999

The Jobs tab provides a listing of all current and historical jobs that have been performed against the catalog, along with detailed information on the status of each job and their input parameters. This is a great debugging tool to understand if data is flowing correctly from your source system into the catalog and that the catalog's index is being updated per your schedule.

Every job listed will include the following details:

Header Description
Job Type This specifies the operation of the job. The two most common job type classifications are

Feed jobs: This includes either full or delta jobs that modify all or part of the records in the catalog.

Index jobs: This takes the current state of records and catalog configuration and creates documents that are made LIVE in our APIs

Status The current state of the job. This specifies if the job is running, queued, successful, or failed.
ID Unique ID which was generated at the time of job creation. This is the same ID as returned via our Feed and Index API when sending a feed or updating your index.
Start time When the job started processing
Duration How long the job took to process
Count If a job has a particular core metric, this will be listed. It is helpful to get an overall sense of historical performance. Depending on your integration, if you see large changes from job to job, this could indicate an issue with the data flowing into the catalog.

Feed: Number of patch operations processed

Index: Number of documents processed

Jobs Search & Filtering

Search and filtering feature is also available under the Jobs tab. This feature is especially useful when you have a lot of jobs generated by your source system or you want to go back in time.

Search by Job ID

414

This is an exact search by the provided job ID. It will return the job information for that specific job ID.

Date range selection filter

The date range selection defaults to “This Month.” It allows you to specify different time periods to filter jobs going back 13 months. Please note that jobs older than 7 days may not have the same debug information available as recent jobs.

Job type filter

This enables you to select the specific jobs you want to filter by. You can use this if you are interested in one or multiple specific jobs and want to exclude other types. The available job types are described below:

  1. Feed jobs
1930

Feed jobs are any jobs that modify records. This could be a full job labeled as:

  • "Feed: Full Products" (replaces the current state of records with what's in the feed), or
  • “Feed: Delta Products” (a delta job that modifies the existing state of records).

Important Properties and Statistics

  • The input_source property tells whether the data modification patch (patch) was supplied via files on SFTP or sent directly in the API request body.
  • The feed_mode property tells whether this was a full or delta job.
  • patch_operations_count gives the number of operations that were in the patch. This doesn't represent the number of unique records as multiple operations may modify a single record, or it could be an operation to remove records from the catalog. If the patch used files via SFTP, the list of files will be shown in the order in which they were listed. This also corresponds to the order in which they are processed by the job.
  1. Index Jobs
1926

Index jobs are jobs that create or update the documents in a catalog's index or other index-related actions.

Important Properties and Statistics

  • The config_etag value specifies a unique configuration identifier used while processing the index job. Jobs with the same etag value used the exact same index configuration.

The statistics available for an index update job are:

indexed_child_count specifies the number of indexed variant documents that were processed during the job.

indexed_parent_count specifies the number of indexed product or item documents that were processed during the job.

If a catalog uses view overrides, these counts may be larger or smaller than expected depending on how the overrides impact the documents needed to support the overrides.

Revert to this configuration: This option allows you to revert the catalog to its previous configuration version if there is a catalog configuration version associated with a catalog job.

  1. Autosuggest Index Jobs

Autosuggest Index jobs update and apply the new or changed configurations or rules to the Autosuggest index. The errors and warnings displayed for a job can provide useful information to debug skipped or unsuccessful jobs.

Note that the Autosuggest Jobs are not displayed by default, and you need to select its filter to see them.

Viewing Filtered Job Results

Each job that matches the search and filter criteria specified will be returned in the list view. You can copy the job ID by clicking on it. You may click on the job to expand it and see more details. You can then see:

  • Start and end times of each job in your local time.
  • Any errors or warnings detected during the processing of the job
  • Further information specific to the type of job