Update 21A

Revision History

This document will continue to evolve as existing sections change and new information is added. All updates appear in the following table:

Date	Product	Feature	Notes
22 APR 2021	Oracle CX Sales Integration	REST - Export Lines Commerce Integration Type for CX Sales	Updated document. Revisied feature information.
10 FEB 2021		IMPORTANT Actions and Considerations	Updated document. Revised feature information.
13 NOV 2020			Created initial document.

Overview

Oracle Configure, Price, and Quote (CPQ) enables companies to streamline the entire opportunity-to- quote-to-order process, including product selection, configuration, pricing, quoting, ordering, and approval workflows. Oracle CPQ provides a flexible, scalable, enterprise-ready solution ideal for companies of all sizes that sell products and services across direct, indirect, and e-commerce sales channels.

This guide outlines the information you need to know about new or improved functionality in Oracle CPQ 21A and describes any tasks you might need to perform for the update. Each section includes a brief description of the feature, the steps you need to take to enable or begin using the feature, any tips or considerations that you should keep in mind, and the resources available to help you.

Key Resources

Refer to Oracle CPQ Administration Online Help for detailed descriptions and instructions.

Security & New Features

We would like to remind you if your system has modified security structures you may need to advise your security administrator of new features you would like to implement.

Give Us Feedback

We welcome your comments and suggestions to improve the content. Please send us your feedback at cpqcloud_documentation_us_grp@oracle.com.

Feature Summary

BML

The following BML feature is available in Oracle CPQ 21A.

Filter Data with Get Transaction BML Function

In 20C and earlier, the gettransaction BML function returns the complete document XML without a way of filtering it. For quotes with several hundred or thousand lines, this can perform poorly. Beginning in 21A, Oracle CPQ provides the ability to filter data when running the gettransaction BML function.

BML Syntax:

Parameters:

Return Type: String

Example:

Providing filter criteria with the gettransaction BML function applies a more directed focus on processing the required XML data.

Steps to Enable

You don't need to do anything to enable this feature.

Tips And Considerations

• A maximum of 20, 000 transaction lines can be generated for the gettransaction XML response.
• The following attributes are not supported with the gettransaction BML function JSON filter criteria:
  • Rich Text
  • HTML & Read Only
  • Approval History

Key Resources

Refer to the Oracle CPQ Administration Online help for details about using the BML Function Editor.

Bulk Upload and Bulk Download Services

The following Bulk Upload and Download feature is available in Oracle CPQ 21A.

Bulk Download of Event Log Data

Beginning with Oracle CPQ 21A, bulk download services supports the download of Event Log data in CSV format. The Event Log data can be filtered by date, business ID, user, action, and server time.

This provides administrators with easier data access to aid in troubleshooting issues.

Steps to Enable

To schedule a bulk download for Event Log data, complete the following steps:

1. Navigate to the Admin Home page.
2. Click Download under Bulk Data Services in the Utilities section. The Download Category List page opens.

3. Select Event Logs under Category.
4. Click Next. The Search Criteria page opens. The following example shows start and end date criteria for the Event Logs data download.

5. Specify the desired criteria. Only the data that satisfies the specific criteria will be downloaded.
6. Click Download. The Download Status page opens showing the status of the Event Logs download request.

Once the bulk download request is completed, download files are stored on the server. These files can be downloaded onto your local system or viewed in your browser from the server location.

Tips And Considerations

• When filtering based on matching a string value, this search is exact (case-sensitive) in order to preserve performance.
• To download all event Log records, leave all the search criteria blank. However, downloading all of the records may take a long time. We recommend you narrow the search criteria before requesting an Event Log bulk download.

Commerce

The following Commerce feature is available in Oracle CPQ 21A.

Commerce Dynamic Menu Attributes

Oracle CPQ 21A introduces Dynamic Menu attributes for JET Commerce UIs. Similar to Configuration Single Select Pick Lists, Dynamic Menu attributes allow you to implement drop-down menus that display dynamic options. Dynamic Menus are available for Commerce main and sub-documents, and they can be referenced in Commerce rules, BML, Formulas, and Document and Email Designer Templates.

Dynamic Menu Domains

The Domain, Variable, and Display determine the menu options for the user side menu. After defining the domain items, customers can simply add new items to the referenced Data Table when they need new menu options. Administrators can select the following items when defining Dynamic Menus:

• Domain - The Data Table that contains the Dynamic Menu options. Dynamic Menus can only use a Data Table for the domain target, unlike Configuration Single Select Pick Lists, which can use a Data Table or an array.

• Variable - The Data Table column that contains the list of variable values of all possible Dynamic Menu options. Just like Single Select Menu and Multi-Select Menu attributes, CPQ uses the variable value of the selected menu option for Commerce processing and rules.

• Display - The Data Table column that contains display names for all possible Dynamic Menu options. Display names determine the menu option names that appear in the user side menu.
  • A display name can be different from or the same as the variable name of a menu option.
  • If administrators intend the display name and variable name to match each other across all entries, they can set the Variable and Display settings to reference the same data table column.

For example, an administrator wants to implement a Dynamic Menu so users can select a country. They create a "Country" Dynamic Menu attribute and select their pre-defined "CountryTax" Data Table for the Domain, the "CountryCode" column for the Variable, and the "Country" column for the Display value. As shown below, the Domain is highlighted in red, the Variable is highlighted in blue, and the Display is highlighted in green.

The following image shows the target "CountryTax" Data Table that contains the menu options.

When added to the JET Transaction UI, the Country menu will show the Display column values as menu options. Another feature to note is the “Type to Filter” functionality, which provides a field where users can enter text filter criteria. The Dynamic Menu will filter out options that do not contain the character(s) entered by the user.

Dynamic Menu Distinct Values

If a Data Table column has multiple items with the same value, the Dynamic Menu filter returns multiple results with the same value, resulting in users seeing the same result multiple times in the Dynamic Menu options.

Administrators can enable Distinct Values to ensure that a value displays only once in the user side menu.

IMPORTANT: When the Distinct Values option is enabled, the Variable and Display columns are set to the same column, the Variable field is not selectable, and the Order By option is set to the selected Display column.

The following image shows user side Dynamic Menu options without and with distinct values enabled.

Dynamic Menu Filters

