Create and manage product families, products, bundles, and product properties

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Define your product catalog by organizing your products in a hierarchical structure by creating products and bundles under a product family, defining related products, and adding properties (attributes) to the parent product family so that all the child products and bundles under a product family automatically inherit the properties.

By default, when you create a product family, product, or bundle record, they are in the Draft state. After you have created a product, defined related products, and configured attributes for the parent product family record, you must publish the product family, product, or bundle record for them to become available in the system to your sales agents for selling. More information:  Publish a product family, product, or bundle

In This Topic

Define products, product families, and bundles

Define product properties

Bundles and kits

Define product relationships for enhanced suggestions during product sale

Clone a product family, product, or bundle

Define products, product families, and bundles

Use the Product.ProductStructure attribute to define whether an item is a product family, product, or bundle. Set the value of this attribute to:

• 1 to create a product

• 2 to create a product family

• 3 to create a bundle

Here are some important points to consider while defining product families, products, and bundles:

• A product family record can contain multiple child product family, product, and bundle instances in a hierarchical structure. For a child product family, child product, or child bundle instance, you define the parent product family instance using the Product.ParentProductId attribute. You can’t change the parent record once you’ve set it.

• A product or bundle can’t be set as a parent, which implies that a product or bundle record can’t have child records.

• A product family, product, or bundle instance can be part of only one product family instance.

• There is no limit on the nesting level for a product family.

• The Product.ValidFromDate and Product.ValidToDate attributes don’t have any out-of-box business logic associated with them, except that there is a check to ensure that the date in Product.ValidToDate should be later than or equal to the date in Product.ValidFromDate. If required, you can implement your own business logic based on these attributes. For example, you could run a scheduled job to automatically retire last season’s products by using the date value in the Product.ValidToDate attribute.

The following code sample demonstrates how you can create a product family and a child product record.

// Create a product family
Product newProductFamily = new Product
{
   Name = "Example Product Family",
   ProductNumber = "PF001",
   ProductStructure = new OptionSetValue(2)
};
_productFamilyId = _serviceProxy.Create(newProductFamily);
Console.WriteLine("\nCreated {0}", newProductFamily.Name);

// Create a product record under the product family
Product newProduct1 = new Product
{
   Name = "Example Product 1",
   ProductNumber = "P001",
   ProductStructure = new OptionSetValue(1),
   ParentProductId = new EntityReference(Product.EntityLogicalName, _productFamilyId),
   QuantityDecimal = 2,
   DefaultUoMScheduleId = new EntityReference(UoMSchedule.EntityLogicalName, _unitGroupId),
   DefaultUoMId = new EntityReference(UoM.EntityLogicalName, _unit.Id)
};
_product1Id = _serviceProxy.Create(newProduct1);
Console.WriteLine("Created {0} under the product family", newProduct1.Name);

Define product properties

Product properties help you define the characteristics of product such as its size, color, or component. A product property is defined using the DynamicProperty entity. While defining a product property, you can only associate it to a product family record in a Draft state, and not to a product or bundle record. The maximum number of product properties that can be associated to a draft product family record is determined by the following organization setting: Organization.MaximumDynamicPropertiesAllowed. The number comes into effect when you publish a child product record or bundle under a product family that the properties are attached to, and not at the time when you attach the properties to a draft product family record.

While creating a product property, you specify its name, the product family record in Draft state with which it is associated, attributes of the property such as whether its hidden, required, or read-only, and the data type of the property. A product property can be of one of the following data types:

You cannot change the data type of a product property after its created. When you create a product property, its created in the Draft state.

The following sample code demonstrates how you can create a product property:

DynamicProperty newProperty = new DynamicProperty
{
    Name = "Example Property",
    RegardingObjectId = new EntityReference(Product.EntityLogicalName,
                                            _productFamilyId),
    IsReadOnly = true,
    IsRequired = true,
    IsHidden = false,
    DataType = new OptionSetValue(3), //Single line of text
    DefaultValueString = "Default Value"
};
_productPropertyId = _serviceProxy.Create(newProperty);

For the complete sample, see Sample: Create and publish products

For information about creating and managing product properties using the web client, see Help & Training: Use properties to describe a product

Change product properties

It's important to know the various states of the product property in order to understand how and when it can be changed. A product property can be in Draft, Active, or Retired state. When a product is created, its in the Draft state, and changes to the Active state once the product family record with which it is associated is published. When the associated product family record is retired, the state of the product property also changes to Retired.

A product property can be changes at two levels: first at the product family level to which the product property is associated with; second at the child product family, product, or bundle level where the product property is inherited.

Changing product property for the product family that its associate with

