The setting file contains the initial information to start a Catalog session. The format of this file is the same than the Configurator initialization file.

Please refer to the previous section “Integration for CPQ Configurator” / “Initialization XML file”.

The default catalog.xml file can be found in the

directory: <CpqInstallDirectory>\conf\run\settings\catalog.

This file can also be accessed through the Designer thanks to the “Manage files” step of the “Administer workspace” process.

There are two ways to call an external service (java class) within the Catalog:

• A custom java class can be used in the settings of the configuration file
• A custom java class can be call in an external component

USE OF EXTERNAL SERVICE IN THE SETTINGS

Refer to the previous section for the Configurator “Use of external services in the settings”.

USE OF EXTERNAL SERVICE IN THE EXTERNAL COMPONENTS

Refer to the previous section for the Configurator “Use of external services in the External Components.

CONCEPT

Catalog provides a standard interface that can be used directly from a hosting application (such as a portal for example or a CRM like in the following example).

This standard interface can be integrated into hosting application by:

• Redirection in the whole client web browser
• Opening a new window for client web browser
• Redirection in a frame in the client web browser

Communications between the hosting application and the Catalog are based on IN and OUT calls using standard web services named “CatalogUI” and “CartStatefulWS” whose exchange flows are based on XML messages.

"IN" WSDL – CatalogUI

Server stub part is deployed within CPQ Application Server and is ready to use Client stub part must be generated and deployed within the hosting application “OUT” WSDL – cartStatefulWS :

Client stub part is deployed within CPQ Application Server and is ready to use

Server stub part must be generated and deployed within the hosting application

The Catalog standard user interface integrates access to the Configurator standard user interface

DETAILED INTEGRATION PROCESS

Initialization and start

Step 1: By using the WSDL definition file “catalogUI.wsdl”, the client stubs are generated and placed into hosting application classpath.

Step 2: A client instance is created and the target point is defined with the correct CPQ URL:

Step 3: Input parameters are set. Two methods for this setup:

• RunUIRequest
  
  
  
  
• RunRequest
  
  

Step 4: The “runUI” / “run” action is executed (depending on the method used in step 3 above):

• RunUI
  
  
• Run
  
  

Step 5: The hosting application redirects with the output URL.

For more details on Catalog XML flow, please refer to the previous section “Initialization XML file”. For more details on Catalog layout XML flow, please refer to the CPQ Customization Guide.

Back to hosting application

On the hosting application side, the class “CartStatefulWSSkeleton.java” must be implemented for the following methods:

• addXML: Send the XML product information – This method is triggered by the ADD_TO_CART action
• refresh: Refresh the hosting application – This method is triggered by the Catalog UI after any action
• checkRights: Test whether the user has sufficient rights to access to the Catalog UI or not .This method is called at the beginning of the session, its result will authorize/unauthorize the display of the Catalog UI
• addXMLMultiple: Send several XML product information – this method is triggered by the SEARCH_AND_ADD action
• getCart: Get the quote information to be displayed in the quote box/sticker UI component. This method is triggered when displaying/refreshing the quote UI component
• updateCart: Update a quote line cell or a quote total cell and get the quote information to be displayed in the quote box/sticker UI component. This method is triggered when the user click update a cell of the quote (quantity for instance)
• getContext: Returns Catalog input parameters. This method is triggered in case of the Catalog is accessed through a bookmark and after the call to the method checkRights has been successful
• getLineXML (previously getLineCartXML): Returns the XML representation of a configured or standard product. This method when displaying/refreshing the quote UI component
• selectLine (previously selectLineCart): Forces the insertion point in the quote box/sticker UI component. This method is triggered on corresponding user action
• createCart: Creates a quote directly from the Catalog. This method is triggered in case of the Catalog is accessed through a bookmark and right after a call to the method getContext.
• cleanup: Try to clean up a quote associated to a Catalog or a Configurator after a timeout
• getExchangeCart: Get the complete object quote (in a serialized form) for re-use for instance in the configuration settings.
• saveXML: Send the configuration result as an XML flow
• copyLines: copy the selected lines of the quote.
• cutLines: cut the selected lines of the quote
• pasteLines: paste the cut/copied lines
• createFolder: create a folder in the quote content.
• deleteLines: delete lines of the quote
• getPath: gives the current line complete and absolute path.
• runLine: open a session of the Configurator or the Catalog according to the type of the quote line

