What's a catalog?

With catalogs, you can configure which products you want to share with an app thanks to a product selection composed of one or several criteria that allow you to filter products.

An app can create one or more catalogs using our REST API. When an app uses catalogs to retrieve product data, it automatically enables the Catalogs tab for this app in your PIM. To configure your catalogs: 

1. Go to Connect, then Connected Apps, 
2. Click Manage app below the concerned app and then click Catalogs.

On this page, you can view a comprehensive list of all catalogs currently managed by the app, complete with their respective labels and statuses. If the catalogs utilize the mapping feature, two additional columns will display the managed currencies and locales, which are essential for multi-locales and multi-currencies targets. In the absence of mapping, these columns will reflect the values entered in the Filter the values tab.

Click on the catalog you want to set up to access the configuration interface.

When you access a catalog, you will see those tabs:

• Product selection: where you will configure criteria to filter your product selection,
• Filter the values: when a catalog is not configured for mapping by the app, this tab is displayed to enable you to select which values to send to the app based on the specified filters,
• Product mapping: otherwise this tab enable you to map your PIM attributes with the app expected targets.
• Settings: this tab displays information regarding the locales and currencies that your application manages or not for the current catalog

Configure your catalog product selection

In the Product selection tab, you can define selection criteria. They are the attributes or system fields you can use to filter your products. Altogether, the criteria will create your Product selection.

You will find the system fields at the top of the list, and below are all the attributes gathered by attribute groups. There is a search bar to help you find the attributes.

Each time you add a criterion, its color turns purple to inform you that it is already used.   
A new line appears in the product selection.

Let's see how a line is organized.

1. You will find the system fields or attribute you chose in purple on the left.
2. Then, you have to choose an operator. Depending on the filter, the operator list changes.

The following fields vary depending on your filter. There can be up to 3 types of fields.

• You can have the value field. For example, if your filter is a multi-select attribute type, you can choose which options you want to filter on.
• If your filter has a value per channel and/or per locale, the channel and locale fields appear to let you choose which locale/channel you want to filter on.

If you want to remove a condition, click on the cross at the end of the line.

Available conditions

To select your products, you can use the following system fields and attribute types of the PIM as conditions:

• Status
• Category
• Completeness
• Family
• Family variant
• Updated
• Identifier attribute
• Simple select attribute
• Multi select attribute
• Text attribute
• Text area attribute
• Measurement attribute
• Yes/No attribute
• Number attribute
• Date attribute
• Reference entity single link attribute
• Reference entity multiple link attribute
• Asset collection attribute
• Price collection attribute
• Table attribute
• Created
• Entity type property
• Groups property
• File attribute
• Image attribute
• Identifier property (i.e. Main identifier)
• Parent property
• Customer Insights properties

Configure the product data mapping

After configuring your product selection, if the catalog is configured with it, you must set up your product data mapping. To do so, let's switch to the Mapping tab. 

You will see 2 columns in this tab: the target list on the left and the configuration of the selected target on the right. The left panel displays all the app's targets to synchronize your product data. In the right panel you can configure the sources to map with the target and, if desired, apply a transformation formula.

Available target types

Apps can require different types of targets: 

• String with no specified format, 
• String with the date-time format,
• String with the link (URI) format,
• Number, 
• Boolean, 
• Array of strings, 
• Array of strings with the link (URI) format,
• Measurement,
• Price.

Multi-locales and multi-currencies

String targets can be simple or multi-locales. 

• For simple strings, you must choose which locale to use for this target value. 
• For multi-locale strings, you select a channel if needed, and Akeneo PIM will automatically manage to send values for all locales managed by the catalog and enabled in your Akeneo PIM. 

Price targets can be mono-currency or multi-currencies.

• For mono-currency prices, you must choose which currency to use for this target. 
• For multi-currency prices, as for multi-locale strings, you select a channel if needed, and Akeneo PIM will automatically manage to send values for all currencies managed by the catalog and enabled in your Akeneo PIM. 

Regardless of whether the price is mono-currency or multi-currencies, it can be simple or multi-locales.

Variations

When managing products with variations in your Catalog, understanding how to effectively structure your catalog is essential. This documentation guides mapping product attributes and variants to ensure seamless integration.

If your Catalog includes products with variations, your App does not need to push the axis when creating the schema, nor is additional configuration necessary. They will be taken into account by default when mapping is created.

The product model will always include:

• Its axis attributes with labels.

The product variation will always include:

• Its axis attributes (code + value)
• Attributes that are related to variation level + labels

To maintain consistency:

• Map product model values at the product level.
• Map product variants at the variant level.

Adopt the same mapping logic whether your catalog includes simple products or product models. Consistency across mapping is crucial for simple products, product models, and variants within your catalog.

Associations

When your app requests associations from Catalogs for Apps, they are seamlessly transferred to you during import. No additional action from the user side is needed.

These associations sent to the app undergo prefiltering using the same rules as the catalog. As a result, your app will exclusively receive associations that align with the filtering parameters established for the respective catalogs.

PIM sources

Using the type information, the source panel suggests all PIM attributes or properties that match the expected target type or could match the target type after applying transformation functions. 

The source panel suggests as PIM sources the following attribute types:

• identifier,
• parent code,
• family (code or label),
• categories (code or label),
• groups,
• product status (enabled),
• text,
• text area,
• date,
• number,
• measurement,
• price,
• simple select (code or label),
• multi-select (code or label),
• yes/no,
• image,
• file,
• single reference entity link:
  • code, 
  • text, 
  • number, 
  • simple select attributes,
  • multi-select attributes,
  • image,
• multiple reference entity link:
  • code, 
  • text, 
  • simple select attributes,
  • image,
• asset collection: 
  • code,
  • text,
  • media file,
  • media link,

Select source

To select a source:

1. Go to the Mapping tab, 
2. Select a target in the left panel, 
3. Then, click Add source and select the property or attribute you want to map.

Source parameters

For each source, you can always define a default value when a value is empty for the selected attribute.

Default values 

When the source value is empty

In the source settings, when possible, we display a Default value when is empty field. If you fill in this field, the PIM will send this value when the product's source attribute value is empty. 

When you have no source to map

For string, number, and boolean targets, you can select a Default value when you have no source to map. In this case, the PIM will send the default value you set up as the target value for all your products.

Replace values

When you map one of the following source types, you can choose to replace your PIM values with new ones. 

• families,
• categories,
• simple select attributes,
• multi-select attributes,
• single reference entity link: code, label, single option, and multiple options attributes
• multiple reference entity link: code, label, and single option attributes

To do so, click Replace values in the Sources section. It displays a new screen where you can manage your replacement values. 

For example, in your PIM, you manage different blue colors: denim, dark blue, light blue, etc. But the marketplace you want to connect only manages the blue color. You might want to replace all your blues with the “Blue” value.

Once you are done, click Confirm. It closes the Option replacement screen and brings you back to the mapping.

Transformation

In the world of product information, one size rarely fits all. Different sales channels, marketplaces, and e-commerce platforms often have unique requirements for how your product data should be structured and presented. To ensure your PIM data perfectly aligns with these diverse needs, Akeneo Catalog for Apps offers a Transformation section, ensuring your product data  is always optimized for its intended destination.

Understanding the Transformation Section

Within the Transformation section, you'll find:

• Source List: A clear display of the data sources you've selected.
• Preview: A helpful preview allowing you to instantly visualize the impact of your transformations. See the example above
• Transformation Field: this is where the magic happens! Use this field to input the functions that will modify your data.  

Using the same source multiple time

Each data source selected is identified by a unique code. If you happen to select the same source multiple times, the code will be suffixed with an underscore and an incremental number, like  _1, _2, and so on, to maintain clarity (e.g., description_2, description_3). These codes are essential as you'll use them directly within your transformation functions.  When you select the same source multiple times, 

 

Crafting your transformations with functions

A transformation is built around a primary function designed to return a data type that is compatible with your target attribute's type. For instance, the CONCATENATE function, which always returns a string, is perfectly suited for a target attribute expecting a string value.

What truly unlocks the power of transformations is the ability to nest functions. This means you can use the output of one function as an argument for another. When functions are nested, the most deeply nested functions are evaluated first, and their results are then used by the parent functions.

Imagine you need to clean HTML tags from your product description and then combine it with the product name. You could achieve this with a nested function like: CONCATENATE(name, ": ", CLEANHTML(description))

Configure value filters

In the Filter the values tab, you can configure data filters to send only the data your app needs.

Available filters

To filter product values, you can use the following filters:

• Channels: when an attribute has value per channel, the PIM sends only product values for the selected channels
• Locales: when an attribute has value per locale, the PIM sends only product values for the selected locales
• Currencies: the PIM sends only prices for the selected currencies 
   

Example

You connect your e-commerce app with your PIM and want to send only data related to your e-commerce channel.

In the Filter the values tab, we advise you to filter the values on your e-commerce channel as in the following screenshot.

Enable/disable a catalog

Once you finish configuring your catalog, update the Enable status value to Yes in the catalog header.

As soon as you enable a catalog, the app will be able to retrieve your product selection data.

On the contrary, if you want to stop the catalog synchronization between Akeneo PIM and the app, update the Enable status value to No in the catalog header.