Conga Product Documentation

Welcome to the new doc site. Some of your old bookmarks will no longer work. Please use the search bar to find your desired topic.

Show Page Sections

Building a Quote Model

Quote Designer allows users to create and manage quote models. It can be accessed from the CPQ Designer.

The configuration of the quote model involves the following parts:

  • General settings
  • Quote status settings
  • Quote header settings:
    • Predefined tabs (parameters, addresses, history, etc.)
    • On demand / automated actions
  • Quote spreadsheet settings:
    • Columns and total cells
    • automated calculations
    • vertical up/down propagations
    • On demand / automated actions
  • Access rights settings
  • Translations
  • Customization of the user interface (layout) – [Complementary to the Layout.xml file]

The quote model is stored in XML format. There is one XML file per model and per model release.

At runtime, the Quotation Engine will apply the object definition as well as the associated business logic setup in the quote model:

  • Quote header:
    • Display the tabs and fields and manage the fields update according to their definition access rights
    • Display and execute the authorized on demand user actions
    • Trigger and execute the automated action
    • etc.
  • Quote spreadsheet:
    • Display and manage the content of the spreadsheet according to their definition and access rights
    • Manage the communication with the Catalog and Configurator modules
    • Manage the cell updates and propagates the subsequent calculation updates
    • Display and execute the authorized on demand user actions
    • Trigger and execute the automated actions

Defining the General Settings

OVERVIEW

General settings are defined in order to:

  • Provide default values for mandatory parameters. At runtime, these values will be used in case of the parameters are not defined.
  • Define the status graph managing life-cycle of quotes from the time they have been created until their deletions.

DEFAULT PARAMETERS

The default parameters are listed in the table below:

PARAMETERVALUES/EXPLANATIONS
LanguageThe default language list is defined in the service.properties file and can be overloaded @runtime within the WS XML file. This parameter is used for the management of the quote model translations, thus it can’t be changed.
CurrencyThe default currency list is defined in the service.properties file and can be overloaded @runtime within the WS XML file.
Decimal separatorComa “,” or decimal point “.”
Group separatoror coma “,”
Monetary format#,##0.00 ¤  Mainly used to adjust the number of decimals. Do not change the pattern structure.
Currency SymbolAssociated with the default currency “€” for example
PARAMETERVALUES/EXPLANATIONS
User IdDefault user id used to trace the events in the quote history as well as to compute the access rights matrix
User NameDefault user name used to trace the events in the quote history
User GroupDefault user group used to trace the events in the quote history as well as to compute the access rights matrix
Allow Duplicate Local LinesRules the insertion of items already present locally – in the current folder - in the quote
Allow Duplicate Global LinesRules the insertion of items already present globally – at any level - in the quote
Warning: When the Quote is linked with the Catalog/Configurator, and when it requests to open a specific catalog / product page or configuration process, the Decimal separator and Group separator used in the Catalog/Configurator will be the one defined in the parameters table above, independently from any language convention (Web browser locale…).

Insertion of items already in the quote

The “Allow Duplicate XXX Lines” parameters described in the table above rule the insertion of duplicates in the quote, either locally or globally. Their behavior is given in the tables below.

This applies only to CT7 and CP7 types of lines.

ADDED ITEM NOT ALREADY IN THE QUOTE
Local GLobal| Result
Yes Yes New line created locally with the added item quantity
Yes No New line created locally with the added item quantity
No Yes New line created locally with the added item quantity
No No New line created locally with the added item quantity
ADDED ITEM PRESENT IN THE CURRENT FOLDER ONLY
Local GLobal| Result
Yes Yes New line created locally with the added item quantity
Yes No The added item quantity is summed with the globally existing item. In that case, it means also that the added item quantity is summed with the locally existing item.
No Yes The added item quantity is summed with the locally existing item
No No The added item quantity is summed with the locally existing item
ADDED ITEM PRESENT AT ANOTHER LEVEL ONLY
Local GLobal| Result
Yes Yes New line created locally with the added item quantity
Yes No The added item quantity is summed with the globally existing item
No Yes New line created locally with the added item quantity
No No The added item quantity is summed with the globally existing item
ADDED ITEM PRESENT BOTH IN THE CURRENT FOLDER AND AT ANOTHER LEVEL
Local Global| Result
Yes Yes New line created locally with the added item quantity
Yes No N/A - the item can't exist at two levels in the quote. The added item quantity is summed with the globally existing item
No Yes The added item quantity is summed with the locally existing item
No No N/A—the item can't exist at two levels in the quote. The added item quantity is summed with the locally existing item

STATUS DEFINITION

The approval process of Quote relies on a graph of statuses the user may have to go through during the quote lifecycle.

For instance when integrated with the standard salesforce.com, the status graph is as follows:



  • Each status can have a list of parents allowing the implementation of complex approval processes as shown in the example above.
  • Each status can be classified into one of the 3 following types: Quote / To-order / Order. Theses 3 types of the status have influence on the quote process steps displayed to the user.
    • For instance: step “Order Now” must be only visible once the quote has been accepted by the customer
  • For each status a business rule can be implemented to define the possible subsequent statuses depending on the value of some business indicators
    • Such as total revenue, % of margin, % of discount, etc. which have been computed in the quote
  • After having changed a quote status, some actions may automatically occur.
    • For instance: The generation of an email assigning a quote review task to the manager of the quote ownerThe status graph is made-up form an empty list. Each status is associated with a set of properties detailed in the table below:
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Code Status code Each status code must be unique
Name Status name displayed to the user in the default language. Other translations are defined in the translation step
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Type Status type The status type influences the process steps displayed in the Quote process bar Quote To-order Order
Parents List of parent status List of parent statuses from whom the current status is dependent
Default status Default status assigned on quote creation Yes/No: Only one status can be defined as the default one
Next statuses list computation Business rule used to display informative messages (via MsgLine variable) and to filter the possible next status(es) in accordance with the content of the quote Note that the returned business message can be HTML formatted None: No rule is assigned Java class: Rule is driven by the execution of a java class Macro: Rule is driven by the execution of a macro
Validate status selection Business rule used to control the status selection and to display error and informative messages. If an error is issued, the change status action is cancelled None: No rule is assigned Java class: Rule is driven by the execution of a java class Macro: Rule is driven by the execution of a macro

Reference:

Refer to Using External Java Class Refer to Macros

information: The status of the quote can be changed using different methods:
  • Manually via the approval step of the quotation process
  • Via an OnDemand action linked to the quote header
  • Via an OnDemand action linked to the quote spreadsheet
  • Via an automated action linked to the quote header
  • Via an automated action linked to the quote spreadsheet
  • Using the matrix access rights, quote actions may be enabled/disabled, and/or quote information may be visible or not, updateable or not depending on combinations of (optional) quote status and (optional) user profile.
  • For instance:
    • Only managers can have access to margin information
    • A sales user cannot update a quote having the "In Review" status

Upon review of a quote the end user is able to post a comment for his/her review. In the default quote model, the latest comment is saved in the ChangeStatusComment field of the Parameter tab. It is then possible to synchronize this field to the CRM (Salesforce, Dynamics,…) by implicit mapping.

Setting-up the Quote Header

OVERVIEW

The quote header is used for:

  • Storing general information about the quote (customer name, delivery, billing addresses, etc.)
  • Receiving information from the host application
  • Managing an event history linked to the life cycle of the quote (e.g. status changes)
  • Triggering actions (Automated or On Demand).

GENERAL PRINCIPLES

At runtime, the quote header can be accessed through a pop-up opened from the quote spreadsheet (via a demand action) or within a dedicated quote process step. It is made up of following predefined tabs:

  • Parameters (Settings)
  • Addresses
  • Quote Information
  • Order Information
  • Change & Control (History)

Tabs are controlled by means of properties listed in the table below:

PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Position Determines the order of the tabs displayed to the user 1, 2, 3
Title Title of the tabs displayed to the user in the default language. Other translations are defined in the translation step
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Access rights Access rights logic to be applied on the current address position Hidden: The address position will never be displayed Open: The address position is always displayed Restricted: The address position is displayed upon matrix rights decision

PARAMETERS TAB

The parameter tab contains a set of pre-defined fields. The table below lists these fields and indicates whether they are mandatory or not.

FIELD NAME DESCRIPTION MANDATORY?
DomainId Domain code Yes
QuoteId Quote Identifier Yes
ReleaseNumber Quote release number Yes
QuoteDescription Quote description No Recommended=yes
CustomerId Customer code No
CustomerName Customer description No
FIELD NAME DESCRIPTION MANDATORY?
Language Quote language used in the Catalog, Configurator and report modules. The language permits to retrieve textual information such as descriptions, product properties in the appropriate language Yes
Currency Quote currency used to retrieve/compute all amounts (header and spreadsheet) Yes
PriceList Price list method used by the Catalog and Configurator modules DEPRECATED
AdvPriceList Advanced pricing method used by the promotion engine DEPRECATED
CostingMethod Cost calculation method used by the Configurator and manufacturing generator modules DEPRECATED
ApplicationDate Application date used in the Catalog and Configurator modules to retrieve/compute pricing amounts. By default, this is the quote creation date but may be changed by the end user. Yes
PartnerCode Partner code coming from CCS No
UserCode User code coming from CCS No
Note: When integrated with CCS all fields not deprecated are automatically filled-in.

When integrated with salesforce.com these fields can be automatically filled-in using the standard mapping mechanism.

Reference: Refer to APPENDIX A – Focusing on Field/Column/Total Cell to learn more about the properties attached to the fields:

ADDRESSES TAB

This tab is used to store addresses associated with the quote. Up to 3 types of address may be defined in the quote model:

  • Customer address ("sold-to")
  • Billing address ("bill-to")
  • Delivery address ("ship-to")

Addresses are controlled by means of properties listed in the table below:

PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Position 3 pre-defined positions of address 1, 2, 3
Label Label of the position address displayed to the user in the default language. Other translations are defined in the translation step
Type Type of address associated to the current address position Sold-to: Associate the “sold-to” address to the position Bill-to: Associate the “bill-to” address to the position Ship-to: Associate the “ship-to” address to the position
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Access rights Access rights logic to be applied on the current address position Hidden: The address position will never be displayed Open: The address position is always displayed Restricted: The address position is displayed upon matrix rights decision
Entry mode Entry mode associated to the current the address position User Input: The input of the address is user free Selection: The input of the address is automated via the execution of an eLink Service (CCS integration only) Reference: Refer to eLink service (deprecated)

For these 3 types of address, a single address object made-up with a list of pre-defined fields can be customized. Available fields are listed in the below, all of them are optional:

FIELD NAME TYPE FIELD NAME TYPE
CustomerName Text Address line 1...5 Text
CustomerDescription Text Zip Code Text
ContactName Text City Text
Phone Phone County/Zone Text
Fax Phone State Text
FIELD NAME TYPE FIELD NAME TYPE
eMail Text Country Text
Comments Text
Reference: Refer to the APPENDIX A – Focusing on Field/Column/Total Cell to learn more about the properties attached to the fields:

QUOTE AND ORDER INFORMATION TABS

Quote and order Information tabs are fully customizable. They are built-up from an empty list into which any type of fields can be added.

For each tab, the limit is governed by the database storage capacity as detailed in the table below:

FIELD TYPE # OF FIELDS
SHORT_TEXT(50) 7
MEDIUM_TEXT(255) 3
LONG_TEXT(512) 3
DECIMAL(38,5) 20
DATE(15) 5
FLAG(1) (BOOLEAN) 5
Extension Table 0..n
FIELD TYPE # OF FIELDS
TEXT_VALUE (4000) 1
DECIMAL_VALUE (38,5) 1
DATE_VALUE(15) 1
FLAG_VALUE(1) (BOOLEAN) 1
Binary Extension Table 0..n
BINARY_VALUE (BLOB) 1
Note: The extension tables are primarily used to store additional information such as binary data or long text. The relation between the primary table (used to store the tab record) and the extension table is of type “0 to N”, meaning that many fields can be mapped with many extension fields. Nevertheless for performance reason, the usage of extensions must be avoid or restricted to very specific use cases

Reference: Refer to APPENDIX A – Focusing on Field/Column/Total Cell to learn more about the properties attached to the fields

Change and Control Tab

The history tab contains read-only information. It traces all events in the life cycle of the quote from the time it has been created until its deletion. Events subject to trace are the followings:

  • Quote creation
  • Quote update
  • Status changed
  • Release creation
  • Active release changed
  • Owner changed

The tab is divided into 2 parts, the first part showing the current stage of the quote and the second one displaying the event history. Each part can be customized in terms of content and visibility rights. The table below lists the possible fields to be displayed:

