Change Sets

Change Sets allow Elastic Path users to create groups of business objects (products, catalogs, promotions, etc.). These groups can be locked to prevent editing and then moved to another Elastic Path instance using the Overview, at which time they can then be "released" to allow editing again. This is typically used as part of a staging to production workflow, where changes made in the staging environment need to be carefully managed before being moved into the production environment.

The Change Set services can be used to manipulate Change Sets, their members, and their assigned users.

Introduction to Change Sets

The following diagram shows the Change Set workflow:

Change set workflow diagram

The basic steps are:

Create a Change Set.
Add objects to it.
Lock it.
Export the changed objects to the production environment using the Overview.
Send notification to the staging environment to finalize the Change Set.

Once finalized, the objects are released and can once again be edited or added to other Change Sets.

By default, Elastic Path functionality covers all of these steps except for the last one. This needs to be provided by an external approval workflow. The other steps may also be used as integration points for external approval workflow tools.

This section describes the Change Set classes and files related to Change Set functionality, the parts of the Change Set database schema, and the services the can be used to Change Set services.

For information on working with Change Sets in the Commerce Manager, see the Elastic Path Commerce Manager User Guide.

Change Set classes and files

Most of the change sets domain classes and interfaces are located in the core library (com.elasticpath.core) in the com.elasticpath.domain.changeset and com.elasticpath.domain.objectgroup packages.

ChangeSet: a collection of business objects
ChangeSetMember: defines the mapping of a business object to a Change Set
ChangeSetStateCode: an enum that defines the possible states of a Change Set (open, finalized, or locked)
ChangeSetUser: defines the mapping of a user to a Change Set that he/she has permissions to manipulate
BusinessObjectDescriptor: describes a business object that can be added to a Chanage Set
BusinessObjectGroupMember: describes a business object that is included to a Chanage Set (similar to BusinessObjectDescriptor, but includes a group identifier)
BusinessObjectMetaData: a map containing information about a business object that can be used by external tools, such as the Data Sync Tool

The following services (defined in com.elasticpath.service.changeset) are used to manipulate Change Sets:

ChangeSetManagementService : used to add, remove, and move Change Sets, as well as to update the state of Change Sets
ChangeSetService : used to add, remove, and move Change Set members
ChangeSetPolicy : an object that defines the rules governing the state of Change Set objects

Change Set service beans are defined in WEB-INF/conf/spring/service/service.xml.

Change Set Database Schema

Change Set database schema

The following database tables are used by change set:

TCHANGESET: contains the Change Sets
TCHANGESETUSER: contains the user to Change Set mappings
TOBJECTGROUPMEMBERS: contains the business object to Change Set mappings (linked to TCHANGESET through the object_group_id column)
TOBJECTMETADATA: contains additional information about business objects

Change Set Services

The following services are used to manipulate Change Sets and their members:

ChangeSetManagementService - provides methods for persisting Change Set objects (add, get, remove, update)
ChangeSetService - provides methods for adding objects to and removing objects from Change Sets
ChangeSetPolicy - controls various aspects of overall Change Set behavior

`ChangeSetManagementService`

The ChangeSetManagementService provides methods for persisting Change Sets objects (add, get, remove, update).

Adding a Change Set

Use the ChangeSetManagementService to create new Change Sets.

ChangeSetManagementService changeSetMgmtService =
    beanFactory.getBean(ContextIdNames.CHANGESET_MANAGEMENT_SERVICE);
    ChangeSet changeSet = beanFactory.getBean(ContextIdNames.CHANGE_SET);
    changeSet.setName("CS01");
    changeSet.setDescription("My first change set");
    ChangeSet updatedChangeSet = changeSetManagementService.add(changeSet);

The service will assign a new unique guid to the change set, set the created date and persist it to the database.

Retrieving Change Sets

Use the ChangeSetManagementService to retrieve Change Sets.

ChangeSetManagementService changeSetMgmtService =
    beanFactory.getBean(ContextIdNames.CHANGESET_MANAGEMENT_SERVICE);
    Collection<ChangeSet> changeSets = changeSetMgmtService.findAllChangeSets(null);

The findAllChangeSets method takes an argument that can be null or it can be a ChangeSetLoadTuner that specifies whether information about the Change Set members is loaded. If null, all Change Set member information is loaded.

You can also search for Change Set by specifying criteria. The following example returns all open Change Sets whose name contains ChangeSet. (The noMembersLoadTuner is configured to load Change Sets without any member information.)

ChangeSetSearchCriteria criteria = new ChangeSetSearchCriteria();
criteria.setChangeSetStateCode(ChangeSetStateCode.OPEN);
criteria.setChangeSetName("CS01");
criteria.setStrictName(false);
ChangeSetLoadTuner noMembersLoadTuner = beanFactory.getBean(ContextIdNames.CHANGESET_LOAD_TUNER);
Collection<ChangeSet> changeSets = changeSetMgmtService.findByCriteria(criteria, noMembersLoadTuner);

