Manage Product Attributes in the Back-Office

Overview

Hint

This section is part of the Product Management topic that provides a general understanding of the product concept in OroCommerce.

A Product Attribute is a type of a custom field in the product details. For product attributes, OroCommerce enables you to manage and group attributes that are unique to a particular product family. By adding the product attributes only to the product families they fit, you can limit the product data to the necessary characteristics.

For example, when your OroCommerce store sells TVs and T-shirts, these items share some generic attributes (e.g., name, vendor), and differ in the remaining attributes set. For example, there might be a Screen properties group containing resolution, diagonal, and matrix that should be linked to the products in the TV product family. For the T-shirts family, the linked attribute group may have color, size, material, fit, and care guidance (washing, ironing, dry cleaning, etc.).

Note

You can manage product attributes per organization. Any changes made to product attributes within one organization do not affect the attributes of others. You can use the attributes created in the global organization in other organizations, but only a system administrator of the global organization can edit them.

By default, OroCommerce comes with the following system product attributes:

Add new product attributes to introduce new custom parameters in your product details. Include product attributes in one or multiple product families into the new or existing attribute group.

Note

System attributes are shared among all product families. You can reorganize the way system attributes are grouped, but you cannot remove a product attribute from the product family.

Hint

Instead of using one general-purpose attribute (e.g., color), create multiple specific attributes (e.g., car_color, laptop_color, table_color). This prevents loading all attributes as filters on all product pages and as a result, reduces the load on the database and improves the overall application performance.

Create a Product Attribute

See a short demo on how to create product attributes, or keep reading the step-by-step guidance below.

The creation of an attribute happens in two steps:

• In step 1, specify basic properties, such as the attribute name and type.

• In step 2, you specify more advanced properties, some of which may depend on the selected attribute type.

Step 1: Select Attribute Type

To create an attribute:

1. Navigate to Products > Product Attributes using the main menu.

2. Click Create Attribute.

Hint

You may receive the following warning message, which notifies you about the limits for the number of attributes that can be created, which can affect the future export of entities.

The number of attributes stored as columns in the X table (the attributes that are relations or that have ever been marked as “A”, “B”, “C”) is approaching the limit after which it will no longer be possible to export Y with the standard X export. Remaining number of attributes - approximately Z.

Once 90% of the limit is reached, you will receive a flash message with the related warning.

Reaching 100% of the limit triggers a warning message on a potential inactive export when clicking the Export button.

3. Complete the following fields:

Field Name

Fill in the field name that should be used to store the values of the product attribute. It should be between 2 and 22 characters long. Use only alphabetic symbols, underscore, and numbers.

Type

Select an attribute type to store the value of the specific data type. For the list of available field types and their purposes, refer to the relevant section of the Entity Field Properties topic or see descriptions in Step 2 below. Select one of the Relations for the attribute to connect your custom entities as product information (these can be used for business intelligence and segments): Many to many — No limit on how many entity records of the selected type can be connected to the attribute, e.g., many custom entity records can be related to many products. Many to one — Attributes cannot have more than one entity record related to them, e.g., Products A-Z can relate to Promotion A. Product A cannot relate to multiple promotions. You can reuse the same promotion in multiple product details. One to many — One attribute can relate to many entity records, but every related entity record can be connected only once. For example, product A can be related to many promotions, but Promotion A cannot be related to multiple products.

4. Click Continue to load the next page.

Step 2: Provide Type-Based Details

Proceed to create the attribute as described below.

1. Fill in remaining general information:

   • Label — Enter the attribute label. It will be displayed both in the back-office and in the storefront.

   • Description — When filled in, the description will be used as a field tooltip when the attribute appears on the forms.

2. Provide additional information for product attributes depending on their type. Not all attribute types have additional fields, as reflected in the table:

BigInt	—
Boolean	—
Date	—
DateTime	—
Decimal	Precision — Maximum number of digits in a decimal number. For example, 15.252 has a precision of 5 and 1.12 has a precision of 3. Scale — Maximum number of digits to the right of a decimal point. For example, 15,252 has a scale of 3 and 1.12 has a scale of 2.
File	File Size — Enter the maximum allowed file size. Allowed MIME Types — Select one or more allowed MIME types from the dropdown. Use DAM - Select whether to enable the use of the Digital Asset Manager for this field. ACL Protected — Select whether to enable ACL check for attachments. File Applications — Select where the file loaded to this field is going to be accessible. Possible applications are default and commerce, where default means back-office and commerce means storefront. If the files or images that you want to upload through this field are going to be accessed only from back-office, then select default; if from both back-office and storefront, then select both default and commerce. Please be aware that this setting is not used when ACL Protected is set to No.
Image	File Size — Enter the maximum allowed file size. Thumbnail Width — Enter the width in pixels. Thumbnail Height — Enter thumbnail height in pixels. Allowed MIME Types — Select one or more allowed MIME types from the dropdown. Use DAM — Select whether to enable the use of the Digital Asset Manager for this field. ACL Protected — Select whether to enable ACL check for attachments. File Applications — Select where the image loaded to this field is going to be accessible. Possible applications are default and commerce, where default means back-office and commerce means storefront. If the files or images that you want to upload through this field are going to be accessed only from back-office, then select default; if from both back-office and storefront, then select both default and commerce. Please be aware that this setting is not used when ACL Protected is set to No.
Integer	—
Money	—
Select and Multi-Select	Perform the following actions: Click + Add next to Options. Type in the option label. Enable the checkbox next to the default option. Repeat for more options. Click Do not set as default link to clear the Default flag.
Multiple Files	File Size — Enter the maximum allowed file size. Allowed MIME Types — Select one or more allowed MIME types from the dropdown. Maximum Number of Files — Enter the maximum number of files allowed to be uploaded. Use DAM — Select whether to enable the use of the Digital Asset Manager for this field. ACL Protected — Select whether to enable ACL check for attachments. File Applications — Select where the file loaded to this field is going to be accessible. Possible applications are default and commerce, where default means back-office and commerce means storefront. If the files or images that you want to upload through this field are going to be accessed only from back-office, then select default; if from both back-office and storefront, then select both default and commerce. Please be aware that this setting is not used when ACL Protected is set to No.
Multiple Images	File Size — Enter the maximum allowed file size. Thumbnail Width — Enter the width in pixels. Thumbnail Height — Enter thumbnail height in pixels. Allowed MIME Types — Select one or more allowed MIME types from the dropdown. Maximum Number of Files — Enter the maximum number of images allowed to be uploaded. Use DAM — Select whether to enable the use of the Digital Asset Manager for this field. ACL Protected — Select whether to enable ACL check for attachments. File Applications — Select where the image loaded to this field is going to be accessible. Possible applications are default and commerce, where default means back-office and commerce means storefront. If the files or images that you want to upload through this field are going to be accessed only from back-office, then select default; if from both back-office and storefront, then select both default and commerce. Please be aware that this setting is not used when ACL Protected is set to No.
Percent	—
String	Length — Enter the maximum allowed string length.
Text	—
WYSIWYG	ACL Protected — Select whether to enable ACL check for attachments. File Applications — Select where the WYSIWYG content loaded to this field is going to be accessible. Possible applications are default and commerce, where default means back-office and commerce means storefront. If the files or images that you want to upload through this field are going to be accessed only from back-office, then select default; if from both back-office and storefront, then select both default and commerce. Please be aware that this setting is not used when ACL Protected is set to No.
Relations: Many to Many One to many Many to One	Target Entity – Select the entity you wish to relate your current attribute to. Bidirectional – Select Yes or No. If set to Yes, the attribute and the selected entity will be interconnected. Related Entity Data Fields – Available only for the Many to Many and One to Many relations. Select those fields of the entity selected in Target Entity which contain information that you want to see on the master entity record edit page. These could be a couple of important details in addition to the title which gives you the most important information about the related entity record. Hold the Ctrl key to choose several fields. Related Entity Info Title – Available only for the Many to Many and One to Many relations. Select the fields of the entity selected in Target Entity by which the users can identify the related entity record. These fields serve as a title to the related entity record on the master entity pages. Choose these fields carefully. It would be a good idea to select a related entity name or similar information. On the view page of the master entity record, these fields will appear as links to the corresponding related entity record. On the edit page of the master entity record, you will see these fields as titles of the section that contains information selected in Related Entity Data Fields. Hold the Ctrl key to choose several fields. Related Entity Detailed – Available only for the Many to Many and One to Many relations. Select those fields of the entity selected in Target Entity which contain additional information that you want to see on the master entity record edit page. The values of the fields selected will be available in the dialog that appears when you click the title of the related entity on the master page edit page. Hold the Ctrl key to choose several fields. Target Field – Available only for the Many to One relation. Select the field of the entity selected in Target Entity by which the entity records will be tied.

