This chapter focuses on the integration of the Configurator module:

• The first section explains how to fulfill the XML initialization files.
• The second section explains how to use external business logic within the Configurator.
• The last two sections explain how to integrate the Configurator standard interface in an external application and how to develop your own custom interface based on the Configurator engine web services.

The settings file contains the initial information to start a configuration session. The default configuration.xml file can be found in the directory:

<CpqInstallDirectory>\conf\run\settings\configurator

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

The file contains the following elements:

New settings can be included in the initialization file by the addition of new “Param” sections. The number of settings is not limited.

If the type is a standard java type, the value is given as a string that will be converted into the true type with the java standard parse method.

Examples:

<cam:Param cpe="CPE.Settings.Session.Address[4].fct" value="true" type="java.lang.Boolean"/> <cam:Param cpe="CPE.Settings.Session.Address[4].cp" value="7.500" type="java.lang.Double"/> <cam:Param cpe="CPE.Settings.Session.Address[4].rue" value="rue lecourbe" type="java.lang.String"/> <cam:Param cpe="CPE.Settings.Session.customDate" value="2009-05- 28T00:00:00.000+02:00" type="java.util.Date" />

If the type is a user-defined java class that inherits of the XMLAble interface, the value is given as an XML string that will be converted into the true type with a call to the fromXML method.

Example:

<cam:Param cpe="CPE.Settings.Session.Address[3]" type="com.cameleon.configurator.service.MyClassAddress" > <cam:Value>

<![CDATA[<Adresse> <num>1</num> <rue>rue Joutx-Aigues</rue> <ville>Toulouse</ville>

<cp>31000</cp> </Adresse>]]> </cam:Value> </cam:Param>

If the type is a user-defined java class that inherits of the JSONAble interface, the value is given as an JSON string that will be converted into the true type with a call to the fromJson method.

Example:

<cam:Param cpe="CPE.Settings.Session.jsonexample" type="com.cameleon.framework.dialogs.serialization.JsonBrowsable" > <cam:Value> <![CDATA[{ "string": "Text", "date": "2018-04-23T18:25:43.511Z", "integer": 45, "number":

123.456, "boolean": true, "nullValue": null, "object": { "id": "1245", "color": "red"

}, "array": [ "Text", 45, false, { "colors": [ { "id": "R", "name": "red" }, { "id": "G", "RGB": "#00FF00" } ] } ] }]> </cam:Value> </cam:Param>

If the type is a user-defined java class that inherits of the GZIPPED JSONAble interface, the value is given as an JSON string that will be converted into the true type with a call to the fromJson method.

Example:

<cam:Param cpe="CPE.Settings.Session.jsonexample" type="com.cameleon.framework.dialogs.serialization.GzippedJsonwBrowsable" value="eJy1kdtq4zAQhq/1FkZXXeimTuz0dBeaLRS23RSnLKWUMJYmiagtBWlM1pS8e+VDNg4NlFx

UBsPMfP/M6Nd7wGfJczJLpqPpU8Kvg3fGuCOr9MIHfGxhTpxtThkXSxRvqfk3u1WYyZZMjckQtI/mkD mswQlY0mhHQphC090WHTmH5HzwwhjzCZ9K0CrIHoo8RdtQbG96PKw+XmV946r2WIAmReWOTtV ijELlkPlcvxd24IlVAndkbjQS2J3W36mwFrUob4ysQP6UjPlpW4O8Wt9nB2HdlG06rR8gx0MbJwRagpXB nXYEWQakjO5eoM2PgTp66aOpqjv2h/2Ly3hwGVZnO7XWtpYRUOEOjW47o+yO+8rhYRSfH2dx9B0W x0dYfF8GE2tkIehYXy+G5/G+r4y9ejn/i6lT/4WdWUui1fXZ2Xq97q2scT1hct6M5NNydUBwUzgyufe6pS ZL78hn7MQv8SPwv5/VOlu4eaY/81/5KjMl4vaZudKEi/oBB836Db4zaN8eXRVa6Dc4ujdSzRXKjjn71oRX 4SCK+lHTO/Bns/kA9foGlw=="></cam:Param>

If the type is a user-defined java class that does not inherit of the XMLAble interface, the value is given in the serialized form of the object.

Example:

<cam:Param cpe="CPE.Settings.Session.Person[2]" type="com.cameleon.configurator.service.Person" value="rO0ABXNyACpjb20uY2FtZWxlb24uY29uZmlndXJhdG9yLnNlcnZpY2UuUGV yc29ubmUi6UrM3IIS&#xa;0wIAA0wAA2FnZXQAE0xqYXZhL2xhbmcvSW50ZWdlcjtMAANub2 10ABJMamF2YS9sYW5nL1N0cmlu&#xa;ZztMAAZwcmVub21xAH4AAnhwc3IAEWphdmEubGFuZ y5JbnRlZ2VyEuKgpPeBhzgCAAFJAAV2YWx1&#xa;ZXhyABBqYXZhLmxhbmcuTnVtYmVyhqyV HQuU4IsCAAB4cAAAABR0AAZEdXBvbnR0AARKZWFu&#xa;" /> </cam:Session>

The Saving Policy is ruled by the setting referenced by “CPE.Settings.Session.SavingPolicy”. This setting defines the content of the saving file when saving the configuration. The value of this parameter can be given in two different formats: Text or XML.

In Text Format, precising the type of the setting is not necessary. The possible policies are:

• Fast: for optimized performances
• Standard: include elements of the Fast policy and details on the generative processes
• Full: full content, including configuration sublines. Does not include sparePartsDetails
• Custom: made to precisely set the details granularity
  Note: By default, this setting is set to the Standard policy. If this setting is emptied or not set, the default policy is Full.
  Note: Depending on the integration, this setting is not set by default with the same values. For example, with Performance Quoting, by default, this setting is set to the Fast Policy

When Custom is chosen, the value must be completed with additional parameters separated with ‘;’. These parameters are the following ones:

• configurationDetails: includes the configuration details in the saving file (true|false)
• domainDetails: includes the domains of configuration variables in the saving file (true|false)
• generativeProcess: includes the results of the generative process in the saving file (true|false)
• notExisting: includes in the saving file objects whose existence is set to false (true|false)
• productDictionary: includes the products dictionary in the saving file. (true|false)
• productLinkType: includes in the product dictionary, the products linked with the generative processes products and whose product link corresponds to the linkType specified in the parameter. Use '~' to separate the various types of links. (e.g. productLinkType="CrossSelling~Breakdown~myCustomLink")
• notUserChoice: includes only elements that are not chosen by the user (true|false)
• sparePartsDetails: includes additional details on Spare Parts, such as hotspot areas, child path, etc (true|false). Requires that configurationDetails is set to true.
• manufacturing: includes details on the manufacturing elements (true|false)
• svgDepth: positive integer representing the number of svg levels in the saving file. NONE and ALL values represent respectively 0 levels and unlimited number of levels
• savedSettings: lists the settings to be saved when the configuration is saved in the cart XML. The use of wildcard (*) is permitted. Settings not in this list will not be saved. If the parameter is not found, all settings are saved. savedSettings=CPE.Settings.Session.,CPE.Settings.Application.

Examples of text format values:

• <cam:Param cpe="CPE.Settings.Session.SavingPolicy" value="Standard"/>
• <cam:Param cpe="CPE.Settings.Session.SavingPolicy" value="Custom;configurationDetails=true;domainDetails=true;generativeProcess=true;n otExisting=false;productDictionary=true; productLinkType=CrossSelling~Breakdown~myCustomLink;notUserChoice=false;sparePartsD etails=false />

XML FORMAT

In XML format, the type of the setting must be given as follow:

• type="com.cameleon.business.xml.savingpolicy.StandardSaving"
• type="com.cameleon.business.xml.savingpolicy.FullSaving"
• type="com.cameleon.business.xml.savingpolicy.FastSaving"
• type="com.cameleon.business.xml.savingpolicy.CustomSaving"

according to the kind of saving policy to use. The scope of each policy is the same than in the text format (See previous chapter).

When using the saving Policies Standard, Full or Fast, the value of the setting is restricted respectively to the following XML values:

• <![CDATA[<SavingPolicy type="Standard" />]]>
• <![CDATA[<SavingPolicy type="Full" />]]>
• <![CDATA[<SavingPolicy type="Fast" />]]>.

When using a Custom saving policy, additional boolean parameters must be given. These parameters are valued with “true” or “false” and are the same than those in text format.

To specify productLinkType, add as many elements as necessary.

In all cases, pay attention to the uppercase and lowercase values and key words.

There are three ways to call an external service (java class) from the Configurator:

• Via a custom java class used within Business Rules and Constraints (BRC)
• Via a custom java class can also be used in settings of the configuration file
• Via a custom java class can be call in an external component

As part of its model, the business user can use external logic. Business Rules and Constraints with a macro content are used for this purpose.

From the macro-language code, it is possible to call some java code. The reference document Macrolanguage Reference Manual explains in detail how to perform java code inclusion. The engine will automatically perform execution of the java code.

In order to be able to call this java code:

In the cameleon.properties: the parameter ml.javalib must be fulfilled with the java class names that must be loaded. (See the description of this parameter in the section “Configuration file: cameleon.properties”.)

The jar file(s) containing the classes corresponding to these external libraries must be also deployed in the CPQ Application Server.

Cloud deployment: For more details on how to deploy external services, please log a ticket on PROS Support Helpdesk.

The “settings” part of the configuration input XML flow enables to add some Java classes (POJO). These classes obviously need to be in the CPQ classpath.

See the previous Part concerning the settings for an example.

CPQ standard UI provides the capability to add customized user interface components

These new components are called External Components. They allow for instance to:

• Display a static piece of information
• Navigate: redirect to or select an element in the UI
• Realize a business action such than a call to a specific external service

For a complete guide on the integration of external component in the Configurator UI, please refer to the CPQ - External Component Tutorial.

CONCEPT

Configurator 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).

