Omni Commerce Connect - Key Concepts and Features

It exposes core business logic and data allowing the integration with other systems, mainly mobile and frontend applications, using REST web services. 

• Exposes core business logic and data using the commercefacades.
• It isn't for CRUD operations
• It uses POJO objects instead of DTO Classes generated by the platformwebservices extension.

• One central place which exposes consistent business rules.
• It is a commerce API.
• It may connect an external CMS, mobile apps, point of sale terminals, consoles, digital ads, touch devices, social networks, call centers or any other system with eCommerce capabilities.
• It allows Scenarios like:
  • Live stream, shop as you watch (TV + Mobile, Checkout)
  • Want this, alert me when near shop (Mobile, Product + Location Services)
  • Not available in store, deliver to home. (Point of Sale, Checkout)
• WsDTO
  • The version 1 of the web services uses the DataObjects returned by the commercefacades. They can be extend using the *-beans.xml application context.
  • To bring stability to the REST responses, the version 2 uses WsDTO which are POJOs which are only used by OCC. The Orika mapper is used for the conversion.

• All the eCommerce data, including the cart, is shared around all channels and hybris cockpits.
• A prototype of a shop may be built using HTML, CSS and Javascript.
• Publishes RESTlike web services with support for XML and JSON.
• Version 1 isn't RESTful because the cart requests requires a session ID.
• Supports OAuth 2 (default) and basic authentication over HTTPS. In the later case, each request must contain the user and the password.
• The security is based on access roles at the service layer and OAuth 2 configuration
• Supports Addons. To extend the web services, use the extension commercewebservicescommons. The extension acceleratorwebservicesaddon is an example of an addon which extends OCC.
• The representation of deep levels of attributes in the response can be configured using the parameter fields.

• Based on Spring MVC
• It is a template. If you want to customize OCC you must create a custom extension using ycommercewebservices as a template.
• Supports XML and JSON. Requests with JSON must send all the information as parameters in the URL.
• Exposes the commercefacades as web services
• Error responses
  • The HTTP Status follows the REST paradigm.
  • The body returns the type of error (mandatory), a message (mandatory), the type of the subject, a subject and a reason.
  • Each exception can be associated to a HTTP Status using Spring.
• It is recommended to use a secure HTTPS connection and client credentials for all requests.
• Cross-Origin Resource Sharing:
  • The extension supports CORS using a standard filter.
  • If no javascript app needs access to the REST web services from another domain, it can be deactivated.
• The extension includes (payment) address validators which are configured using Spring:
  • FieldNotEmptyValidator, FieldNotEmptyOrTooLongValidator, CompositeValidator (delegates validation to other validators), CountryAwareAddressValidator (delegates using the country code as criteria).

• Cookies: Most of the requests are stateless except for the cart requests. In this case the cookie returned by the server must be used in the subsequent requests. It is recommended to save the cookie from the first request and send it in every subsequent request.
  • The second version of the web services are stateless. The cart ID and user ID iis used for these requests.
• All the requests accept the parameters lang and curr to change the language and the currency of the returned response. If they are empty, the default configuration of the base store is used.
• All request have a version number to encourage the versioning of the web services. 
  • The second version is for experimentation.
• After the version of the REST services comes the UID of the basestore. The urls for the different types of items may be configured. This applies only to version 2.

These requests are stateful if you are using version 1 of the web services. A cookie is generated for the cart which must be sent in the subsequent requests.

Version 2 doesn't use sessions. The ID of the cart is used instead.

1. Log in using the client credentials (POST /rest/oauth/token) if anonymous access to the web services is deactivated. The result must be the same as browsing the website as an anonymous user.
2. Create customer (POST /customer)
3. Log in as the new customer (POST /rest/oauth/token)
4. Create a new address (POST /customers/current/addresses)
5. Get the current cart (GET /cart). Save the cookie.
6. Add entries with (POST /cart/entry)
7. Set the delivery address (POST /cart/address/delivery or DELETE and PUT)
8. Get the available delivery modes (GET /cart/deliverymodes)
9. Set a delivery mode (PUT /cart/deliverymodes/)
10. Create a payment information (POST /cart/paymentinfo)
11. Authorize the payment using a credit card (POST /cart/authorize)
12. Place order (POST /cart/placeorder)
13. See the orders (GET /orders)
14. Log out (POST /customers/current/logout)

• Cart
  • Get the current cart
  • Create, update or remove a cart entry
  • Set or remove the delivery address of the cart
  • Get the delivery modes supported by the base store for the delivery address
  • Set or remove a delivery mode
  • Create credit card payment information
  • Set the credit card payment information of the cart. It uses the payment information in the customer profile
  • Authorization of a credit card payment
  • Place the order
  • Restoration of an anonymous cart
  • Applies a promotion to the cart or remove its
  • Applies a voucher code to the cart or it releases it
