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

What's New for Cortex API 1.10.0

What's New for Cortex API 1.10.0

Elastic Path Cortex API Version 1.10.0 includes bug fixes, performance improvements, and new features.

If you have any questions, contact Support or go to the Grep community site for the latest information and access to support bulletins, forums, and other Elastic Path resources.

New Features

Promotions and Coupons

Added new APIs and integrations to support displaying and applying promotions and coupon defined in Commerce Engine:

  • Promotions:
    • Retrieve promotions applied to items.
    • Retrieve promotions applied to cart line items.
    • Retrieve promotions applied to cart totals.
    • Retrieve promotions applied to shipping options.
    • Retrieve promotions applied by coupons.
    • Retrieve promotions applied purchases.
  • Discounts:
    • Retrieve discount generated by cart subtotal promotions.
    • Retrieve discount generated by cart promotions for a purchase.
  • Coupons:
    • Apply coupons to order.
    • Remove coupons from order.
    • Retrieve coupons applied to order.
    • Retrieve coupons applied to purchase.

Personalization

Added Cortex framework support for personalization of prices, promotions and slots in clients:

  • Added new http header: x-ep-user-traits to transport of user traits from client application for personalization purposes.
  • User traits are automatically inferred from Commerce Engine data available about the shopper.
  • Added extension points for defining custom inferred traits.
  • Out of the box, Prices, Promotions and Slots resources can be personalized with user traits.

Recommendations

Added new API integrations to support displaying recommendations sourced from Commerce Engine:

  • Retrieve item cross-sell recommendations.
  • Retrieve item up-sell recommendations.
  • Retrieve item accessory recommendations.
  • Retrieve item warranty recommendations.
  • Retrieve item replacement recommendations.
  • Retrieve item topseller recommendations.

Payment Tokenization

Added new API integration to support storing payment tokens with an order or a shopper's account:

  • Add payment token to profile for repeated use
  • Remove token from profile.
  • Add payment token to order for one time use.
  • Remove token from order.

Shipments

Added new APIs and integrations to support displaying shipping information about a purchase:

  • Retrieve shipments for a purchase

Tooling

  • APIs can now be defined in XML and used to generate source code.
  • Simpler Programming Model
    • Read From Other is now an annotation
    • Linking handled in Cortex framework
    • Max-age creation in Cortex framework
    • Self object creation handled in Framework
    • Type field auto-generated type generated from entity-type in definitions

Recommendations Page Size Configuration File

Cortex now requires a page size to set the pagination for recommendations. Since a large number of recommended items may be available, the page size will limit the number of items retrieved per request.

To set the recommendations page size:

  1. In your C:/etc/ep/cortex/system/config directory, create a file named recommendationsPageSize.config.
  2. In recommendationsPageSize.config, add the following field and define your page size value:
rest.recommendations.page.size.VALUE=I"<positive integer>"

Example with 5 items per page:

rest.recommendations.page.size.VALUE=I"5"

TypeBuilderFactory

TypeBuilderFactory is no longer recommended for use with entities. It will be removed in the future. Use the entity builders instead.

Before:

ItemEntity encodedItemEntity = TypeBuilderFactory.builder(ItemEntity.Builder.class)
											 .withItemId(encodedItemId)
											 .build();

After:

ItemEntity encodedItemEntity = ItemEntity.Builder.builder()
											 .withItemId(encodedItemId)
											 .build();

Enhancements

Recommendations

The LookupStrategy interface has been split into 3. There is now a dedicated interface each for both item promotions and navigation promotions

OnFailure Result Builder Interface

The OnFailure result builder interface has changed slightly. This is not an API breaking change, but we have simplified creating error messages a little bit.

The builder methods now accept formatting args as a parameter so that you can write String.format() style messages inline.

Old: public static FailedResultBuilder returnBadURI(final String message) New: public static FailedResultBuilder returnBadURI(final String message, final Object... formatArgs)

eg. You should prefer the new style to the old, although both will work.

Old style: OnFailure.returnBadURI(String.format("My happy message with type %s and name %s", type, name)); New style: OnFailure.returnBadURI("My happy message with type %s and name %s", type, name));

We have added some new parameters to the cortex ce webapp archetype.

