DATABASE INITIALIZATION

As explained in the reference document CPQ Installation Guide, The database configuration must follow the requirements in the table below:

Do not: Database users must be tied to the “cameleon_tablespace” and cannot be a DBA.

In the standard installation tool, both tables and indexes are installed in the same tablespace.

As, for large database, it is recommended to dissociate indexes and tables in two distinct tablespaces, this architecture is supported for CPQ but must be done manually.

Reference: To encrypt the database credentials, please refer to the CPQ Installation Guide.

OPTIMIZING THE JBOSS STANDALONE.SH/.BAT FILE

After installing CPQ, a default server profile is provided. This server profile has the following form:

SERVER_PROFILE="-Xms128m -Xmx1024m -Xss512k -XX:MaxPermSize=256m"

It is recommended to update the server profile in order to optimize the environment based on the expected load.On 64-bit environments, we recommend adding the -XX:+UseCompressedOops option, which can improve performance of the 64-bit JRE when the Java object heap is less than 32 gigabytes in size. In this case, Hotspot compresses object references to 32 bits, reducing the amount of data that it must process. The server profile would thus become:

SERVER_PROFILE="-Xms128m -Xmx1024m -Xss512k -XX:MaxPermSize=256m - XX:+UseCompressedOops”

MAIN CONFIGURATION FILE: CAMELEON.PROPERTIES

The cameleon.properties file contains all the parameters of CPQ that can impact the behavior of the application.

This file can be found in: \conf\

The cameleon.properties file contains a list of parameters grouped by theme. We present the different parameters into the following section except for those for the caches that are detailed in a further section.

ERROR PAGES CUSTOMIZATION

The cameleon.properties file allows to declare URLs for customized error pages as follows:

In case of an outside custom error page used in the "cameleonUI.errorPage.exception.url" property, some information about the error might be forwarded to the error page (depending on the exception type) as GET parameters.

USER TRACING

The cameleon.properties file enables tracing of user connections via the following parameters:

When tracing is activated, the following information will be logged:

• The access type (ACCESS, SAVE, etc.)
• The users’ IP address
• The users’ original IP address
• The timestamp
• The user name (= the connected user in the Designer)
• The users’ first name
• The users’ last name
• The process name
• The parent object workspace/class/name
• The version information:
  • Internal identifier
  • Fix number
  • Version label
  • Version start date
  • The user name for the user who created the version
  • The timestamp of creation
  • The user name for the user that fixed the version
  • The timestamp of fix creation
  • « false » (a static field, no longer used)
  • « false » if the version is a « real » version, « true » if the version is a working version
• The concerned object (e.g. the object which has been saved)

REPORT GENERATION

The following parameters available in cameleon.properties are available for report generation:

PRICING

PROS PRICING INTEGRATION (POD OR PPSS)

POD INTEGRATION

The following parameters available in cameleon.properties aim at managing the POD Integration:

PPSS INTEGRATION

The following parameters available in cameleon.properties aim at managing the PPSS Integration:

STANDALONE CART INTEGRATION

The following parameters available in cameleon.properties aim to manage the standalone cart integration (indexWS)

MS DYNAMICS CRM INTEGRATION

The following parameters available in cameleon.properties aim to manage MSCRM Integration:

SFDC INTEGRATION- OAUTH SETUP

QUOTE

The following parameters available in cameleon.properties are dedicated to Quote administration:

AVALARA TAX MANAGEMENT

The following parameters available in cameleon.properties are dedicated to the integration of the Avalara Tax Management solution:

Reference: For more details on how to integrate the Quote with the Avatax API, please refer to the Quote Designer and Customization GuideNo Content found for /db/organizations/conga/repositories/current/content/documents/Production/Smart_CPQ/user_guide/designer_getting_started/designer_getting_started.dita.

CACHE CONFIGURATION

Cache Presentation

The Configurator uses at runtime two levels of cache.

The first level of cache that we called Application Cache is a versatile cache. The use of this cache enables to gather the efforts of loading of the configuration objects between the different users that run a configuration on the same application server. Indeed, configuration objects are loaded from the database level only once: when the first user of the server is trying to access to the object, the next users are loading the objects from the cache rather than the database. This cache is said to be versatile as the lifetime of the objects in the cache is the same than the lifetime of the application server itself.

The objects in the cache are java objects already well-formed so that the work to get the data and morph them into a new object is already done for all new users.

The second level of cache called Database Cache or DB Cache is a persistent cache. This cache takes place in the loading process between the database and the Application Cache. This cache enables to gather the efforts of loading of the configuration objects between the different users running configurations on anyone server among the set of parallel application servers. All objects in this Database Cache are stored as a java serialization object.

To clearly understand how these caches work together, consider the following typical sequence of actions to be performed when a request for an object is sent by the client application:

As we can see in the figure above, the retrieval of an object from the repository for a user session consists in one or two steps:

1. Obtain the Java Object from the Server Cache

When the client application uses the CPQ API during a configuration session to get a new configuration object, this object is searched into the server cache.

In the case the object is already present in this cache, then

• An instantiated copy of the object is retrieved to the client application.

In the case the object is not already present in this cache, then:

• CPQ sends a request to the DB cache to get the data of the object. The tasks related to the DB cache in order to retrieve the data of the object are described in the step 2.
• Once the DB Cache has retrieved the data of the object, CPQ converts these data (all data concerning the object are retrieved as a serialized form of the object) into a real java object. This Java Object is then injected into the server cache so that it will be available for any new request.
• An instantiated copy of the object is retrieved to the client application.
  1. Obtain the serialized object from the DB cache