• Catalogs
  
  • Listing of all the products catalogs and their versions from the base store. It may return their categories, subcategories and products.
  • Gets basic information, categories, subcategories and products  of one catalog or catalog version
  • Return all the subcategories, products and basic information of a category
• Customer Groups
  • Creation of a new customer group
  • Assignation or removal of members to a customer group
  • Listing of all the members and subgroups of a customer group
  • Listing of all the subgroups of customergroup.
• Customers
  • Registration of a customer
  • Logout
  • Change the password
  • Restore of the password
  • Change the login of the current user. How is this request used?
  • Sets the default address of a customer
  • Update and listing of the profile of a customer (title, name, language and currency)
  • Listing, update and deletion of the addresses
  • Creation of a new address
  • Listing, update and removal of the credit card payment information
  • Update of the billing address associated with a credit card payment information
  • Listing of the customer groups of the current or a given customer
• Orders
  • Listing of all the orders of the current customer
  • Listing of the details of one order
• Products
  • Search the products of the catalogs of a base store using a query. Returns also the available facets, available sort options and pagination options. Backed by the Solr search engine.
  • Suggestions for a given search term. Backed by the Solr search engine.
  • Details of a product including the price, description, basic information, gallery, categories, promotions, stock, reviews, classification and references.
  • Full or incremental export of products
  • Creation of a product review
  • Listing of products of the express update feed
  • Stock level of a product for stores located near a given geocoordinates or a place (string)
• Promotions
  • Listing of product and order promotions
  • Details of a single promotion
• Stores
  • Listing of stores near a location (string or geocoordinates). It backed by the navigation services.
  • Location of a store, given its name
• Vouchers
  • Details of a single voucher
• WCMS Components
  • Returns an images of a CMS components. Find out where is this request used.
  • Returns the details of a parragraph CMS component. Find out where is this request used.
• Miscellaneous resources
  • Listing of available languages and currencies in the base store (or in the system as fallback)
  • Listing of delivery countries
  • Listing of payment card types
  • Listing ot titles

• ROLE_TRUSTED_CLIENT: Use by frontends to register customer and update carts and address of customers and anonymous, do the checkout and see the carts of register users
• ROLE_CUSTOMERGROUP: Used by registered users to access OCC. They can update their carts and address but not register customers
• ROLE_CLIENT: Validation of addresses. Find out when it is used.

The SAP Hybris documentation has a good description of the required requests: OCC Sample Flows

Calls References

List of all four OAuth scenarios

• Supported flows
  • The frontend app could be, for example, a mobile or an AngularJS app.
  • Resource Owner Password Flow:
    • With the username and password of the customer and the frontend app credentials, a pair of access and refresh tokens are generated. Then the authorization HTTP header is filled with the access token in each of the subsequent requests of the frontend app.
    • Less secure because it contains the credentials of the customer.
  • Authorization Code Flow Or Server-side Flow:
    • The frontend app redirects the customer to an authorization server. The customer enters the username and password and gets an authorization token. The customer is redirected to the frontend app again. The frontend app exchanges this authorization token for a pair of access and refresh tokens.
    • This is the normal flow of Single Sign On (SSO).
    • Recommended
    • The credentials of the frontend app must be kept secure.
    • It is unclear how the client_secret is protected apart from using HTTPS.
  • Implicit Flow Or Client-Side Flow:
    • The frontend app redirects the customer to an authorization server. The customer enters the username and password and gets a token in the hash part of the url to go back to the frontend app. Then javascript code reads the access token in the hash and uses it to access the frontend app.
    • For Javascript-Apps which require temporary access. Is like Single Sign On for javascript. Insecure.
  • Client Credentials Flow: The same as Resource Owner Password Flow but here the frontend app authorizes itself to the authorization server using its own credentials and no customer credentials are involved.
• The refresh token is used to obtain a new a access token, when the old one has expired or it is above to expire.
• Roles
  • Anonymous
  • (Trusted) Clients
  • Customers
  • Guests (A customer who has set his email in the cart)

• The Right Flow for the Job: Which OAuth 2.0 Flow Should I Use?
• Creating an AddOn for OCC Web Services

• There are currently three ways to implement web services in Hybris and it is unclear which one is going to be further developed by Hybris:
  • Platform Web Services
  • Omni Commerce Connect v1
  • Omni Commerce Connect v2

–Based on Hybris version 6.5 and 1905