Commerce Integrations

Overview

Administrators can create Commerce Integrations which integrate with an external system commonly a CRM system, such as Oracle Sales, Microsoft Dynamics 365, or Salesforce.

The Integrations page displays current Commerce Integrations and shows the Order, Name, Type, ID Field, Description, Last Modified, and linked Actions. The following example shows Commerce Integrations for an Oracle Sales integrated site.

Commerce Integrations

Note: The Integrations Types available for your site are dependent upon your CRM Integration.

Notes:

  • Oracle CPQ 23B introduced the Standard Process to simplify set up for integrations with Oracle CPQ. The Standard Process automatically provides several predefined REST integrations for Oracle Sales and BML integrations for Oracle Order Management and Oracle Subscription Management. Customers can add additional integrations and they can delete integrations that are not needed.
  • REST Integration types are only supported for Oracle Sales integrations.

Administration

ClosedAdd a BML Integration

To add a BML Integration to a Commerce process, complete the following steps:

  1. Navigate to the Admin Home page.
  2. Click Process Definition in the Commerce and Documents section.

  3. For the applicable process, select Integrations from the Navigation drop-down.

  4. Click List. The Integrations page displays.
  5. Click Add. The Select Integration Types page displays.
  1. Select the BML Type option, then click Next.

BML Edit Integration page

  1. Enter the Name and Variable Name of the BML integration.
  2. If required, enter a Description.
  3. Select a Run Type value:
    • Always Run: the BML function runs every time the process is requested.
    • Requires Partner Session: the BML function only runs when a partner session is active.

  4. Click Define to open the BML Editor.

  5. Using the BML Editor, define the BML function that you want to run when the Commerce action is invoked. Upon closing the BML Editor, you are returned to the Edit Integration page.
  6. Click Add to save this integration.

ClosedAdd an Integration Cloud Service

  1. Navigate to the Admin Home page.
  2. Click Process Definition in the Commerce and Documents section.

  3. For the applicable process, select Integrations from the Navigation drop-down.

  4. Click List. The Integrations page displays.

  5. Click Add. The Select Integration Types page displays.

  6. Select Integration Cloud Service and click Next.

    Add ICS commerce integraton

    1. Name: Enter a name (i.e. label) for the integration.
    2. Variable Name: Enter a unique identifier. This field 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. Action:  This is just a label for the integration to describe how it will be used, and does not have any effect on how it works.
    6. Endpoint URL: (only applicable to Gen3 integrations) Enter the applicable ICS endpoint.
    7. Services: (only applicable to Gen2 integrations) When a CPQ–OIC Adapter is configured, select the applicable service.

  7. Click Add.

    The process now appears on the Integrations page.

ClosedAdd a REST – Export Lines Integration

Complete the following steps to create a REST – Export Lines Integration.

  1. Navigate to the Admin Home page.
  2. Click Process Definition in the Commerce and Documents section.

  3. For the applicable process, select Integrations from the Navigation drop-down.

  4. Click List. The Integrations page displays.

  5. Click Add. The Select Integration Types page displays.

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

  7. Complete the fields in the Integration Information section.

    Add REST - Export Lines Integration

    1. Name: Enter a name (i.e. label) for the integration.
    2. Variable Name: Enter a unique identifier. This field 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.
      This field indicates which Commerce attribute stores the external ID of the object being updated by the integration.

    6. Line Type Filter: Select one of the following options. This field cannot by edited after creation.

      • 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
      • Custom: Administrator specifies a line-level attribute which indicates if that line should be included or not included in the export. When Custom is selected, the Filter Attribute field displays.

    7. Filter Attribute: This field is only displayed when the Custom Line Type Filter is selected.
      The filter can be Boolean or text and if the attribute value is "true" then the line is included in the export. If the attribute value is anything other than "true", the line-level attribute is not included in the export.

      Notes:

      • The filter attribute must be a sub-document Boolean or Text type attribute.
      • At this time, REST Integrations are only supported with Oracle Sales integrations. Any lines which are synchronized will be visible in the Oracle Sales Workspace. Any lines filtered will not be available in Oracle Sales.

  8. Complete the fields in the Endpoints section.

    REST – Export Lines Integration Endpoints

    1. MetaData URL: The endpoint to retrieve the metadata about CRM attributes available for mapping for this integration.

    2. Child Resource: Name of the child resource from metadata for mapping attributes.
    3. Integration URL: The endpoint used to invoke the export operation.
    4. Integration Request Headers: This field takes the headers to be passed in the request to the above integration endpoint.

    5. 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.

  9. Click Add.

Notes:

  • REST Integration types are only supported for Oracle Sales integrations.
  • The Standard Process includes the Sync Quote Lines integration by default. Customers can add additional REST – Export Lines integrations in the Commerce Process and they can delete integrations that are not needed.

ClosedAdd a REST – Export Integration

Complete the following steps to create a REST – Export Integration

  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, and then click Next.

  6. Complete the fields in the Integration Information section.

    REST – Export Integration

    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 5,000 milliseconds.

    5. ID Field: Enter the documentVarName.attributeVarName.
      This field indicates which Commerce attribute stores the external ID of the object being updated by the integration.

  7. Complete the fields in the Endpoints section.

    REST – Export Integration Endpoints

    1. MetaData URL: The endpoint to retrieve the metadata about CRM attributes available for mapping for this integration.
    2. Child Resource: Name of the child resource from metadata for mapping attributes.
    3. Integration URL: The endpoint used to invoke the export operation.
    4. Integration Request Headers: This field takes the headers to be passed in the request to the above integration endpoint.

    5. 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.

Notes:

  • REST Integration types are only supported for Oracle Sales integrations.
  • The Standard Process (introduced in Oracle CPQ 23B) includes the REST Upsert Quote and REST Line Sync Complete integration by default. Customers can add additional REST – Export integrations in the Commerce Process and they can delete integrations that are not needed.

ClosedAdd a REST – Import Integration

Complete the following steps to create a REST – Import Integration.

  1. Navigate to the Admin Home page.
  2. Click Process Definition in the Commerce and Documents section.

  3. For the applicable process, select Integrations from the Navigation drop-down.

  4. Click List. The Integrations page displays.

  5. Click Add. The Select Integration Types page displays.

  6. Select REST – Import, and then click Next.

  7. Complete the fields in the Integration Information section.

    REST – Import Integration

    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 5,000 milliseconds.

    5. ID Field: Enter the documentVarName.attributeVarName.
      This field indicates which Commerce attribute stores the external ID of the object being updated by the integration.

    6. Document Level: Select Main Document.

  8. Complete the fields in the Endpoints section.

    REST – Import Integration Endpoints

    1. MetaData URL: The endpoint to retrieve the metadata about the CRM attributes available for mapping for this integration.

    2. Child Resource: Name of the child resource from metadata for mapping attributes.

    3. Integration URL: The endpoint used to invoke the import operation.

    4. Query Parameters: This section can be used to define query parameters for imports.

      Notes:

      • Some query parameters are managed automatically for batch processing.
      • limit, offset, and totalResults query parameters should be avoided as they may disrupt automated batch processing.
      • When multiple query parameters with the same key but different values are used, the first query parameter in the string will be picked up for execution.

    5. Integration Request Headers: This field takes the headers to be passed in the request to the above integration endpoint.

  9. Click Add.

Notes:

  • REST Integration types are only supported for Oracle Sales integrations.
  • The Standard Process (introduced in Oracle CPQ 23B) includes the REST Import Opportunity and Import Revenue Lines integrations by default. Customers can add additional REST – Import integrations in the Commerce Process and they can delete integrations that are not needed.

ClosedAdd an Import (Query and Result Parser) Integration

Complete the following steps to create an Import (Query and Result Parser) Integration.

  1. Navigate to 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 Import (Query Generator and Result Parser) and then click Next.

  6. Enter the Name for the integration.

  7. Enter the Variable Name for the integration.

  8. Enter the ID Field in the format <document_var_name>.<att_var_name>.

  9. Click Browse to select and load a SOAP Generator XSL into the integration, based on your use case.

  10. Click Browse to select and load a Result Parser XSL into the integration, based on your use case.

    The result parser converts one XML format into another. If the partner system returns a valid id, then Oracle CPQ populates the transaction field projectname_quote with the name value coming from the partner - sf:Name.

  11. Click Add.

  12. To view the integration, click the Integration name. Preview the SOAP XML by entering a Commerce Transaction ID. For more information, see the topic Finding the Transaction ID.

ClosedEdit or Preview a Commerce Integration

Administrators are able to view SOAP or REST (Update 22D and later) request and response payloads for Commerce integrations via the Edit Integration page. This can help when setting up or troubleshooting integrations by providing easily accessible attribute mapping information.

  1. Click Admin to go to the Admin Home Page.

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

    The Processes page opens.

  3. For the Commerce Process, choose Integrations in the Navigation drop-down and click List.

    The Integrations page opens.

  4. Click the name of the integration you want to edit.

    The Edit Integration page opens.

  5. Make any desired changes.
  6. To access Attribute Mapping for REST type integrations, click Edit for the applicable mapping.

  7. To preview the integration, enter a Transaction ID and click a Preview link.

    For more information, see the topic Finding the Transaction ID.

    This will execute the integration, and may modify the remote site.
  8. Click Update.

Both SOAP and REST integrations require a valid external key, for example:

  • The REST – Import integration requires a valid Opportunity Number (opportunityNumber_t) field to be populated.
  • The REST – Export integration requires a valid Opportunity Id (opportunityID_t) field to be populated.
  • The REST – Export Lines integration requires a valid OSC Transaction ID (oRCL_OSC_TransactionID_t) field to be populated. This value corresponds to OrderHeaderId from the preview response of the REST – Export integration.

ClosedView Commerce Integration Parameters

Oracle CPQ exposes parameters for Commerce integrations, such as Oracle Sales and Salesforce. The following items are exposed:

  • Site Name
  • Site URL
  • Commerce Process Id
  • Copy Process Action Id
  • Open Transaction Action Id
  • Transaction Id
  • Create Quote Version Action Id
  • Commerce Process Version Id
  • Commerce Process Variable Name

Complete the following steps to view Commerce integration parameters.

  1. Navigate to the Admin Home page.
  2. Click Process Definition in the Commerce and Documents section.
  3. For the applicable process, select Integrations in the Navigation drop-down, and the click List.

  4. Click View Parameters.

    View Commerce Process Parameters

    The integration parameters and action Ids are displayed.

    Commerce Process Integration Parameters

  5. To hide the parameters, click Hide Parameters.

ClosedPredefined Commerce Integrations for Oracle Sales

The following default predefined integrations are included in the Oracle CPQ Standard Process for CPQ sites integrated with Oracle Sales. Administrators can add additional integrations, modify attribute mappings, and delete integrations that are not needed.

ClosedSync Quote Lines

This integration synchronizes quote lines from CPQ to Oracle Sales.

  • Type: REST Export Lines
  • Timeout: 20000
  • ID Field:
    • Standard Process:transaction.oRCL_SFA_TransactionID_t
    • Oracle Sales Reference Application:transaction.oRCL_OSC_TransactionID_t
  • Integration Trigger:
    • Standard Process:oRCL_SFA_UpdateOpportunity
    • Oracle Sales Reference Application:oRCL_OSC_UpdateOpportunity
  • Document Level: Sub Document
  • Line Type Filter: All Lines
  • MetaData URL:/crmRestApi/resources/11.13.18.05/salesOrderLines/describe
  • Integration URL:/crmRestApi/resources/11.13.18.05/salesOrders
  • Integration Request Headers:Upsert-Mode:true
  • Batch Size: 500
  • Sync Quote Lines Attribute Mapping

ClosedREST Upsert Quote

This integration imports the opportunity header information from Oracle Sales to a CPQ transaction.

  • Type: REST Export Lines
  • Timeout: 20000
  • ID Field:
    • Standard Process:transaction.oRCL_SFA_TransactionID_t
    • Oracle Sales Reference Application:transaction.oRCL_OSC_TransactionID_t
  • Integration Trigger:
    • Standard Process:oRCL_SFA_UpdateOpportunity
    • Oracle Sales Reference Application:oRCL_OSC_UpdateOpportunity
  • Document Level: Sub Document
  • Line Type Filter: All Lines
  • MetaData URL: /crmRestApi/resources/11.13.18.05/salesOrderLines/describe
  • Integration URL: /crmRestApi/resources/11.13.18.05/salesOrders
  • Integration Request Headers:Upsert-Mode:true
  • Batch Size: 500
  • REST Upsert Quote Attribute Mapping

ClosedREST Line Sync Complete

This integration exports transaction level data from CPQ to the Oracle Sales quote and sales order header object.

  • Type: REST - Import
  • Timeout: 100000
  • ID Field: transaction.opportunityNumber_t
  • Document Level: Main Document
  • MetaData URL: /crmRestApi/resources/11.13.18.05/opportunities/describe
  • Integration URL: /crmRestApi/resources/11.13.18.05/opportunities/{optyNumber}
  • REST Line Sync Complete Attribute Mapping

ClosedREST Import Opportunity

This integration updates the "Last Synchronized" date for an Oracle Sales quote and sales order header object to trigger upsert of opportunity revenue lines.

  • Type: REST - Import
  • Timeout: 100000
  • ID Field: transaction.opportunityNumber_t
  • Document Level: Main Document
  • MetaData URL: /crmRestApi/resources/11.13.18.05/opportunities/describe
  • Integration URL: /crmRestApi/resources/11.13.18.05/opportunities/{optyNumber}
  • REST Import Opportunity Attribute Mapping

ClosedImport Revenue Lines

This integration imports revenue lines from an Oracle Sales opportunity and creates related quote lines on a CPQ transaction.

  • Type: REST - Import
  • Timeout: 20000
  • ID Field: transaction.none
  • Integration Trigger: transaction.opportunityNumber_t
  • Document Level: Sub Document
  • MetaData URL: /crmRestApi/resources/11.13.18.05/salesOrders/describe
  • Child Resource: ChildRevenue
  • Integration URL: /crmRestApi/resources/11.13.18.05/opportunities/{opty_number}/child/ChildRevenue
  • Query Parameters:
    • Key: q
    • Value: SplitTypeCode!=DETAILCHILDSPLIT,RecurTypeCode!=CHILDRECUR
  • Import Revenue Lines Attribute Mapping

ClosedTCA Account Integration

This integration is used to retrieve Bill To, Sold To, and Ship To customer information from Oracle Sales.

  • Type: BML
  • Run Type Always Run

  • BML Function

    return commerce._s_tCAAccountIntegration();

 

Troubleshooting

ClosedDebugging CRM Integration

NOTES

Refer to the following documents for more information focused on Oracle Sales to Oracle CPQ integration implementation.

Custom Variable Name Conventions

In Oracle CPQ 23D, CPQ adopted Oracle CX Sales variable naming conventions for custom items. When an administrator creates a new custom Commerce item, the "_c" suffix is appended to the variable name. The new naming convention for custom variable names provides more consistency for integrations with Oracle Sales.

Beginning in Oracle CPQ 24C, customers can submit a service request to disable the "_c" suffix on variable names for custom Commerce entities (Actions, Analytics, Attributes, Data Columns, Integrations, Library Functions, Rules, Steps, etc.). The "_c" suffix is enabled by default for standard and legacy Commerce processes.

  • Customers can submit a Service Request (SR) on My Oracle Support to disable the "_c" suffix on variable names for custom Commerce entities
  • When the "_c" is disabled, the "_c" variable name suffix will not be required for newly created custom Commerce entities.
  • Disabling the "_c" variable name suffix for custom Commerce entities will not change existing variable names.
  • The "_c" suffix setting will not impact existing variable names when cloning a Commerce process or migrating Commerce items. Target variable names will be the same as the variable names from the source Commerce process.

Notes:

  • Oracle CPQ does not support using different integration types in the same Commerce action. Only integrations of a single type are able to be used on a given Commerce Action; you cannot mix integration types.
  • Oracle CPQ 20B implements XML Translation Line Limits to prevent performance issues that could occur when generating XML for quotes with an extremely large number of transaction lines.

Related Topics

Related Topics Link IconSee Also