Configure property groups and properties

  • Updated

Properties are data elements that define your products. You can use them for internal purposes like shipping weight or external purposes like attributes visible to a customer. For example, the properties for a table might be Material, Finish, and Shape. 

You can use property groups to organize multiple properties together. You might have a property group for Shipping Data with Shipping Height, Shipping Length, and Shipping Weight as properties. Property groups help you organize and more easily edit product data within Optimizely Product Information Management (PIM). Property groups are not sent to commerce through integration and do not affect the way data displays on your site.

The PIM comes with a Base Property Group that includes the product number, product title, URL segment, and deactivate on date because these are the required properties for products in Optimizely Commerce.

Configured Commerce Storefront View

Properties mapped to attributes display as filterable attributes when customers search for or browse your Configured Commerce site.

Properties also display as product content on the product detail page, including properties mapped as attributes, product descriptions, and specifications. Transactional data such as product pricing, tax, and inventory information comes from your ERP.

See the Review How the PIM Data Appears to Customers article for more details.

Best Practices

Before you start adding properties and property groups, refer to the Design Considerations for Properties and Property Groups article to learn more about how properties affect your PIM ecosystem. You should also consider if a property will be an attribute or product description, so you know where it appears to customers on your website.

If you have properties like color, material, or dimensional data that are used by many products, you may not want to create specific property groups. Instead, you can have property groups such as Common Attributes–properties assigned to a template to show for products with that template.

You should also think about governance. Many properties have a specific set of valid values. You may want to use a dropdown control type instead of a text field to enforce data governance. For example, for faucets and wood furniture, you can create a Finish dropdown property with Copper, Chrome and Nickel values for faucets, and Maple, Walnut and Pine values for furniture. You can enable the template-specific values option to select the finishes when defining both the faucet template and the furniture template. Defining the values of a property also enforces consistency in spelling.

If it is easier to create properties without defining valid values during implementation, you can enable the adhoc values option for properties and import your product data to generate values. You can then disable adhoc values for your properties and review the values to clean up inconsistencies. The new value replaces any existing product with the old value, making it easier to clean up your data.

Use properties in conjunction with product templates to enforce governance. You may define properties as globally required and use validation to limit valid values for a property. You can then use product templates to define which properties are available and which of those to require or recommend for specific groups of products.


Carrie is a Senior Merchandiser managing the PIM implementation for her company, Victory Distribution. Carrie worked with her team to design the best structure for importing and managing their product information in the PIM, as well as how customers view and access product information on their Optimizely Commerce website. She now needs to build that structure in the PIM.

Carrie wants to start her PIM configuration with faucets. She has identified both global and faucet-specific characteristics that she needs to add as properties. She must first create the property groups for these properties, making it easier to assign properties to specific products later.

Carrie goes to Configure > Properties. She clicks the Create a Property Group icon to create a group for Dimensions, Brands and Common Attributes. The Dimensions and Brands groups include universal information that applies to all products. The Common Attributes group includes properties that not all products use but may be common for multiple types. For instance, Carrie will have different product templates for Kitchen Faucets and Bathroom Faucets, but they will both use properties from this Common Attributes group.

Carrie clicks Create and adds the following properties to the Dimensions group, marking them all Globally required and mapping these to the Configured Commerce fields with the same name:

  • Length (in)
  • Width (in)
  • Depth (in)
  • Weight (lbs)

Carrie clicks Create and adds the following properties as dropdowns to the Brands group, marking them as Globally required and mapping these to the Configured Commerce fields with the same name:

  • Brand
  • Product Line

Carrie clicks Create and  adds the following properties as dropdowns to the Common Attributes group and maps these as Attributes:

  • Finish

  • Number of Handles

  • Faucet Type

  • Faucet Handle Type

  • Faucet Installation Type

Properties List page

Use the Properties List page to search for, filter and select property groups and property records for editing or deleting.

List Format Navigation and Editing

You can select the columns to display, sort data by clicking column headers, and filter records by properties.

Editing – Click an individual property record to view and edit its details.

Search by name – Enter a partial or full property name to narrow the results. Applied filters appear above the grid. You can clear filters individually or all at once.

Only unmapped properties – Select this checkbox to see properties that have not been mapped to Commerce. If you have any filters applied, only properties that match the filter and status of the checkbox display in the list.

Filters – Click the Filter icon to enable or disable column filters. This adds a row below the column headers with options for filtering each property. Filtering also updates the count of records and paging options. Click a filter to open a window to change the filter option or value. Depending on the column's property data type and control type, you may see the following options:

  • Search operator of Contains, Does not contain, Starts with, Ends with, Equals, Does not equal, or Reset

  • Property value of Yes, No, Is Empty, or Is Not Empty

Columns – Click the Column Selector icon to choose from an alphabetical list of properties to show or hide as columns, with the exception of Name, which is required. You can also search for a specific property to filter the list. Drag and drop column headers to change their order or expand columns as needed.

Pagination – Go to other pages using the pagination controls under the list. By default, 25 products display in the list with options to view 50 or 100 per page.

Export Properties – Click Export to export all properties, your currently filtered list of properties, or your currently selected properties. You can also Export for Translation if using Multilanguage.

Organize Property Groups

Add Property Groups

  1. Click Configure in the taskbar.
  2. Select the Properties tab.
  3. Click Add Property Group in the left menu.
  4. Add a Name and Description for your property group.
  5. Click Save or Save & Create New to continue adding groups.

Edit Property Groups

  1. Hover over the property group you want to edit and select the Edit icon.
  2. Edit the Property Group Name and/or Description.
  3. Click Save.

Delete Property Groups

  1. Hover over the property you want to edit and select the Delete icon.
  2. Click OK when the confirmation message appears.

Organize Properties

Add Properties

  1. Click Create on the Properties page.
  2. Select the Property Group for the new property.
  3. Add a Property Name. You cannot use spaces in the Property Name, and any spaces you add will be replaced with underscoring in your list of properties.
  4. Add a Display Name that will show to your customers. It automatically populates with the Property Name but can be changed. Multiple properties can share a display name.
  5. Add a Property Description. This is an internal-only field that describes a property for your team.
  6. Select the Globally required option if this property should be required for every product.
  7. Select Multi language if you have multiple languages on your Commerce site.
  8. Select a Control Type. Depending on which control type you select, you may have to fill in additional fields below the selection or on the Values tab to define the parameters for this property. For example, text fields require you to set a Minimum Character Length and a Maximum Character Length. Refer to the Control Types Table for fields specific to each control type.
  9. Decide if you want to Enable Mapping to Commerce. If you select Map Field, choose the appropriate Property Mapping from the generated lis. The list is pre-filtered to include only Commerce fields that are not already mapped and are compatible with the property’s control type and validation. A Property Mapping of Attribute or Specification has additional configuration options. Attribute and Specification are also generic mappings that can be reused. They are automatically created in Configured Commerce from integration from the PIM.
  10. If you selected a Control Type of Radio Button, Multi Select or Dropdown, click the Values tab to enter values for the property.
    • Note: You can save the property without entering values and add them at a later time.
  11. Select the Template Specific Values checkbox to customize available values based on template. For example, you may want to have different Length values available for patch cables (1.5 ft, 3 ft, 6 ft) compared to bulk cables (250 ft, 500 ft, 1,000 ft). Template-specific values can be entered when you import or edit the product template record.
  12. Select the Allow Adhoc Values checkbox (Dropdown only) to enable product imports to add new dropdown values. Enter the minimum and maximum character length for the adhoc values. Values are only added through the product import when they meet this validation.
  13. Add values one at a time or click the Add multiple values link to copy and paste a list of values from XLS, CSV, or TXT.
  14. If entering values for Radio Button, you can optionally select a default value for the property. Any product that does not have a value defined for this property uses the default value when imported or created.
  15. Drag and drop the values to rearrange the sort order. Click the values column header to alphabetically order the values.
  16. Click Save.
  17. If you want to assign the newly created property to templates, click the Template Assignments tab.
    • Select the Included checkbox to add the property to the template.

    • Select the Required or Recommended checkbox to make the property a required or recommended field for a template.

    • Select a checkbox in the Template row to select or deselect all templates for the Included, Required, or Recommended columns.

If you are looking to map a field that is hidden in Configured Commerce, you need to set the Property configuration to Can Edit = yes.  See the example below.

Move or Edit Properties

If you have a large number of templates and products, changes to things like Globally Required may take time to show up on your templates and products because there is a background job that runs to update all the templates and products.

If you change a property's definition in a way that invalidates the mapping to Configured Commerce, you must remap the property (such as if you change the control type or the validation rules for things like max length, this may make the initial mapping invalid).

To move properties, click the Reorder icon on the Properties screen. From there, you can drag and drop properties within or between groups to ensure they are in the order in which it is easiest to work with them.


Delete Properties

Deleting a property can affect your product data and organization in ways you might not anticipate. Optimizely recommends you do not delete properties unless it is necessary, such as if you discontinue selling a line of products that has properties specific to only those products.

  1. Find the property you want to delete.
  2. Select the checkbox, and click Delete.
  3. Click Confirm Changes when the warning message appears.

Bulk Delete Properties

You may need to delete many properties at once with a bulk delete.

  1. Select the properties you want to delete from the property list.

  2. Select Delete in the footer bar.

  3. Click Confirm Changes when the warning message displays to proceed.

Control Types Table

This table shows the Control Type options available for properties.

When mapping to specifications, enter a sort order, which will be the order of the tab.

Control Type Description Property Mapping to Configured Commerce Examples
Text Field A text value that is likely to be unique for each product, like a model number. Configuration options include default value, min and max character length, and a RegEx entry value.
  • Specification
  • Long Description
  • Model Number
Text Area A longer text value, like a description. Configuration options include default value, min and max character length, and a RegEx entry value.
  • Specification
  • Long Description
Radio Button A single selection from multiple options. Recommended when you have a small number of options. Enter your values and set a default value on the Values tab.
  • Attribute
  • Custom Availability Message
  • Unit of Measure
Multi Select Multiple selections from multiple options. Enter your values and set a default value on the Values tab. 
  • Attribute
Dropdown A single selection from multiple options. Recommended when you have a large number of options. Enter your values on the Values tab. Select the Allow Adhoc Values checkbox if new values should automatically be added, and then set a min and max character length and an optional RegEx entry value.
  • Attribute
  • Custom Availability Message
  • Unit of Measure
HTML HTML-formatted text, like on the tabs on the product detail page.
  • Specification
  • Long Description
Number A number-only property. Enter min and max values, number of decimals and a default value.
  • Unit Cost
  • Weight
Date Picker A date-only property.
  • Activate On
  • Deactivate On
Date/Time Picker A property that lets you set both a date and time.
  • Activate On
  • Deactivate On
Boolean You want a true/false, yes/no or on/off property.
  • Track Inventory
  • Is Discontinued
  • Default as Visible

Externally Managed Properties from Configured Commerce

You can externally manage property values in the PIM to avoid maintaining identical data in more than one spot. For example, your company may want to manage product release dates in your ERP system, which would then sync the ActivateOn date with Configured Commerce and the PIM.

The PIM: Sync Product Data job pushes the values of externally managed products from Configured Commerce to the PIM. See Publish Optimizely PIM updates to Optimizely Configured Commerce for more information on the sync jobs.

You cannot specify the value of a property in the PIM (whether through property or product imports or edits) when it is marked as externally managed. You can update all other details for the property manually or through imports.

  1. Select a Control Type of Text Field, Text Area, HTML, Number, Date Picker, Date/Time Picker, or Boolean.
    • Note: You cannot externally manage properties with a Control Type of Radio Button, Multi Select or Dropdown.
  2. Select Map Field below Enable Mapping to Commerce.
  3. Select the appropriate Property Mapping from Configured Commerce. You cannot externally manage properties mapped to Attribute or Specification.
  4. Enter any minimum or maximum character or value that is lower than the corresponding property's value in Configured Commerce. For example, if the Brand property max character length in Configured Commerce is 250, you must enter a value of 250 or lower in the PIM.
  5. Select the Externally Managed checkbox. The property is now externally managed by Configured Commerce

Import Properties

You can import new properties and values or update details for properties in bulk. You can import properties without values in the import file and add them later.

The import template provided in the PIM is multi-sheet. Older single-sheet import template files will still be supported.

Formatting Data for Import

The import template provided in the PIM has two sheets: Properties and Property Values. 

An asterisk (*) denotes a required column on the sheets detailed below.


You can provide information in the following columns on the Properties sheet:

  • Name*– The unique identifier used by the application for the property.
  • Display Name– The display name used throughout the PIM for the property and on the website if the property is a customer facing attribute. If no value is entered, the value from the name field is used.
  • Property Group*– Visually groups similar properties together when editing product data in the PIM. The property group displays as a fieldset when editing products. If the property group listed doesn't exist, then it is created.
  • Description– A description of the property and displays as a tooltip when editing products.
  • Globally Required– Indicates whether or not this property is required for all products. The default is No.
  • Externally Managed– Indicates whether this property is managed within the PIM or if the data is pushed from Commerce in a recurring integration job. The default is No.
  • Control Type*– The control type used to edit this property within the PIM. (Options: Text Feld, Text Area, Radio Button, Multi Select, Dropdown, HTML, Decimal, Date Picker, Date/Time Picker, Toggle)
  • Default Value– Used for properties for products created or imported with no data for this property. (Optional for Text Field, Text Area and Radio Button control types and Number data type.)
  • Minimum Character Length– The minimum character length allowed. Only valid for text field and text area control types. The default is 0. (Optional for Text Field and Text Area control types)
  • Maximum Character Length– The maximum character length allowed. The default is 250 for Text Field and 1000 for Text Area. (Optional and only valid for Text Field and Text Area control types)
  • RegEx– Adds property specific validation rules. (Optional and only valid for Text Field and Text Area control types.)
  • Template Specific Values– Determines whether or not each template will use the full list of values or if they are restricted to using a subset. The default is No. (Optional for dropdown, radio button and multi select control types)
  • Allow Adhoc Values– Determines if users can add additional values when editing products or importing data or if they can only select from pre-defined ones. The default is No. (Optional for Dropdown control type)
  • Minimum Value– The minimum value allowed for numbers. The default is 0. (Optional for Number data type)
  • Maximum Value– The maximum value allowed for numbers. (Required for Number data type)
  • Number of Decimals– The number of decimals allowed for numbers. The default is 0. (Optional for Number data type)
  • Boolean Label– The label for Boolean controls. Options are Yes/No, True/False and On/Off. (Required for Boolean data type)
  • Mapped to Commerce Field– Defines what this property maps to in Commerce. Do not map data that will not be published to Commerce.

Property Values

You can provide information in the following columns on the Property Values sheet:

  • Property Name*– The name of the property to which the value is being added. Must match a Property Name established on the Properties sheet.
  • Values*– The available options for properties with Radio Button, Multi Select, and Dropdown control types. Values must be 255 characters or less.

Property Import Procedure

  1. Click the Properties button on the Imports page or the Import button on the Properties page.
  2. Click Download Template if you have not already formatted your properties according to the template format.
  3. Click Choose File. The property import only supports .xls or .xlsx files.
  4. Locate your property file and click Open.
  5. Click Continue. If you receive any validation errors, resolve them before attempting to import again. You can download the provided file to view error messages that are specific to each row.
  6. View your import progress at the top of the page or click Cancel to stop it. A log of the import displays on the Imports page.

Note: When a property import has validation errors, the tabs/sheets with errors will be red in the generated file.

Export Properties

You can export the property information for all properties, a filtered list or selected properties.

  1. Select properties, if you wish to export only some.
  2. Click Export, and select either All properties, Filtered list or Selected properties.
  3. Click Continue. Do not close the export window before the file is ready for download.
  4. Click the Download exported file link when it appears.