Why: Due to recent changes in our maven pom structure (introduction of the webapp parent pom in particular), we were limiting extension cases without making this change, so it's happening now.

What: These parameters describe the maven coordinates of the ce wrapper in much the same way that we locate resource configuration, which arguably should always have been there.

Now when you generate the cortex webapp, you will be asked for 3 sets of information:

  1. Cortex Webapp coordiates:
    Define value for property 'groupId': : com.mycompany
    Define value for property 'artifactId': : cortex-webapp
    Define value for property 'version':  1.0-SNAPSHOT: : 
    Define value for property 'package':  com.mycompany: :
  2. Cortex CE Wrapper coordinates (**new**)
    Define value for property 'ep-commerce-engine-wrapper-artifact-id': : ext-ce-wrapper
    Define value for property 'ep-commerce-engine-wrapper-group-id': : com.mycompany
    Define value for property 'ep-commerce-engine-wrapper-version': : 1.0-SNAPSHOT
  3. Cortex WebApp Resource Configuration
    Define value for property 'resource-configuration-artifact-id': : ext-resource-configuration
    Define value for property 'resource-configuration-group-id': : com.mycompany
    Define value for property 'resource-configuration-version': : 1.0-SNAPSHOT
The happy little characters in the middle there are the new ones for the ce wrapper.

Internal SPI Change: @ResourceUri has been renamed

  • @ResourceUri has been renamed to @AnyResourceUri
  • @SingleResourceUri has been created as a more targeted alternative

To upgrade, it is safe to rename every usage of @ResourceUri to @AnyResourceUri

This name change is to better signify what the annotation actually matches. @AnyResourceUri is a greedy annotation that will match any resource URI. The new annotation @SingleResourceUri has been created to target only a single resource URI.

@SingleResourceUri should be used in all cases where a single resource uri is to be matched. This annotation is useful for matching the child resource uri in below cases:

  • /parent/child/childId/parentId
    @Path({@ResourceName.PATH_PART, @SingleResourceUri .PATH_PART, @ResourceId.PATH_PART})
  • /parent/child/childId
    @Path({@ResourceName.PATH_PART, @SingleResourceUri .PATH_PART})

@AnyResourceUri is useful for matching both the child and grandchild resource uris in below case:

  • /parent/parentId/child/childId/grandchild/grandchildId
    @Path({@ResourceName.PATH_PART, @ResourceId.PATH_PART, @AnyResourceUri .PATH_PART})

Internal SPI Change: Entity location change

As part of this release, several entities have been replaced by versions generated from the definitions schema. These may have changed name, or been relocated to a different package or bundle.

Old Name Old Package Old Bundle New Name New Package New Bundle
AddressDto

com.elasticpath.rest.resource.commons

.integration.addresses.dto

ep-resource-address-commons AddressDetailsEntity

com.elasticpath.rest.definition.base.common

ep-rest-base-definitions-api
AddressEntity

com.elasticpath.rest.schema.entity

ep-resource-profiles AddressEntity com.elasticpath.rest.definition.addresses ep-resource-addresses-api
BillingAddressEntity

com.elasticpath.rest.schema.entity

ep-resource-combined-schema AddressEntity

com.elasticpath.rest.definition.addresses

ep-resource-addresses-api
CostEntity com.elasticpath.rest.schema.entity ep-resource-combined-schema CostEntity com.elasticpath.rest.definition.base.common ep-rest-base-definitions-api
CreditCardPaymentMeansDto

com.elasticpath.rest.resource.purchases

.paymentmeans.integration

ep-resource-purchases PaymentMeansCreditCardEntity com.elasticpath.rest.definition.purchases ep-resource-purchases-api
DeliveryDto

com.elasticpath.rest.resource.orders.integration.deliveries.dto

ep-resource-orders DeliveryEntity com.elasticpath.rest.definition.orders ep-resource-orders-api
NameEntity

com.elasticpath.rest.schema.entity

ep-resource-combined-schema NameEntity com.elasticpath.rest.definition.base.common ep-rest-base-definitions-api
OrderDto

com.elasticpath.rest.resource.orders.integration.deliveries.dto

ep-resource-orders OrderEntity