If strictName is set to false, the search matches all Change Sets whose names contains CS01 (for example, CS01 and abcCS01def). If set to true, then the results will only contain the Change Sets whose names match CS01 exactly.

Updating the Change Set State

Use the updateState method to change the state of a Change Set.

changeSetMgmtService.updateState(changeSetGuid, ChangeSetStateCode.LOCK, null);

The ChangeSetStateCode enum defines the possible Change Set states:

OPEN

The shange set is open. Objects can be added to and removed from the change set.
LOCKED

The Change Set is locked. Objects cannot be added to or removed from the Change Set. Objects in the Change Set cannot be modified.
FINALIZED

The Change Set has been finalized. This means that changes made to objects in the Change Set have been synchronized to the target system and the objects have been released (i.e., unlocked). Once the objects are released, they can once again be edited and added to other Change Sets.|

Moving Objects From One Change Set to Another

Use the updateAndMoveObjects to move objects from one Change Set to another.

ChangeSetLoadTuner allMembersLoadTuner = beanFactory.getBean(ContextIdNames.CHANGESET_LOAD_TUNER);
allMembersLoadTuner.setLoadingMemberObjects(true);
allMembersLoadTuner.setLoadingMemberObjectsMetadata(true);

Collection<BusinessObjectDescriptor> objectsToMove = new HashSet<BusinessObjectDescriptor>();

Pair<ChangeSet, ChangeSet> sourceAndTargetChangeSet =
changeSetMgmtService.updateAndMoveObjects(sourceChangeSetGuid, targetChangeSetGuid,
    objectsToMove, allMembersLoadTuner);

ChangeSet sourceChangeSet = sourceAndTargetChangeSet.getFirst();
ChangeSet targetChangeSet = sourceAndTargetChangeSet.getSecond();

updateAndMoveObjects returns a Pair containing the source and destination Change Sets after the business objects have been moved.

`ChangeSetService`

The ChangeSetService provides methods for adding objects to and removing objects from change sets.

Adding objects to a Change Set

ChangeSetService changeSetService = beanFactory.getBean(ContextIdNames.CHANGESET_SERVICE);
Map<String, String> metadata = new HashMap<String, String>();

changeSetService.addObjectToChangeSet(changeSetGuid, object, metadata);

changeSetGuid is the change set GUID. The object parameter can be either a domain object (Product, Category, etc.) or a BusinessObjectDescriptor. The metadata map can be used to pass information during synchronization, for example, to pass Change Set update information to the Data Sync Tool.

Finding an object’s Change Sets

An object can only belong to one active (non-finalized) Change Set at any given time. Use the ChangeSetService’s findChangeSet methods to get an object’s active Change Set.

Object domainObject
...
ChangeSet changeSet = changeSetService.findChangeSet(domainObject);

findChangeSet can take either a domain object (Product, Category, etc.) or a BusinessObjectDescriptor as a parameter.

`ChangeSetPolicy`

ChangeSetPolicy controls various aspects of Change Set behavior, including:

By default, Elastic Path includes a default Change Set Policy implementation, ChangeSetPolicyImpl, which is configured in core/ep-core/src/main/resources/spring/service/service.xml

<bean id="changeSetPolicy" parent="abstractChangeSetPolicy"/>

<bean id="abstractChangeSetPolicy" abstract="true" class="com.elasticpath.service.changeset.impl.ChangeSetPolicyImpl">
    <property name="changeSetDao" ref="changeSetDao"/>
    <property name="businessObjectResolver" ref="businessObjectResolver"/>
    <property name="businessObjectGroupDao" ref="businessObjectGroupDao"/>
    <property name="metadataResolvers">
        <list>
            <ref bean="promotionMetadataResolver"/>
            <ref bean="productMetadataResolver"/>
            <ref bean="productSkuMetadataResolver"/>
            <ref bean="categoryMetadataResolver"/>
            <ref bean="dynamicContentMetadataResolver"/>
            <ref bean="dynamicContentDeliveryMetadataResolver"/>
            <ref bean="priceListDescriptorMetadataResolver"/>
            <ref bean="priceListAssignmentMetadataResolver"/>
            <ref bean="categoryTypeMetadataResolver"/>
            <ref bean="savedConditionMetadataResolver"/>
            <ref bean="baseAmountMetadataResolver"/>
            <ref bean="catalogMetadataResolver"/>
            <ref bean="attributeMetadataResolver"/>
            <ref bean="skuOptionMetadataResolver"/>
            <ref bean="skuOptionValueMetadataResolver"/>
            <ref bean="productTypeMetadataResolver"/>
            <ref bean="brandMetadataResolver"/>
        </list>
    </property>
    <property name="changeSetDependentResolvers">
        <list>
            <ref bean="baseAmountChangeSetDependencyResolver"/>
            <ref bean="productChangeSetDependencyResolver"/>
            <ref bean="productBundleChangeSetDependencyResolver"/>
            <ref bean="categoryChangeSetDependencyResolver"/>
            <ref bean="skuChangeSetDependencyResolver"/>
            <ref bean="promotionChangeSetDependencyResolver"/>
            <ref bean="catalogCategoryTypeChangeSetResolver"/>
            <ref bean="productTypeChangeSetDependencyResolver"/>
        </list>
    </property>