QUOTE CURRENT STAGE
Field NameType
CurrentStatusText
CurrentStatusTypeText
StatusDateDate
CurrentActiveRelaseNumber
ActiveRelaseDateDate
CurrentOwnerIdId
QUOTE CURRENT STAGE
CurrentOwnerNameText
CurrentOwnerGroupText
OwnerDateDate
UserCreateIdId
UserCreateNameText
UserCreateGroupText
CreateDateDate
LastUpdateUserIdId
LastUpdateUserNameText
LastUpdateUserGroupText
LastUpdateDateDate
EVENT HISTORY
Field NameType
EVENT HISTORY
EventDateDate
EventDescriptionText
From (release #, status, owner)Text
To (release #, status, owner)Text
UserIdId
UserNameText
UserGroupText
CommentsText

ONDEMAND ACTIONS

At runtime, from the quote header, the end-user can trigger On Demand actions such as (Save, Close, etc.). These actions may be predefined or specific.

In all cases, actions are declared according to the properties detailed in the table below:

PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
PositionSequential position of the action1,2,3, …
NameInternal name of the actionAll actions must have unique names in a given quote model
PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
TypeAction typeNone: No action Predefined: Associate a predefined action eLink: Associate a service of type eLink (CCS integration only) eLinkPage: Associate a service of type eLinkPage JavaClass: Associate an action of type JavaClass Macro: Associate an action of type Macro Workflow: Associate a service of type Workflow (CCS integration only)
TitleTitle of the action displayed to the user in the default language.Other translations are defined in the translation step
Help Message (optional)Tooltip displayed to the user in the default languageOther translations are defined in the translation step
Display in read only modeFlag indicating whether the action must be shown when the quote is looked or notYes/No Recommendation: disable actions that can’t be performed when the quote is looked
Access rightsAccess rights logic to be applied on the actionHidden: The action will never be displayed Open: The action is always displayed Restricted: The action is displayed upon matrix rights decision

AUTOMATED ACTIONS

At runtime, automated actions can be raised on events linked to the quote header. For example: trigger a notification type action when the quote changes status.

Reference: : Refer to Events

The automated actions can be either pre-defined of specific. In all cases, they are declared according to the properties detailed in the table below:

PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
TriggersRefer to Appendix mentioned aboveMany triggers can be associated to a given action
NameInternal name of the actionAll actions must have unique names in the quote model
TypeAction typeNone: No action Predefined: Associate a predefined action eLink: Associate a service of type eLink (CCS integration only) eLinkPage: Associate a service of type eLinkPage JavaClass: Associate an action of type JavaClass Macro: Associate an action of type Macro Workflow: Associate a service of type Workflow (CCS integration only)
Waiting Message (optional)Message (in the default language) displayed to the user while executing the actionOther translations are defined in the translation step

Setting-up the Quote Spreadsheet

OVERVIEW

The quote spreadsheet is built-up with lines and sublines, columns and total cells, on which actions, calculations and propagations can be proposed/applied as shown in the screenshot below :



FEATURE DESCRIPTION
Lines Various types of line can be added to the spreadsheet: Multi-level folders Products of type “standard”, ”configured” “sales product” or “specific” In addition products may be breakdown in a multi-level tree of sublines
Actions Various on demand and automated actions can be associated with the spreadsheet
FEATURE DESCRIPTION
Columns The spreadsheet is made up of columns, which detail the products information as well as their associated pricing information (such as prices, margin, discount, etc.)
Calculations and propagations Calculations and up/down propagations may be defined on cells in the spreadsheet
Total cells Various total cells may be defined in order to provide a summary of the spreadsheet (total amount, margin, etc.)

GENERAL SETTINGS OF THE SPREADSHEET

The table below describes the settings managing the behavior of the spreadsheet:

PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Auto save Active the auto-save function after each update Yes/No Yes is the recommended value
Line numbering Activate the automatic line numbering function None: Disable the function Sequential: Display a sequential number without taking into account the line/subline hierarchy Hierarchical: Display a hierarchical number taking into account the line/subline hierarchy
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Optimize dependencies Activate the dependency optimization function Yes/No Yes is the recommended value in order to activate @runt-time the dependencies matrix (refer to chapter 3.3.4)
Mass mode Activate the mass mode on quote lines/sublines actions On/Off When set to ‘On’, the automated actions on lines and sublines are optimized for mass processing
Folder lines (FO) Activate the capability to create a multi-level hierarchy of folders On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the folder hierarchy
Standard Item lines (SI) (DEPRECATED) Activate the capability to add standard items coming from the classic Catalog module On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown
Configured product lines (CP) (DEPRECATED) Activate the capability to add configured product coming from the classic Configurator module On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown
Specific product lines (SP) Activate the capability to add specific products freely created by the user On/Off
Configured product lines (CP7) Activate the capability to add configured product generated by the Configurator module On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown
PROPERTY DESCRIPTION VALUES/EXPLANATIONS
Standard item lines (SI7) Activate the capability to add standard product retrieved by the Configurator module via a product matching rule On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown
Standard item sublines (LNK) Activate the capability to retrieve as sublines a hierarchical breakdown of products of type SI7 On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown Link type: Type of the link to retrieve from the product relations
Standard item lines (CT7) Activate the capability to add standard product from the Catalog module On/Off Number of levels: Unlimited, 1..6 Limits the authorized depth of the product breakdown
Standard item sublines (LNKCT) Activate the capability to retrieve as sublines a hierarchical breakdown of products of type CT7 On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown Link type: Type of the link to retrieve from the product relations
Sales product lines (SP7) Activate the capability to add sales products from the Catalog module On/Off Number of levels: Unlimited, 1..6 Limit the authorized depth of the product breakdown

Mass Mode

If you are dealing with large quotes, activating the mass mode allows to optimize the spreadsheet actions when manipulating high numbers of lines.



When the Mass Mode is set to ‘On’, the triggers associated with the actions on lines and sublines are called in a way more adapted to large volumes of data.

In details, the triggers concerned by the Mass Mode are the following:

LINESSUBLINES
LineUpdateBefore LineUpdateAfterSubLineUpdateBefore SubLineUpdateAfter
LineRefreshBefore LineRefreshAfterSubLineRefreshBefore SubLineRefreshAfter
LineCreateBefore LineCreateAfterSubLineCreateBefore SubLineCreateAfter
LineCopyBefore LineCopyAfterSubLineCopyBefore SubLineCopyAfter
LinePasteBefore LinePasteAfterSubLinePasteBefore SubLinePasteAfter
LineDeleteBefore LineDeleteAfterSubLineDeleteBefore SubLineDeleteAfter
LineMoveBefore LineMoveAfterSubLineMoveBefore SubLineMoveAfter

To improve the performances of your triggers by using the mass mode, you could define macros that will test if the corresponding action is unitary or has to be performed on a set of lines. To do so, you just have to test if the rowsSelected table contains elements (mass mode) or not (unitary mode), and execute your action accordingly. Here is an example of macro that can be used in that way:

DEFINE my_Update_Before()

COLUMN DEFINITION

Spreadsheet columns are fully customizable. They are built-up from an empty grid into which any type of fields can be added.

Reference: Refer to Focusing on Field/Column/Total Cell to learn more about the properties attached to the fields.

The limit is governed by the database storage capacity as well as by the cloud edition (SaaS deployment only) as detailed in the tables below:

GENERIC FIELD TYPE# FIELDS
SHORT_TEXT(50)10
MEDIUM_TEXT(255)10
LONG_TEXT(512)10
DECIMAL(38,5)35
DATE(15)5
FLAG(1) (BOOLEAN)5
BLOB_TEXT(500000000)1
BLOB_TEXT(500000000)1
SPECIFICFIELDS EXPLANATION
DS_SCOPE(2)Internal. Do not use
DS_TYPE(2)Internal. Do not use
ID_CNY_GENERIC_ITEMDEPRECATED
ID_GENERIC_ITEMDEPRECATED
SPECIFICFIELDS EXPLANATION
ID_ITEMDEPRECATED
APE_TOTAL(38,5)DEPRECATED
APE_PRICE(38,5) APE_QUANTITY(38,5)DEPRECATED DEPRECATED TOTAL(38,5) PRICE(38,5)
EXTENSION TABLEBINARY EXTENSION TABLE
TEXT_VALUE (4000)BINARY_VALUE (BLOB)
DECIMAL_VALUE (38,5)BINARY_VALUE (BLOB)
DATE_VALUE(15)BINARY_VALUE (BLOB)
FLAG_VALUE(1) (BOOLEAN)BINARY_VALUE (BLOB)
BINARY_VALUE (BLOB)BINARY_VALUE (BLOB)
SAASSTANDARD EDITIONPREMIUM EDITION
Number of columns2030
Note: The extension tables are primarily used to store additional information such as binary data or long text. The relation between the primary table (used to store the spreadsheet columns) and the extension table is of type “0 to N”, meaning that many columns can be mapped with many extension fields. Nevertheless for performance reason, the usage of extensions must be avoided (or limited to very specific use cases)

Propagation Definition

Three types of computations can be defined for each column:

  • Horizontal calculation (green arrows in the example below)
    • Horizontal calculations allows cells to be calculates from other cells of the current line
      • Horizontal calculations are specified for each type of line/subline in the input mode of the column.
  • Vertical up propagation (blue arrows in the example below)
    • Up propagation allows parent cells to be calculated from its child lines.
      • Up propagation are specified for each type of line/subline in the Up Propagation rule of the column
  • Vertical down propagation (red arrows in the example below)
    • Down propagation allows cells to be calculated from the parent line.
    • Down propagation are specified each type of line/subline in the Down Propagation rule of the column

The following tables illustrate the calculations carried out for an example model.



ARROWSLINE TYPECOMPUTATIONCOLUMNSEXPLANATION
Blue arrowsFolder (FO)Up PropagationUnit Price; Price; Net PriceFolder prices are the sum of prices of the inferior level
Red arrowsProduct lines (CP, SI, SP)Down PropagationDiscount %Discount is spread on the inferior level lines
Green arrowsProduct lines (CP, SI, SP)Horizontal CalculationNet price Discount %Net price is computed with the price and the discount Discount is computed with the Price and the Net price
Green cellsProduct lines (CP, SI, SP)Horizontal CalculationUnit PricePrice is retrieved from the Catalog/ Configurator module using XPATH requests

OnDemand Grid Actions

On Demand actions can be displayed in the menu bars at the top of the spreadsheet. These actions may be predefined (access to the quote header, change status, XML export, save, etc.) or specific.

In all cases, these actions are declared according to the properties detailed in the table below:

PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
PositionSequential position of the action1,2,3, …
PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
NameInternal name of the actionAll actions must have unique names in the quote model
TypeAction typeNone: No action Predefined: Associate a predefined action eLink: Associate a service of type eLink (CCS integration only) eLinkPage: Associate a service of type eLinkPage JavaClass: Associate an action of type JavaClass Macro: Associate an action of type Macro Workflow: Associate a service of type Workflow (CCS integration only)
Help Message (optional)Tooltip displayed to the user in the default languageOther translations are defined in the translation step
Waiting message (optional)Message (in the default language) displayed to the user while executing the actionOther translations are defined in the translation step
Display in read only modeFlag indicating whether the action must be shown when the quote is consultedYes/No Recommendation: disable actions that can’t be performed when the quote is consulted
Access rightsAccess rights logic to be applied on the actionHidden: The action will never be displayed Open: The action is always displayed Restricted: The action is displayed upon matrix rights decision

OnDemand Line Actions

At runtime, from the spreadsheet an “onMouseOver” flyer comes up, allowing the user to access various actions applicable on line(s) selected beforehand according to their scope of application defined by;

  • The number of lines selected:
    • Single (only one line may be selected)
    • Multiple continuous (several consecutive lines may be selected)
    • Multiple discontinuous (several lines which do not have to be consecutive may be selected)
  • The authorized type of lines (FO, SP, CP7, SI7, etc.)

These actions can be predefined (copy, paste, delete, item record, etc.) or specific.

In all cases, actions are declared according to the properties detailed in the table below:

PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
Position/ShortcutAction can be present either in the flyer (in this case the position is required) or as a shortcut of a given columnPosition LiCj: LineColumn Shortcut: Name of column, whose triggers the action on user click
NameInternal name of the actionAll actions must have unique names in a given quote model
PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
TypeAction typeNone: No action Predefined: Associate a predefined action eLink: Associate a service of type eLink (CCS integration only) eLinkPage: Associate a service of type eLinkPage JavaClass: Associate an action of type JavaClass Macro: Associate an action of type Macro Workflow: Associate a service of type Workflow (CCS integration only)
Activation ConditionDetermines the line selection condition whose will enable the actionSelection mode: Single, Multiple_continuous, Multiple_discontinuous Line type: Any, or Multiple selection among following list: FO, SI, PC, SP, CP7, SI7, LNK, CT7, LNKCT, SP7
Help Message (optional)Tooltip displayed to the user in the default languageOther translations are defined in the translation step
Display in read only modeFlag indicated whether the action must be shown when the quote is consultedYes/No Recommendation: disable actions that can’t be performed when the quote is consulted
Access rightsAccess rights logic to be applied on the actionHidden: The action will never be displayed Open: The action is always displayed Restricted: The action is displayed upon matrix rights decision
Note: When the spreadsheet is paginated, OnDemand Line Actions can only apply on the lines of the current page.

Automated Actions

At runtime, automated actions can be raised on events linked to the quote spreadsheet. For example: trigger a message when the margin threshold exceeds…

Reference: Refer to APPENDIX C – Focusing on Events

Automated actions can be predefined or specific. In all cases, they are declared according to the properties detailed in the table below:

PROPERTYDESCRIPTIONVALUES/EXPLANATIONS
TriggersRefer to Appendix mentioned aboveMany triggers can be associated to a given action
NameInternal name of the actionAll actions must have a unique names in a given quote model
TypeAction typeNone: No action Predefined: Associate a predefined action eLink: Associate a service of type eLink (CCS integration only) eLinkPage: Associate a service of type eLinkPage JavaClass: Associate an action of type JavaClass Macro: Associate an action of type Macro Workflow: Associate a service of type Workflow (CCS integration only)
Waiting Message (optional)Message (in the default language) displayed to the user while executing the actionOther translations are defined in the translation step

Focusing on Catalog and Configurator Integration

When integrated with the Catalog and Configurator modules, as soon as a product is added to the quote, quote lines are automatically generated depending on the type of the added product.

CATALOG

Adding a product from the Catalog

When standard products are added to the spreadsheet from the Catalog, one (CT7) line is created per selected product. Each column evaluated with XPath queries are executed from the XML file associated with each product.

The added products may come with a sales breakdown. In this case, sub-lines belonging to the parent line will be created in the spreadsheet. Similarly, each column evaluated with XPath queries are executed from an extract of the XML associated with the parent product.



Actions associated with the Catalog

NAMEDESCRIPTION
SI ViewProduct display (access to the corresponding catalog page)
NAMEDESCRIPTION
Item RefreshRefresh of prices and characteristics of the product
Back to CatalogReturns to the catalog. If no catalog has yet been opened, the default catalog is opened.
Quick Create SI LineAdds one or more products whose code or description matches the search string.
Catalog ListDisplays a list of catalogs in the left-hand menu of the quote spreadsheet.
Reference: : Refer to Predefined Actions to learn about the catalog-linked actions.

Mapping between the Catalog and the quote lines

The table below details the correspondences between the breakdown lines issued from the Catalog and quote line/subline types:

CATALOG LINESQUOTE LINE (OR SUBLINE) TYPES
STANDARD SALES ITEMSCT7
Linked products: BREAKDOWN_LINK (or CUSTOM_LINK…)LNKCT (subline)
SALES PRODUCTSSP7
Linked products: BREAKDOWN_LINK (or CUSTOM_LINK…)LNKCT (subline)

To generate LNKCT type of sublines mapped with custom product links (different to the standard one of type breakdown) the steps described below must be followed:

  1. Declare in the configuration file of the Catalog a custom saving policy which includes the custom product link(s) to be stored in the XML file:

    For instance:

    <cat:Param cpe="CPE.Settings.Session.SavingPolicy" value="Custom; configurationDetails=true;

    domainDetails=false; generativeProcess=true; notExisting=false; productDictionary=true;

    productLinkType= "customLink1~customLink2" />

  2. Declare in the general settings of the spreadsheet the custom link type to be mapped with the subline of type LNKCT (refer to chapter “General Settings of the spreadsheet”)
  3. Use XPATH mechanism to retrieve information from the product links (like the other type of lines)

Note:

  • By default, if no type is declared in the quote model, the Breakdown type of link is taken into account to create LNKCT lines)
  • Multiple product link types may be mapped

CONFIGURATOR

Adding a Configured Product

The product resulting from the configuration process creates a line (CP7) in the quote spreadsheet. If a configured product is modified, its line is updated. Each column evaluated with XPath queries are executed from the XML file resulting from the configuration process.

The configured product may be broken down into sub-lines. In this case, sub-lines belonging to the

parent line will be created in the spreadsheet. Similarly, each column evaluated with XPath queries are executed from an extract of the XML resulting from the configuration process.



Actions associated with the Configurator

NAMEDESCRIPTION
PC ViewRelaunches the configuration process in read only mode with the answers reloaded from the latest saved XML
PC UpdateRelaunches the configuration process with the answers reloaded from the latest saved XML
Item RefreshRefreshes the configuration (carries out configuration and price calculations and other generative processing again)
Configurator ListList of configurable products directly accessible from the left-hand menu of the Quote module
Reference: : Refer to APPENDIX B – Using Predefined Actions to learn about the Configurator-linked actions

Updating a Configuration Variable

Within the spreadsheet, the user can directly update configurable variable without returning to the

configuration process. The update is automatically sent to the Configurator as a background task. Line and sublines are then refreshed with the modifications arising from the configuration result.

In the example below, the color, height and width of the product configured may be changed in the spreadsheet:



  • The input mode must be "Direct Configuration Update"
  • The horizontal calculation must be setup with a XPath query targeting the value to be retrieved
    • Example

      : /conf:ConfigurationTree/conf:ConfigurableProduct/conf:Form[@cpe='CPE.workspace/C P/myCP.workspace/FO/myFO']/conf:FormProperty/conf:SingleValuation/conf:Value/onf: integerValue

  • Following additional properties must be setup to automate the update from the spreadsheet:
    • cpeOfFP = CPE of the targeted question (FP)
    • Example:
    • CPE.AC/CP/RootCP.AC/CP/CP13.AC/FO/Form1CP13.FP/fpBooleanForm1CP13)
    • typeOfFP = "VALUE", "QTY", "COMMENT" depending on which property of the question to be updated
    • typeOfValuation (optional) = "BOOLEAN", "DATE", "FILE", "INTEGER", "LONGTEXT", "MONETARY", "NUMERIC", "PK", "TEXT", "URL"

Important Note on Format: the variable format in the quote and configuration should be identical for the update to be successful. In the case of Date and Boolean variables, because the format is different between the configuration and the quote, one should use intermediary columns / FPs to ensure that the right conversions are performed for the Conf Update to be successful.

Restrictions

  • Only variables belonging the "root" context can be updated (update in looped instances is not supported)
  • If the structure of the configured product is modified after the value of the variable has been changed, certain data belonging to line or sub-lines may be lost (for example, manual discount entered on a sub-line which no longer exists).
  • Values format should be the same on configurator and cart side. In some cases (Dates for example) it is impossible to have a same format on both sides.

    In such cases one would need to create additionnal columns, FPs and logic on the model (configuration and quote) to perform the necessary conversions.

Mapping between the Configurator and the quote lines

The table below details the mapping mechanism between the breakdown lines issued from the configuration process and quote line/subline types.

SALES BREAKDOWN ROOT LINEQUOTE LINE TYPES
Whatever the type of the rootLine (CODIFICATION or COMPLETE_MATCHING or GENERATED_ITEM)CP7
Note: If the rootLine is a “MATCHED ITEM” or a “COMPLETE MATCHING”, all “CODIFICATION” or “COMPLETE MATCHING” sublines will be ignored by the quote
SALES BREAKDOWN SUBLINESQUOTE LINE TYPESQUOTE SUBLINE TYPES
CODIFICATION lines/sublines
Sub type: CODIFIED_ITEMCP7Child CP7
Sub type: MATCHED_ITEMSI7Child SI7
SALES BREAKDOWN SUBLINESQUOTE LINE TYPESQUOTE SUBLINE TYPES
Sub type: GENERATED_ITEMCP7Child CP7
COMPLETE_MATCHING lines/sublines
Sub type: CONFIGURABLE_PRODUCTSI7 ChildSI7
Sub type: SALES_PRODUCTSI7 ChildSI7
Sub type: STANDARD_SALES_ITEMSI7 ChildSI7
BREAKDOWN_LINK lines (or CUSTOM_LINK…)
Sub type: CONFIGURABLE_PRODUCTLNK
Sub type: SALES_PRODUCTLNK
Sub type: STANDARD_SALES_ITEMLNK
CONFIGURABLE_PRODUCTOut of scope - ignored
SALES_BREAKDOWN_LINEOut of scope – ignored
PARTIAL_MATCHINGOut of scope – ignored
Note: Please note that the GENERATED_ITEM subType should not be used in a production environment