com.elasticpath.rest.definition.orders

ep-resource-orders-api
PriceEntity

com.elasticpath.rest.resource.prices.schema

ep-resource-prices PriceEntity

com.elasticpath.rest.definition.prices

ep-resource-prices-api
PriceRangeEntity

com.elasticpath.rest.resource.prices.schema

ep-resource-prices PriceRangeEntity

com.elasticpath.rest.definition.prices

ep-resource-prices-api
ProfileDto

com.elasticpath.rest.resource.profiles.integration.dto

ep-resource-combined-schema ProfileEntity com.elasticpath.rest.definition.profiles ep-resource-profiles-api
PurchaseDto

com.elasticpath.rest.resource.purchases.integration

ep-resource-purchases PuchaseEntity

com.elasticpath.rest.definition.purchases

ep-resource-purchases-api
PurchaseLineItemEntity

com.elasticpath.rest.resource.purchases.lineitems.integration

ep-resource-purchases PurchaseLineItemEntity

com.elasticpath.rest.definition.purchases

ep-resource-purchases-api
TaxEntity

com.elasticpath.rest.schema.entity

ep-resource-combined-schema TaxEntity com.elasticpath.rest.definition.base.common ep-rest-base-definitions-api

The factory used to construct these new Entities is also different to the old Entity format. For example:

PriceEntity priceEntity = ResourceTypeFactory.createResourceEntity(PriceEntity.class)
                                             .setPurchasePrice(Collections.singletonList(purchaseCostEntity));
ItemPriceEntity result = TypeBuilderFactory.builder(ItemPriceEntity.Builder.class)
                                           .addingPurchasePrice(purchaseCostEntity)
                                           .build();

Redirect Response Code has changed

The redirect response code has changed from 303 SEE OTHER to 307 TEMPORARY REDIRECT. This change was made to better align the response code with the intended use in the HTTP specification. In Browser based applications, the browser will treat this response code the same as 303 SEE OTHER.

This affects the following calls:

  • GET /carts/{scope}/default
  • GET /profiles/{scope}/default

Billing Info Invalid Order Error Code Change

Calling POST to select billing info of a user for a non-existent order returns an error code.

/orders/<scope>/<invalid_order_id>/billingaddressinfo/selector/<default_billing_addr_uri>

Before: 403

After: 404

3rd Party Library Changes and Upgrades

Updated Dependencies

  • Apache Felix Configuration Admin Service has been upgraded from 1.6.0 to 1.8.0
  • Apache Felix File Install has been upgraded from 3.2.6 to 3.2.8
  • Apache Felix Framework has been upgraded from 4.2.1 to 4.4.0
  • Apache Felix Http Api has been upgraded from 2.2.0
  • Apache Felix Http Base has been upgraded from 2.2.0 to 2.2.2
  • Apache Felix Http Bridge has been upgraded from 2.2.0 to 2.2.2
  • Apache Felix Http Proxy has been upgraded from 2.2.0 to 2.2.2
  • Apache Felix Http Whiteboard has been upgraded from 2.2.0 to 2.2.2
  • Apache Felix Metatype Service has been upgraded from 1.0.8 to 1.0.10
  • Apache Felix Web Management Console has been upgraded from 4.2.0 to 4.2.2
  • Apache HttpClient OSGi bundle has been upgraded from 4.3.1 to 4.3.3
  • Apache HttpCore OSGi bundle has been upgraded from 4.3 to 4.3.2
  • Apache Shiro - Core has been upgraded from 1.2.2 to 1.2.3
  • Commons Lang has been upgraded from 3-3.1 to 3-3.3.2
  • Jackson Core has been upgraded from 2.3.0 to 2.3.2
  • Jackson Databind has been upgraded from 2.3.0 to 2.3.2
  • Jackson Jaxrs Base has been upgraded from 2.3.0 to 2.3.2
  • Jackson-annotations has been upgraded from 2.3.0 to 2.3.2
  • Jackson-JAXRS-JSON has been upgraded from 2.3.0 to 2.3.2
  • Jackson-module-JAXB-annotations has been upgraded from 2.3.0 to 2.3.2
  • Jersey Core has been upgraded from 1.17.1 to 1.18.1
  • Jersey Server has been upgraded from 1.17.1 to 1.18.1
  • Jersey Servlet has been upgraded from 1.17.1 to 1.18.1
  • Logback Classic Module has been upgraded from 1.0.13 to 1.1.2
  • Logback Core Module has been upgraded from 1.0.13 to 1.1.2
  • MessagePack For Java has been upgraded from 0.6.7 to 0.6.10
  • Metrics Core has been upgraded from 3.0.1 to 3.0.2
  • SLF4J API Module has been upgraded from 1.7.5 to 1.7.7
  • JCL 1.1.1 Implemented Over SLF4J has been upgraded from 1.7.5 to 1.7.7
  • JUL To SLF4J Bridge has been upgraded from 1.7.5 to 1.7.7
  • Log4j Implemented Over SLF4J has been upgraded from 1.7.5 to 1.7.7
  • OSGi LogService Implemented Over SLF4J has been upgraded from 1.7.5 to 1.7.7
  • CXF URI Template Utilities has been upgraded from 1.5 to 1.6