3. In the Storefront options section, set up the storefront options applicable to the product attribute.

Important

Please note that if the option is not applicable to attributes of the selected type (e.g., image, text, multi-select, etc.), it does not appear in this section.

Show On View	Defines whether the attribute is visible or hidden in the storefront.
Show On Form	Defines whether the attribute is enabled in the storefront forms.
Exportable	If enabled, the attribute content is to be displayed in the product data export file in the storefront.
Searchable	If enabled, the attribute content can be found in the storefront via search.
Filterable	Defines whether a dedicated filter is available for the attribute in the storefront.
Filter By	Defines the type of filtering to be applied to the attribute: Fulltext search — Find the exactly matching text and similar words. This type of filtering helps find the required values even if the entered text contains typos or incomplete words. Exact value — Look for the values that exactly match the entered text.
Sortable	Defines whether sorting is available for the attribute in the storefront. Note Please note that the sortable option is not applicable for the multi-select attribute type. Make sure to set the option to ‘0’ or ‘No’ when using the importing strategy.
Global Search Boost	Available for the OroCommerce Enterprise edition if Elasticsearch is used as the search engine. This option enables you to boost the value of the field during search. By default, the boost for sku is set to 5, for names to 3, meaning that the searchable word is first searched among SKUs, then names, etc. The option works for searchable attributes only.
Similar Products Boost	Available for the OroCommerce Enterprise edition if Elasticsearch is used as the search engine. This option allows you to use the attribute in the related products calculation. By default, all attributes are skipped. The option works for string, many-to-one, boolean, select and multi-select attributes only.
Similar Products Boost in Shopping Lists	Available for the OroCommerce Enterprise edition if Elasticsearch is used as the search engine. This option allows you to use the attribute in the related products calculation. By default, all attributes are skipped. The option works for string, many-to-one, boolean, select and multi-select attributes only.

4. In the Back-Office options section, fill in the Import & Export subsection to configure details of the product attribute’s import/export:

Column Name	Enter the name of the column (in a CSV file) that would represent the attribute you are creating. If left blank, a label will be used.
Column Position	Type a number that corresponds to the position of the attribute in a CSV file.
Use As Identity	Specify whether this column should be used as an identifier of the entity record. Select No, Only when not empty, or Always. If set to Only when not empty, the field may be omitted in the identity when it has no value.
Exclude Column	Select No, if you want this field available for export, or Yes if you wish to exclude the column.
Export Fields	If the attribute is of the relation type, this option defines which fields of the related entity record to export: Identity only – Export only the field that serves as an identifier of the related entity record. All – Export all fields of the related entity record.

5. In the Back-Office options section, fill in the Other subsection, specifying the configuration options for the product attribute view, search and use in the back-office and storefront.

Note

Please note that available options depend on the type selected for the attribute (e.g., image, text, multi-select, etc.).

