Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

ID Encoding

ID Encoding

Cortex API identifies entities such as orders, customers, items, searches, slots, navigations, and so on with IDs. To uniquely identify each domain object, the Elastic Path Core assigns each object a GUID (Globally Unique IDentifier).

The Cortex API provides a Base32Util utility class to convert the GUIDs used by the Elastic Path Core and the encoded IDs used in Cortex API.

IDs vs GUIDs

Cortex API uses IDs instead of GUIDs for the following reasons:

  • GUIDs may contain URI incompatible characters
  • GUIDs are tightly coupled with Elastic Path Core domain objects

Converting between IDs and GUIDs

The conversion between Elastic Path Core GUIDs and Cortex API IDs is done by calling Base32Util within a resource's lookup or writer implementation classes.

For example, the following method in the shipment-details resource's LookupImpl class shows how an ID is converted into a GUID before sending the information to the Elastic Path Core via the ShippingOptionLookupStrategy:

               <html><body>
<pre class="j-path">shipmentdetails<span class="j-pathsep">/</span>src<span class="j-pathsep">/</span>main<span class="j-pathsep">/</span>java<span class="j-pathsep">/</span>com<span class="j-pathsep">/</span>elasticpath<span class="j-pathsep">/</span>rest<span class="j-pathsep">/</span>resource<span class="j-pathsep">/</span>shipmentdetails<span class="j-pathsep">/</span>shippingoption<span class="j-pathsep">/</span>impl<span class="j-pathsep">/</span>ShippingOptionLookupImpl.java</pre>
<pre class="java">@Override
<span class="j-key">public </span>ExecutionResult&lt;ShippingOptionRepresentation&gt; getShippingOption<span class="j-sym">(</span><span class="j-key">final </span>String scope,
    <span class="j-key">final </span>String shipmentDetailsId, <span class="j-key">final </span>String shippingOptionId<span class="j-sym">) {
  </span><span class="j-key">return new </span>ExecutionResultChain<span class="j-sym">() {
    </span>@Override
    <span class="j-key">protected </span>ExecutionResult&lt;?&gt; build<span class="j-sym">() {
      </span>String decodedShippingOptionId = Base32Util.decode<span class="j-sym">(</span>shippingOptionId<span class="j-sym">)</span>;
      String decodedShipmentDetailsId = Base32Util.decode<span class="j-sym">(</span>shipmentDetailsId<span class="j-sym">)</span>;
      ShippingOptionDto shippingOptionDto = Assign.ifSuccessful<span class="j-sym">(
          </span>shippingOptionLookupStrategy.getShippingOptionForShipmentDetails<span class="j-sym">(</span>scope, decodedShipmentDetailsId, decodedShippingOptionId<span class="j-sym">))</span>;
      String shippingOptionUri = URIUtil.format<span class="j-sym">(</span>resourceName, scope, shipmentDetailsId, ShippingOption.URI_PART, shippingOptionId<span class="j-sym">)</span>;
      ShippingOptionRepresentation representation = shippingOptionTransformer.transformToRepresentation<span class="j-sym">(
          </span>shippingOptionDto, shippingOptionUri<span class="j-sym">)</span>;
      <span class="j-key">return </span>ExecutionResultFactory.createReadOK<span class="j-sym">(</span>representation<span class="j-sym">)</span>;
    <span class="j-sym">}
  }</span>.execute<span class="j-sym">()</span>;
<span class="j-sym">}</span></pre>
</body></html>
            

The example below shows Base32Util encoding a GUID into an ID before sending the result to other parts of the resource.

               <html><body>
<pre class="j-path">shipmentdetails<span class="j-pathsep">/</span>src<span class="j-pathsep">/</span>main<span class="j-pathsep">/</span>java<span class="j-pathsep">/</span>com<span class="j-pathsep">/</span>elasticpath<span class="j-pathsep">/</span>rest<span class="j-pathsep">/</span>resource<span class="j-pathsep">/</span>shipmentdetails<span class="j-pathsep">/</span>destinationinfo<span class="j-pathsep">/</span>impl<span class="j-pathsep">/</span>DestinationInfoLookupImpl.java</pre>
<pre class="java">@Override
<span class="j-key">public </span>ExecutionResult&lt;String&gt; findSelectedAddressIdForShipment<span class="j-sym">(</span><span class="j-key">final </span>String scope, <span class="j-key">final </span>String shipmentId<span class="j-sym">) {

  </span><span class="j-key">return new </span>ExecutionResultChain<span class="j-sym">() {
    </span>@Override
    <span class="j-key">protected </span>ExecutionResult&lt;?&gt; build<span class="j-sym">() {
      </span>String decodedShipmentId = Base32Util.decode<span class="j-sym">(</span>shipmentId<span class="j-sym">)</span>;
      ShipmentDetailsDto shipmentDetailsDto = Assign.ifSuccessful<span class="j-sym">(
          </span>shipmentDetailsLookupStrategy.getShipmentDetail<span class="j-sym">(</span>scope, decodedShipmentId<span class="j-sym">))</span>;
      String orderId = shipmentDetailsDto.getOrderCorrelationId<span class="j-sym">()</span>;
      String addressId = Assign.ifSuccessful<span class="j-sym">(
          </span>destinationInfoLookupStrategy.findSelectedAddressIdForShipment<span class="j-sym">(</span>scope, orderId, decodedShipmentId<span class="j-sym">))</span>;
      <span class="j-key">return </span>ExecutionResultFactory.createReadOK<span class="j-sym">(</span>Base32Util.encode<span class="j-sym">(</span>addressId<span class="j-sym">))</span>;
    <span class="j-sym">}
  }</span>.execute<span class="j-sym">()</span>;
<span class="j-sym">}</span></pre>
</body></html>