Transcription

Oracle CPQ Connector for SalesforceUpgrade and Data Migration Guide

TABLE OF CONTENTSTABLE OF CONTENTS. 2REVISION HISTORY. 4OVERVIEW . 5PREREQUISITES . 6UPDATE THE CPQ CLOUD INTEGRATION SETTINGS .7CHECK THE REFERENCE APPLICATION VERSION .7Locate the CPQ Cloud Version Info .8Locate the Reference Application Information .9CREATE THE QUOTE INTEGRATIONS . 11Create the Lightning Quote Upsert Integration .11Create the Quote Import Integration .14CREATE THE LIGHTNING SYNC ACTION . 16UPDATE THE EXISTING COMMERCE INTEGRATIONS . 19Replace the Opportunity Import Integration XSLs .20Replace the User Import Integration XSLs .22Replace the Quote Upsert Integration XSLs .24Replace the Line Item Upsert Integration XSLs .26Replace the Quote Upsert Complete Integration XSLs .28Modify the Existing Integration XSLs .30Change the Namespace of Packaged Objects . 30Change the API Name of Packaged Fields. 31UPDATE THE EXISTING ACCOUNT INTEGRATIONS . 33Create the Account Import Integration XSLs.33Create the Contact Import Integration XSLs .36UPDATE THE EXISTING PARTS INTEGRATIONS . 38Modify Existing Integration XSLs.38Update the Import/Export Parts Integration XSLs .39Update the Import/Export Parts Extended Descripions Integration XSLs .42Update the Import/Export Price Book Entry Integration XSLs .45MIGRATE SALESFORCE DATA TO THE NEW PACKAGE OBJECTS . 48PRODUCT MIGRATION . 49Export Part Numbers .50Update Part Numbers .52QUOTE MIGRATION . 57Prepare the Oracle Quote Object .59Export the Legacy Quotes .60Prepare the Quote Upload File .63Insert the Legacy Quotes Into the New Object .65QUOTE LINE ITEM MIGRATION . 70Prepare the Oracle Quote Line Item Object .71Export the New Oracle Quotes .72Export the Quote Products .75Prepare the Quote Line Item Upload File.77Insert the Legacy Quote Products Into the New Object.79Mark New Quotes as Active .84

USER MIGRATION . 94Export the Legacy Users .96Prepare the User Upload File .99Insert the Legacy Users Into the New Object .1063

REVISION HISTORYThis document will continue to evolve as existing sections change and new information is added.All updates appear in the following table:DateJuly 2019What's ChangedNotesInitial Document Creation.4

OVERVIEWThis document is written for the administrator of your organization who has the access and permissionsto change your Salesforce Org and your CPQ Cloud Site. The purpose of this document is to supplementthe Oracle CPQ Connector for Salesforce Installation and Setup Guide by giving additional detail tocustomers upgrading from older installations for the Salesforce Commerce Integration (managedpackage version 7 and earlier) to the new Oracle CPQ Connector for Salesforce (managed packageversion 8 and later). The Oracle CPQ Connector for Salesforce is also sometimes referred to as theSalesforce Connector or Salesforce Lightning Adapter.New customers integrating Salesforce and CPQ Cloud for the first time typically are provisioned with thelatest (version 5) Salesforce Reference Application (Ref App). If version 5 of the Salesforce Ref App isalready preloaded on your site, you do not need to perform the Upgrade procedures in this document.If you never have installed managed package version 7 or earlier into your Salesforce environment, youdo not need to perform the Migration procedures in this document.This guide focuses on the following: Updating your CPQ Cloud site to use the latest integration settings and transforms Migrating your existing CPQ data from the old Salesforce objects to the new onesGIVE US FEEDBACKWe welcome your comments and suggestions to improve the content. Please send us your feedback atcpqcloud documentation us [email protected]

PREREQUISITESThis document assumes you have already read and completed the steps outlined in the Oracle CPQConnector for Salesforce Installation and Setup Guide, there are a few additional pre-requisites to beaware of which are listed in the table below.PrerequisiteDescription/Additional InformationIntegration FilesRetrieve the ZIP folder containing the latest integration files from theIntegrate CPQ Cloud with Salesforce article in My Oracle Support.Salesforce Data LoaderDownload and install the Data Loader. This tool is used to export,insert and delate Salesforce records in bulk.Other 3rd party Salesforce Data Loaders or ETL tools can be used butthe steps provided below may not apply.Microsoft Excel or similarSome steps below will require the preparation and transformation ofdata.Microsoft Excel was used as the reference for these procedures,however you may choose to use another tool to perform thesesteps.My Oracle Support AccountYou need an active My Oracle Support account to complete thesesteps and receive assistance. Refer to My Oracle Support.IMPORTANT: The Migration portion of this guide was authored for and certified against the latestversion of the Oracle CPQ Connector for Salesforce, Version 8.2. The steps will be similar for Version 8(Summer 18) and Version 8.1 but they may not be identical.6

UPDATE THE CPQ CLOUD INTEGRATION SETTINGSOracle CPQ Cloud typically provisions new CPQ Cloud sites with one of a few different ReferenceApplications. The Reference Application (referred to as Ref App) is a set of pre-configured metadataincluding attributes, actions, integrations, icons, and themes which are applied to each customer’s CPQsite to accelerate their initial implementation.New customers intending to integrate to Salesforce are provisioned with the Salesforce ReferenceApplication. However there are some situations where a CPQ site may not have the latest Salesforce RefApp applied. For example, if the site was provisioned with an older Salesforce Ref App version andneeds to be updated, or if the site is being integrated to Salesforce after moving from another CRMsolution.This section describes the steps to update your CPQ site’s integration settings to align with the latestversion of the Salesforce Ref App which supports the Salesforce Connector.IMPORTANT: Ensure that you have the latest Integration XSL files. Contact My Oracle Support if youneed assistance.CHECK THE REFERENCE APPLICATION VERSIONBefore you begin it is important to check the version of the Reference Application applied to your CPQsite. This section provides the steps to retrieve the Ref App version and the Catalog of Ref Appelements. This provides a more detailed view of the initial state of your site.This section provides procedures for the following: Locate the CPQ Cloud Version InformationLocate the Reference Application Information

LOCATE THE CPQ CLOUD VERSION INFOTo locate the CPQ Cloud version information, complete the following steps:1. Log in to CPQ Cloud.2. Navigate to the Admin Home page.3. Click CPQ Version Info. The Releases page displays.4. Note the Version.5. Click Back.8

LOCATE THE REFERENCE APPLICATION INFORMATIONWhen a CPQ Cloud site is provisioned, the Ref App is pre-loaded into the environment. In addition, filesare added to the File Manager which indicate the version of the Ref App that is provisioned and describesthe change history for the Ref App. These files are used to identify if your site requires updating to connectto the latest Managed package.To locate the current Reference Application Version Info and Read Me files, complete the following steps:1. Log in to CPQ Cloud.2. Navigate to the Admin Home page.3. Click File Manager under Utilities. The File Manager page displays.4. Click on the About folder.5. From the list of files within the folder, click on the README.txt file. The README file opens.9

6. Review the Oracle CPQ Cloud Reference Application version information to check if you haveSalesforce Ref App Version 5.0 or later. If you have version 5.0 or later, you do not need tocomplete the remaining steps in the Update the CPQ Cloud Integration Settings section.7. (Optional) Return to the About folder and select the RefAppVersionInfo.txt file. TheRefAppVersionInfo file opens. Review the change log and Ref App version information.8. (Optional) Return to the About folder and select the CatalogOfRefAppElements.xlsx file. TheCatalogOfRefAppElements file opens. Review the Microsoft Excel file which itemizes all of theelements contains in the latest Ref App.10

CREATE THE QUOTE INTEGRATIONSThe Oracle CPQ Connector requires two additional Integrations that were not present in version 4 orearlier of the Ref App. These must be created manually before Quotes can be created from Salesforce.This section provides steps to create these two required Integrations.The two new integrations are: Lightning Quote Upsert IntegrationQuote Import IntegrationCREATE THE LIGHTNING QUOTE UPSERT INTEGRATIONThe Lightning Quote Upsert Integration is a new Commerce Integration of type Export. It is associatedwith the Lightning Sync action and pushes the unique Transaction ID back to Salesforce immediatelyafter the Transaction is created. It populates the External ID field on the Oracle Quote object.To create the new Integration on each Commerce Process you are connecting to Salesforce, completethe following steps:1. Navigate to the Admin Home page.2. Click on Process Definition under Commerce and Documents. The Processes page displays.3. Select your process and click Integrations from the Navigation drop down.4. Click List. The Integrations page displays.5. Click Add. The Select Integration Types page displays.11