Dynamic Menus can filter the menu options shown to the user based on static values or other attribute values. Within the Filter field, administrators can define a query to filter which Data Table column values to display to the user. The size of the Filter text box supports 4000 characters.

In addition to the Country menu, the administrator wants to implement a Dynamic Menu so users can select a state. They create a "State" Dynamic Menu attribute and select their pre-defined "StateTax" Data Table for the Domain and the "State" column for the Variable and the Display value.

The following image shows the target "StateTax" Data Table that contains the menu options.

Filter Syntax

CPQ can interpret query specifications that follow a subset of MongoDB syntax.

IMPORTANT: For more complex filters, refer to the Query Specification Syntax topic in Oracle CPQ Administration Online Help and MongoDB’s Query Documents documentation.

For example, within the State Dynamic Menu attribute the administrator defined a Filter to match the "CountryCode" column in the StateTax Data Table to the value selected in the Country attribute. The Dynamic Menu will filter the menu options based on the user selection. Example Filter: {CountryCode:"|country|"}

When a user selects "United States" from the Country drop-down, the "State" Dynamic Menu uses the "US" CountryCode value to filter the "State" column values from the "StateTax" Data Table. On the user side, only menu options whose "CountryCode" value matches the value selected in the "Country" attribute value are shown.

Case Sensitive Dynamic Menus

The Case Sensitive option determines if the matching between the selected attribute value and the defined "Variable" Data Table column differentiates between capital and lowercase letters. By default, this option is disabled and matches are case insensitive. If your site has case sensitive variable values, you should enable this option to ensure the desired results are returned. If your site has case sensitive display values and the Case Sensitive option is disabled, the site will return the first value based on the "Order By" selection and direction.

For example, assume that a Dynamic Menu has the same column defined tor the Variable and Display values. The chosen column has the following values: red, Red, and RED.

• If Case Sensitive is disabled, no matter which option a user selects they will get back the value that is deemed first based on the Order By selection and direction. This may not be the value associated with the case sensitive option they chose, because the site is performing a case-insensitive match and all of the values match each other (e.g. red = Red = RED)

• If Case Sensitive is enabled, when a user selects a case sensitive option they will always get the value that matches their selection, because the site is performing an exact match and the values do not match each other (e.g. red ? Red ? RED)

Dynamic Menu Translations

Customers can also provide translations for Dynamic Menu display values for named supported languages. To enable translations, administrators select the "Translations" option and provide the translated values in the target Data Table domain.

The column selected for Display contains the base language values. Language codes are appended to the column name for the translated values. Data Table column names for all other language columns should use the following format: "<Display Column Name>_<Language_Code>"

• Dynamic Menus support two-letter translations language codes. For example, the following column is used to provide French translations for the Country display values: "Country_fr"
• Dynamic Menus also support additional two-letter country codes. When using country codes, the first two characters of a language code define the language and the last two characters define the country. For example, the following column is used to provide Brazil Portuguese translations for the Country display values: "Country_pt_BR"

IMPORTANT:

• The Data Table column selected for "Display" must contain the site base language values. CPQ does not look for a differently named column with the site base language code suffix.
• Language codes are case sensitive.
• Refer to the Oracle CPQ Administration Online Help for supported language codes.

For the following example, English is the site base language. Therefore, the "Country" column contains English values. The "Country_de" column contains German translations, the "Country_es" column contains Spanish translations, and the "Country_fr" column contains French translations.

The following image shows user side Dynamic Menus for German, Spanish, and French translated sites.