There are two user actions triggering a back to the hosting application:

1. Using the “CLOSE” action – in this case the initial parameter exitURL is used to redirect to hosting application.
   
   
2. Using the “ADD_TO_CART” action – in this case the initial web service

   URL bindingTargetPoint is used, the method AddXML is executed and the redirection is made with returned URL

   
   
   

Implementation example of quote skeleton class:

When building your own custom Catalog interface, the hosting application relies only on the Catalog engine to apply the business logic and drive the content of the user interface.

CONCEPT

Several entry points are provided to facilitate the integration of the Catalog engine in a custom interface (a “Catalog Engine” Web Service whose stub server part is integrated within CPQ; the client stub part should be generated and used by the information system).

Each of them will be detailed in following paragraphs.

Moreover, (from Version 10SP1) REST API can also be used to create a custom user interface.

INTEGRATE CATALOG STATELESS WEB SERVICE

General Overview

A “Stateless” Web Service is provided. It allows building custom interfaces and/or creating high level services or batches without having to maintain a Catalog session.

The “Stateless” Web Service is called only once, the following actions have to be driven from the hosting application side:

• Preparation of the input Catalog XML flow
• Call of the “Stateless” Web Service which executes the following actions
  • Creation of a Catalog engine
  • Injection of the Catalog XML flow
  • Return of Web Service with updated Catalog XML flow and errors/messages
• Parsing and integration of the output Catalog XML flow

For more details on this web service operation, possible parameters and returned objects please refer to the Catalog WS Javadoc.

For more details on Catalog XML flow, please refer to the section “Initialization XML file”.

Implementation process

Step 1: By using the WSDL definition file “CatalogStatelessWS.wsdl”, the client stubs is generated and placed into hosting application classpath.

Step 2: A client instance is created and the target point is defined with the correct CPQ URL:

Step 3: Input parameters including the Catalog XML flow are set:

Step 4: Catalog results is retrieved:

INTEGRATE CATALOG API

A CPQ engine API is provided, it allows the development a custom application with a full control of the Catalog engine, ensuring also the best possible performances.

This kind of integration is recommended for rich interfaces development. It offers the possibility to add an abstraction level on top of the CPQ API and thus provide hosting applications with business oriented services that can group several CPQ API calls.

General Overview

One Catalog engine corresponds to one CatalogClient class instance:

• This is a client class of a stateful EJB which:
  • Communicates with application server (which hosts CPQ) by EJB calls
  • Manages and masks dialogs with EJB
  • Uses the same code in local (local CPQ server) or remote access (distant CPQ server)
• It exposes services by themes in specific interfaces:
  • CatalogNavigationSvc: defines navigation services. These methods are used to retrieve the Catalog business objects.
  • CatalogActionSvc: defines action methods, such as engine creation and products export.
  • CatalogObservationSvc: defines observation mechanisms for user messages and errors.
  • CatalogSearchSvc: provides facilities for searches in Catalog engine.
  • CatalogDebugSvc: provides different services for test and validation (or debug) purposes.
    
    

For more details on this API, please refer to the Catalog Engine Javadoc.

Implementation process

The Catalog is an implementation of the Catalog service (CatalogSvc). You will find in this class all that you need to access and communicate with the Catalog.

Step 1: Using the XML Catalog flow, creation of a Catalog engine session

The Catalog engine API can work both in local or remote modes. The setup is made via the JNDI address defined in the cameleon.properties file (located into the <CpqInstallDirectory>/“conf”):

java.naming.provider.url=remote://127.0.0.1:4447 (which can be local or remote)

Step 2: product collections can be loaded

Step 3: Sub-collections can be browsed

Step 4: Standard product can be retrieved

INTEGRATE CATALOG REST API

REST-like APIs are provided to integrate CPQ into the IS.

It consists of a set of JSON (or XML) over HTTP APIs with nearly a one-to-one correspondence with the CPQ Engine JAVA APIs.

Because a configuration engine is inherently stateful the provided APIs are stateful and a session is maintained through the JSESSIONID cookie. Any load balancer sitting between the client and the CPQ server has to be setup with a sticky session based on this cookie.

The CPQ engines REST API documentation is available in the CpqEnginesREST Javadoc (also available in connect.pros.com)

See Rest API for more information.