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:
| PARAMETER | VALUES/EXPLANATIONS |
|---|---|
| Language | The 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. |
| Currency | The default currency list is defined in the service.properties file and can be overloaded @runtime within the WS XML file. |
| Decimal separator | Coma “,” or decimal point “.” |
| Group separator | or coma “,” |
| Monetary format | #,##0.00 ¤ Mainly used to adjust the number of decimals. Do not change the pattern structure. |
| Currency Symbol | Associated with the default currency “€” for example |
| PARAMETER | VALUES/EXPLANATIONS |
|---|---|
| User Id | Default user id used to trace the events in the quote history as well as to compute the access rights matrix |
| User Name | Default user name used to trace the events in the quote history |
| User Group | Default user group used to trace the events in the quote history as well as to compute the access rights matrix |
| Allow Duplicate Local Lines | Rules the insertion of items already present locally – in the current folder - in the quote |
| Allow Duplicate Global Lines | Rules the insertion of items already present globally – at any level - in the quote |
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
- 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 |
When integrated with salesforce.com these fields can be automatically filled-in using the standard mapping mechanism.
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 |
|---|---|---|---|
| Text | Country | Text | |
| Comments | Text |
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 |
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 Name | Type |
| CurrentStatus | Text |
| CurrentStatusType | Text |
| StatusDate | Date |
| CurrentActiveRelase | Number |
| ActiveRelaseDate | Date |
| CurrentOwnerId | Id |
| QUOTE CURRENT STAGE | |
|---|---|
| CurrentOwnerName | Text |
| CurrentOwnerGroup | Text |
| OwnerDate | Date |
| UserCreateId | Id |
| UserCreateName | Text |
| UserCreateGroup | Text |
| CreateDate | Date |
| LastUpdateUserId | Id |
| LastUpdateUserName | Text |
| LastUpdateUserGroup | Text |
| LastUpdateDate | Date |
| EVENT HISTORY | |
|---|---|
| Field Name | Type |
| EVENT HISTORY | |
|---|---|
| EventDate | Date |
| EventDescription | Text |
| From (release #, status, owner) | Text |
| To (release #, status, owner) | Text |
| UserId | Id |
| UserName | Text |
| UserGroup | Text |
| Comments | Text |
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:
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Position | Sequential position of the action | 1,2,3, … |
| Name | Internal name of the action | All actions must have unique names in a given quote model |
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Type | Action type | None: 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) |
| Title | Title 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 language | Other translations are defined in the translation step |
| Display in read only mode | Flag indicating whether the action must be shown when the quote is looked or not | Yes/No Recommendation: disable actions that can’t be performed when the quote is looked |
| Access rights | Access rights logic to be applied on the action | Hidden: 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.
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:
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Triggers | Refer to Appendix mentioned above | Many triggers can be associated to a given action |
| Name | Internal name of the action | All actions must have unique names in the quote model |
| Type | Action type | None: 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 action | Other 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:
| LINES | SUBLINES |
|---|---|
| LineUpdateBefore LineUpdateAfter | SubLineUpdateBefore SubLineUpdateAfter |
| LineRefreshBefore LineRefreshAfter | SubLineRefreshBefore SubLineRefreshAfter |
| LineCreateBefore LineCreateAfter | SubLineCreateBefore SubLineCreateAfter |
| LineCopyBefore LineCopyAfter | SubLineCopyBefore SubLineCopyAfter |
| LinePasteBefore LinePasteAfter | SubLinePasteBefore SubLinePasteAfter |
| LineDeleteBefore LineDeleteAfter | SubLineDeleteBefore SubLineDeleteAfter |
| LineMoveBefore LineMoveAfter | SubLineMoveBefore 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 |
| SPECIFIC | FIELDS EXPLANATION |
|---|---|
| DS_SCOPE(2) | Internal. Do not use |
| DS_TYPE(2) | Internal. Do not use |
| ID_CNY_GENERIC_ITEM | DEPRECATED |
| ID_GENERIC_ITEM | DEPRECATED |
| SPECIFIC | FIELDS EXPLANATION |
|---|---|
| ID_ITEM | DEPRECATED |
| APE_TOTAL(38,5) | DEPRECATED |
| APE_PRICE(38,5) APE_QUANTITY(38,5) | DEPRECATED DEPRECATED TOTAL(38,5) PRICE(38,5) |
| EXTENSION TABLE | BINARY 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) |
| SAAS | STANDARD EDITION | PREMIUM EDITION |
|---|---|---|
| Number of columns | 20 | 30 |
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.
- Horizontal calculations allows cells to be calculates from other cells of the current line
- 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
- Up propagation allows parent cells to be calculated from its child lines.
- 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.
| ARROWS | LINE TYPE | COMPUTATION | COLUMNS | EXPLANATION |
|---|---|---|---|---|
| Blue arrows | Folder (FO) | Up Propagation | Unit Price; Price; Net Price | Folder prices are the sum of prices of the inferior level |
| Red arrows | Product lines (CP, SI, SP) | Down Propagation | Discount % | Discount is spread on the inferior level lines |
| Green arrows | Product lines (CP, SI, SP) | Horizontal Calculation | Net price Discount % | Net price is computed with the price and the discount Discount is computed with the Price and the Net price |
| Green cells | Product lines (CP, SI, SP) | Horizontal Calculation | Unit Price | Price 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:
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Position | Sequential position of the action | 1,2,3, … |
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Name | Internal name of the action | All actions must have unique names in the quote model |
| Type | Action type | None: 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 language | Other translations are defined in the translation step |
| Waiting message (optional) | Message (in the default language) displayed to the user while executing the action | Other translations are defined in the translation step |
| Display in read only mode | Flag indicating whether the action must be shown when the quote is consulted | Yes/No Recommendation: disable actions that can’t be performed when the quote is consulted |
| Access rights | Access rights logic to be applied on the action | Hidden: 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:
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Position/Shortcut | Action can be present either in the flyer (in this case the position is required) or as a shortcut of a given column | Position LiCj: LineColumn Shortcut: Name of column, whose triggers the action on user click |
| Name | Internal name of the action | All actions must have unique names in a given quote model |
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Type | Action type | None: 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 Condition | Determines the line selection condition whose will enable the action | Selection 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 language | Other translations are defined in the translation step |
| Display in read only mode | Flag indicated whether the action must be shown when the quote is consulted | Yes/No Recommendation: disable actions that can’t be performed when the quote is consulted |
| Access rights | Access rights logic to be applied on the action | Hidden: 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 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:
| PROPERTY | DESCRIPTION | VALUES/EXPLANATIONS |
|---|---|---|
| Triggers | Refer to Appendix mentioned above | Many triggers can be associated to a given action |
| Name | Internal name of the action | All actions must have a unique names in a given quote model |
| Type | Action type | None: 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 action | Other 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
| NAME | DESCRIPTION |
|---|---|
| SI View | Product display (access to the corresponding catalog page) |
| NAME | DESCRIPTION |
|---|---|
| Item Refresh | Refresh of prices and characteristics of the product |
| Back to Catalog | Returns to the catalog. If no catalog has yet been opened, the default catalog is opened. |
| Quick Create SI Line | Adds one or more products whose code or description matches the search string. |
| Catalog List | Displays a list of catalogs in the left-hand menu of the quote spreadsheet. |
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 LINES | QUOTE LINE (OR SUBLINE) TYPES |
|---|---|
| STANDARD SALES ITEMS | CT7 |
| Linked products: BREAKDOWN_LINK (or CUSTOM_LINK…) | LNKCT (subline) |
| SALES PRODUCTS | SP7 |
| 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:
- 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" /> - 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”)
- 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
| NAME | DESCRIPTION |
|---|---|
| PC View | Relaunches the configuration process in read only mode with the answers reloaded from the latest saved XML |
| PC Update | Relaunches the configuration process with the answers reloaded from the latest saved XML |
| Item Refresh | Refreshes the configuration (carries out configuration and price calculations and other generative processing again) |
| Configurator List | List of configurable products directly accessible from the left-hand menu of the Quote module |
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
- Example
- 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 LINE | QUOTE LINE TYPES |
|---|---|
| Whatever the type of the rootLine (CODIFICATION or COMPLETE_MATCHING or GENERATED_ITEM) | CP7 |
| SALES BREAKDOWN SUBLINES | QUOTE LINE TYPES | QUOTE SUBLINE TYPES |
|---|---|---|
| CODIFICATION lines/sublines | ||
| Sub type: CODIFIED_ITEM | CP7 | Child CP7 |
| Sub type: MATCHED_ITEM | SI7 | Child SI7 |
| SALES BREAKDOWN SUBLINES | QUOTE LINE TYPES | QUOTE SUBLINE TYPES |
|---|---|---|
| Sub type: GENERATED_ITEM | CP7 | Child CP7 |
| COMPLETE_MATCHING lines/sublines | ||
| Sub type: CONFIGURABLE_PRODUCT | SI7 Child | SI7 |
| Sub type: SALES_PRODUCT | SI7 Child | SI7 |
| Sub type: STANDARD_SALES_ITEM | SI7 Child | SI7 |
| BREAKDOWN_LINK lines (or CUSTOM_LINK…) | ||
| Sub type: CONFIGURABLE_PRODUCT | LNK | |
| Sub type: SALES_PRODUCT | LNK | |
| Sub type: STANDARD_SALES_ITEM | LNK | |
| CONFIGURABLE_PRODUCT | Out of scope - ignored | |
| SALES_BREAKDOWN_LINE | Out of scope – ignored | |
| PARTIAL_MATCHING | Out of scope – ignored |
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:
- 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" /> - 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)
- 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:
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.
- 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 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;
}
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 columns—ContractSyncID, ContractLineType and RenewalType —have to be defined in the Quote model with the following characteristics:
- 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.
BEST PRACTICES TO COMPUTE THE CONTRACTSYNCID COLUMN
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
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 generationinformation: 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=PDFservice.MyProposal.outputFormat=PDF,RTFservice.MyProposal.outputFormat=UserChoice
- Examples :
- 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 othersWarning: 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
.formatprovided in thepackage
<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>
- Example:
- 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"/><imageExpressionclass="net.sf.jasperreports.engine.JRRenderable"><[CDATA[com.cameleon.doc.DrawingEdge.getDrawingJasper($F{Drawing})]]></imageExpression></image>
- Example:
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 "
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})".
- In "
- 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.
- Create a variable called: "
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"));
- If the chosen locale exists, it is set as a system parameter sent to the report generator:
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_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.
- CPQ will try to find a translation file corresponding to the locale
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 LINE | MATRIX COLUMN: COMBINATIONS OF USER GROUPS AND STATUSES | REMARKS |
|---|---|---|
| Tabs having the « Access Rights » property set to « Restricted » (Parameters, Address, Quote/Order info, Change and control tabs) | Checkbox Visibility ON Checkbox Update ON | Checked 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 ON | Tab 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 LINE | MATRIX COLUMN: COMBINATIONS OF USER GROUPS AND STATUSES | REMARKS |
|---|---|---|
| Columns having the « Access Rights » property set to « Restricted » | Checkbox Visibility ON Checkbox Update ON | Checked 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 |
