Commerce Integrations

Overview

Administrators can create Commerce Integrations which integrate with an external system commonly a CRM system, such as Oracle CX 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 CX 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 CX 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 CX 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

Notes:

  • REST Integration types are only supported for Oracle CX 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.

ClosedPredefined REST Integrations for Oracle CX Sales

Sync Quote Lines

  • Type: REST Export Lines
  • Timeout: 20000
  • ID Field:
    • Oracle CX Sales Reference Application: transaction.oRCL_OSC_TransactionID_t
    • Standard Process: transaction.oRCL_SFA_TransactionID_t
  • Integration Trigger:
    • Oracle CX Sales Reference Application: oRCL_OSC_UpdateOpportunity
    • Standard Process: oRCL_SFA_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

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 CX Sales integrations. Any lines which are synchronized will be visible in the Oracle CX Sales Workspace. Any lines filtered will not be available in Oracle CX 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.

ClosedAdd a REST – Export Integration

Notes:

  • REST Integration types are only supported for Oracle CX 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.

ClosedPredefined REST Integrations for Oracle CX Sales

REST Upsert Quote

  • Type: REST Export Lines
  • Timeout: 20000
  • ID Field:
    • Oracle CX Sales Reference Application: transaction.oRCL_OSC_TransactionID_t
    • Standard Process: transaction.oRCL_SFA_TransactionID_t
  • Integration Trigger:
    • Oracle CX Sales Reference Application: oRCL_OSC_UpdateOpportunity
    • Standard Process: oRCL_SFA_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

REST Line Sync Complete

  • 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

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.

ClosedAdd a REST – Import Integration

Notes:

  • REST Integration types are only supported for Oracle CX 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.

ClosedPredefined REST Integrations for Oracle CX Sales

REST Import Opportunity

  • 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

Import Revenue Lines

  • 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

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.

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

Use Cases

ClosedEnable a Commerce Integration

This use case provides a high level overview for enabling a Commerce Integration.

Note: Required attributes, actions, and integrations are typically provided in CPQ reference application, integration package, or Standard Process.

  1. If required, create CPQ Commerce document attributes for integration parameters.

    For example, CRM Opportunity Id, CRM Opportunity Number

    1. Navigate to the Admin Home Page.
    2. Click Process Definition in the Commerce and Documents section.
    3. Select Documents from the applicable process Navigation drop-down, and then click List.
    4. Select Attributes from the main document Navigation drop-down, and then click List.
    5. Create and save the attribute to represent the applicable CRM item.

  2. If required, create an action to trigger the integration.

    For example, Update Opportunity

    1. Navigate to the Admin Home Page.
    2. Click Process Definition in the Commerce and Documents section.
    3. Select Documents from applicable process Navigation drop-down, and then click List.
    4. Select Actions from the main document Navigation drop-down menu, and then click List.
    5. Create and save the action that will be used to trigger the integration.

  3. Create an integration.

    Refer to the procedures listed in the Administration section for more information.

  4. Add the integration to the action.

    This step is used to identify the Commerce actions that will run the integration when they are invoked.

    1. Navigate to the Admin Home page.

      • For Commerce process actions, navigate to:

        Process Definition > Commerce and Documents > Process Actions

      • For Commerce main document actions, navigate to:

        Process Definition > Commerce and Documents > Main Document > Actions

    2. Open the applicable action, and then click the Integration tab.
    3. Select the applicable integration from the Integration List and move it to the Selected Integration list by clicking the right arrow symbol. You can move it above or below other functions.
    4. Click Apply or Update to save changes.
  5. Deploy the Commerce Process.

Troubleshooting

ClosedDebugging CRM Integration

NOTES

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

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.

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