Contact Information	Labels the product attribute as contact information that may be used in the marketing lists. The contact information may be: Empty — In this case, the product attribute will not be treated as contact information. Email — When this option is selected, the product attribute value is treated by marketing lists as email addresses. Phone — When this option is selected, the product attribute value is treated by marketing lists as a phone number.
Show on Form	In this field, select Yes if you wish to have the product attribute displayed and be editable on record and page edits.
Applicable Organization	This checkbox determines whether you want the product attribute to be available throughout all organizations.
Available in Email Templates	Select Yes if you wish the product attribute to be available in email templates. To use the product attribute value in the email template: When creating an attribute, mark it as Available in Email Templates. Navigate to System > Emails > Templates and click Create Email Template. In the template, select Product as the entity that the template should relate to. On the entity variables list on the right, find the attribute and click on it to add to the template.
Add To Grid Settings	The option controls the availability and display of the product attribute in the products grid: By default, Yes and Display is selected which makes the product attribute available and visible in the grid. The Yes and do not display option means that the product attribute is hidden by default, but the visibility may be toggled in the grid settings. The Yes as Mandatory option adds it permanently to all grid views and disables visibility toggle. No – The product attribute visibility and appearance order cannot be toggled in the grid settings
Show Grid Filter	Select Yes to display the filter for the product attribute on the user interface.
Grid Order	Defines the order of the product attributes in the product grid. The product attributes with a smaller value of the grid order number will be displayed before the attributes with a bigger value.
Show On View	Select Yes if you wish to have this product attribute displayed on the product view page.
Priority	Priority defines the order of the product attributes on the view, edit, create pages. Custom product attributes are always displayed one by one, usually below the system fields. If no priority is defined or the defined priority is 0, the product attributes will be displayed in the order in which they have been added to the system. The product attributes with a higher priority (a smaller value) will be displayed before the attributes with a lower priority.
Searchable	When set to Yes, the attribute is included in the search options in the back-office.
Auditable	When set to Yes, the system will log changes made to this product attribute value when a user edits the product details.

6. Once all options are configured, and the necessary information is provided, click Save.

7. If the created attribute is of a table column storage type, click Update Schema to reindex the data for search and filter.

Note

The product attribute storage type is set to table column for the attribute with Select of Multi-Select data type, and also for the attribute of any type with Filterable or Sortable option enabled. If this step is omitted, the newly created attribute will not appear in the select attribute options in other areas of OroCommerce (e.g., product families configuration).

You can check an attribute’s storage type on the page with the attributes list:

Warning

Schema changes are permanent and cannot be easily rolled back. We recommend that developers back up data before any database schema change if changes have to be rolled back.

Import Product Attributes

Import File option helps import a large bulk of product attributes information into the product attributes list using the .csv file.

Example of product attributes bulk import template

fieldName	type	entity.label	entity.description	entity.contact_information	form.is_enabled	importexport.header	importexport.order	importexport.identity	attachment.mimetypes
field_money	money	label_value	description_value	marketinglist.entity_config.	yes	header_value	12	no	mimetypes_value

Note

Keep in mind that multi-select attribute type doesn’t support the sorting option, so make sure to set this option to “0” or “No” when preparing the corresponding file for importing.

To import a bulk of product attributes:

1. In the main menu, navigate to Products > Product Attributes.

2. Click Import File on the top right.

Hint

You may receive the following warning message which notifies you about the limits for the number of attributes that can be imported, which can effect the future export of entities.

The number of attributes stored as columns in the X table (the attributes that are relations or that have ever been marked as “A”, “B”, “C”) is approaching the limit after which it will no longer be possible to export Y with the standard X export. Remaining number of attributes - approximately Z.

Pay attention that the maximum number of columns in the row must fit in a single 8192-byte heap page. For example, if all the columns are simple fields, such as integer values, then the quantity of columns can reach 1,600. The number of fields or attributes in the exporting entity must be within the bespoke limit; otherwise, this may impose a restriction on export functionality.

Once 90% of the limit is reached, you will receive a flash message with the related warning.

Reaching 100% of the limit triggers a warning message on a potential inactive export when clicking the Export button.

3. Prepare data for import: Create your bulk information in the .csv format. Once your file is ready, click Choose File, select the prepared comma-separated values (.csv) file, and click Import File.

Note

Ensure that your .csv file is saved in the Unicode (UTF-8) encoding. Otherwise, the content of the file can be rendered improperly.

4. Validate import results: Click Validate to check your import results. If there are any Records with errors, fix them in the .csv file before starting the import.

5. Launch import: After successful validation, click Import File.

6. Click Cancel to decline the import.

Important

Interactive status messages inform about the import progress, and once the import is complete, the changes are reflected in the list upon refresh. Additionally, an email message with the import status is delivered to your mailbox.

Follow the on-screen guidance for any additional actions. For example, for the inventory template, select one of the options: a) inventory statuses only or b) detailed inventory levels.

Related Topics

• Using product attributes in product families

• Translate Product Attribute Options