</bean>

Supporting New Object Types in Change Sets

The objectTypes property in the changeSetPolicy bean definition is a map of object types keyed on the interface class name.

<property name="objectTypes">
    <map>
    <entry>
        <key><value>com.elasticpath.domain.catalog.ProductBundle</value></key>
        <value>Product Bundle</value>
    </entry>
    <entry>
        <key><value>com.elasticpath.domain.catalog.Product</value></key>
        <value>Product</value>
    </entry>
    <entry>
        <key><value>com.elasticpath.domain.catalog.ProductSku</value></key>
        <value>Product SKU</value>
    </entry>
...

To add support for a new business object, add a new key-value pair to the map.

note

New business object types may also require new Object GUID resolvers.

Configuring Object GUID Resolvers

All business objects that can be added to Change Sets are required to have a globally unique business identifier. Many Elastic Path domain objects have a built-in GUID property, but others do not.

Object GUID resolvers are used to locate the unique business identifier of a business object. The following resolvers are available out of the box:

DefaultObjectGuidResolver, used for most Elastic Path domain object types, this simply uses the domain object’s GUID as the business object GUID
CategoryGuidResolver, which constructs a GUID from the Category’s non-unique GUID and the parent Catalog’s GUID
PriceListDescriptorGuidResolver, which uses the PriceListDescriptorDTO's GUID
BaseAmountDtoGuidResolver, which uses the BaseAmountDTO's GUID

The supported object GUID resolvers are defined in the objectGuidResolvers of the changeSetPolicy bean. The default GUID resolver is set in the defaultObjectGuidResolver property.

<property name="objectGuidResolvers">
    <map>
        <entry key="com.elasticpath.domain.catalog.Category">
            <bean class="com.elasticpath.service.changeset.impl.CategoryGuidResolver" />
        </entry>
        <entry key="com.elasticpath.common.dto.pricing.PriceListDescriptorDTO">
            <bean class="com.elasticpath.service.changeset.impl.PriceListDescriptorGuidResolver"/>
        </entry>
        <entry key="com.elasticpath.common.dto.pricing.BaseAmountDTO">
            <bean class="com.elasticpath.service.changeset.impl.BaseAmountDtoGuidResolver"/>
        </entry>
    </map>
</property>
<property name="defaultObjectGuidResolver" ref="defaultObjectGuidResolver"/>

If you need to support additional business object types that cannot use one of these resolvers, you can create a custom resolver by extending ObjectGuidResolver and adding a mapping to the objectGuidResolvers property of the changeSetPolicy bean definition.

Controlling Addition of Objects to Change Sets

The isChangeAllowed method of ChangeSetPolicy is implemented to determine whether objects can be added to the specified Change Set. The default implementation simply checks to see if the Change Set is in the OPEN state.

public boolean isChangeAllowed(final String changeSetGuid) {
    final ChangeSet changeSet = this.changeSetDao.findByGuid(changeSetGuid);
    if (changeSet == null) {
        LOG.info("Change set with GUID: " + changeSetGuid + " could not be found");
        return true;
    }
    final ChangeSetStateCode stateCode = changeSet.getStateCode();

    return ObjectUtils.equals(ChangeSetStateCode.OPEN, stateCode);
}

Commerce

8.4.x

Core Engine

Commerce Manager

Search Server

Integration Server

Data Sync

Cross-Platform Technologies

Shopping Cart

Account Management

Building Projects

Extending The Platform

Extending Commerce Manager

Extending Search Server

Managing Database

Managing Assets

Event Messaging

Using Spring Beans

Testing the Code

Best Practices

Internationalization and Localization

Introduction to Change Sets

Change Set classes and files

Change Set Database Schema

Change Set Services

`ChangeSetManagementService`

Adding a Change Set

Retrieving Change Sets

Updating the Change Set State

Moving Objects From One Change Set to Another

`ChangeSetService`

Adding objects to a Change Set

Finding an object’s Change Sets

`ChangeSetPolicy`

Supporting New Object Types in Change Sets

note

Configuring Object GUID Resolvers

Controlling Addition of Objects to Change Sets