To extend a Helix resource, start with the Resource API definition by defining a new entity with a <is-a> element. The <is-a> element should contain the entity you're extending.

For example, to extend the Profile entity in the Profiles resource with a new property:

  <entity>
    <name>ext-profile</name>
    <description><![CDATA[The profile of the logged in customer.]]></description>
    <is-a>profiles.profile</is-a>
    <property>
      <name>club-code</name>
      <description><![CDATA[Customer's club code.]]></description>
      <string/>
    </property>
  </entity>
      

This new entity resource, ExtProfileEntity, is a ProfileEntity with a new club-code property.

When creating a new resource, relationships and resources are also defined. However, when extending the Profiles resource with an additional field, the relationships and resources defined by the Profiles resource are used. You may define additional relationships as needed.

The next step is to create a repository for your new entity. Your new repository will extend the repository of the entity you're extending. The repository will be used by the prototype classes to perform CRUD operations. Continuing with the example in the previous step where a ExtProfileEntity extends a ProfileEntity, the ExtProfileEntityRepositoryImpl repository will extend the ProfileEntityRepositoryImpl repository. You will need to override methods from ProfileEntityRepositoryImpl to provide the new functionalities that you need.

A converter should also be created to convert the equivalent Commerce Engine object into the new entity. The new Converter class should extend the Converter class of the entity that's being extended. For example, ExtProfileEntityConverter should extend ProfileEntityConverter. The convert method will need to be overriden to build the ExtProfileEntity with the additional property from a Commerce Engine Customer object.

The next step is to create the prototype classes that your new entity will need. The prototype classes implement the interfaces that extend the EntityResourceDefinition interface. When creating new resources, the interfaces would be generated from the <resource> element of the Resource API definition. For extending a Helix resource, the interfaces of the entity that's being extended will be used.

For example, prototype classes for ExtProfileEntity will implement the ProfileResource interfaces. To be able to see the new club-code, a prototype class for the READ operation has to be implemented. This ReadExtProfilePrototypeclass will implement the ProfileResource.Read interface.

All prototype classes for the new resource have to be annotated with the @PrototypeExtension annototation. The annototation signals that the prototype classes are extensions and will be used to handle requests instead of the prototype classes of the resource that's being extended.

        @PrototypeExtension
        public class ReadExtProfilePrototype implements ProfileResource.Read
      

In order for the Cortex Server to recognize the Helix resource, and to wire in any dependencies, a wiring class must be created. When extending a Helix resource, the new wiring class should extend the wiring class of the resource being extended. For example, the ExtProfileWiring class will extend the ProfileWiring class. Override methods only if needed. See Configuring Prototypesfor more information about wiring.