The 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 Configurator are based on IN and OUT calls using standard web services named “ConfiguratorUI” and “CartStatefulWS” whose exchange flows are based on XML messages.

"IN" WSDL – ConfiguratorUI :

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

DETAILED INTEGRATION PROCESS

Initialization and start

Step 1: By using the WSDL definition file "configuratorUI.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 to the output URL.

For more details on configuration XML flow, please refer to the previous section "Initialization XML file".

For more details on configuration layout XML flow, please refer to the CPQ Customization Guide.

Back to hosting application

On the hosting application side, the class "CartStafefulWSSkeleton.java" must be implemented for the following methods:

• addXML: Send the configuration result – This method is triggered by the ADD_TO_CART action.
• refresh : Refresh the hosting application – This method is triggered by the Configurator UI after any action
• cleanup : Try to clean up a quote associated to a Catalog or a Configurator after a timeout
• checkRights :Test whether the user has sufficient rights to access to the Configurator UI or not

  .This method is called at the beginning of the session, its result will authorize/unauthorize the display of the Configurator UI

• getExchangeCart : Get the complete quote object (in a serialized form) for re-use for instance in the configuration settings.
• saveXML : Send the configuration result as an XML flow

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.

1. 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 configuration interface, the hosting application relies only on the Configurator engine to apply the business logic and drive the user interface.

CONCEPT

A standard « ConfiguratorEngine » web service is provided. It includes several contracts (WSDL) detailed in the paragraphs below.

The server stub part is already deployed within CPQ Application Server and is ready to use. The client stub part must be generated and deployed within the hosting application.

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

INTEGRATE CONFIGURATOR STATEFUL WEB SERVICE

General Overview

A “Stateful” Web Service allows to:

• Initialize a configuration session
• Raise events
• Set valuations
• Get the configuration objects
• Clear objects
• Close the session

Let see the following example to illustrate the different calls to build a custom UI:

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

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

Implementation process

Step 1: By using the WSDL definition file “ConfiguratorStatefulWS.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: The caller initializes a configuration session by sending an XML configuration flow

Step 4: Different actions can be performed:

Step 5: Configuration results can be retrieved thanks to:

Step 6: at the end, the session is closed:

INTEGRATE CONFIGURATOR STATELESS WEB SERVICE

General Overview

A “Stateless” Web Service is provided, its interest is to allow creating high level services or batches without having to maintain a 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 configuration XML flow (a regular configuration XML message with additional valuations if needed)
• Call of the “Stateless” Web Service which executes the following actions
  • Creation of a Configurator engine
  • Injection of the configuration XML flow
  • Return of Web Service with updated configuration XML flow and errors/messages
• Parsing and integration of the output configuration XML flow

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

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

Implementation process

Step 1: By using the WSDL definition file “ConfiguratorStatelessWS.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 configuration XML flow are set:

With additional valuations of formProperties (optional):

Step 4: Configuration results is retrieved:

INTEGRATE CONFIGURATOR API

A CPQ engine API is provided, it allows the development of a custom application with a full control of the CPQ 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 layer 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 configuration engine corresponds to one ConfiguratorClient 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:
  • NavigationSvc: interface providing methods to get CPQ objects
  • ActionSvc : interface providing methods to execute actions (set values) on engine
  • ObservationSvc: interface providing methods to check and follow configuration state
  • SearchSvc: interface providing methods to search objects in database
  • DebugSvc: interface providing methods to test and validate models
    
    

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

Implementation process

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

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

The 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: the configuration process can be started:

Step 3: Sub-objects of the configurable product can be loaded such than AbstractForm, FormProperty, etc.

INTEGRATE CONFIGURATOR 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 CameleonREST Javadoc (also available in connect.pros.com)

See Rest API for more information