6. Select Export (SOAP Generator).7. Click Next. The Edit Integration page displays.8. Enter the connection information for the fields. Refer to the table below for field information.Edit Integration FieldPurpose/DescriptionName(Required) Enter a descriptive Name for this integration. For example,Lightning Quote UpsertVariable Name(Required) The variable name for this integration. For example,oRCL SFDC LightningQuoteUpsertDescriptionEnter a description of the integration. For example, Updates the OracleQuote record that is created initially when a new quote is created inLightning mode. This integration exports the Transaction ID, sets theOpportunity ID and Account ID, and sets the associated Data Set on theOracle Quote.TimeoutEnter the timeout amount in milliseconds. For example, 500012

Edit Integration FieldPurpose/DescriptionID Field(Required) Enter the ID field for this integration in the form of document var name . attr var name .The ID field must precisely match the previously defined name.For example, transaction.oRCL SFDC TransactionID t9. Click Choose File next to SOAP Generator XSL. Browse to the location of the file and select thefile. The file name is oRCL SFDC LightningQuoteUpsert SOAPGenerator.xsl and click Open.10. Click Choose File next to Result Parser XSL. Browse to the location of the file and select the file.The file name is oRCL SFDC LightningQuoteUpsert ResultParser.xsl and click Open.11. Click Add.IMPORTANT: If you experience issues with the Integration files, enter a sample Transaction ID then clickPreview SOAP XML to view the XML result.13

CREATE THE QUOTE IMPORT INTEGRATIONThe Quote Import Integration is a new Commerce Integration of type Import. It is used to retrieve thelatest information from the Oracle Quote when a Transaction is opened. Particularly important when anOracle Quote has been copied or moved underneath a new parent account or opportunity.To create the new Integration on each Commerce Process you are connecting to Salesforce, completethe following steps:1. Navigate to the Admin Home page.2. Click on Process Definition under Commerce and Documents. The Processes page displays.3. Select your process and click Integrations from the Navigation drop down.4. Click List. The Integrations page displays.5. Click Add. The Select Integration Types page displays.6. Select Export (SOAP Generator).14

7. Click Next. The Edit Integration page displays.8. Enter the connection information for the fields. Refer to the table below for field information.Edit Integration FieldPurpose/DescriptionName(Required) Enter a descriptive Name for this integration. For example,Quote ImportVariable Name(Required) The variable name for this integration. For example,oRCL SFDC QuoteImportDescriptionEnter a description of the integration. For example, Imports the OracleQuote details and populates the corresponding attribute values on theTransaction.TimeoutEnter the timeout amount in milliseconds. For example, 5000ID Field(Required) Enter the ID field for this integration in the form of document var name . attr var name .The ID field must precisely match the previously defined name.For example, transaction.opportunityID t9. Click Choose File next to SOAP Generator XSL. Browse to the location of the file and select thefile. The file name is oRCL SFDC QuoteImport SOAPGenerator.xsl and click Open.10. Click Choose File next to Result Parser XSL. Browse to the location of the file and select the file.The file name is oRCL SFDC QuoteImport ResultParser.xsl and click Open.11. Click Add.IMPORTANT: If you experience issues with the Integration files, enter a sample Transaction ID then clickPreview SOAP XML to view the XML result.15

CREATE THE LIGHTNING SYNC ACTIONWhen configuring the CPQ Site Settings in the CPQ Connector users are prompted to supply a LightningSync Action. This Lightning Sync Action is not present in version 4 or earlier of the Ref App. This must becreated manually before Quotes can be created from Salesforce. This section provides steps to createthis action.The Lightning Sync Action is a special action that is only to be used by the Lightning UI. It should not beincluded on the Transaction Layout. When new Quotes are created using the new Lightning UI, theLightning Sync action runs as a nested action inside of the New Transaction action. It uses the LightningQuote Upsert Integration to write the External ID value for the Transaction back to the Oracle Quoterecord in Salesforce immediately after the Transaction is created.To create and configure the Lightning Sync action, complete the following steps:1. Navigate to the Admin Home page.2. Click on Process Definition under Commerce and Documents. The Processes page displays.3. Select your process and click Documents from the Navigation drop down.4. Click List. The Document List page displays.5. Locate your Main Document and click Actions from the Navigation drop down.6. Click List. The Action List page displays.16