During use, the session language (typically the logged in user's language) is used to determine which display value to show. If a display value translation cannot be found for the session language, the site base language display value will be used. This can occur if a specifically named column for the session language does not exist in the data table or if the column exists but there is no value in that row.

When an administrator selects the Translations option for a Dynamic Menu attribute, the Available Translations section appears. This list shows the supported language set of a site. A "P" checkmark icon indicates the appropriate translation column is found, and an "x" icon indicates the appropriate translation column was not found. Hovering the mouse over each language will indicate the name of the column from which translations are expected to be found for the language.

Advanced Validations

When the Advanced Validations option is enabled, data validations are triggered on a direct value changes and are also triggered during any modification action even when the value has not changed.

IMPORTANT: You should only enable this option when validations are required, to prevent negative impacts on performance. The performance impact will be even greater for sub-document Dynamic Menu attributes.

Dynamic Menu attributes allow customers to implement drop-down menus that display dynamic options for Commerce main and sub-documents. Dynamic Menu attributes have several advantages over Single Select Menu attributes:

• Administrators can easily maintain menu options using Oracle CPQ Data Tables.
• Updated table values for Live or deployed Data Tables are automatically available in the Dynamic Menu.

Steps to Enable

Complete the following steps to create a Commerce Dynamic Menu Attribute.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition, in the Commerce and Documents section.
3. Select Documents from the Navigation drop-down menu for the applicable process, and then click List.
4. Select Attributes from the Navigation drop-down menu for the main or sub-document, and then click List.
5. Click Add.

Main Information

6. Enter the attribute Label.
7. Enter the attribute Variable Name. The Variable Name field populates automatically. Variable names can only contain alphanumeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only.
8. Select Menu from the Attribute Type drop-down menu.
9. Select the Dynamic Menu for the Menu Source.

Dynamic Menu Population

10. Set the following Domain-related fields. Refer to Dynamic Menu Domains for more information.
    1. Domain: Select the Data Table resource that defines the Dynamic Menu options.
    2. Distinct Values: Select this option to ensure that a value displays only once to users in the Dynamic Menu.

IMPORTANT: The "Translations" option is not available when the Distinct Values option is enabled.

1. 3. Variable: Select the Data Table column that contains the variable values of the Dynamic Menu options.

IMPORTANT: The Variable field is not selectable when the Distinct Values option is enabled.

1. 4. Display: Select the Data Table column that contains display names for the Dynamic Menu options.
   5. Order By: Select the Data Table column used to sort Dynamic Menu user options.
   6. Order By Direction: Select Ascending or Descending order.
   7. Filter: (optional) Define a query to filter which menu options in the Domain are shown to the user. Refer to Dynamic Menu Filters for more information.
   8. Case Sensitive: Select this option if your site has case sensitive variable values. By default, this option is not selected and matches are case insensitive. Refer to Case Sensitive Dynamic Menus for more information.
   9. Translations: Select this option to display translated menu values in the user's language preference, when the translated values are provided in the Data Table resource. Refer to Dynamic Menu Translations for more information.
   10. Advanced Validation: When enabled, data validations run on the Dynamic Menu attribute even when there is no change in the value.

IMPORTANT: You should only enable this option when required, to prevent negative impacts on performance. The performance impact is even greater for sub-document Dynamic Menu attributes.

11. Click Add or Add and New to save changes.

Tips And Considerations

IMPORTANT:

• Commerce Dynamic Menus are only available in the JET Transaction UI.
• Commerce Dynamic Menus are not supported in Basic or Advanced filtering in the Transaction Line Item Grid.
• Commerce Dynamic Menus do not support Transaction Array, HTML, or RTE type of attributes in the Attribute Editor Dynamic Menu Population Filters.
• Whenever the previously stored value of a Commerce Dynamic Menu is no longer available (i.e. the value or display columns in the Data Table were deleted), users will only see the error when they expand the Commerce Dynamic Menu attribute on the Transaction UI.
• When using Commerce web services, the v11 Commerce Transaction REST APIs are required to support Dynamic Menu attributes.
• You should limit the use of sub-document dynamic menu attributes to prevent negative impacts on performance.
• CPQ does not recommend referencing main document attributes in sub-document Dynamic Menu Filters.
• When "Advanced Validation" is enabled for sub-document Dynamic Menus, validations are only performed for those attributes when their value has been changed or when the user clicks on the menu to see available options. Commerce Dynamic Menus are not available as references in Data Columns and Reporting Manager.

Data Tables

The following Data Table feature is available in Oracle CPQ 21A.

View Undeployed Data Tables

Beginning with Oracle CPQ 21A, the color of the circle icon for data tables that have not been deployed is changed from blue to orange. The orange circle icon identifies Data Tables where the saved version of the table differs from the deployed version of the table. When the Data Table is deployed, the orange circle icon is removed.

Data Table Administration with Data Table Not Deployed

This change allows end users to more easily recognize the status of the Data Table.

Steps to Enable

You don't need to do anything to enable this feature.

Developer Tools

The following Developer Tools are available in Oracle CPQ 21A.

Oracle CPQ Developer Toolkit

To help administrators and developers manage CPQ technical artifacts, Oracle CPQ 21A introduces the CPQ Developer Toolkit. This toolkit is a combination of Command Line Interface (CLI) and open REST APIs that allow customers to communicate with their CPQ site. This client-side tool can change the way administrators work with BML code.

In Oracle CPQ 21A, the Developer Toolkit is enabled to be used with Commerce and Util BML Libraries. Customers use Commerce and Util BML Libraries heavily within CPQ environments. These elements play important roles during CPQ implementation and expansion. The Oracle CPQ Developer Toolkit can reduce the amount of time spent implementing, testing, and deploying complex BML across different CPQ environments.

Customers can use the CPQ Developer Toolkit to implement the continuous development and integration practices for their CPQ scripts and code. With the CPQ Developer Toolkit, you will be able to:

• Pull the latest Util and Commerce BML Libraries to your local systems
• Use your preferred tools to write BML code locally and deploy it to your CPQ sites
• Manage BML Libraries with your own source control tools (e.g. Git, CVS, SVN)
• Validate and test your changes directly with CLI
• Write, save, and execute unit tests for BML Libraries

CLI Command Help

The following table lists the most common CLI command options. You can use the "--help" parameter to show details for all Developer Toolkit CLI commands and their options.

Push Spec

Push specs are used to determine a set of files to upload from the local file system to the remote CPQ server as part of the push operation. Users can specify the path of individual files/folders to upload, OR, they can create a file with .push as the file extension to define a set of files/folders to upload. If the push spec or push spec file are not defined, the entire source directory containing the current directory is uploaded.

Suggested Workflow

The following image displays the suggested workflow when using the Oracle CPQ Developer Toolkit. CPQ recommends that you commit to source control from the beginning to help avoid conflicts and to drive your development process efficiently. If you're going to use Developer Toolkit with source control, set source control up as a part of your development process. For optimal results, Developer Toolkit and source control should be used together consistently. The workflow shows an admin/developer team approach for working on BML. It assumes that administrators and developers have the appropriate CPQ administrator access and the Oracle CPQ Developer Toolkit has been successfully downloaded and set up. If desired, steps six and seven can be fully automated by setting up a continuous integration process.

Unit Tests for BML (BMLT)

To support modular testing and development, CPQ Developer Toolkit introduces BML Unit Tests (BMLT) for Util and Commerce Libraries. Unit tests are written to ensure that BML code behaves as intended and they work similar to test scripts in the debugger.

• All test functions have a Boolean return, "true" for pass and "false" for fail. If a test fails, it will not run any further operations, such as save and deploy.

• Administrators must create a "_tests" sub-directory for each BML Library tested.
  • For Util BML Libraries: util/_tests
  • For Commerce BML Libraries: <Commerce Process>/<Main Document>/util/_tests

For example, oraclecpqo/transaction/util/_tests

• Unit Tests cannot be deleted from the server. Administrators can deprecate the unit tests by deleting the contents of the _tests file.

• The structure of a test function versus a standard util function is similar, with a few key exceptions:
  • All test functions have a return type of Boolean.
  • Test functions do not have parameters and do not allow importing attributes.

• To write unit tests for Commerce Libraries, developers can use the importtransactiondata() function. This function uses the BSID to load all buy-side transaction data into the BMLT.

Syntax: importtransactiondata(BSID)

• Unit Tests for Util functions with imported attributes are facilitated with the setAttribute() function

Syntax: setAttribute(attrVarName, attrValue)

• • attrVarName: A String specifying the variable name of the attribute whose value is to be set.
  • attrValue: A correct data type value to assign for the given attribute.

IMPORTANT: setAttribute cannot be used as a method outside of Unit test functions.

The Developer Toolkit enables source driven development, a robust developer experience, and modular testing and development. As a result, Oracle CPQ environments that leverage BML Util and Commerce Libraries will be easier to set-up, maintain, and extend.

• The source driven development allows administrators to pull code from their CPQ site to their local directory and associate it with their desired version control system. Administrators can use the latest collaboration technologies, such as Git to source control BML across the CPQ environment.

• The Developer Toolkit provides a powerful built-in command-line interface (CLI) to use for development and major operations such as testing and deployment. After pulling their code from CPQ, developers can write BML code using their favorite tools or Text Editors.

• The Developer Toolkit allows developers to save unit tests for BML libraries. The unit tests are similar to test scripts in the debugger and can be used to validate changes. Developers can write unit tests and use the CLI to run unit test cases, separately or along with the deployment.

Steps to Enable

Certified and Supported Environments

Certified Versions - The following application versions are certified for the CPQ Developer Toolkit.

System Requirement - JDK 11 or higher must be installed to use this tool.

Supported - Oracle CPQ supports the following clients for the Developer Toolkit.

1. MacOS 10.14.* with Z Shell and Mac Terminal
2. Windows 10.0*
3. Oracle Linux Server 7.4*

Code Editor and Version Control System

Developers can use any IDE or code editor to work on their BML code.

Version Control System

Developers can use any version control system of their choice. We recommend that you leverage Developer Toolkit with source control consistently, to help avoid conflicts and to drive your development process efficiently.

Install the CPQ Developer Toolkit CLI

Complete the following steps to install the CPQ Toolkit CLI.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Developer Toolkit CLI, in the Developer Tools section.
3. Select Click to Download.
4. Download the Developer Toolkit CLI:

• For Windows, select Download CPQToolkit-windows.zip
• For Linux or macOS, select Download CPQToolkit-unix.tar.gz

5. Extract the zip or tar files to your local working directory.
6. Add the CPQToolkit "bin" directory to your PATH variable.
7. Run the "cpq-toolkit –help" command to verify the CLI installation.

Tips And Considerations

• Limit the number of developers that can perform pull, save, or deploy commands directly to CPQ.
• Use your source control system to manage a master version of the site contents.
• Push specs should only include BML Library functions that the developer is currently working on.
• At a given time, only one developer should be working on a specific BML function or test.

JET Transaction UI

The following JET Transaction UI feature is available in Oracle CPQ 21A.

Unit Conversion Support for Float Attributes

Beginning in Oracle CPQ 21A, the JET Transaction UI supports float attributes with defined conversion fields. When a conversion class is associated with a float attribute, users can indicate which units they are using when setting attribute values. Customers can use one of the built in conversion classes or they can create their own. The conversion classes are sets of units of measurement with multipliers that will convert values from one unit type to another. Administrators create two attributes; one for input and another for output. The first attribute, which is associated with a conversion class, is the input attribute. The second attribute is the output attribute.

Length Unit Conversion Use Case – The input Float attribute is linked to a pre-defined length conversion class that allows the user to select whether the length is in inches, feet, yards, or any other unit included in the class. The output Float attribute contains the length in meters. The following image shows the conversion functionality.

1. In the first step, the user is hovering over the Length attribute that has Help Text enabled.
2. In the second step, the user enters a length of "7" and selects "Yards" for the unit of measure.
3. In the third step, the value for the Length in Meters attribute is converted.

Administrators can use Float attributes to convert defined input units to a specific unit of measure.

Steps to Enable

Select a Conversion Unit

Complete the following steps to view CPQ's pre-defined conversion classes.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click General Site Options in the General section.
3. Click Unit Conversions in the Features Settings section.

If you need to create your own conversion unit, refer to the Unit Conversions topic in the Oracle CPQ Administration Online Help.

Create an Input Float Attribute

Complete the following steps to create a Float Attribute with Conversion Fields.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition in the Commerce and Documents section.
3. Select Documents for the applicable Commerce process, and then click List.
4. Select Attributes for the applicable main or sub-document, and then click List.
5. Click Add.
6. Enter the Label and Variable Name of the attribute.
7. Choose the Float from the Attribute Type drop-down.
8. Click Add.
9. (Optional) If you want to provide user Help Text, click on the Edit button next to the Description field, enter the message you want to display to the user, and click Save. For the Length example shown above, the following Help Text message was added.

10. Set the remaining Main Information, Groups, and Validation fields as required. For more information, refer to the CPQ Administration Online Help Commerce Document Attributes topic.
11. Select the applicable Conversion Fields.
    1. For the Conversion Group, select the applicable conversion class. (e.g. Length)
    2. For the Conversion Unit, select the desired unit of measure for the output attribute. (e.g. Meters)

12. Click Apply or Update to save the attribute.

Create an Output Float Attribute

Complete the following steps to create an output Float attribute for the converted value.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition in the Commerce and Documents section.
3. Select Documents for the applicable Commerce process, and then click List.
4. Select Attributes for the applicable main or sub-document, and then click List.
5. Click Add.
6. Enter the Label and Variable Name of the attribute.
7. Choose the Float from the Attribute Type drop-down.
8. Click Add.
9. Set the remaining Main Information, Groups, and Validation fields as required. Refer to the Commerce Document Attributes topic in CPQ Administration Online Help for more information.
10. Do not set the Conversion Fields for the output Float attribute.
11. Click Apply or Update to save the attribute.

Create a Formula to Update the Output Float Attribute

Complete the following steps to create a formula to update the output Float attribute with the converted value.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition in the Commerce and Documents section.
3. Select Formulas for the applicable Commerce process, and then click List.
4. Add the Output Float attribute to the Attribute Name.
5. Add the Input Float attribute to the Formula.
6. Click the Add icon to save the formula.

Add Float Attributes to the Transaction UI Layout

Add both the input and output Float attributes to the Transaction UI. Refer to the JET Responsive Layout Editor topic in CPQ Administration Online Help for more information.

Tips And Considerations

• When using Commerce web services, the v11 Commerce Transaction REST APIs are required to support Unit Conversion for Float attributes.
• When an input attribute is placed in the Line Item Grid, it will be displayed as Read-Only. Users can edit the input attribute as normal through the Line Details, but not directly in the Line Item Grid.

Oracle CPQ Asset-Based Ordering

The following Asset-based Ordering (ABO) feature is available in Oracle CPQ 21A.

Support Business Time Zone for Asset-Based Ordering

The Oracle CPQ Ref App used by the ABO package stores the commerce start, end, and request dates as date-only format without timestamp and time zone, while asset start and end dates are stored with full timestamp information. In Oracle CPQ 20C and earlier, during the translation of the date information between commerce and asset, the commerce date is always based on the "0" hour of the server default time zone (usually GMT+0).

End users that are in the same time zone as the server default see the commerce asset date and time information consistently. However, when an end user is located in a different time zone than the server default and their user profile is set to display their local time zone, the conversion between the server time zone and the user's local time zone may transition midnight and cause the commerce date display to be different than the asset date display.

In Oracle CPQ 21A, an updated 21A ABO package provides a new administrator-defined business-level time zone setting called businessTimeZone. The business time zone is used, rather than the server default time zone, as the basis for all asset-related date and full timestamp translations. This provides administrators the ability to set a time zone that is more relevant to their business.

The updated package interprets the commerce date fields consistently during ABO processing based on the specified business time zone setting. End users may need instruction on how to interpret their user interface display of start, end, and request date fields in relation to the overall business time zone setting.

Steps to Enable

If you do not have an ABO package installed, you can apply the Oracle 21A ABO package to your Oracle CPQ 21A site.

Within the 21A ABO package, the abo_loadDefaultContext BML function has been enhanced to include the businessTimeZone setting.

Existing customers wanting to upgrade to the 21A ABO package can upgrade and merge their customization to the new package or review the text files provided in the 21A ABO package with their current files and make the necessary modifications. For more information about upgrading, refer to the Oracle CPQ 19B or later Asset-Based Ordering Implementation Guide.

Tips And Considerations

• The default businessTimeZone setting is GMT+0.

• Once set up, asset start and end dates are populated based on business time zone; therefore, changing the business time zone setting to a different time zone should be avoided. If a change to the business time zone is required, it must be carefully planned with detailed analysis regarding the impact to legacy data.

• Only an end user with the same time zone preference as the business time zone will see start and end date matching the business time zone on the asset user interface. End users in different time zones than the designated business time zone will see a different start and end date displayed for an asset based on that end user's time zone preference. End users need to be aware of how the date fields are displayed in relation to the overall company business time zone setting.

Key Resources

Refer to the Oracle CPQ 19B or later Asset-Based Ordering Implementation Guide for detailed information.

Oracle CX Sales Integration

Oracle CPQ 21A provides the following features that support Oracle's goal to provide superior cross-application CX solutions to customers.

REST - Export Lines Commerce Integration Type for CX Sales

Oracle CPQ 21A introduces the REST – Export Lines Commerce integration type to replicate and synchronize CPQ quote lines to Oracle CX Sales. In prior integrations quote line data did not exist on CX Sales, so users had to open one or more transactions to retrieve quote line information. This feature enables CX Sales users to search across multiple quotes to quickly retrieve the quote line data. In CPQ 21A, quote lines are synced back to CX Sales to provide visibility of the quote lines within CX Sales 21A. Additionally, the user-friendly attribute mapping UI allows administrators to drag and drop attributes to define integration mappings and eliminates the need to understand or edit XSL syntax. This integration supports the ability to integrate all quote lines, part lines, or root lines on an associated Commerce action. Root lines are models or parts without parent items and they are used to forecast revenue at a model level instead of a part level. Root line integration is useful for customers with large quotes to prevent performance issues when synchronizing a large number of quote lines.

The Quote Lines integration for CX Sales provides an efficient method to synchronize CX Sales quote lines to CPQ transaction lines to enable extensive search, reporting, and BI capabilities in Oracle CX Sales. The new searches provide data-driven information to support multiple company roles:

• Sales representatives can use this information to identify sales opportunities, direct a sales approach, and aid in discount decisions. They can also use this information to prompt customer follow-ups for status, product issues, availability issues, and renewals.

• Managers can evaluate appropriate discounts, measure product promotion marketing campaign results, focus sales team efforts, understand pricing sensitivity, and prepare sales reports.

• Customer service representatives can view order summaries and status to respond to customer inquiries.

• Site administrators can verify that integrations are working correctly. 

Steps to Enable

Complete the following steps to create a REST – Export Lines Commerce Integration for CX Sales.

IMPORTANT: The REST – Export Lines integration is only available when CX Sales is identified as the Integration CRM Partner.

1. Log in to Oracle CPQ and open the Admin Home page.

2. Click Process Definition, in the Commerce and Documents section.

3. Select Integrations from the Navigation drop-down menu for the applicable process, and then click List.

4. Click Add. 

5. Select REST – Export Lines, and then click Next.

6. Complete the fields in the Integration Information section.

   1. Name: Enter a name (i.e. label) for the integration.

   2. Variable Name: Enter a unique identifier. This cannot by edited after creation.

   3. Description: If required, enter a description for the integration.

   4. Timeout: If a value is not specified, this field will default to 5000 milliseconds.

   5. ID Field: Enter the documentVarName.attributeVarName that stores the ID field for the corresponding CX Sales salesOrderHeaders object. For the standard quote lines integration with Oracle CX Sales the values will be, transaction.oRCL_OSC_TransactionID_t

   6. Line Type Filter: Select one of the following options.

• Root Lines: Include only models or parts that do not have a parent item.
• Part Lines: Include only part items.
• All Lines: Include all root models, child models, and parts.

7. Complete the fields in the Endpoints section.

• MetaData URL: The endpoint to retrieve the metadata about the CX Sales attributes available for mapping for this integration. For the standard quote lines integration with Oracle CX Sales the values will be as shown below.

• Integration URL: The endpoint used to invoke the upsert quote lines operation. For example:

• Integration Request Headers: This field takes the headers to be passed in the request to the above integration endpoint. For the standard quote lines integration with Oracle CX Sales, this value will be Upsert-Mode:true.

• Batch Size: Batch Size is automatically set to the maximum of 500 quote lines to be integrated in a single invocation of the API endpoint. CPQ automatically handles the multiple invocations needed for larger quotes.

8. Click Add.

Attribute Mapping for CX Sales Quote Line Integration

Oracle CPQ 21A also introduces a new Attribute Mapping page that allows administrators to customize their CX Sales integration without the use of XSL. This page provides a user-friendly interface to map attributes. It supports text?based searches to find attributes and drag and drop functionality to add attributes. CPQ attributes are grouped by Transaction and Transaction Line levels. Transaction attributes are displayed first and have a blue sidebar. Transaction Line attributes are displayed after Transaction attributes and have a lavender sidebar.

The Attribute Mapping page displays the CPQ attributes on the left side of the page and the CX Sales attributes on the right side. The mapped attributes are displayed in the middle. Icons identify the attribute type and the attribute variable name is displayed when hovering over an attribute name. Administrators can add new attribute mappings and edit or delete existing attribute mappings.

The new Attribute Mapping page has essential pre-defined attribute mappings for new customers and allows CX Sales customers to customize their integration without the use of XSL.

Steps to Enable

New customers will have these mappings defined as part of the provisioned reference implementation. Existing customers will have a migration package to create this standard integration. Customers can complete the following steps to add new attribute mappings or edit the existing attribute mappings.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition, in the Commerce and Documents section.
3. Select Integrations from the Navigation drop-down menu for the applicable process, and then click List.
4. Click on the REST – Export Lines integration name.
5. Click Edit next to Request Mapping.
6. Click the Add Row icon or drag and drop an attribute to create a new attribute mapping row.
   1. Select the appropriate CPQ attribute on the left side.
   2. Select the appropriate CX Sales attribute on the right side.
   3. Click on the Apply icon or click outside the row to register the mapping.

7. To delete an attribute mapping, click on the delete icon.
8. To edit an existing attribute mapping, click on the edit icon.
9. Click Save to save changes, or Finish to save changes and exit the page.

Predefined CX Sales Quote Lines Integration Items

Oracle CPQ 21A provides new customers with predefined CX Sales integrations. Existing customers can import a migration package to implement the predefined integration content.

PREDEFINED CX SALES ATTRIBUTE MAPPINGS

The following table shows the predefined CX Sales predefined attribute mappings. An asterisk (*) precedes new CX Sales Reference Application attributes. Refer to CPQ Administration Online Help additional attribute information.

With limited implementation set up, customers can create quotes and the two sites can exchange information about quote lines created or updated in Oracle CPQ.

Steps to Enable

Predefined CX Sales integrations are provided in the CX Sales Reference Application image for new sites.

A CX Sales Reference Application migration package and implementation instructions will be provided on My Oracle Support for existing customers.

Web Services

The following Web Service features are available in Oracle CPQ 21A.

• Conversion Units for Float Attributes
• Expanded Domains for Commerce Dynamic Menus
• Developer Toolkit REST APIs
• Unit Conversion REST API
• User Management REST APIs

Conversion Units for Float Attributes

Commerce REST APIs prior to v11 did not support Float attributes with unit conversions for the JET Transaction UI. The v11 Commerce REST APIs provide support for complex objects for Float attributes when conversion units are defined. The following example shows the "length" Float attribute with value of "6" and the "ft" conversion unit.

The v11 Commerce REST APIs provide conversion unit support for float attributes.

Steps to Enable

Review the REST service definition in the REST API guides, available from the Oracle Help Center > your apps service area of interest > REST API. If you're new to Oracle's REST services you may want to begin with the Quick Start section.

Developer Toolkit REST APIs

Oracle CPQ 21A provides REST APIs to support the following Developer Toolkit functions: download, validate, save, and deploy site BML and BMLT (BigMachines Extensible Language Test) files. Refer to the Developer Toolkit and REST API topics in Oracle CPQ Administration Online Help or REST API Services for Oracle CPQ in the Oracle Help Center for additional information and examples.

Developer Toolkit - Download REST API

Use this endpoint to download zip file of site's BML and BMLT files.

• Endpoint: /rest/v11/adminMeta
• Method: GET

Developer Toolkit - Save REST API

Use this endpoint to validate and save BML and BMLT updates provided in the request body.

• Endpoint: /rest/v11/adminMeta/actions/save
• Method: POST

Developer Toolkit – Validate REST API

Use this endpoint to validate BML and BMLT updates provided in the request body.

• Endpoint: /rest/v11/adminMeta/actions/validate
• Method: POST     

Developer Toolkit – Validate and Save REST API

Validate and Save BML and BMLT payload data

• Endpoint: /rest/v11/adminMeta/actions/forceSave
• Method: POST

Developer Toolkit – Validate, Save, and Deploy REST API

Use this endpoint to validate, save and deploy BML and BMLT updates provided in the request body.

• Endpoint: /rest/v11/adminMeta/actions/forceDeploy
• Method: POST

Developer Toolkit – Validate and Run Tests REST API

Use this endpoint to validate and run BMLT tests.

• Endpoint: /rest/v11/adminMeta/actions/test
• Method: POST

Developer Toolkit – Validate, Save, Run Tests, and Deploy REST API

Use this endpoint to validate and save BML and BMLT updates provided in the request body, run BMLTs, and then deploy.

• Endpoint: /rest/v11/adminMeta/actions/deploy
• Method: POST

The Developer Toolkit REST APIs allow administrators to use web services to perform Developer toolkit functions.

Steps to Enable

Review the REST service definition in the REST API guides, available from the Oracle Help Center > your apps service area of interest > REST API. If you're new to Oracle's REST services you may want to begin with the Quick Start section.

Expanded Domains for Commerce Dynamic Menus

The "expandedDomains" property can be included in Commerce action and interact REST API requests to return domain information for specified dynamic menu attributes. The "expandedDomains" property is an array of field names that returns an "availableElements" array with expanded domains in the state object response.

Endpoint Sample

"expandedDomains" Request Sample

Dynamic Menu Response Sample

The "expandedDomainCriteria" property is used to specify document numbers and search text for sub-document dynamic menu attributes. It contains a map for two entries.

• nodes - The sub-document number of the dynamic menu attribute that is to be expanded. This field is required.
• searchText - The type in text with which the dynamic menu options should be filtered. This field is optional. 

NOTE: "expandedDomainCriteria" will be empty for all static menus and main document dynamic menus.

The following example shows a sub-document dynamic menu attribute request sample with additional search criteria.

The v11 action and interact Commerce REST APIs provide support for Commerce Dynamic Menus.

Steps to Enable

Review the REST service definition in the REST API guides, available from the Oracle Help Center > your apps service area of interest > REST API. If you're new to Oracle's REST services you may want to begin with the Quick Start section.

Unit Conversion REST API

The v11 Unit Conversion REST API, delivered in Oracle CPQ 21A, provides support for unit conversion for Float Attributes. Refer to the Unit Conversion REST API topic in Oracle CPQ Administration Online Help or REST API Services for Oracle CPQ in the Oracle Help Center for additional information and examples.

Get Unit Conversions

Use this endpoint to retrieve a list of conversion units. The REST API returns the following items for each conversion unit: unit variable name, identifier, group variable name, unit display name, and a link to the conversion.

• Endpoint: /rest/v11/conversionUnits
• Method: GET

The {"groupVarName":"value"} REST API endpoint query can be used to return conversion units for a specific unit class. For example, the following query will return the length conversion units.

The Unit Conversion REST API provides conversion unit support for Commerce Float attributes.

Steps to Enable

Review the REST service definition in the REST API guides, available from the Oracle Help Center > your apps service area of interest > REST API. If you're new to Oracle's REST services you may want to begin with the Quick Start section.

User Management REST APIs

Beginning in Oracle CPQ 21A, new and updated v11 REST APIs expand web service support to manage CPQ users. The following new User Management REST APIs are available. Refer to the User Management REST API topic in Oracle CPQ Administration Online Help or REST API Services for Oracle CPQ in the Oracle Help Center for additional information and examples.

Get Users

This endpoint returns all users accessible to the current user as JSON data or as a Zip file depending on Accept type passed in the request header.

• Endpoint: /rest/v11/users
• Method: GET
• Accept Header: application/json - Returns a JSON object (default application type) or application/zip - Returns a zip file

Get Company Users

This endpoint returns all users for the specified company accessible to the current user as JSON data or as a Zip file depending on Accept type passed in the request header.

• Endpoint: /rest/v11/companies/{companyName}/users
• Method: GET
• Accept Header: application/json - Returns a JSON object (default application type) or application/zip - Returns a zip file

Import Company Users

This endpoint is used to import users of specified company stored in a zip file. A task is initiated when you import a zip file and the task Id is returned in the response. You can use task Id to check the status of the task and the log file associated with the task through the child link in the response. If administration groups are enabled, then only users with User Administrator permission and Access to the Bulk Upload segment are allowed to import users.

• Endpoint: /rest/v11/companies/{companyName}/users/actions/import
• Method: POST
• Form-data: Key- file Value-zip file

Get User Access Permissions

This endpoint returns Product Family and Data Table folder access permissions for the specified user. Access permissions for a user will be available only when Admin Access Control is disabled.

• Endpoint: /rest/v11/companies/{companyName}/users/{userName}/accessPermissions
• Method: GET

Update User Access Permissions

This endpoint replaces the Product Family and Data Table folder access permissions of an existing user with new permissions passed in the request body.

• Endpoint: /rest/v11/companies/{companyName}/users/{userName}/accessPermissions
• Method: PUT

Get User Groups

This endpoint returns all groups assigned to specified user.

• Endpoint: /rest/v11/companies/{companyName}/users/{userName}/groups
• Method: GET

Update User Groups

This endpoint replaces all groups of an existing user with the groups passed in the request body.

• Endpoint: /rest/v11/companies/{companyName}/users/{userName}/groups
• Method: PUT

Get User Password Security Question

The endpoint returns the password security question for the specified user.

• Endpoint: /rest/v11/companies/{companyname}/users/{userName}/password
• Method: GET

Update User Password, Security Question, or Secret Answer

This endpoint is used to change the password, security question, or the secret answer of the current user.

• Endpoint: /rest/v11/companies/{companyname}/users/{userName}/password
• Method: PATCH

Bulk Update User Status

This endpoint is used to perform a bulk update of active and inactive users based on the criteria passed in the request body.

• Endpoint: /rest/v11/users/actions/bulkUpdate
• Method: POST

The v11 request and response structures for the following existing User Management REST APIs have major changes to provide behavior consistent with the CPQ User Administration UI. These changes also provide support for additional use cases, user access permissions, and user groups. Refer to the User Management REST API topic in Oracle CPQ Administration Online Help or REST API Services for Oracle CPQ in the Oracle Help Center for additional information and examples.

• Get Company User (GET) /rest/v11/companies/{companyName}/users/{userName}
• Create a Company User (POST) /rest/v11/companies/{companyName}/users
• Update/Create a Company User ( PUT) /rest/v11/companies/{companyName}/users/{userName}
• Update a Company User (PATCH) /rest/v11/companies/{companyName}/users/{userName}

The User Management REST APIs allow administrators to manage CPQ users using v11 web services.

Steps to Enable

Review the REST service definition in the REST API guides, available from the Oracle Help Center > your apps service area of interest > REST API. If you're new to Oracle's REST services you may want to begin with the Quick Start section.

Tips And Considerations

IMPORTANT:

• When integrating with an external application, the Export and Import User REST APIs are not supported via Oracle Integration Cloud Service (ICS) Oracle CPQ Adapter for REST API Services.
• CPQ updated the previous version of PUT operations for User Management REST APIs to comply with REST standards. Parameters that are not explicitly included in the request body are defaulted to the default value. This includes deselecting any selected Boolean properties, such as "User Administrator" and "Web Services Only". It will also clear any non-required user fields that are not specified.

IMPORTANT Actions and Considerations

PRE-UPGRADE CONSIDERATIONS

Modifications to Known Functionality

Before upgrading to Oracle CPQ 21A, we recommend you review the modifications to known functionality and plan accordingly.

• When adding a large number of records in a horizontal configuration array in JET UI, the response time is very slow and the page may become unresponsive. If this occurs, we recommend you convert the horizontal configuration arrays to vertical format.

• As previously announced beginning in Oracle CPQ 21A, Internet Explorer browser certification and support is discontinued as we transition from Internet Explorer to Microsoft Edge browser support.

• Beginning in Oracle CPQ 21A, we will support the current REST version and the two previous REST versions. Older (three versions back and earlier) REST versions may continue to function; however, Oracle will not address new issues that arise.

• Beginning in Oracle CPQ 21A, the currency decimal precision rounding behavior for JET UI and Document Designer is modified to always function as HALF_UP. Following an upgrade to CPQ 21A, Document Designer templates automatically deploy with this change. Previously, this behavior was set to HALF_ODD.

• Oracle CPQ 21A removed the JET toolbar wrapper around the Configuration actions conveyer belt element at the top of the JET Configuration UI. If you have created custom styling for Configuration actions inside the conveyor belt element or for the toolbar itself, refactoring is required to remove references to the (oj-toolbar) class.

Planned Changes to Supported Features

The following changes to supported features will be occurring in a future update. We recommend that you plan for these transitions.

• Beginning in Oracle CPQ 21B, we will discontinue support for low complexity password strength. This change will impact end users the first time they reset their passwords following the 21B upgrade.

• Beginning in Oracle CPQ 21B, we will end support for Lightweight Directory Access Protocol (LDAP) User Management.

• Document Engine, which is used to created proposals and submissions, is being deprecated. Customers need to recreate their existing DocEngine Templates with the Document Designer. Upon upgrade to Oracle CPQ 21C, customers will no longer have access to Document Engine administration for the editing of templates. They will, however, retain edit access to the raw XSL templates that Document Engine produced. We recommend that you do not create new documents using Document Engine and transition to Document Designer as soon as possible. To learn more about Document Designer, refer to the Document Designer Overview topic in the Oracle CPQ Administration Online Help.

• Configuration Page Templates are being deprecated. This administrative feature was not widely implemented. If you are among the customers that currently have configuration page templates in your environment you need to migrate to standard configuration flows. Beginning in Oracle CPQ 21C, customers will no longer be able to create and edit the configuration page templates. To learn more about Configuration Flows, refer to the Configuration Flows topic in the Oracle CPQ Administration Online Help.

• The Oracle CPQ shopping cart feature is being deprecated. The shopping cart displays the total number of items in the cart and the total cost for those items. Based on recent data, usage of shopping cart functionality among customers is low. If your implementation uses shopping cart, you will be receiving separate communication from CPQ Product Management to understand your use case and discuss potential alternatives. Upon upgrade to Oracle CPQ 21D, customers will no longer have access to the shopping cart feature.

Custom JavaScript

If customers have added custom JavaScript that leverages the Document Object Model structure or specific elements, classes or IDs, this customization should be thoroughly tested and may require refactoring. For more information about custom JavaScript, go to Style & Templates > JET JavaScript Customization in the Oracle CPQ Administration Online Help.

Migration

When using Import From Source or Connect To Destination to migrate content, both sites must use the same major update. The migration of content can only occur across minor updates within the same major update.

• "Major update" = Update 21A
• "Minor update" = Update 21A Patch 1

When using Migration Packages, content from 19A and forward can be uploaded to the latest site version.

Resolved Known Issues

For information on bugs fixed in Update 21A, refer to the Oracle CPQ 21A Resolved Known Issues document available on My Oracle Support and the Oracle CPQ Administration Online Help.

Translation

For some system-defined messages and components, strings were removed and others added in Oracle CPQ 20C. If you have created your own implementation-specific translations of system-defined strings, some of these strings may no longer appear. Other strings may appear in English. The strings appearing in English are new and require translation.

Most of these messages and components are on the Administration side of Oracle CPQ, but you should review both your end user and administration pages before deploying your updated installation to confirm that all strings appear in the desired language.

Translation Status

Oracle CPQ supports the consumption of both single and multi-byte character sets. Submit a service request on My Oracle Support to enable your site for a new language.

For the following languages, a translation of the Oracle CPQ user interface is available for both the platform and the reference application:

• Chinese (Simplified) [China]
• Chinese (Traditional) [Taiwan]
• Czech [Czech Republic]
• Danish [Denmark]
• Dutch [Netherlands]
• English
• Finnish [Finland]
• French
• French [Canada]
• German
• Hungarian [Hungary]
• Italian
• Japanese [Japan]
• Korean [South Korea]
• Norwegian (Bokmål) [Norway]
• Polish [Poland]
• Portuguese [Brazil]
• Romanian [Romania]
• Russian [Russia]
• Spanish (Worldwide)
• Swedish [Sweden]
• Turkish [Turkey]

POST-UPGRADE CONSIDERATIONS

Upgrade and test all test instances on Oracle CPQ 21A before upgrading to production.

Browser Support

CPQ Cloud supports all browser versions that meet the criteria of the Oracle Software Web Browser Support Policy.

If you experience issues using a supported browser version, open a ticket on My Oracle Support to resolve the issue. If an issue arises when using a supported browser, use a certified browser version until the delivery of a fix. Certified browsers are selected based on current market share and thoroughly tested to work with the current version's standard functionality.

Certified Browsers

Windows

• Google Chrome 85.x
• Mozilla Firefox 80.x
• Microsoft Edge 85.x

Mobile Devices

• Apple iPad iOS 14.x, Safari browser
• Apple iPhone iOS 14.x, Safari browser

IMPORTANT:  - Beginning in Oracle CPQ 21A, Internet Explorer browser certification and support is discontinued. - Compatibility issues with the selected browsers may exist when sites contain additional JavaScript, alternate CSS, or other custom functionality. Customizations may require add-on work. Contact My Oracle Support to determine the availability of workarounds and minor fixes.

Salesforce Integration Support

Oracle officially supports version 8.1, 8.2, and 8.3 of the Oracle CPQ Connector for Salesforce. We also continue to support version 7.2 of the legacy Oracle CPQ Commerce Integration.

Training

Please refer to the release documentation for all versions between your current version and the version to which you are upgrading to see all new functionality, resolved known issues, and functional known issues.

Refer to the Oracle CPQ Administration Online Help to become familiar with the new features introduced in Oracle CPQ 21A. For additional help, see My Oracle Support.

Verify any information not explicitly mentioned in this document as supported by the software against the product help for Oracle CPQ 21A.

Additional Information

For more information on Oracle CPQ, visit the Oracle CPQ Documentation site.

Disclaimer

The details in this document are provided for high-level informational purposes only and are not intended to function as a specification or to replace the Online Help. Upgrading to a subsequent release may require the re-deployment of Commerce Processes, Configuration, or global function settings. Modifications to integration XSL files or APIs may also be required.