Understanding Feed & Configuring Attributes

## 💡 **Prerequisites**
﻿
**Knowledge Prerequisites **
We recommend reading the following guides before starting:
﻿[Catalog Management](🔗﻿): This guide introduces you to the Catalog Management feature. 
**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](🔗﻿) for a non-staging-only account 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: **A file containing the current set of all records in the catalog. You will have a separate product and content feed if you have both products and content on your site.
**Catalog: **Catalog contains a set of product or content data for a single language. Catalog contains:
a unique name identifier like _catalog_name_ or _domain_key_
a configuration
a set and type of raw data (product or content records)
a set of transformed data (documents)
a collection name (describes how a catalog relates to another catalog)
 A catalog can power a single site or multiple sites.
**Record: **A record is a piece of raw and unmodified information that you send Bloomreach. This raw information can include details like the product ID, attributes, variants, and views.   
**Document: **Documents comprise product records that have been transformed according to catalog configurations and stored in Bloomreach.
# **Understanding the Feed**
﻿
**Navigation path**: The Catalog Management application can be viewed in the Discovery dashboard under the path `Setup -> Catalog Management.`
## **Catalog Listing**
﻿
**Catalog Name**: This is the unique identifier for the Catalog and is used nearly throughout all API calls and pixel events. In certain Search APIs, this is also the value of the _domain_key_ parameter
**Catalog Language**
Specification whether it is a **Product** or **Content** Catalog
**Catalog Versions: **The Production and Staging environment versions available for that Catalog
**Note**: Catalogs are an account-level resource, so when you select a specific site in the dashboard dropdown, the parent account of the site selected will be used.
## **Catalog Versions High-Level Details**
﻿
Each Catalog version contains high-level details such as:
**1. The last time the Catalog's index was updated**
This indicator helps you know if your Catalog is up to date.
**2. Number of Documents in that Catalog** 
In the standard scenario, this is the total count of unique items and item variations in a Catalog as sent in the feed and currently indexed
Inclusive of variants
Inclusive of availability
Inclusive of invalid items like invalid price, missing title, or URL
In a multi-view override scenario, the number of documents represent the uniqueness of a product grouped into views. Suppose the product price varies across views. The price in views 1, 2, 3 is $10.99, and the price in views 4, 5, 6, is $11.99. In this case, we would generate 2 documents, one for each unique grouping of views based on the product data.
**3. Byte size of data in the Catalog**
This shows the cumulative amount of customer data across all the documents in the Catalog's index. This is nearly equivalent to taking each document, turning it into a JSON object, and summing the byte size of all the objects.
**Note:** If you’d like to add an additional Catalog to the account, Bloomreach Support can help set it up for you. Please provide the language and name, and specify if it's a Product or Content Catalog.
## **Catalog Feed (Feed Tab)**
﻿
On clicking a Catalog, you’ll be taken to the **`Feed`** tab. Under the **`Feed`** tab, you can search for <strong>raw feed records</strong>, view all feed data, and see the overall record counts. A catalog's feed contains the current state of the data records that have been sent in or modified via our Feed API from the source system powering this catalog. 
When you're investigating data-related issues, this is your go-to spot. The **`Feed`** section allows you to: 
View the current state of the feed 
Understand what data Bloomreach has received from your source system 
Confirm if we have all the attributes you expect for your data.
If you don't see data in the Catalog's feed and the index is up to date, then you won’t see this data in our search results or other API responses. 
**Records List**
﻿
The Records list view will show all products and items. Records are specific to the feed and shouldn't be confused with documents. Feed records are turned into documents based on the catalog configuration at index update time during indexing.
The records shown remain in their raw form without any modification from the source system.
When viewing, you’ll see up-to-date records received through any full or delta feed jobs that have been successfully processed. There may be a slight delay between success and data showing in the UI, but it is minimal.
The feed records shown here are only available and reflected in search results and API responses once the catalog's index is updated. Typically, the source system will update the index by performing our Update Index API call.
## **Understanding Product Details in the Records**
Every record will show the following details for a specific product or item: 
**Product or item identifier (Product ID)**
﻿
Product ID is **not an attribute** of the record. In the feed, it can be found as part of the path property, eg. if in the path property "/products/123", the product ID is 123. Bloomreach doesn't generate an ID for a record, it is always specified in the feed by the customer.
**Attributes**
﻿
Each record lists the attributes related to that product or item. Initially, you’ll see a set of 4 attributes in each product record. To view the **complete list of attributes**, click on the **`Show all attributes`** dropdown. 
﻿
This will display a list of all the product or item level attributes with their values. Values that begin and end in double quotes are string values; otherwise, they are the literal JSON value supplied in the feed. Values of the data can be easily copied to use elsewhere.
**Variants**
﻿
The record also lists the variants of the specific product/item. You can see a variants dropdown under each record. Click on the dropdown to view each variant's attributes and identifiers. On clicking the dropdown, you get a grid view of all unique attributes in that product or item like Variant ID, Color, Color Family, Color Group, Default SKU, and Integer SKUID.
﻿
You can also click any product variant and view all of its attributes. 
﻿
**Search for Products/Product Variant using Product ID/ Variant ID**
﻿
You can use the search bar to search the feed data for a specific product ID. The same search feature is available for finding a specific variant in the list of variants. Please note that the Product/Variant ID used here must be an **exact match**.
# **Configuring Attributes (Attributes tab) **
﻿
﻿
This section allows you to
**View the list of all configurations applied to custom attributes:** The list of custom attribute configurations helps you understand how custom attributes function and behave in our Search and Suggest APIs.
**Change the custom attributes configurations: **Based on your understanding of the current custom attributes configurations, you can choose a different setting as per your needs. 
By modifying the properties, you can control how the attribute behaves in our APIs. Suppose you have a custom attribute in your data called "_display_value1_" and you would like that attribute to show up in our API responses. You would first need to make a custom attribute configuration for _"display_value1_" and tell Bloomreach that the attribute should be "displayable." After that change is saved and the index is updated, you can query our APIs and request that "_display_value1_" is returned in the response. When the index is updated, the feed data will be applied to this list of custom attribute configurations, and documents will be generated accordingly.
Custom attributes may be sent in the feed before configuration and will be visible in the Feed tab; however, they will not be usable until they have been configured.
There are certain **enterprise accounts** where default configured behavior may be defined differently for attributes that do not have an explicit custom configuration. It's important to know your default account setting to understand how all your custom attributes will be treated during indexing.
You can specify the following for each custom attribute configuration: 
<table>
  <tr>
   <td><strong>Configuration </strong>
   </td>
   <td><strong>Description</strong>
   </td>
   <td><strong>Available Options</strong>
   </td>
  </tr>
  <tr>
   <td><strong>Level</strong>
   </td>
   <td>Specify the level at which this attribute appears in your Product Data - either it's in the basic Product attributes (Product), or it's reported in the variants / SKUs section and is a (Variant) attribute instead. Please note that this setting does not change <em>where</em> a value is stored.
   </td>
   <td>Actions associated with dropdown options:
<p>
<strong>Product: </strong>Specify that the attribute appears at the product level in the associated product documents 
<p>
<strong>Variant: </strong>Specify that the attribute appears at the variant level in the associated variant documents
   </td>
  </tr>
  <tr>
   <td><strong>Facetable</strong>
   </td>
   <td>Specify whether the attribute and its value may be used for faceting, filtering, sorting, and merchandising rules.  
This also controls whether Bloomreach should treat the attribute as part of our dynamic facet feature. If an attribute is specified as a dynamic facet attribute, Bloomreach will determine if the attribute should be returned as a facet in the API response algorithmically.  
   </td>  
   <td>Actions associated with dropdown options:  
<p>  
<strong>Dynamic</strong>: Corresponds to  
<ul>
<li>Search features ON 
<li>Dynamic facet ON
</ul>
<p>
<strong>Manual</strong>: Corresponds to 
<ul>
<li>Search features ON 
<li>Dynamic facet OFF  
</ul>
<p>
Manual implies that you can use this attribute in <a href="https://documentation.bloomreach.com/discovery/docs/facet-management">facet management</a> and manually work with it.
<p>
<strong>Off</strong>: Corresponds to 
<ul>
<li>Search features OFF
<li>Dynamic facet OFF  
</li>
</ul>
</li>
</ul>
</li>
</ul>
   </td>
  </tr>
  <tr>
   <td><strong>Displayable</strong>
   </td>
   <td>Specify whether the attribute may be returned in API responses so that it can be displayed in your frontend.
<p>
When returning a result set, Product ID(pid) is the only attribute returned in each document by default. You can explicitly request additional parameters in the Search API call using the`fl` parameter. However, the additional attribute must be configured as <em>displayable</em> first.
   </td>
   <td><strong>Checking </strong>this returns the attribute in the API response if used in the <em>fl</em> parameter.
<p>
<strong>Unchecking </strong>this prevents returning the attribute in the API response. 
   </td>
  </tr>
  <tr>
   <td><strong>Searchable</strong>
   </td>
   <td>Specify whether the attribute's value will be used when matching products or items during a keyword search.  It affects only recall, not ranking.
   </td>
   <td><strong>Checking </strong>this allows the attribute to be used as part of the searchable keyword text.
<p>
Checking for a large-sized or a multi-value attribute can decrease the recall set relevance of a keyword search.  
<p>
<strong>Unchecking </strong>this blocks the attribute from being used as part of searchable keyword text.
   </td>
  </tr>
  <tr>
   <td><strong>Multi-valued</strong>
   </td>
   <td>Specify whether the attribute's value should be returned and treated as an array or a single value. Make sure to align this with the feed format in nearly all circumstances.
   </td>
   <td><strong>Checking</strong> the box returns this attribute as a multi-valued array in the associated documents. 
<p>
If a record is scalar and this box is checked, the value will be an array of the single value. 
<p>
<strong>Unchecking</strong> the box returns the attribute as a scalar. 
<p>
If a record is an array and this box is unchecked, the first value of the record array will be the scalar value of the attribute. 
   </td>
  </tr>
  <tr>
   <td><strong>Data type</strong>
   </td>
   <td>Specify whether the attribute's value should be returned and treated as text or number. This should align with the feed format in nearly all circumstances.
   </td>
   <td>Actions associated with dropdown options:
<p>
<strong>Text: </strong>Choose this for a text-type attribute
<p>
<strong>Number:  </strong>Choose this for a number-type attribute
   </td>
  </tr>
</table>
**Setting New Attribute Configurations **
﻿
Click on **`Add an Attribute Configuration`** to configure a new attribute.
This displays a new attribute field. Here, you can specify the attribute name and select the desired configurations.
<strong>Catalog Configuration Changes </strong>
﻿
This visual shows the process of making changes to the existing attribute configurations of the attribute _sample_field_name_11_. The process of changing existing attribute settings is simple. You can rename, select/deselect existing configurations or choose the options provided in the dropdown lists to get the desired changes. To revert the changes, click the Revert symbol. 
After configuring attributes, proceed with [this](🔗﻿) guide to push the changes to production. 
# **Points to remember**
﻿
﻿
You can hover over each configuration property to reveal a quick tooltip on what it does.
Duplicate attribute names are not allowed. 
Bloomreach **Reserved Attribute names** cannot be used as attribute names.
To edit or promote configuration changes, you need a role with the appropriate catalog permissions to modify catalogs.
## 💡 Prerequisites

## 📔 Glossary

# Understanding the Feed

## Catalog Listing

## Catalog Versions High-Level Details

## Catalog Feed (Feed Tab)

## Understanding Product Details in the Records

# Configuring Attributes (Attributes tab)

# Points to remember