When CPQ sends a request to get the data of an object to the DB cache, two cases can occur: the object is already present in the DB cache or the object is not present.

In the case the object is already present in the DB cache, then

• A copy of the serialized form of the object that is in the DB cache is retrieved to the client API.

In the case the object is not already present in this cache, then:

• CPQ loads the data of the object from the database and build a java version.
• Then, this java version of the object is serialized and the serialization is injected into the DB cache in order to be available for any further request.
• Once the DB Cache has retrieved the data of the object, CPQ converts these data (all data concerning the object are retrieved as a serialized form of the object) into a real java object. This Java Object is then injected into the server cache so that it will be available for any new request.

By this mechanism, CPQ ensures any object is built only one time from the database which is the most costly operation. Once the engine object is built, it is serialized and will be stored into the DB cache in an asynchronous way. Any later access to this object will get the object in the worst case from this DB cache. Obviously, in the best case the object is already present in the application server cache and directly returned from this cache.

Natively, the caches load the object in an opportunistic way: objects are loaded at each level of cache when one user needs them. The first user to access to an object is thus penalized with the loading time of the object. To prevent this, CPQ integrates mechanisms to preload the caches. The preloading is managed by two optional daemons running on the application server: the Serialization Agent, in charge of the loading of objects into the DB Cache, and the Preload & Change Detection Agent, in charge of the loading of objects into the Application Cache and also in charge of maintaining the consistency of the Application Cache with the content of the DB Cache.

Focusing on the Serialization Agent

In order to accelerate the access time to objects (and especially new objects coming from a new released version), it is necessary to have the serialized form of objects already preloaded into the DB Cache before the first access to the objects.

When importing a new version the Serialization Agent must be informed of the list of new objects

that must be loaded into the DB Cache. This action can be done through the Designer or via a call to the API serializeObject.

According to the parameters of cameleon.properties of each JBoss target, the preloading of the DB Cache can be distributed among the different JBoss server instances:

• The serializeObjects API is called on a server that is the one that leads the loading process. It adds into the database the list of primary keys of the objects to be loaded.
• On all Jboss instances if activated, the Serialization Agent is running and is in charge of verifying at fixed time intervals if the DB cache needs to be filled. If some task must be performed, the agent will participate to the effort by loading a subset of the to-be-loaded objects. The activation and actions of this agent are conditioned by the cameleon.properties file.
  
  

Thus, the above picture shows the process is launched with the call on one server of the API serializeObjects that will populate a list of primary key in the DB cache.

Then, for all the servers where the serialization agent is activated, the serialization agent will access to the primary key list and take in charge a subset of keys.

For all element of this subset, the serialize agent will load the data of the object from the database, build the java object with these data, serialize the java object and finally register the serialize form of the object into the DB cache.

Despite the use of the Serialization Agent to preload the cache, all objects of a version are not necessarily pre-loaded. Objects in the DB cache can still be loaded opportunistically on request.

Focus on the Preload & Change Detection Agent

Enabling the Preload & Change Detection Agent on each JBoss target node will automatically pre-loaded the Application Cache.

This agent will load in the Application Cache all objects from the DB Cache that belong to a valid version (meaning whose validity date is lesser or lesser or equal to) at + delayTime (the delay time is a parameter in cameleon.properties. See Cache Parameters).

For instance, if you know a complete new version of your models is loaded in the application cache in 15 minutes, the parameter should at least be valued with 15.

This agent is also in charge of reloading all objects in the application server cache as soon as they have been updated into the DB Cache (update for a fix for instance via a new call to the API serializeObjects).

The activation and actions of this second agent are conditioned by parameter(s) in cameleon.properties.

The following schema gathers the actions that can influence the loading of objects in the caches:

In the above picture, one can see the DB cache is populated by two possible actions: the preloading API call or the use of an object that was not loaded and that is loaded on the fly.

Concerning the application cache, insertion of object can be done due to the preloading agent according to the DB cache or due to the access by the user to a not loaded object.

Cache Parameters

Hereafter, can be found the complete list of parameters of the cameleon.properties file that are dedicated to the management of the cache agents:

ENGINE CACHE CONFIGURATION

This parameter enables external applications to be informed of cache changes.

The content of the application cache can also be parameterized with the cache.xml file that can be found in the directory : \conf.

The cache.xml file defines what kind of configuration objects are used in the cache. With the default configuration file, the following objects will be subject to cache: Forms with their Form Properties, Configurable Products, Rich Media Object, Business Rules & Constraints, CPQ Meta Data, Sales Methods, Sales Pricing Grids, Sales Custom Grids, Standard Items, Business Property Sets, and Business Values.

EXTERNAL SERVICES: SERVICES.PROPERTIES FILE

Since version 8.0, the Designer allows integrating external services:

• External Business Services : these services allow for Java classes to be called from within the Designer menu toolbar
• Document Generation Services : these services allow for reporting services called from within the Designer menu toolbar

External Business Services

In order to add a business service, proceed as follows:

The com.cameleon.modelingui.services.plugins.ExternalService interface to be implemented is the following:

package com.cameleon.modelingui.services.plugins;

/**

* The default external service behavior

*

* @author PROS

*/

public interface ExternalService

/**

* The execute method. You have to implement this method.

The input parameters implement the following interface:

The resulting output will have to implement the following interface:

}

The business service section template is the following:

BUSINESS SERVICE CONFIGURATION

External Reports

In order to add a report generation service, proceed as follows: