Commerce Actions
Overview
Commerce actions trigger events within documents to occur. The Commerce system creates a default set of actions for use in each document, and generates additional actions when Commerce documents include certain attribute types.
Both main documents and sub-documents can consist of system-generated actions as well as user-defined actions, created based on supported action types. Because actions are required to carry out operations based on the business logic, they are comprised of components.
All Commerce actions are administrated from the Admin Actions page. You can customize system-generated actions by modifying action labels and creating action rules.
In addition to the system-generated action defaults, you can also create custom actions for the purpose of saving document data, directing the system to a different page, offering print or email options, and showing the change history for a document.
Users usually perform Commerce actions, but timers can be set up so the system can automatically perform Commerce actions after specified periods of time.
Displaying Actions on the Transaction UI
Buttons signify actions like send, respond, update, and so on. The Buttons display type is available for the Legacy Transaction UI and the JET Transaction UI.
Actions are displayed in an Action drop-down menu on the JET Transaction UI.
Notes
- The Actions Menu display type is not available on the Legacy Transaction UI.
- Only one display type is allowed for an action or sticky action toolbar, administrators can display Buttons or an Actions Menu, but not both.
For more information on displaying action on the Transaction UI, refer to Toolbars and Sticky Action Toolbars and Actions sections for the JET Responsive Layout Editor or the Legacy Desktop Layout Editor.
FullAccess users can define actions in a Commerce Process. All the action types below are common for the main document and sub-document.
Add from Catalog (Available for Main Document and Sub-Document)
Allows the user to add line items to a Transaction from the main document. Add from Catalog actions take a user to the home page from where the user can navigate to specific catalog items/parts/favorites and add desired items to the Transaction.
Destination rules can be set for Add from Catalog type actions. Multiple Add from Catalog type actions can be added to the same document to offer users different catalog destinations within the application.
This action has different options for the main document and sub-document:
-
Main Document: Here the tab contains a simple URL field. The valid value for the URL field is the relative path to any page on the Oracle CPQ application.
For example: On the main document, you can use an Add from Catalog action as a quick link that always goes back to the same page, either a page in the catalog or a Favorites List page.
-
Sub-Document: Here the tab contains a simple URL field as well as an advanced function option.
On sub-documents, you can set up advanced destination rules for Add to Catalog type actions. This has the added benefit of enabling you to link the Add from Catalog action to different catalog pages depending on the subsystem components that still need to be added to the document.
The valid value for the URL field is the relative path to any page on your application.
The advanced function is usually used to display the action in the line item section of the main document.
Add from Catalog type actions created for sub-documents should be added to the line item group for the main document only. They should not be added to the sub-document view.
Back (Available for Main Document and Sub-Document)
Used to take the user back, depending on which document they are on. If the user is on the sub-document, clicking Back will take the user to the main document.
Copy Line Items (Available for Main Document)
The Copy Line Items action can be defined only for the main document. This action enables users to make one or more copies of one or more line items (configured and non-configured) at a time.
It is a Modify action. However, unlike other modify types actions, the Copy Line Item Action has an Initialization tab and has no Integration tab.
Note: When a Copy Line Items action is added to the JET UI Line Item Grid, the Copy action is not available when the Select All function is used.
- As a workaround users can select the first item in the Line Item Grid, navigate to the last item, and then press the Shift key while selecting the last item in the Line Item Grid.
The Copy Line Items action is available with the Select All function when the Copy action is outside the Line Item Grid.
Copy Line Items Order of Operations
- Click Copy.
- The form Data is saved as is (along with the line item group attribute values and other main document parameters on the form/document JSP page).
- Run Initialization.
- Run Modify tab of Copy Line Item action.
- Run Advanced Modification of Copy Line Item action.
- Run Advanced Validation of Copy Line Item action.
- Set quantity to
1
within the Copy Line Item action Initialization tab. -
Select the option Default to Quantity in the General tab to specify that the Number of Copies field in pop-ups is pre-populated with the desired quantity.
- When the user selects the line item of quantity "n" and then clicks Copy Line Item, a pop-up with the number of copies with a pre-populated value "n" is displayed to the user.
- When the user clicks Copy, "n" copied line items with quantity 1 ( Initialization tab will initialize the quantity to 1) is produced. If n=1, then the Copy Line Items pop-up does not appear.
Implementing Copy Line Items in an Integrated Process
To successfully implement the Copy Line Item action in an integrated process, the user must set the opportunity's line item ID to Revert to Default in the Initialization tab of the Copy Line Item action. This is done to ensure that the copied line items are added to the Salesforce opportunity with the unique line item ID's.
- Set the maximum number of copies in the General tab for this section.
- When copying a configured line item, both mandatory and non-mandatory recommended items are copied, along with configured line item.
- If the maximum number of copies is higher than 1, a pop-up appears after clicking Copy Line Item. The user can specify the number of copes in this pop-up. You can also specify that the Number of Copies field in the pop-up be populated with the quantity of the selected line item.
- You can map the line item attribute to the pop-up in the Admin Columns page.
- Recommended items are copied, maintaining the ratio of the configured line item (model) to the recommended items.
-
You cannot copy a recommended item separately.
Example: Assume that a model M1is associated with a dozen of part P1 (recommended item). If you make two copies of M1, then you will get two additional line items of M1 and two additional dozens of part P1
- This action does not allow users to copy non-configured line items (parts) if they do not have access to the required Price Books.
Copy To Favorites (Available for Main Document
The Copy to Favorites is a special action to copy selected line items from the Transaction to the Favorites List.
The Copy To Favorites action is available only on the main document. It is a special action that is used to copy selected line items from the transaction to the Favorites List. From here the user can add it back to the Transaction.
Beginning in Oracle CPQ 22A support has been added to invoke a Commerce Transaction when reconfiguring an item from the Favorites List. The Commerce invocation action will be visible on the Configuration page when a Favorite is reconfigured. Prior to this feature implementation, users would need to save the reconfigured Favorite and exit Configuration, and then go into Commerce to add the Favorite to a quote. Note that if you are reconfiguring a Favorite and you invoke a Commerce Transaction instead of saving the Favorite, the changes you made are not saved to that item in the Favorite List.
Display History (Available for Main Document and Sub-Document)
Used to extract the change history for a document. This action requires an XSL format file that controls how and which changes appear.
XSL Views: The Display History action contains a special tab called XSL Views tab. The XSLs displayed on this tab come from the Printer Friendly/History XSL Views section. This action can be associated with one or more XSL views. If multiple XSL views are made available with the action, users can select the form they want to use.
E-mail (Available for Main Document and Sub-Document)
Enables users to access email-friendly document formatting. It is a Modify action and hence has all characteristics of a Modify action, including document views, integration and the modify tab.
- XSL Views Tab:
The Email action contains a special tab called the XSL Views tab. This action type must be used in conjunction with an XSL format file that contains the email-friendly format you want to associate with that particular Email action. The XSLs displayed on this tab come from the Printer Friendly/History XSL Views section. This action can be associated with one or more XSL views. If multiple XSL views are available, users can select an email form from the ones available. - Email Fields Tab:
The Email action also contains a special tab called the Email Fields tab. Email field rules instruct the system to auto-populate fields in the Email pop-up window. With the fields populated by the system, users can sent out emails quickly. Email field rules apply to the Email Commerce action only.
Export Attachment (Available for Main Document and Sub-Document)
The Export Attachment action enables a user to add the proposal (PDF) to the related partner opportunity (only on an integrated application). It is a Modify action and hence has all characteristics of a Modify action including document views, integration, and the modify tab.
- XSL Views Tab:
This action contains a special tab called the XSL Views tab. This action type must be used in conjunction with an XSL format file that contains the printer-friendly format you want to associate with that particular action. The XSLs displayed on this tab come from the Printer Friendly/History XSL Views section. This action can be associated with one or more XSL views. If multiple XSL views are made available with the action, users can select the email form they want to use.
Export Line Items (Available for Main Document)
The Export Line Items action enables users to download the Transaction Line Items with all the attributes currently accessible to them. The export includes all their viewable information from the Line Item Grid as determined by their user profile settings.
Upon executing the Export Line Items action, users can download the Transaction Line Items with all the attributes currently accessible to them. The export includes all their viewable information from the Line Item Grid as determined by their user profile settings. If a Line Item Grid column is hidden from the end user by a Commerce hiding rule or a Line Item Grid view filter, that data is exported.
Note: This feature is only available with JET Transaction UI.
Import Line Items (Available for Main Document)
The Import Line Items action enable users to export line item data to a Microsoft Excel (XLSX) file on the user's local computer. With this file users can run formulas and calculations on the Transaction data quickly and easily.
Upon executing the Import Line Items action, users can import line item data from a modified CPQ-exported Microsoft Excel (XLSX) file. This feature leverages Microsoft Excel with Oracle CPQ Commerce to add new or modify existing transaction line data. End users can perform analysis and approval activities before importing line item modifications into the CPQ Transaction. Independent line items or unconfigured Model line items can be added to the CPQ export XLSX file. The export XLSX file provides necessary identification data to determine modifications to a pre-existing CPQ Line Item.
Note: This feature is only available with JET Transaction UI.
Lock (Available for Main Document)
The Lock action enables users to lock a Transaction for situations when a Transaction owner needs to freeze activity on the Transaction and prevent any further changes. For example, prior to submitting a quote for approval or when finalizing a quote and converting it to an order. The Lock action is a Commerce action type, which is available on main documents. When a Transaction is locked, only the locking user can make changes. Other users are only able to view the Transaction in read-only mode.
Refer to Transaction Locking for more details.
Note: The Lock action is not automatically available on the JET Transaction UI. Administrators must create a Lock action and then add the action to the Commerce JET Responsive Layout.
Modify (Available for Main Document and Sub-Document)
Most common type of user-defined action. A Modify action can be entirely customized to suit the FullAccess user's needs.
Print (Available for Main Document and Sub-Document)
Enables users to access printer-friendly forms for printing.
It is a Modify action and hence has all characteristics of a Modify action, including document view, integration and the Modify tab.
XSL Views: The Print action contains a special tab called the XSL View tab. This action type must be used in conjunction with an XSL format file that contains the printer-friendly format you want to associate with that particular Print action. The XSLs displayed on this tab come from the Printer Friendly/History XSL Views section. This action can be associated with one or more XSL views. If multiple XSL views are available, users can select a print form from the ones available.
Refresh (Available for Main Document and Sub-Document)
This action refreshes the current Transaction or Transaction Line with last saved data; the refresh action removes the existing values and replaces with the last saved data.
Submit (Available for Main Document)
The Submit action set is a series of Modify actions in Commerce that are essentially sub-actions of Submit. The Submit action set is comprised of Submit, Request Approval, Approve, Reject, and Revise.
Refer to Submit Action Set for more details.
Unlock (Available for Main Document)
This action enables users to unlock a locked Transaction.
Refer to Transaction Locking for more details.
Note: The Unlock action is not automatically available on the JET Transaction UI. Administrators must create an Unlock action and then add the action to the Commerce JET Responsive Layout.
Version (Available for Main Document)
This action is mainly used in Oracle CX Sales integration, to version Quotes.
For more information, see the topic Oracle CX Sales Integration.
System-Generated Commerce Actions
Action Name | Variable Name | Description |
---|---|---|
Autofill |
_auto_fill_action |
Automatically links data from the Accounts database to the main document. Users must enter an ID into the Customer ID field. This action is automatically created (or removed) when a Customer ID attribute field is created (or removed). |
Browse |
_browse_action |
Dialog box pops up that allows users to search the Accounts database for a customer record. When a user clicks Populate, after selecting an accounts record, the corresponding accounts record data is auto-populated into the mapped account fields in the main document. This action is automatically created (or removed) when a Customer ID attribute field is created (or removed). |
Change Currency |
_change_currency |
Users can change the currency of the transaction to a selected currency from a drop-down. This action is automatically created when a main-document is created. This action will only appear to users on transaction that don't contain line items. |
Create [next main document] |
_create_<next_main_document_variable_name> |
Users can move on to the next main document in the Commerce Process. This action automatically appears with all main documents. |
Open [sub-document] |
_open_<sub_document_variable_name> |
Users can view product details on a line item within the sub-document. This action is automatically created when a sub-document is linked to a main document. |
Refresh Quote |
refreshQuote |
Pulls data from the server, but does not save it. While doing so, it will not perform a modification. |
Remove [sub-document] |
_remove_<sub_document_variable_name> |
Users can remove the products that are displayed on the sub-document. This action is automatically created when a sub-document is linked to a main document. |
Select Alternate Address |
_select_alternate_address_action |
Host company users can associate an alternate Accounts address with a Transaction. The system only displays this action when the Customer ID field associated with a Transaction has multiple addresses. |
Update Line Items |
_update_line_items |
Users can modify line item data on a main-document, then save the changes. This action is automatically created when a sub-document is linked to a main document. |
View |
_view_crm_action |
Allows suppliers to view an accounts profile when an ID appears in the Customer ID attribute field. This action is automatically created (or removed) when a Customer ID attribute field is created (or removed). |
Action Name | Variable Name | Description |
---|---|---|
Create [sub-document] |
_create_<sub_document_variable_name> |
Users can create another sub-document. The system automatically creates the Create action if there is another sub-document attached to the next main-document in order. |
Recalculate |
_calculate_price_action |
Users can re-calculate pricing data after a pricing field is altered. This action is automatically created when a Price Attribute Set is added to a sub-document. |
Reconfigure |
_reconfigure_action |
Users are returned to the Model Configuration page to make changes to line items. This action is automatically created when a Configurable Attribute Set is added to a sub-document. |
Standard Process Commerce Actions
Beginning in Oracle CPQ 23B, the Standard Process is delivered for new Oracle Sales integrated site installations and is the default process when creating a new Commerce process There is no change to existing Commerce process definitions The Standard Process actions come with predefined functional logic that is ready for customers' use If required, seeded logic can be overridden by administrators to incorporate their customization logic.
Note: Standard Process actions cannot be deleted, but the action functions can be viewed, overridden, and easily returned to their default values. Most Standard Process actions can be removed from the layout if a customer does not want to use them.
Components of an Action (i.e. Tabs)
You can create destination rules for the Modify and Add from Catalog type actions.
Standard Process actions have predefined functional logic for destination options. If required, seeded logic can be overridden by administrators to incorporate their customization logic.
- To view or customize destination options, check the Override Standard Destination option, and then click Apply.
- To return to the standard destination options, uncheck the Override Standard Destination option, and then click Apply.
Add from Catalog Action
This action supports both simple and advanced destinations. These destinations are specified with the use of URL. The user can pass information from commerce to the catalog by appending the data to the query string of the URL.
Destination | Description |
---|---|
Simple Destination | This option allows you to hard code a URL. |
Define Destination Rule | This option allows you to write an advanced function that returns a string. The string that is returned specifies the destination URL. The inputs available to the Advanced Destination are system variables, main document and sub-document attributes. The Advanced Destination can also call commerce and utils library functions. |
Modify Action
Options | Description |
---|---|
Parent Page |
Upon clicking the action, the user will be taken to the top level page. Example: on a Modify action called Save on the main document; the destination could be set to the parent page. Upon clicking this action, the user is taken to the top level page.. |
Same Page |
Upon clicking the action, the user will remain on the current page. Example: on a Modify action called Save on the main document; the destination could be set to same page. Upon clicking this action, the user would remain on the current document. |
Custom Destination |
Upon clicking the action, the user will be taken to the URL specified in this field. A valid value for this field is the relative path to any page on the Oracle CPQ application. In addition, this field may be a complete URL for a destination external to the Oracle CPQ application. Example: The value |
External Object ID Attribute |
Upon clicking the action, the user will be punched-in to the appropriate object on the partner site. A valid value for this field would be the variable name of the attribute which stores the partner object Id information. Example: If a Commerce attribute with variable name |
Define Destination Rule |
Upon clicking the Define Function action, the user will be taken to the URL returned by running a BML function. The valid value return value for this function is a string. Any URL whose relative path is a page on the Oracle CPQ application would be a valid return value. Example: The value |
Close Parent Window |
Upon clicking this action, the current embedded Transaction will close and the user will be taken to the parent site. Using this method provides the following benefits:
|
Rules-Based Destination using an Advanced Function
A destination script can be used to send an Add from Catalog action to one page or another. This script appends the appropriate model name into a URL string, which is returned as the destination link. Example:
model_name=""; for a in quote_detail { if( a._document_number == _system_current_document_number ) { model_name=a._model_name; } } if( model_name == "Big Pump" ) { model_name = "Big%20Septic%20Tank"; } if( model_name == "Big Septic Tank" ) { model_name = "Big%20Pump"; } return "acme.bigmachines.com/commerce/new_equipment/products/ model_configs.jsp?segment=Mega%20Pumps&product_line=Gamera%20Pumps%20and%20Tanks&model=" + model_name;
Creating Destination Rules for a Modify Action
-
Select the radio button beside the desired Destination Options.
Options Description Parent Page Upon clicking the action, the user will be taken to the top level page.
Example: on a Modify action called Save on the main document; the destination could be set to the parent page. Upon clicking this action, the user is taken to the top level page..
Same Page Upon clicking the action, the user will remain on the current page.
Example: on a Modify action called Save on the main document; the destination could be set to same page. Upon clicking this action, the user would remain on the current document.
Custom Destination Upon clicking the action, the user will be taken to the URL specified in this field. A valid value for this field is the relative path to any page on the Oracle CPQ application. In addition, this field may be a complete URL for a destination external to the Oracle CPQ application.
Example: The value
/commerce/buyside/commerce_list.jsp
would be valid for the custom destination, as the user will be taken to their Favorites page.External Object ID Attribute Upon clicking the action, the user will be punched-in to the appropriate object on the partner site. A valid value for this field would be the variable name of the attribute which stores the partner object Id information.
Example: If a Commerce attribute with variable name
partner_opportunity_id
contained the partner opportunity ID, this attribute variable name would be in the Partner Object Id attribute field.Define Destination Rule Upon clicking the Define Function action, the user will be taken to the URL returned by running a BML function. The valid value return value for this function is a string. Any URL whose relative path is a page on the Oracle CPQ application would be a valid return value.
Example: The value
/commerce/buyside/commerce_list.jsp
would be valid, as the user will be taken to their Favorites page.Close Parent Window Upon clicking this action, the current embedded Transaction will close and the user will be taken to the parent site. Using this method provides the following benefits:
- Simplifies integration by removing dependency upon the "Return To Oracle CX Sales" BML script, which required administrators to specify and maintain multiple return URLs.
- Improves the user experience by retaining user context when a user is directed back to Oracle CX Sales from CPQ. Previously the web page was refreshed to generic return URL, and the user's navigation history was lost.
- Click Apply to save changes. Click Update to save changes and return to the Actions List page. Click Update and New to save changes and create a new action. Click Back to return to the Actions List without saving changes.
- If desired, select Translations: Oracle CPQ content and product templates can be translated into the following languages: French, German, and Spanish.
Creating Destination Rules for an Add from Catalog Action
- Click the Destination tab.
-
Select the radio button beside the desired Destination Options.
Destination Option Description Simple Destination Used to hard-code a specific destination page, either a page in the catalog or the Commerce List page. Must enter the destination URL. Supports a single destination page. Define Destination Rule Used to define rules that instruct the system where to take the user based on a condition. Supports different destinations. Click Define Function. Can pass attribute values with a Reconfigure action. - Select one of the following:
- Translations: Oracle CPQ content and product templates can be translated into the following languages: French, German, and Spanish.
- Apply: saves changes and remains on the page.
- Update: saves changes and returns to the Document List page.
- Back: returns to the Document List page without saving changes.
Populating a Multi-Select Menu in Configuration
The values in all caps should be replaced accordingly. CONFIG_ATT_VARIABLE_NAME=VALUE
should be used for the configuration attribute(s) that you want to set. To add multiple attributes, it should be delimited by "&".
http://yourcompany.bigmachines.com/commerce/new_equipment/products/model_configs.jsp?
segment=SEGMENT_VARIABLE_NAME&product_line=PRODUCT_LINE_VARIABLE_NAME&model=MODEL_VARIABLE_NAME&CONFIG_ATT_VARIABLE_NAME = VALUE&_variable_name_punchin=true
To set a multi-select menu, the values in VALUE
should be separated by a ~
(tilde).
Example: CONFIG_ATT_VARIABLE_NAME = VALUE1~VALUE2~VALUE3~VALUE4
The Document Views tab allows the FullAccess user to control the display of an action to users in different steps of the transaction. The FullAccess user can make the action active or inactive in a certain step to a particular participant profile.
The General tab is the only tab that is common to all action types. It holds action information such as Label, Variable Name, Modifications and Validations.
Element | Option | Description |
---|---|---|
Label |
Text label that is displayed on the action button. |
|
Variable Name |
Unique required field identifying the action in rules. The Variable Name field populates automatically. Variable names can only contain alpha-numeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only. |
|
Description | Description of the action. | |
Action Icon | Icon that is displayed on the Transaction button. | |
Show Loading Dialog |
|
This option turns on or off a loading dialog on the commerce side when the user clicks on the action. The image and text for the loading dialog can be customized in the site settings. |
Action Timeout |
Timeout Threshold in minutes |
Administrators can set Timeout Thresholds on individual Commerce actions. The specific Commerce action Timeout Threshold setting takes precedence over the general Commerce setting. This allows the administrator to isolate performance issues on a single Commerce action. |
Execute Action if Associated Integrations Timeout |
|
This option specifies if an action will execute if an Integration associated in the action Integration tab times out. |
Run Validation Before Modify |
|
This feature allows administrators to set validation rules to run before Advanced Modify. If validation fails, an error message is generated and associated integrations will not occur. This prevents integrations from being triggered before validation occurs. |
Layout Path | Button that opens up the Layout Editor located on the main document. | |
Advanced Modify- Before Formulas |
|
Advanced modification refers to an action’s capability to modify attribute values in the current document using an advanced function when the user clicks on the action. When this option is selected, the advanced modification will be run before the formulas created in Formula Management are used. |
Override Standard Advanced Modify-Before Formulas |
This option is displayed for Standard Process actions.
|
|
Advanced Modify- After Formulas |
|
Advanced modification refers to an action’s capability to modify attribute values in the current document using an advanced function when the user clicks on the action. When this option is selected, the advanced modification will be run after the formulas created in Formula Management are used. Advanced modification is run at the end and therefore can override the value set by an attribute’s modify tab. |
Override Standard Advanced Modify-After Formulas |
This option is displayed for Standard Process actions.
|
|
Advanced Validation
|
|
Advanced validation refers to an action’s capability to validate the attribute values in the context of the current document and its associated parent/ child, when the user clicks on the action. Example: user can validate an attribute on a sub-document using an advanced validation function on the main document and vice-versa. Basic data type validation is always done for all attribute types. The system supports the following types of validation settings for Commerce actions:
|
Maximum Number of Copies |
Only available for Copy Line Items action. Specifies the maximum number of copies a user can make. If you choose a number greater than one, a pop-up appears and the user can input the desired number of copies. The FullAccess user can map the attributes that are displayed on the pop-up by selecting Display in pop-up for Copy Line Item in the Admin Column page for Line Item Columns. |
|
Default to Quantity |
Only available for Copy Line Items action. If the FullAccess user selects this option, then the number of copies field in the Copy Line Item pop-up is pre-populated with the quantity of the selected line item(s). If the quantity of the selected line items is greater than the maximum number of copies specified by the FullAccess user, then the Number of Copies field is pre-populated with the maximum number of copies. |
-
Defining an advanced modification allows you to change the values of multiple attributes at the same time when a particular action is clicked.
Example: it will return values from a Commerce Library Pricing Function, when a user clicks Save, Submit, or Update Line Items. This allows you to create the price logic once and run it on multiple actions.
-
Defining an advanced validation allows you to display an error message if the user has clicked an action, but has entered something incorrectly.
Example: you could write a BML script that has an error message reading- "Line Item 2 exceeds the maximum allowable discount."- based on your particular parameters.
The Integration tab (displayed only if the site is integrated to a partner) determines the order in which data is exchanged between Oracle CPQ and a partner application. The order in which the integration XSLs are specified in this tab determines the order in which data is either sent to or received from the partner.
The Modify tab is available for all 'Modify’ type actions (system-generated or user-defined). This tab controls the manner in which a transaction gets its data; it allows you to manipulate the values in the attributes by specifying behavior in this tab. The Modify tab contains a list of all attributes available in the current tab with five options for each attribute.
Modify Behavior for Standard Process Actions
Standard Process actions come with standard settings and values for the modify tab. These values and settings can also be overridden and returned to the standard values by removing the override.
- To customize standard defaults, check the Override Standard Modify option, and then click Apply.
- To return to the standard defaults, uncheck the Override Standard Modify option, and then click Apply.
Using the Modify Tab to Set Your Behavior
- Click the Modify tab.
-
Select one of the following actions for each listed Attribute Name:
Action Description Define Function This option implies that the user must define a function that calculates the attribute value. Click Define after selecting the radio button. Use the Script Editor to create a function that sets the attribute value. You can use this option to determine current system variables, such as the currency conversion rate or system date. Use Specified Value This option implies that the attribute will get its value specified in the corresponding field. Enter a value in the value field next to the radio button. Leave Value Unchanged It implies that the attribute will retain its current value, whether its a user input or system defined. Revert to Default This option implies that the attribute value will be reset to its default value. Save from Form This is the default option. This option implies that the attribute will always retrieve its value from the user input on the commerce side. - Select one of the following:
- Translations: Oracle CPQ content and product templates can be translated into the following languages: French, German, and Spanish.
- Apply: saves changes and remains on the page.
- Update: saves changes and returns to the Document List page.
- Update and New: saves changes and creates a new action.
- Back: returns to the Document List page without saving changes.
When setting modify rules for the Autofill type Commerce action, the options set on the Modify tab have a higher precedence than mapping rules set on the Mapping tab. To force the system to use mapping rules for auto-filling fields instead of modify rules, use the Leave Value Unchanged setting. If this setting is used and mapping rules are not available for a field, then the system populates the field using the attribute's default value.
You can configure all listed attributes the same way by choosing an option and selecting the Select All radio button at the bottom of the column.
Commerce action performance analysis was introduced in Oracle CPQ 19A to help customers identify potential performance hindrances. Beginning in Oracle CPQ 20B, the performance analysis will include the run-time for the action's BML, including the library functions and select BML functions for the specified transaction or transaction line. The performance analysis shows elapsed time for processing-intensive elements of a Commerce action's BML. This feature allows the administrator to troubleshoot common performance complaints, such as "the system is slow when I save my quote". This feature can also be used to benchmark BML performance before and after implementing a script change.
For example: The following image displays the performance analysis for the Save action.
- XSL Views: These action types must be used in conjunction with an XSL template file to produce a commerce side output. Such actions can be associated with one or more XSL views. If multiple XSL views are available, users can select an XSL template from the ones available. The XSL views option applies to print, email and display history actions; it enables you to support custom forms and page displays using XSL and XSL-FO. XSL Views are usually associated with the following action types:
- Display History
- Export Attachment
- Email Fields: Email actions contain a special tab called Email Fields. Email field rules instruct the system to auto-populate fields in the Email pop-up window. With the fields populated by the system, users can send out emails quickly. Email field rules apply to the email Commerce action only.
-
Mappings: Available only for actions related to the accounts section. Account fields and commerce attributes are mapped in this tab. When the user selects a customer account ID and clicks on a relevant action, the mapping specified in the respective action will populate the commerce attributes with data from the corresponding accounts fields. Mapping rules are used to link data from one document to another in the same process, or from the Account database to a commerce document. Example: use mapping rules to link Account customer records to a commerce document's ’Bill To/Ship To’ fields.
Mapping rules have a higher precedence than an attribute's default value, however, they have a lower precedence than Modify rules. To force the system to use mapping rules when a user performs an Autofill or Select Address action, use the Leave Value Unchanged setting on the Modify tab.When a user performs an Autofill, Browse or Populate action, the system uses the mapping set up for the Autofill action. When a user performs a Select Address action, the system uses the mapping set up for the Select Address action.
Administration
Adding Commerce Actions
- Click Add at the bottom of the Actions List page.
- Enter a Name. This field will be used to link back to edit the action.
-
Enter a unique Variable Name.
The Variable Name field populates automatically. Variable names can only contain alpha-numeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only.
- Select your desired Action Type from the drop-down.
- Click Add to save changes and open Admin Action editor or click Cancel to return to Document List without saving changes.
- Edit the tabs available. Refer to the Tabs section above.
- Select one of the following:
- Translations: Oracle CPQ content and product templates can be translated into the following languages: French, German, and Spanish.
- Apply: saves changes and remains on the page.
- Update: saves changes and returns to the Document List page.
- Update and New: saves changes and creates a new action.
- Back: returns to the Document List page without saving changes.
The new action appears in alphabetical order on the Actions List page.
Cloning Commerce Actions
- Navigate to the Action List page and perform one of the following actions:
- Mark the checkbox of the desired action under the Select column and then click Clone.
- Click on the name of the action you wish to clone. When the Admin Action page displays, click Clone.
The Admin Action page for the newly cloned action displays.
- Enter a Name in the Label field for the new cloned action.
-
Enter a unique Variable Name or accept the default variable name in the Variable Name field for the new cloned action.
- Click Clone. The Admin Action page for the new cloned action displays.
Deleting Commerce Actions
-
Mark the checkbox of the desired action under the Select column within the Actions List page.
- Click Delete.
Use caution when deleting a Commerce action because it is not possible to recover the deleted data. Upon a deletion, all associated rules within the Commerce action are also deleted.
Notes:
- It is not possible to delete default, system-generated actions. For default actions created in association with document attributes, the system deletes these actions automatically when the corresponding attribute is deleted.
- Standard Process actions cannot be deleted, but the action functions can be viewed, overridden, and easily returned to their default values Most Standard Process actions can be removed from the layout if a customer does not want to use them.
- You can delete all custom actions by checking the Select All box and then clicking Delete.
Editing Commerce Actions
-
Modify the Label.
The Variable Name field populates automatically. Variable names can only contain alpha-numeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only.
-
Modify the Description, if required. The description is for your reference and appears on the Actions for Document page.
-
Edit the desired rules associated with the action.
Edits are not visible until the process is deployed (or redeployed). All actions besides system defined actions can be deleted even after a process has been deployed.
Formulas in Reconfiguration Scenarios
The Reconfigure action is split into one parent (Reconfigure) and one sub-action (Reconfigure Inbound). This eliminates the need for conditionals to segregate logic.
- The parent action (Reconfigure) contains all things common to both Reconfigure actions and its own identifiers: Label, Variable Name, Description, Action Icon, Show Loading Dialog, Layout Path, and Document Views Tab.
- The sub-action (Reconfigure Inbound) only contains what is specific to it.
- This allows administrators to execute a formula per attribute on:
- Outbound paths from a Commerce Transaction.
The Formula will run immediately after the user clicks the Reconfigure action in Commerce, and before the user enters Configuration.
- Inbound paths to a Commerce Transaction.
The Formula runs after the user clicks Save in the Reconfiguration, and before the user returns to the Commerce page.
- Formula execution is consistent with the existing order of operations for inbound and outbound executions.
Generate a Commerce Action Performance Analysis
To generate a Commerce action performance analysis, perform the following steps:
-
Navigate to the Action List page.
Admin > Commerce and Documents > Process Definition > Documents > Actions
-
Click on the name of the applicable action.
The Admin Action page opens.
- Click on the Performance tab.
-
Enter the applicable information:
-
For main document actions, enter the Transaction ID.
-
For sub-documents, enter the Transaction ID and Document #.
-
-
Click Generate.
The performance analysis operation includes BML functions in Advanced Modify Before and After Formulas, Advanced Validation, Modify options, Destination options, and BML integrations. Upon execution, the Commerce action Performance tab displays the following times for associated BML loops, BMQL, URL data calls, library calls, and JSON parsing.
- Total Time: Total time taken, in milliseconds, to execute the nested BML, including any time spent executing BML items that have their own entries.
- Incremental Time: Time taken, in milliseconds, to execute the nested BML, excluding time spent executing BML items that have their own entries.
- Child Rollup Time: Total combined time taken, in milliseconds, for all BML items called from this BML item.
Notes:
- Actions that do not have BML functions will not show the Performance tab.
- The run-time breakdowns are specific to BML functions and do not reflect non-BML execution times.
- Generating a Performance Analysis does not save changes to the quote.
- The external integrations defined in the Integration tab are not executed when generating a Performance Analysis, but calls from other BML using the urldata functions will execute and may modify external systems
Use Case - Auto Update Sub-Document Attributes
Administrators add Boolean, Currency, Date, Float, Integer, Menu, Text, and Text Area attributes to the output of their auto update action. Then when an end user triggers the auto update function, the function will modify the value of the specified attribute.
Sample Auto Update Use Case
An end user may want to specify a quote-level discount percent to auto update all line items rather than manually entering a discount value for each line item, as follows:
-
Define the main doc-level attribute Quote Level Discount % with Trigger Auto Update selected. In this case Quote Level Discount is a Float attribute.
-
Define the BML Function for the Auto Update – Before Formula of the main doc calling out the Line Item attributes to auto update.
-
Once a Quote Level Discount % value is entered, the quote will auto update and apply the discount value to the applicable line item attributes including the Purchase Date, Discount %, and Override Discount.
-
Auto update of Commerce Boolean, Date, Single-Select Menu, Multi-Select menu, Commerce Dynamic Menu, and Text Area attributes is only applicable to the JET User Interface. This functionality is not supported using mobile or the legacy UI.
-
In Oracle CPQ 21A and earlier, non-supported attributes can be included in an auto update BML script. When the BML script is run these unsupported attributes types are skipped. Be advised that during Oracle CPQ 21B upgrade, Commerce Boolean, Date, Menu, and Text Area attributes included in an auto update BML script will no longer be skipped and will auto update accordingly.
Notes
Notes:
- In order for any action to appear on a commerce document, it must be included in the document view.
- Commerce actions can be created, deleted, and edited one document at a time.
- User will be prevented from creating or adding Quotes from Configuration to Commerce if mandatory items are missing.
Custom Variable Name Conventions
Beginning in Oracle CPQ 23D, CPQ will adopt Oracle CX Sales variable naming conventions for custom items. When administrators create new custom entities in a Standard or non-Standard Commerce Process, an “_c” suffix will be appended to the variable name.
- The new naming convention for custom variable names provides more consistency for integrations with Oracle CX Sales.
- This update only effects new custom entities, and there is no change to existing custom entities.