To generate LNK type of sublines mapped with custom product links (different to the standard one of type breakdown) the steps described below must be followed:

  1. Declare in the configuration file of the Configurator a custom saving policy which includes the custom product link(s) to be stored in the XML file:

    For instance:

    <cam:Param cpe="CPE.Settings.Session.SavingPolicy" value="Custom; configurationDetails=true;

    domainDetails=false; generativeProcess=true; notExisting=false;

    productDictionary=true; productLinkType= "customLink1~customLink2" />

  2. Declare in the general settings of the spreadsheet the custom link type to be mapped with the subline of type LNK (refer to chapter General Settings)
  3. Use XPATH mechanism to retrieve information from the product links (like the other type of lines)

Note:

  • By default, if no type is declared in the quote model, the Breakdown type of link is taken into account to create LNK lines)
  • Multiple product link types may be mapped

Synchronization column concept

The Sync column allows the end-user to re-launch configuration process associated with configured product while keeping manual entries made in the spreadsheet (e.g. discounts, tax etc.). This mechanism applies if and only if the SyncID remains identical after each re-launch.

How to implement the Sync column?

  • Identify the column to store the SyncID : set the property “Sync Column” to ”Yes”
  • The SyncID could be for example retrieved via XPATH of the CPE of the Codified Line, or the CPE

    of the Matched Item.

How does it work?

  • Before accessing the configuration process an image of the configured product breakdown is memorized with included the values of the editable columns
  • After the configured product lines and sublines have been re-created, the editable values are re-applied and the propagation are launched, simulating thus, the user inputs (from the top line (root) to the bottom line and from the left to the right.)

NEGOTIATION TOOLS

The quote spreadsheet embeds tools to help the users to determine the right price and quickly adjust quoted prices that do not align with financial objectives:

Note: The following features are only available when using the Quote Layout V2.


Pricing and Discount Guidance

The guidance thresholds (up to 5 levels) displayed in the widget associated to the Guidance type of column can either come from CPQ (predefined) or PROS PO (predictive).

In addition, a maximum and minimum value must be provided as well.

The visual scale between thresholds, min, max, and current value is respected in the diagram.

At the top, a header presents the different thresholds defined, and their associated value. You can click on one of the threshold to assign its value to the guidance widget.

Discount and Pricing guidance can be handled:

  • Example of a Pricing Guidance:
    • The column is used to store the final discounted price.

  • Example of a Discount Guidance:
    • The column is used to store the discount (in percentage or in amount) to be applied on the List Price (Max. Price)

The guidance column parameterization has to comply to the following rules:

  • The type of the guidance column AND the type of the columns containing the levels have to be identical (e.g. For a Discount Guidance stored as a Percentage, the target/expert/floor level columns have to be Percentages)
  • A minimum of 2 levels ((Expert and Floor) are necessary to render the widget
  • The Maximum price is mandatory. The Max. Price column is considered as the List Price i.e. the price corresponding to a 0% discount.
  • The values of the levels have to be correctly ordered:
    • For Pricing guidance: Expert > level-2 > ...> Floor
    • For discount guidance: Expert < level-2 < ...< Floor

Finally, it is recommended that the column is Computed in addition to ‘UserInput’ to predefine the default guidance value.

Edge cases:

  • If the user tries to input a value that is below the minimum value, then the minimum value is applied
  • If the user tries to input a value that is above the maximum value, then the maximum value is

    applied

  • When trying to open the guidance widget, if the current discount is beyond the min / max values, the guidance widget will still be displayed. The graph won't be able to present the current value. You can use the guidance header to select one of the thresholds and set the guidance value.

    This helps user getting "back on track" if they have manually assigned an invalid value from the



  • The guidance widget can handle negative values.

The following CSS classes are is associated to the component:

.level-1 {

background-color:$Score1-Color;

fill:$Score1-Color;

}

.level-1.off {

background-color:$Score1-off-Color;

fill:$Score1-off-Color;

}

Level-2 to 5 are also available. The last level is identified by a different class : .level-red

.level-red {

background-color:$Score-red-Color;

fill:$Score-red-Color;

}

.level-red.off {

background-color:$Score-red-off-Color;

fill:$Score-red-off-Color;

}

Scoring

The scoring type of column (or type of total cell) stores an integer (from 0 to 100 – the score can be computed) and is used to render a visual indication of the quality of the negotiation on the quote line and/or on the full quote.

It is possible to define up to 5 thresholds for the scoring. For example:



  • If the currentScore >= Level-1 Score (Expert), the ‘level-1’ class is used and corresponds to the green color in the default theme.
  • If Level-2<= currentScore < Level-1, the ‘level-2’ class is used.
  • If Level-3<= currentScore < Level-2, the ‘level-3’ class is used.
  • If Level-4<= currentScore < Level-3, the ‘level-4’ class is used.
  • If Level-5<= currentScore < Level-4, the ‘level-5’ class is used.
  • If currentScore < Level-5, the ‘level-red’ class is used and corresponds to the red color in the default theme.

Example of rendered UI:



The following CSS class names are used to render the scoring column :

.level-1 {

background-color:$Score1-Color;

fill:$Score1-Color;

}

.level-1.off {

background-color:$Score1-off-Color;

fill:$Score1-off-Color;

}

Level-2 to 5 are also available. The last level is identified by a different class : .level-red

.level-red {

background-color:$Score-red-Color;

fill:$Score-red-Color;

}

.level-red.off {

background-color:$Score-red-off-Color;

fill:$Score-red-off-Color;

}

Reference: : The description of the Score and Guidance type of column is available in the following chapter: APPENDIX A – Focusing on Field/Column/Total Cell.

Contract Lifecycle Management (CLM)

OVERVIEW

CPQ embeds functionalities to cover the contract lifecycle management (referred in this documentation as CLM.

The CLM functionalities work as follows:

  • Lines Items, including folders and sublines, are identified individually by a ContractSyncID
  • On click on the SFDC action ‘Create Contract’, the current quote is compared with the quote of the parent contract.
  • Lines are compared according a set of columns
  • The result of the comparison is populated in the ContractLineType columns of the current quote and then the quote is synchronised in SFDC.
    Note: You can have more details on the ContractLineType in the chapter Best practices to compute the ContractSyncID column
  • In order to get the CLM to work, some modifications to the quote model are necessary:
    • The following columns—ContractSyncID, ContractLineType and RenewalType —have to be defined in the Quote model with the following characteristics:

      ContractSyncID

      <columnDef accessRights="hidden" syncColumn="yes" >

      …

      <name>ContractSyncID</name>

      …

      <columnDataValidation emptyValue="NotAllowed">

      …

      </columnDataValidation>

      </columnDef>

      ContractLineType

      <columnDef accessRights="hidden" syncColumn="no" >

      …

      <name>ContractLineType</name>

      <dataType>

      <dataTypeNumber minValue="0.0" maxValue="4.0" numDecimal="0"

      groupSeparator="off" negativeFormat="brackets"

      negativeRedColor="on"/>

      </dataType>

      …

      <columnDataValidation emptyValue="NotAllowed">

      …

      </columnDataValidation>

      </columnDef>

      RenewalType

      <columnDef accessRights="hidden" syncColumn="no" >

      …

      <name>RenewalType</name>

      <dataType>

      <dataTypeNumber minValue="0.0" maxValue="1.0" numDecimal="0"

      groupSeparator="off" negativeFormat="brackets"

      negativeRedColor="on"/>

      </dataType>

      …

      <columnDataValidation emptyValue="NotAllowed">

      …

      </columnDataValidation>

      </columnDef>

  • The following stateless functions also have to be defined as Automated actions:

CLMQuoteCompareMergeStatelessAction

The “keycolumns” entity requires to specify the columns that one wishes to use for the comparison,

separated by a tilda ~.

For instance, if you look for changes between two contracts on columns DateBeginning, DateEnd and Totalprice, you will have to configure it as follows:

<automatedAction>

<name>CLMQuoteCompareAndMerge</name>

<trigger type="StatelessExecutionMode"/>

<actionType>JavaClass</actionType>

<settings>

<nameValueEntity name="javaClass" value="com.sfdc.integ.output.

CLMQuoteCompareMergeStatelessAction"/>

<nameValueEntity name="keyColumns" value="DateBeginning~DateEnd~TotalPrice"/>

</settings>

</automatedAction>

CLMCreateQuoteFromContract

<automatedAction>

<name>CLMCreateQuoteFromContract</name>

<trigger type="StatelessExecutionMode"/>

<actionType>JavaClass</actionType>

<settings>

<nameValueEntity name="javaClass" value="com.sfdc.integ.output.

CLMQuoteFromContractStatelessAction"/>

</settings>

</automatedAction>

When creating the contract of an amendment, the amendment lines are compared with the original quote lines. To do that, the Managed Package has to re-inject any line that had been deleted from the original quote. The lines are injected in a specific folder with type ‘deleted’ for both folder and sublines. The idea is that at this stage (contract creation), in most cases, the quote itself isn’t going to be opened again, only the contract will be used.

But, when calculating totals, or for approvals, it is important to ignore these specific lines. You can do that by inspecting the lines type (column ContractLineType): if the value is ‘4’, it means the line was deleted and should be ignored. The same applies for triggers upon adding lines : pay attention that these ‘deleted’ lines can be injected when creating the amendment contract.

Note: CLM is available from V11.1 only within Salesforce.com

BEST PRACTICES TO COMPUTE THE CONTRACTSYNCID COLUMN

Note: The details in this section are simply here as guidelines and should be adapted to each environment.

One of the challenges of the CLM functionality is to make sure that each line items that need to be compared has a unique identifier. This identifier can, but it’s not compulsory, be used for the synchronisation in SFDC. We recommend that the ContractSyncID column should be defined this way:

XML Sample

<columnDef accessRights="open" syncColumn="yes" >

…

<name>ContractSyncID</name>

…

<columnDataValidation emptyValue="NotAllowed">

<columnComputation lineType="CP7" isChildLine="no" entryMode="Computed">

<ifComputed>

<actionType>Macro</actionType>

<settings>

<nameValueEntity name="macroString" value="ComputeSyncID"/>

<nameValueEntity name="CPE"

value="//conf:ItemSalesBreakdownLine/@cpe"/>

<nameValueEntity name="ItemID"

value="//conf:ItemSalesBreakdownLine/@cpeOfItem"/>

<nameValueEntity name="ItemPK"

value="//cat:StandardItem/@cpe"/>

</settings>

</ifComputed>

</columnComputation>

…

</columnDataValidation>

</columnDef>

And the associated Macro ought to be defined as follow

Macro language Sample

DEFINE ComputeSyncID()

LOCAL timeStamp DateCreate[aliasLine]

LOCAL timeID ACDate(timeStamp, "yyyyMMdd HHmmss")

LOCAL timeString timeID.getDate("yyyyMMddHHmmss")

IF ((parents[aliasLine]<>0) AND (rowTypes[aliasLine]="CP7"))

DISPLAY CPE + "/" + ItemPK + "/" + ItemID + "/"

ELSE

DISPLAY CPE + "/" + ItemPK + "/" + ItemID + "/" + timeString

END_IF

END_DEFINE

This macro will compute the ContractSyncID for every line type defined in the column ContractSyncID and will assign to it the following:

If the line is a CP7 subline then the ContractSyncID will be

@CPE/SI@CPE/@CPEofItem

For every other line the ContractSyncID will be

@CPE/SI@CPE/@CPEofItem/TimeofInsertionInCart

Note: Bear in mind this method is not sufficient for CP7 Sublines and we recommend that a number coming from the configuration itself is to be added at the end of

the @CPE/SI@CPE/@CPEofItem string.

USING THE COMPARISON METHOD OUTSIDE SFDC

It is possible to call the comparison method called compareAndMergeQuotes outside of the SFDC

mechanism described above (the one triggered on ‘Create Contract’). This could be useful in order to compare two quotes. It could be called from CPQ Macro Language as follows:

Macro language Sample

LOCAL hashColList ArrayList()

/* just comparing the quantity column */

hashColList.add("Quantity")

LOCAL quo1PK CartPK(/*<PK quote to be compared of the following form domain_id.release

eg : -_cart1.1>*/)

LOCAL syncColumn "ContractSyncId"

CartTools.compareAndMergeQuotes(quo1PK, Controller, syncColumn, hashColList)

Focusing on report integration

OVERVIEW

Quote gives the ability to generate high-quality documents in multiple output formats. Generated documents can be viewed and emailed to the customer.

When Quote is used as a standalone tool, they are volatile, meaning that they are destroyed when the session is closed.

When integrated with salesforce.com or Microsoft Dynamics CRM they are synchronized within the CRM before being destroyed.

The document generation is based on three different sources, which are merged together:

  • One or several jasper report templates
  • The XML buffer containing the quote data (header information, spreadsheet lines and sublines, total cells)
  • Optional user parameters prompted before the generation
    information: Please check the technical requirements to know which Jasper Report version is included in the CPQ package.

    The Quote XML (which can be retrieved using the exportXML action) is included into a root structure <origin> <form>

    All the namespaces (conf:, cam:, cat:) are automatically removed

SETUP OF END-USER PARAMETERS

Possible end-users’ parameters are detailed in the table below:

PARAMETER USAGE EXPLANATIONS
Output format Allows the user to choose the output format of the document being generated Supported format: PDF, xls, rft (word), docx, xlsx, HTML
ON/OFF parameters Allows the user to enable/disable options implemented into the document templates Such as: Display of pricelist, discount, etc. Selection of the sections to be printed; CoverPage, Cover Letter, Terms & Conditions, Table of Contents, etc.
Numeric or text parameters Allows the user to enter specific values or to choose values among a predefined list of value Such as: Payment terms, special offers, etc.
Formatted text parameters Allows the user to personalize the content of some paragraphs Such as: Text of the cover letter, additional notes, etc.
External uploaded file Allows the user to merge with content stored into files to be uploaded Such as: Logo of the customer’s company, specific terms & conditions, etc.
Merge of documents attached to the quote lines Allows the user to include as annexes additional documents attached to the quote lines in the spreadsheet Such as: Product datasheet, drawing, etc.

How to setup the output formats?

  • The output format can be either fixed or opened to the user choice among a pre-defined list of formats
  • The setup is made through the property outputFormat of the report service which can either contains one (or a list of) output format or the value <UserChoice>
    • Examples :
      • service.MyProposal.outputFormat=PDF
      • service.MyProposal.outputFormat=PDF,RTF
      • service.MyProposal.outputFormat=UserChoice
  • Report services are declared in the file service.properties and can be overloaded from the XML WS file

How to setup ON/OFF, numeric, text, formatted text or external file parameters?

  • From the report template:

  • Declare a parameter with the required type according to the following mapping table:
    • ON/OFF parameter: java.lang.Boolean,
    • Numeric/Integer parameter: java.lang.Integer,
    • Numeric/Decimal parameter: java.lang.Double,
    • Text parameter: java.lang.String
    • Formatted text parameter: java.lang.String
    • External file parameter: java.lang.String
    • Tick the case “Use it as a prompt”
    • Associate a default value and a description
  • Associate following additional properties:
    • Group: (optional) allows to gather several parameters in common groups – names are free but cannot be translated
    • GroupPosition: (optional) integer. Allows to control the order of the groups to be prompted to the user
    • listOfValues: with the following syntax "id:value;id:value;id:value" in order to setup a pre-defined list of values
    • layout=upload for parameter of type “external file upload”
    • layout=html for parameter of type “formatted text”
    • layout=LongText for parameter of type “formatted text without a WYSIWYG editor
  • From the proposal step page of Quote:
    • Prompted parameters are retrieved from the main report template and displayed per groups along with their description and their appropriate input mode:
    • checkbox for Booleans
    • combo box for those having a list of values
    • upload fields for those having the property “layout=upload”
    • wysiwyg text editor for those having the property “layout=html”
    • textfield for the others
      Warning: Parameter names must not contain special characters

How to group and order the report parameters to be prompted to user?

  • This ability is provided with two optional properties associated to each parameter defined in the report template:
    • Group=
    • GroupPosition=
  • The property “Group” defines the title of the section into which the parameter belongs whereas the “GroupPosition” defines the order the sections displayed in the settings page.

How to convert decimal values into monetary values?

  • Use the method .format provided in the

    package <com.cameleon.framework.business.formatters.MonetaryFormatter> as shown in the example below:

    • (new com.cameleon.framework.business.formatters.MonetaryFormatter(new Locale($F{User_Country}, $F{User_Language}), $P{User_Currency})).format(new double($F{Price1}),$F{User_MonetaryFormat})

How to include the 2D graphic associated with a configured product?

  • Retrieve in a field of type String the content of the tab “SVG” associated with the parent quote line:
    • Example:

      <field name="Drawing" class="java.lang.String">

      <fieldDescription><![CDATA[itemXML/ConfigurationTree/ConfigurableProduct/

      GenerativeProcess/ItemSalesBreakdownLine/Drawing/DrawingResult/SVG]]>

      </fieldDescription>

      </field>

  • Create an object of type image "net.sf.jasperreports.engine.JRRenderable"
  • Use the method “getDrawingJasper(String)” to display the graphic in the report
    • Example:

      <image evaluationTime="Now" hyperlinkType="None"

      hyperlinkTarget="Self" >

      <reportElement x="170" y="70" width="250" height="300" key="image-1" positionType="Float"/>

      <box></box>

      <graphicElement stretchType="NoStretch"/>

      <imageExpression

      class="net.sf.jasperreports.engine.JRRenderable">

      <[CDATA[com.cameleon.doc.DrawingEdge.getDrawingJasper($F{Drawing})]]>

      </imageExpression>

      </image>

How to include the generation of the table of content?

  • In the main report:
    • In the "report Inspector" tree, unfold "Scriptlets" branch and click on "REPORT". Complete "Scriptlet Class" by: "com.accesscommerce.cart.report.Scriptlet". (This updates the parameter "REPORT_SCRIPTLET".)
    • Create a variable called : "HeadingsCollection" and put the value "java.util.Collection" in its "Variable Class" parameter
    • Complete the field "Initial Value Expression" in the created variable’s parameters with : "new java.util.ArrayList()"
    • Before sub-report, in the band "Summary" of the page, add a label (static text) called : "BEGIN_TABLE_CONTENTS"
    • (This allows you to move the table of contents at the beginning of the report.)
    • Beware the field must have a height equal or greater than 14.

In the call of sub-report from the main report :

  • Make it pass the variable "HeadingsCollection" as a parameter.
  • Do the same for all sub-reports except the Table of Contents.

In the sub-report of the main report:

  • In the band "Summary" of the page, add a label (static text) called:
  • "BEGIN_TABLE_CONTENTS".
  • Beware the field must have a height equal or greater than 14.
  • Create a parameter called: "HeadingsCollection".
    • This is used to retrieve the value of the variable passed as a parameter of the sub-report by the parent report. Do the same for all sub-reports except the Table of Contents.
    • Create a variable called: "HeadingsCollection" and put the value "java.util.Collection" in its "Variable Class" parameter.
    • Complete the fields "Initial Value Expression" and "Variable Expression" in the created variable parameters with: "$P{HeadingsCollection}".
    • In the band "Summary" of the page, include in the display order pages you want to see before the table of contents.
  • (i.e.: You want: Page 1: Cover Page, Page 2: Cover Letter.)
  • Then add after them the Table of contents sub-report.

In the call of Table of contents sub-report :

  • In "connection type" put: "use a data source expression".
    • In "data source expression" put: "new net.sf.jasperreports.engine.data.JRBeanCollectionDataSource($V{HeadingsCollection

      })".

  • Make it pass the variable "HeadingsCollection" as a parameter.

In Table of contents sub-report :

  • Create a field called: "headingType" and is type is Integer.
  • Create a field called: "headingText" and is type is String.
  • Create a field called: "reference" and is type is String.
  • Create a field called: "pageIndex" and is type is Integer.
    • Create a variable called: "Page" and is type is Integer. Put on "Variable Expression" : "new Integer($F{pageIndex}.intValue())"
    • To create a standard table of contents, re-use the example file Proposal_Summary.jrxml. You will have the first two title’s levels of Table of contents with the right conditions.

Define the fields that belong to the table of contents:

All titles must be owned or included in the sub-report which belongs to the "Details" section of the sub-report with the "Summary" section which is located in the sub-report "Table of Contents".

  • Draw a line under the title that you want to see in the table of contents.
  • For this line, complete the field "Print when expression" with the value: "$P{REPORT_SCRIPTLET}.addHeading("Section_name", "Level_of_title_in_Table_of_contents”, "Text_to_display")"

i.e. : $P{REPORT_SCRIPTLET}.addHeading("HealthQuote", "1","Your personalized health quote".

Or with a variable :

$P{REPORT_SCRIPTLET}.addHeading("HealthQuote ", "2",$F{TitleOffer})

  • The created line does not appear in the generation of report.

How to setup locales to be used in reports?

  • CPQ has the capability to send a locale to the report generator at runtime in order to use it as the locale of the generated report.
  • The setup is made through the property locales of the report service that contains one value for a given locale or the value . One locales parameter has to be declared per locale to be made available.
    • The following input are accepted:
    • service.MyProposal.locales=fr-FR,en-US,nl-NL
    • service.MyProposal.locales.FR.fr-FR=Français
    • service.MyProposal.locales.US.fr-FR=French
    • service.MyProposal.locales.FR.en-US=Anglais
    • service.MyProposal.locales.US.en-US=English
    • service.MyProposal.locales.FR.nl-NL=Hollandais
    • service.MyProposal.locales.US.nl-NL=Nederland
  • At runtime, if the locales parameter is defined, a new combo box is displayed in the report parameter view to display the locale choice (with translations defined in the service parameters), in order for the end-user to choose one.
    • If the chosen locale exists, it is set as a system parameter sent to the report generator:

      datas.addSystemParameter("REPORT_LOCALE", Locale.forLanguageTag

      (request.getParameter("localeChoice"));

The locale, if it exists, must also be saved in the parameter settings table.

  • If the locales parameter is set to "Cart", the locale from the Quote will be sent to the report generator. - service.PROPOSAL.locales=Cart - Use Language connector (convertCountry & convertLanguage) to convert the cart language to a locale. - No need to display it in runtime parameter view.
    • During the design phase, if you want to personalize some fields from your report template, you have to declare a translation file per locale.
    • Path and name: reportPath + reportName + "/translations/translations_"

      +locale.toString()+ ".properties”

    • The "locale" portion of the translations file name needs to be: xx_XX
    • In each translation file, you have to declare each field for which you want to distinguish the locale. To do so, use the following syntax:
      • For instance in translations_fr_FR.properties:

  • For instance in translations_en_US.properties:

  • At runtime, if locales is used (Cart or list) in the cartServices.properties file:
    • CPQ will try to find a translation file corresponding to the locale
      • If found, CPQ send it to the report generator that applies the translation for the fields declared in the corresponding translation file.

How to setup multilingual reports?

  • The setup is made through the property reportMultiLanguage=Yes of the report service
  • Report services are declared in the file service.properties and can be overloaded from the XML WS file
  • Each set of report and sub reports (one per language) must be stored in a dedicated subfolder named with the language ID.

Example:

  • US (english) language
  • …/US/proposal.jrxml
    • …./US/proposal_CoverLetter.jrxml
    • …
  • FR (french) language
    • …/FR/proposal.jrxml
    • …/FR/proposal_CoverLetter.jrxml
    • …

Jasper translations bundles in sub-reports

If a Jasper report includes sub-reports, the report has to be completed with the following elements for the sub-report definition:

<subreportParameter name="REPORT_RESOURCE_BUNDLE">

<subreportParameterExpression><![CDATA[$P{REPORT_RESOURCE_BUNDLE}]]>

</subreportParameterExpression>

</subreportParameter>

This has to be repeated if the sub-report also has sub-reports.

Building the Access Rights Matrix

OVERVIEW

The access rights are used to restrict visibility and update rights on the objects declared in the quote model according to several combinations of user groups and quote statuses.

3 modes of access rights can be associated to each element (tab, field, action, column, total cell) declared in the quote model:

  • Hidden: the element is hidden to everyone whatever the status of the quote
  • Open: the element is visible and (in case of fields only) updatable by everyone whatever the status of the quote
  • Restricted: the visibility and (in case of fields only) update rights of the element are controlled by the application of an access rights matrix made with combinations on the quote statuses and/or the user groups.

One access rights matrix is associated to each part of the quote model: the quote header and the quote spreadsheet.

Header Access Rights Matrix

The access rights matrix concerns all the elements of the quote header having the property "Access rights" set to "restricted". Each element is listed as a line in the matrix. The matrix properties are detailed in the table below:

Rights are cumulative. In case of contradictory settings, the rights ON will win over the rights OFF

MATRIX LINEMATRIX COLUMN: COMBINATIONS OF USER GROUPS AND STATUSESREMARKS
Tabs having the « Access Rights » property set to « Restricted » (Parameters, Address, Quote/Order info, Change and control tabs)Checkbox Visibility ON Checkbox Update ONChecked checkboxes enable the associated rights Emptied checkboxes disable the associated rights
For each « Restricted » tab, fields having the « Access Rights » property set «to « Restricted »Checkbox Visibility ON Checkbox Update ONTab containing restricted fields must have a restricted access too If a tab is not visible/updatable, none of its fields could be visible/updatable Only the property “visible” can be managed for the tab “Change & Control” and its associated fields
For each actions having the « Access Rights » property set to « Restricted »Checkbox Visibility ON

Spreadsheet Access Rights Matrix

The access rights matrix concerns all the elements of the quote spreadsheet having the property "Access rights" set to "restricted". Each element is listed as a line in the matrix. The matrix properties are detailed in the table below:

Rights are cumulative. In case of contradictory settings, the rights ON will win over the rights OFF

MATRIX LINEMATRIX COLUMN: COMBINATIONS OF USER GROUPS AND STATUSESREMARKS
Columns having the « Access Rights » property set to « Restricted »Checkbox Visibility ON Checkbox Update ONChecked checkboxes enable the associated rights Emptied checkboxes disable the associated rights
For each On Demand Menu actions having the « Access Rights » property set to « Restricted »Checkbox Visibility ON
For each On Demand Grid actions having the « Access Rights » property set to « Restricted »Checkbox Visibility ON
For each On Demand Line actions having the « Access Rights » property set to « Restricted »Checkbox Visibility ON

Translating the quote model

A default language is associated as a global parameter within the quote model. This language is used afterwards for entering all the object descriptions declared in the quote model.

Other translations can be defined using the translation function associated to each part of the quote model: the quote header and the quote spreadsheet.

QUOTE HEADER TRANSLATIONS

The translation matrix concerns all the translatable properties of the quote header. Each element is listed as a line in the translation matrix detailed in the table below:

LINES FROM COLUMN <DEFAULT LANGUAGE> TO COLUMN <LANGUAGE>
Status: names Tabs: titles Fields: labels, help messages, domain of values On demand actions: title, help and waiting messages Automated actions: waiting messages Default translations cannot be changed from this matrix Destination language is selected from the language list

SPREADSHEET TRANSLATIONS

The translation matrix concerns all the translatable properties of the quote spreadsheet. Each element is listed as a line in the translation matrix detailed in the table below:

LINES FROM COLUMN <DEFAULT LANGUAGE> TO COLUMN <LANGUAGE>
Columns: titles, help messages, domain of values Total cells: titles, help messages, domain of values On demand line actions: help and waiting messages On demand grid actions: titles, help and waiting messages On demand menu actions: titles, help and waiting messages, additional labels Automated actions: waiting messages Default translations cannot be changed from this matrix Destination language is selected from the language list