Configure properties and property groups

  • 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 of a table might be Material, Finish, and Shape

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 let you organize and 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.

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 Configured Commerce.

The following image shows the Configured Commerce storefront view. Properties mapped to attributes display filterable attributes when customers search for or visit 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 How product data appears to customers.

Best Practices

Before adding properties and property groups, see Design considerations for your data to learn more about how properties affect your PIM ecosystem. Also, consider if a property is an attribute or product description so you know where it displays to customers on your website.

You may not want to create specific property groups if you have properties like color, material, or dimensional data many products use. 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, you can create a Finish dropdown property with Copper, Chrome, and Nickel values for faucets and Maple, Walnut, and Pine values for wood furniture. You can enable the template-specific values option to select the finishes when defining the faucet and furniture templates. Defining the values of a property also enforces consistency in spelling.

Suppose it is easier to create properties without defining valid values during implementation. In that case, you can enable the ad-hoc values option for properties and import your product data to generate values. You can then disable ad-hoc values for your properties and review the values to clean up inconsistencies. The new value replaces any existing product with the old one, making cleaning up your data easier.

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 to require or recommend for specific groups of products.

Example to configure properties

Suppose you are a Senior Merchandiser managing the PIM implementation for your company, Victory Distribution. You worked with your team to design the best structure for importing and managing product information in PIM and how customers view and access product information on their Configured Commerce website. You need to build that structure in the PIM.

You want to start your PIM configuration with faucets. You identified both global and faucet-specific characteristics that you need to add as properties. You must first create the property groups for these properties, making it easier to assign properties to specific products later.

  1. Go to Data Setup > Properties.
  2. Click 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, you will have different product templates for Kitchen Faucets and Bathroom Faucets, but they will both use properties from this Common Attributes group.
  3. Click Create and add 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)
  4. Click Create and add 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
  5. Click Create and add the following properties as dropdowns to the Common Attributes group and map 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.


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 display above the grid. You can clear filters individually or all at once.
  • Only unmapped properties – Select this checkbox to see properties not mapped to Configured Commerce. If you apply any filters, 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, except for 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 selected properties. You can also Export for Translation if using Multilanguage.

Create properties

  1. Go to Data Setup > Properties.
  2. Click Create. The Properties Details page displays.


  3. Select the Property Group for the new property.
  4. Add a Property Name. You cannot use spaces in the Property Name; any spaces you add are replaced with underscoring in your list of properties.
  5. 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.
  6. (Optional) Add a Property Description. This is an internal-only field that describes a property for your team.
  7. (Optional) Select Globally Required so that properties require values for all products, regardless of template, before they can be published. Every template is updated to include this property when adding a globally required property.
  8. (Optional) Select the Externally Managed option. This property is read-only within PIM; the data comes from commerce through integration. Externally managed properties cannot use the radio button, multi-select, or dropdown control types. Properties must be mapped to be set as externally managed.
  9. 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. See Control Types Table for fields specific to each control type.


    Decide if you want to Enable Mapping to Commerce. If you select Map Field, choose the appropriate Property Mapping from the generated list. The list is pre-filtered to include only Configured 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.

    If you selected a Control Type of Radio Button, Multi Select, or Dropdown, click the Values tab to enter values for the property.

    You can save the property without entering values and add them later.
  10. Select the Template Specific Values checkbox to customize available values based on a template. For example, you may want 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.
  11. Select the Allow Adhoc Values checkbox (Dropdown only) to enable product imports to add dropdown values. Enter the minimum and maximum character lengths for the ad-hoc values. Values are only added through the product import when they meet this validation.
  12. 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.
  13. 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.
  14. Drag and drop the values to rearrange the sort order. Click the values column header to order the values alphabetically.
  15. Click Save.
  16. If you want to assign the 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.

Map control types

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 a 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 a 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 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

Map hidden fields

If you want to map a field hidden in Configured Commerce, set the property configuration to Can Edit = yes. See the example below.

Edit properties

If you have many 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 the templates and products.

Suppose you change a property's definition in a way that invalidates the mapping to Configured Commerce. In that case, 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).

Move properties

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 a property

Deleting a property can affect your product data and organization in ways you might not anticipate. You should not delete properties unless necessary, such as discontinuing selling a line of products with 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 displays.

Delete many 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.

Create a property group

  1. Go to Data Setup > Properties.
  2. Click Create a Property Group in the left menu.


  3. Add a Name and Description for your property group.
  4. Click Save or Save & Create New to continue adding groups.

Edit a property group

  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 a property group

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

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 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.