Added Dependencies

  • Google Guava 16.0.1
  • JCache Java Temporary Caching API 1.0.0

Removed Dependencies

  • Apache Commons Codec 1.8
  • ConcurrentLinkedHashMap 1.4
  • Jersey Apache HTTP Client 4.x 1.17.1
  • Jersey Client 1.17.1

Environment Changes

  • For changes on Recommendations Page size Please follow the instruction in Configuring Recommendations Page Size
  • Deployment Configuration Change: Tomcat fails to stop when this listener wants to unload thread local impls that have been unloaded by OSGI. We have removed this Listener from the Tomcat configuration for server.xml and recommend the same when deploying.
      <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

Transitive Dependencies

Due to the wild-carding changes above, the rest-resources dependencies no longer need to be specified in addition to the epcommerce dependency. Only the ep-commerce dependency is required.

An example using carts, both dependencies were previously required:

<dependency>
	<groupId>com.elasticpath.rest.resource</groupId>
	<artifactId>ep-resource-carts</artifactId>
	<scope>provided</scope>
</dependency>
<dependency>
	<groupId>com.elasticpath.rest.integration.epcommerce</groupId>
	<artifactId>ep-resource-carts-epcommerce</artifactId>
	<scope>provided</scope>
</dependency>

Now only the epcommerce dependency for carts:

<dependency>
	<groupId>com.elasticpath.rest.integration.epcommerce</groupId>
	<artifactId>ep-resource-carts-epcommerce</artifactId>
	<scope>provided</scope>
</dependency>

This may impact your customisations if you have overridden any of the dependency plugin execution groups to customise your Cortex webapp.

New Properties in the Cortex Webapp

Note:

This is not the parent webapp, but ep-cortex-dce-webapp.

<ep-commerce-engine-wrapper-group-id>com.elasticpath.rest.integration.epcommerce</ep-commerce-engine-wrapper-group-id>
<ep-commerce-engine-wrapper-artifact-id>ep-commerce-engine-wrapper</ep-commerce-engine-wrapper-artifact-id>
<ep-commerce-engine-wrapper-version>1.10.100.20140827092242</ep-commerce-engine-wrapper-version>

Messaging And JMS Connection Pools

New in this release, Cortex makes use of JMS messaging to communicate some business events to other EP applications as well as to other subscribed integration systems.

To facilitate this messaging there are some changes to the Cortex WebApp infrastructure as described here: UpdatedDeploymentGuide

Pay particular attention to the changes to Tomcat context.xml (note the addition of a JMSConnectionFactory configuration) and the new Tomcat container library dependencies (for connection pooling) that we use in the Tomcat Maven Plugin and Cargo Maven Plugin.

OSGi WEB-INF/bundles Wildcards

The following artifacts:

<artifactItem>
	<groupId>com.elasticpath.rest.relos</groupId>
	<artifactId>ep-relos-resource-management</artifactId>
	</artifactItem>
<artifactItem>
	<groupId>com.elasticpath.rest.relos</groupId>
	<artifactId>ep-relos-resource-management-index-by-name-strategy</artifactId>
</artifactItem>
...
...

Are now replaced with wildcards:

<includeGroupIds>
	com.elasticpath.rest,
	com.sun.jersey,
	com.fasterxml.jackson
</includeGroupIds>

OSGi Bundles Execution Group Changes

Execution groups before:

copy-relos-OSGi-bundles
copy-event-OSGi-bundles
copy-integration-commons-OSGi-bundles
copy-resource-server-commons-OSGi-bundles
copy-carts-resource-and-integration-OSGi-bundles
copy-item-resource-and-integration-OSGi-bundles
copy-prices-resource-and-integration-OSGi-bundles
copy-navigations-resource-and-integration-OSGi-bundles
copy-registrations-resource-and-integration-OSGi-bundles
copy-slots-resource-and-integration-OSGi-bundles
copy-assets-resource-and-integration-OSGi-bundles
copy-availabilities-resource-and-integration-OSGi-bundles
copy-orders-resource-and-integration-OSGi-bundles
copy-paymentmethods-resource-and-integration-OSGi-bundles
copy-paymenttokens-resource-and-integration-OSGi-bundles
copy-profiles-resource-and-integration-OSGi-bundles
copy-purchases-resource-and-integration-OSGi-bundles
copy-shipmentdetails-resource-and-integration-OSGi-bundles
copy-taxes-resource-and-integration-OSGi-bundles
copy-totals-resource-and-integration-OSGi-bundles
copy-searches-resource-and-integration-OSGi-bundles
copy-creditcards-resource-and-integration-OSGi-bundles
copy-emails-resource-and-integration-OSGi-bundles
copy-geographies-resource-and-integration-OSGi-bundles
copy-commerce-engine-OSGi-bundles
copy-shared-libs-OSGi-bundles
copy-logging-OSGi-bundles
copy-transitive-resource-dependencies-OSGi-bundles
copy-spring-OSGi-bundles
copy-gemini-blueprint-OSGi-bundles
copy-jersey-OSGi-bundles
copy-apache-http-OSGi-bundles
copy-apache-camel-bundles
copy-jackson-OSGi-bundles
copy-felix-OSGi-bundles
copy-osgi-webconsole-OSGi-bundles

Execution groups after:

copy-cortex-OSGi-bundles
copy-resource-configuration-OSGi-bundles
copy-commerce-engine-OSGi-bundles
copy-dependant-OSGi-bundles
copy-logging-OSGi-bundles
copy-blueprint-osgi-bundles
copy-osgi-base-OSGi-bundles
copy-osgi-webconsole-OSGi-bundles

Cortex WebApp Extension Project Update

We have added some new parameters to the cortex ce webapp archetype.

Why: Due to recent changes in our maven pom structure (introduction of the webapp parent pom in particular), we were limiting extension cases without making this change, so it's happening now.

What: These parameters describe the maven coordinates of the ce wrapper in much the same way that we locate resource configuration, which arguably should always have been there.

Now when you generate the cortex webapp, you will be asked for 3 sets of information:

  1. Cortex Webapp coordiates:
    Define value for property 'groupId': : com.mycompany
    Define value for property 'artifactId': : cortex-webapp
    Define value for property 'version':  1.0-SNAPSHOT: : 
    Define value for property 'package':  com.mycompany: :
  2. Cortex CE Wrapper coordinates (**new**)
    Define value for property 'ep-commerce-engine-wrapper-artifact-id': : ext-ce-wrapper
    Define value for property 'ep-commerce-engine-wrapper-group-id': : com.mycompany
    Define value for property 'ep-commerce-engine-wrapper-version': : 1.0-SNAPSHOT
  3. Cortex WebApp Resource Configuration
    Define value for property 'resource-configuration-artifact-id': : ext-resource-configuration
    Define value for property 'resource-configuration-group-id': : com.mycompany
    Define value for property 'resource-configuration-version': : 1.0-SNAPSHOT

The happy little characters in the middle there are the new ones for the ce wrapper.

Planned API changes

  • A mapping resource was added to support AEM item lookups. This resource will be refactored in the future into a uniform search API.
  • Possible promotions APIs are not integrated with Commerce Engine and may be removed in the future.
  • Store and Navigations recommendations are not integrated with Commerce Engine and maybe removed in the future.