For a Draft product family record, you can change a product property associated to it. Once you publish the product family record (changes to Active state), you cannot change the product property until you revise the product family record. After revising the product family record (changes to Under Revision state), and then overwrite the published (active) version of the property to make changes. For information about product life cycle, see Publish, revise, revert, retire, and activate products (product lifecycle)

Changing inherited product property for the child product family, product, or bundle

For a product property in the Draft state, the child product family, product, and bundle records can override the inherited property to define their own version of the property. For example, override the inherited property to change its name or change attributes from hidden to visible, required to optional, or read-only to updatable. You cannot override or change the data type of the inherited property.

To override a product property, you create an instance of the product property and set the BaseDynamicPropertyId property to the GUID of the property you are overriding. Additionally, you also associate the new property instance to the child product family, product, or bundle record where its being overridden.

The following sample code demonstrates how you can override an existing product property record, say with GUID _productPropertyId, and associate the overridden property to the product record, say with GUID _product1Id. After this, you can update the attributes of the new property to specify your own values to complete the override.

// Override a product property
DynamicProperty newOverrideProperty = new DynamicProperty();
newOverrideProperty.BaseDynamicPropertyId = new EntityReference(DynamicProperty.EntityLogicalName,
                           _productPropertyId);
newOverrideProperty.RegardingObjectId = new EntityReference(Product.EntityLogicalName, _product1Id);
_productOverridenPropertyId = _serviceProxy.Create(newOverrideProperty);

// Retrieve the attributes of the cloned property you want to update                    
ColumnSet columns = new ColumnSet();
columns.AddColumns("name", "isreadonly", "isrequired");
DynamicProperty retrievedOverridenProperty = (DynamicProperty)_serviceProxy.Retrieve(
                                               DynamicProperty.EntityLogicalName, _productOverridenPropertyId,
                                               columns);

// Update the attributes
retrievedOverridenProperty.Name = "Overridden Example Property";
retrievedOverridenProperty.IsReadOnly = true;
retrievedOverridenProperty.IsRequired = false;
_serviceProxy.Update(retrievedOverridenProperty);

For the complete sample, see Sample: Create and publish products

For a product property in the Active state, you can overwrite the inherited property for the child product family, product, or bundle record provided both the following clauses are true:

• The child product family, product, or bundle record is in the Under Revision state.

• The inherited active product property is already overridden.

To overwrite a product property, you create an instance of the product property and set the BaseDynamicPropertyId property to the GUID of the already overridden property. Additionally, you also associate the new property instance with the product family, product, or bundle record that is in the Under Revision stage.

The following sample code demonstrates how you can overwrite a product property record in the active state that is already overridden, say with GUID _productOverridenPropertyId, and associate the new property to the product record in the Under Revision state, say with GUID _product1Id. After this, you can update the attributes of the new property to specify your own values, and complete the overwrite.

// Overwrite a product property
DynamicProperty newOverwriteProperty = new DynamicProperty();
newOverwriteProperty.BaseDynamicPropertyId = new EntityReference(DynamicProperty.EntityLogicalName,
                           _productOverridenPropertyId);
newOverwriteProperty.RegardingObjectId = new EntityReference(Product.EntityLogicalName,
    _product1Id);
_productOverwrittenPropertyId = _serviceProxy.Create(newOverwriteProperty);

// Retrieve the attributes of the cloned property you want to update
ColumnSet myCols = new ColumnSet();
myCols.AddColumns("name", "isreadonly", "isrequired");
DynamicProperty retrievedOverwrittenProperty = (DynamicProperty)_serviceProxy.Retrieve(
                                                   DynamicProperty.EntityLogicalName, _productOverwrittenPropertyId,
                                                   myCols);

// Update the attributes of the cloned property to complete the overwrite 
retrievedOverwrittenProperty.Name = "Overwritten Example Property";
retrievedOverwrittenProperty.IsReadOnly = true;
retrievedOverridenProperty.IsRequired = false;
_serviceProxy.Update(retrievedOverwrittenProperty);

For the complete sample, see Sample: Create and publish products

Bundles and kits

A bundle is a feature introduced in Dynamics 365 to replace the older kit functionality. Similar to a kit, a bundle is a collection of products that is sold as single unit. Product bundling is useful in grouping products in a way that customers get more benefit from the full line of products or to offer discounts on bundled products that enables you to group products and sell as a single unit.

Only products can be added to a bundle; you can’t add a product family, a bundle, or a kit record to a bundle. You can add products to a bundle or a kit by creating a product association record using the ProductAssociation entity. The ProductAssociation.ProductId record specifies the bundle or kit that you want to add a product to and the ProductAssociation.AssociatedProduct specifies the product to be added. The maximum number of products that can be added to a bundle is determined by the following organization setting: Organization.MaxProductsinBundle.