7. Click Add. The Admin Action page displays.8. Enter the connection information for the fields. Refer to the table below for field information.Edit Integration FieldPurpose/DescriptionLabel(Required) Enter a descriptive Name for this integration. For example,Lightning SyncVariable Name(Required) The variable name for this integration. For example,oRCL SFDC LightningSync tAction Type(Required) Select the action type from the drop down. For example,Modify.9. Click Add.10. Enter the connection information for the fields. We recommend you leave the default settingsfor this action. Refer to the table below for field information.Edit Integration FieldPurpose/DescriptionDescriptionEnter a description for this integration. For example, Runs when a newOracle Quote has been created using Lightning mode in the Oracle CPQConnector. This action runs the related Lightning Quote Upsertintegration that associates the Transaction to the Oracle QuoteAction IconSets the icon graphic to display for this specific action.Show Loading DialogSpecifies if the loading icon displays while the action runs. Select Yes orNo.Action TimeoutSpecifies the amount of time before action session times out.Execute Action If AssociatedIntegrations TimeoutSpecifies the amount of time before action session times out if theassociated integration session times out.Desktop Layout PathSpecifies the desktop layout for this action.Mobile Layout PathSpecifies the mobile layout for this action.17

Edit Integration FieldPurpose/DescriptionRun Validation BeforeModifySpecifies if validation is run before the modify action.Advanced Modify – BeforeFormulasSpecifies any BML you want to execute before formulas evaluate.Advanced Modify – AfterFormulasSpecifies any BML you want to execute after formulas evaluate.Advanced ValidationSpecifies the different validation types for this action.11. Click on the Integration tab.12. Select the Lightning Quote Upsert (Export) from the Integration list.13. Click Update.18

UPDATE THE EXISTING COMMERCE INTEGRATIONSExisting CPQ sites typically have a set of integrations that are used to import data from the Opportunityand the User objects and also export data to the Oracle Quote and Oracle Quote Line Items. You mayhave created a number of custom integrations to import or export data from additional Salesforceobjects.When upgrading the administrator needs to decide how to refactor each Integration to use the newobjects which are part of the Oracle CPQ Connector for Salesforce. There are two options:1. Replace your existing integrations with the new reference integrations and merge your fieldmappings and other customizations into the reference integration.2. Keep your existing integrations and modify them to point to the new Salesforce Objects.Generally, if you have made only modest changes to the original integrations since your initialdeployment, we would recommend choosing Option 1 since the new behavior will closely mirror theoriginal functionality and the effort to re-map fields is minimal.If you have highly customized integrations which have complex queries or work in concert with customtriggers in Salesforce, we recommend Option 2. In this scenario your existing test cases remain and youdo not need to re-develop any of these customizations.This section provides directional guidance for both approaches.IMPORTANT: The integration names mentioned below may not precisely match the integration namesthat exist in your environment.19

REPLACE THE OPPORTUNITY IMPORT INTEGRATION XSLSMost Salesforce to CPQ integrations have a process by which Opportunity data is imported fromSalesforce and saved to the Transaction in CPQ Cloud. This Integration typically runs on the NewTransaction action and contains the SOAP Generator XSL and the Result Parser XSL that requiremodification.The SOAP Generator constructs the select query which fetches the Opportunity field values for example,name, stage, close date and win probability for the specified Opportunity ID.The Result Parser transforms the response into a XML document which maps the results of the query toCommerce Attributes on the Transaction.To replace the existing XSL files with new files, complete the following steps:1. If you have made customizations to your existing Integration, modify the reference XSL filesprovided to include these customizations. For example, custom field mappings, custom objectqueries, transform templates, or comments.2. Navigate to the Admin Home page.3. Click on Process Definition under Commerce and Documents. The Processes page displays.4. Select your process and click Integrations from the Navigation drop down.5. Click List. The Integrations page displays.20

6. Click the Opportunity Import link under the Name column. The Edit Integration page displays.7. Click Choose File next to SOAP Generator XSL. Browse to the location of the file and select thefile. The file name is oRCL SFDC OpportunityImport SOAPGenerator.xsl and click Open.8. Click Choose File next to Result Parser XSL. Browse to the location of the file and select the file.The file name is oRCL SFDC OpportunityImport ResultParser.xsl and click Open.9. Click Update.IMPORTANT: If you experience issues with the Integration files, enter a sample Transaction ID then click PreviewSOAP XML to view the XML result. Each provided XSL file includes comments which provide guidance on how to modify these files tosuit your needs. Open these files in the text editor of your choice, make your desired changes, saveand re-upload to CPQ.21

REPLACE THE USER IMPORT INTEGRATION XSLSSome Salesforce to CPQ integrations have a process by which User data is imported from Salesforce andsaved to the Transaction in CPQ Cloud. This Integration typically runs on the New Transaction action andcontains the SOAP Generator XSL and the Result Parser XSL that require modification.The SOAP Generator constructs the select query which fetches the User field values for example, nameand contact information for the specified User ID.The Result Parser transforms the response into a XML document which maps the results of the query toCommerce Attributes on the Transaction.To replace the existing XSL files with new files, complete the following steps:1. If you have made customizations to your existing Integration, modify the reference XSL filesprovided to include these customizations. For example, custom field mappings, custom objectqueries, transform templates, or comments.2. Navigate to the Admin Home page.3. Click on Process Definition under Commerce and Documents. The Processes page displays.4. Select your process and click Integrations from the Navigation drop down.5. Click List. The Integrations page displays.22

6. Click the User Import link under the Name column. The Edit Integration page displays.7. Click Choose File next to SOAP Generator XSL. Browse to the location of the file and select thefile. The file name is oRCL SFDC UserImport SOAPGenerator.xsl and click Open.8. Click Choose File next to Result Parser XSL. Browse to the location of the file and select the file.The file name is oRCL SFDC UserImport ResultParser.xsl and click Open.9. Click Update.IMPORTANT: If you experience issues with the Integration files, enter a sample Transaction ID then click PreviewSOAP XML to view the XML result. Each provided XSL file includes comments which provide guidance on how to modify these files tosuit your needs. Open these files in the text editor of your choice, make your desired changes, saveand re-upload to CPQ.23

REPLACE THE QUOTE UPSERT INTEGRATION XSLSAll Salesforce to CPQ integrations have a process by which Transaction data is exported to Salesforce andsaved to the Oracle Quote object that is part of the managed package. This Integration typically runs onthe Return to Opportunity action and contains the SOAP Generator XSL and the Result Parser XSL thatrequire modification.The SOAP Generator aggregates the Transaction attribute values and constructs the upsert query whichcreates the Oracle Quote, if it does not exist, and populates the associated Oracle Quote field values forthe specified Oracle Quote ID.The Result Parser transforms the response into a XML document which writes the results of the upsert,usually just the Oracle Quote ID which was created or updated, to corresponding Commerce Attributeson the Transaction.To replace the existing XSL files with new files, complete the following steps:1. If you have made customizations to your existing Integration, modify the reference XSL filesprovided to include these customizations. For example, custom field mappings, custom objectqueries, transform templates, or comments.2. Navigate to the Admin Home page.3. Click on Process Definition under Commerce and Documents. The Processes page displays.4. Select your process and click Integrations from the Navigation drop down.5. Click List. The Integrations page displays.24

6. Click the Quote Upsert link under the Name column. The Edit Integration page displays.7. Click Choose File next to SOAP Generator XSL. Browse to the location of the file and select thefile. The file name is oRCL SFDC QuoteUpsert SOAPGenerator.xsl and click Open.8. Click Choose File next to Result Parser XSL. Browse to the location of the file and select the file.The file name is oRCL SFDC QuoteUpsert ResultParser.xsl and click Open.9. Click Update.IMPORTANT: If you experience issues with the Integration files, enter a sample Transaction ID then click PreviewSOAP XML to view the XML result. Each provided XSL file includes comments which provide guidance on how to modify these files tosuit your needs. Open these files in the text editor of your choice, make your desired changes, saveand re-upload to CPQ.25

REPLACE THE LINE ITEM UPSERT INTEGRATION XSLSAll Salesforce to CPQ integrations have a process by which Transaction Line data is exported toSalesforce and

Salesforce Connector or Salesforce Lightning Adapter. . Integration Files . Retrieve the ZIP folder containing the latest integration files from the . Integrate CPQ Cloud with Salesforce: . These files are used to identify i