You can also use the Sales tab in the system settings area in Dynamics 365 or Dynamics 365 for Outlook to specify the maximum number of products that can be added to a bundle. More information:   TechNet: Manage product catalog configuration

The following code sample demonstrates how you can add products to a bundle.

// Add a product to a bundle
ProductAssociation newAssociation1 = new ProductAssociation
{
   AssociatedProduct = new EntityReference(Product.EntityLogicalName, _product1Id),
   ProductId = new EntityReference(Product.EntityLogicalName, _bundleId),
   Quantity = new decimal(15),
   ProductIsRequired = new OptionSetValue(0),
   UoMId = new EntityReference(UoM.EntityLogicalName, unit.Id)
};
_product1AssociationId = _serviceProxy.Create(newAssociation1);                    

// Add another product to the bundle                    
ProductAssociation newAssociation2 = new ProductAssociation
{
   AssociatedProduct = new EntityReference(Product.EntityLogicalName, _product2Id),
   ProductId = new EntityReference(Product.EntityLogicalName, _bundleId),
   Quantity = new decimal(20),
   ProductIsRequired = new OptionSetValue(1),
   UoMId = new EntityReference(UoM.EntityLogicalName, unit.Id),                        
};
_product2AssociationId = _serviceProxy.Create(newAssociation2);

if ((_product1AssociationId != null) && (_product1AssociationId != null))
Console.WriteLine("\nAdded both the products to the bundle");

For the complete sample, see Sample: Add products to a bundle.

Differences between kits and bundles

Both kits and bundles enable you to group products into a single unit, but here are some differences between the two.

Define product relationships for enhanced suggestions during product sale

You can define related products for a product that are displayed as suggestions to your sales agents during opportunity or order management. The product suggestions for a product enables your sales agents to recommend related products and bundles/kits to the customers, and increase product sales. You can define the following relationships for a product: accessory, cross-sell, substitute, and up-sell. For example, Surface Pro can be added as an up-sell product for Surface RT so that when your sales agent is adding Surface RT to any opportunity, quote, order, or invoice, Surface Pro will be suggested as the up-sell option.

Use the ProductSubstitute.SalesRelationshipType attribute to define product relationships. Set the value of this attribute to:

• 0 for up-sell

• 1 for cross-sell

• 2 for accessory

• 3 for substitute

While defining product relationships, it’s important to define the direction of the relationship to prevent duplication of data. The supported directions the product relationships are:

Use the ProductSubstitute.Direction attribute to specify direction for a product relationship. Set the value of this attribute to:

• 0 for uni-directional

• 1 for bi-directional

The following code sample demonstrates how you can define relationships for products.

// Set product relationship
// Set product1 and product2 as substitute of each other (bi-directional)
ProductSubstitute newProductRelation = new ProductSubstitute
{
   SalesRelationshipType = new OptionSetValue(3),
   Direction = new OptionSetValue(1),
   ProductId = new EntityReference(Product.EntityLogicalName, _product1Id),
   SubstitutedProductId = new EntityReference(Product.EntityLogicalName, _product2Id)
};
_productRelationId = _serviceProxy.Create(newProductRelation);

Clone a product family, product, or bundle

Use the CloneProductRequest message to clone a product family, product, or bundle record, and create a copy of the record under the same parent node. You must provide the ID of the record to clone. Cloning a product record also copies the properties of the product. The cloned record is created with the date and time stamp appended to the original values in the Product.Name and Product.ProductNumber attributes; the date time stamp denotes the time when the record was cloned. The following code sample demonstrates how to clone a product.

CloneProductRequest cloneReq = new CloneProductRequest
{
   Source = new EntityReference(Product.EntityLogicalName, _productId)
};

CloneProductResponse cloned = (CloneProductResponse)_serviceProxy.Execute(cloneReq);                                     
_productCloneId = cloned.ClonedProduct.Id;

// Retrieve the cloned product record
Product retrievedProduct = (Product)_serviceProxy.Retrieve(Product.EntityLogicalName, _productCloneId, new ColumnSet(true));
Console.WriteLine("\nCreated clone product: {0}", retrievedProduct.Name);

Next step

Publish your product records to make products available for selling by your sales agents. More information:  Publish a product family, product, or bundle

See Also

Publish, revise, revert, retire, and activate products (product lifecycle)
Sample: Create and publish products
Sample: Clone product records
Sample: Add products to a bundle
Product catalog entities

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright