NetSuite Integration Series: Part 2: Keep data in Sync between Oracle CX Sales (Engagement Cloud) and NetSuite
November 2, 2020 | 13 minute readIntroduction:
The purpose of this post is to introduce readers to the realtime integration between Oracle CX Sales (formerly Engagement Cloud or Sales Cloud) and NetSuite.
We explore how to keep customers in sync between Oracle CX Sales and NetSuite when CX Sales is the source of truth. We will build this integration using Oracle Integration Cloud (OIC), which is an offering that helps customers build and orchestrate complex integrations between various systems.
The same principal can be applied to objects other than the Customer and to certain objects in Oracle ERP Cloud which support Business Events - triggers which notify OIC whenever an object is changed (Created, Updated, Deleted)
One of the challenge in syncing data between the two systems is that each system has it's own primary identifier and mapping the two requires some way to store cross-reference - which ID in System 1 maps to which ID in System 2
We will explore how this problem can be solved easily in NetSuite using a concept called External ID.
Main Article:
We will build 2 integrations:
1. When a customer is created in Oracle CX Sales, it will be created in NetSuite
2. When a customer is updated in Oracle CX Sales, it will be UPSERTed in NetSuite.
An UPSERT operation is an attempt to make an update to a record. If the record does not exist, then it will be created. This scenario can happen if a record gets created in Oracle CX Sales and is not sync'ed to NetSuite. We use the UPSERT operation to ensure subsequent updates to that record propagate to NetSuite.
How to maintain Cross Reference:
IDs in Oracle CX Sales and NetSuite do not match as both have their own ID generation algorithm. To maintain cross-reference, there are two ways.
1. Oracle CX Sales has fields for storing Source System Reference which can be used to store the corresponding ID of the other system
2. NetSuite has a similar system field for storing the ID of the partner application. It is called ExternalId.
Since the source of truth for our use case is Oracle CX Sales, we will store the ID of Oracle CX Sales in the ExternalId field of the Netsuite record.
Another thing to note is that a Customer is stored as an Account object in CX Sales. The ID field for Account in CX Sales is called the PartyId
Now let's build the integration.
High Level Steps for building the integration:
1. Create an adapter connection for NetSuite in Oracle Integration Cloud
2. Create an adapter connection for CX Sales in Oracle Integration Cloud
3. Create an integration which listens to Account Created event from CX Sales and uses the Account data to create a customer in NetSuite. It populates the ExternalId field in NetSuite record with the value of the PartyId field of the Account. This helps in referencing the NetSuite record using CX Sales ID
4. Create an integration which listens to Account Updated event from CX Sales and uses the Account data to UPSERT a customer in NetSuite. It uses ExternalId to query and update the record using PartyId field of the Account. If the record matching the ExternalId is not found, it is created in NetSuite.
5. Configure OIC credentials in CX Sales/Engagement Cloud so that it can send a Business Event to OIC
Once the integrations are built and activated the flows can be tested by:
1. Creating a new account - account should be created in NetSuite
2. Updating the newly created account - account should be updated in NetSuite
3. Updating an existing account which has not been sync'ed with NetSuite - Account should be created in NetSuite.
Detailed Steps:
Create an adapter connection for NetSuite in Oracle Integration Cloud (OIC)
Login to OIC, Go to Connections and click Create
In the "Create Connection - Select Adapter" dialog, Find and select "NetSuite"
In the "Create Connection" dialog, provide a Name and Description of the adapter and click Create
In the NetSuite Connection configuration page, provide the following information:
WSDL URL: https://webservices.netsuite.com/wsdl/NetSuite_application_version/netsuite.wsdl, where NetSuite_application_version is the version of the NetSuite application, e.g., 2020_1_0
The web services may or may not be hosted at the above location. The adapter can programmatically determine the correct URL for the web services. NetSuite hosts customer accounts in multiple locations. For example:
- webservices.netsuite.com
- webservices.na1.netsuite.com
Security Policy: User Credentials
Email Address: Email address used to login to NetSuite
Account: Your NetSuite Account ID. You can go to Setup -> Company -> Company Information to get it
Role: The Id of the NetSuite role which will be used for this integration. User should have been assigned this role.
Password: Password of the user
Application Id: This is a mandatory field starting with 2015_02. You can use an existing integration application in NetSuite or create a new one by navigating to Setup -> Integration -> Manage Integrations -> New
Test and Save the connection.
Create an adapter connection for CX Sales in Oracle Integration Cloud
Login to OIC, Go to Connections and click Create
In the "Create Connection - Select Adapter" dialog, Find and select "Oracle Engagement Cloud"
In the "Create Connection" dialog, provide a Name and Description of the adapter and click Create
In the Oracle Engagement Cloud Connection configuration page, provide the following information:
Engagement Cloud Host: the URL for your CX Sales host, e.g., https://<pod_name>.fa.us6.oraclecloud.com
Username: User name of the user that will be used for integrations
Password: Password of the user that will be used for integrations
Test and Save the connection.
Create an integration which listens to Account Created event from CX Sales
ç. It populates the ExternalId field in the NetSuite record with the value of the PartyId field of the Account. This helps in referencing the NetSuite record using CX Sales ID
Login to OIC and navigate to Integrations -> Create
OIC provides a variety of integration styles to choose from depending on your requirement. For this integration we will use the "App Driven Orchestration" pattern.
Provide Integration Name and description
The integration designer page opens. You are prompted to choose a trigger for the newly created App Driven Integration. This defines the starting point of the integration. We will choose the Engagement Cloud connection we created earlier
Configure Engagement Cloud Endpoint wizard opens. Provide a meaningful name for your endpoint, e.g., "GetAccountCreatedEvent"
On the next step of the wizard, choose "With Business Events" and search for and select "Account Created Event"
You can optionally provide an XPath filter expression to only filter the records you want to see - e.g., you can filter on a country.
On the next step of the wizard, choose None s Response Type and click Next
Review the details on the Summary screen, click Done.
Back in the integration canvas, we'll add another step in the integration to invoke NetSuite and create a customer after receiving the "Account Created" event.
To do so, hover over the integration and a "+" sign will appear
Click on the "+" sign and choose the NetSuite connection we created earlier.
Provide a meaningful name to the endpoint, e.g., CreateCustomer
On the operations page of the wizard, choose the following:
Processing Mode: Synchronous
Operation Type: Basic, Add
Your Selected Business Objects: Shuttle the Customer Business Objects to the right
Review the summary and click Done
Since fields in 2 applications do not match, the next step is to map the payload that comes from CX Sales/Engagement Cloud to NetSuite.
On the Integration designer canvas, click the pencil icon against the mapping, to open the mapping editor
We will not go into the details of the mapping editor, but you can drag and drop to map CX Sales fields on the left to NetSuite on the right.
The most important mapping is the PartyId mapping (Engagement Cloud) to ExternalId (NetSuite). This ensures that you can find NetSuite records using PartyId without having to store the InternalId of NetSuite somewhere.
We have mapped only the basic fields, but in a real world integration, a lot more fields will be mapped.
Validate and Save the mapping.
Back on Integration Designer, you can now add tracking information so that each instance of the integration can be identified at runtime
Click on the stacked lines icon on the right and click on Tracking
Drag the required fields (up to 3) for tracking and Save.
Back in the Integration Designer, save the integration and return to the Integration home page.
On the integration home page, hover over the newly created integration. A set of icons will pop up. Click on the Power button icon
You can select additional tracking during development to debug issues. For the purpose of this post, we chose not to. Click Activate to activate the integration.
Create an integration which listens to Account Updated event from CX Sales
The integration uses the Account data from CX Sales to UPSERT a customer in NetSuite. It uses ExternalId to query and update the record using PartyId field of the Account. If the record matching the ExternalId is not found, it is created in NetSuite.
Steps to create this integration are essentially the same as the previous integration. There are 3 differences that I will highlight below.
In the configure Oracle Engagement Cloud Endpoint, choose "Account Updated Event"
In the Configure NetSuite Endpoint wizard,
On the operations page of the Configure NetSuite Endpoint wizard, choose the following:
Processing Mode: Synchronous
Operation Type: Basic, Update
Your Selected Business Objects: Shuttle the Customer Business Objects to the right
On the same screen, click "Processing Options". This will open "Configure NetSuite Endpoint Processing Options" page
Select the checkbox "Insert record on Update if not existing". This will ensure the adapter issues an UPSERT operation, instead of a simple Update.
Configure OIC credentials in CX Sales/Engagement Cloud
It is required to enable CX Sales to invoke OIC integration and send a Business Event to OIC
Navigate to /soa/composer URL of your Engagement Cloud instance - https://<base_url>/soa/composer
After logging in, click on Manage Security
In the Manage Credentials dialog, provide the following information and click Register:
csf-key: This value is a concatenation of the Identity Domain and Service Instance of the OIC instance.These values can be found by clicking on your profile -> About screen.
So if the Identity Domain = idcs-43rfd44reefd54f22 and Service Instance = OICInstanceDev, the csf-key will be idcs-43rfd44reefd54f22OICInstanceDev
User Name: User Name used to login to the OIC instance
Password: Password of the user provided above
Confirm Password: Same as above
You should get a success message.
This concludes all the configuration required. Now it is time to see the results. Run the following tests:
1. Creating a new account - account should be created in NetSuite
2. Updating the newly created account - account should be updated in NetSuite
3. Updating an existing account which has not been sync'ed with NetSuite - Account should be created in NetSuite.
References:
Using Business Events in Fusion-based SaaS with Oracle Integration Cloud Service Part - 1
Using Business Events in Fusion-based SaaS with Oracle Integration Cloud Service Part - 2
Naveen Nahata
Cloud Solution Architect (A-Team)
Previous Post
Learn How to Be the Best at Fusion Applications Cloud Multi pillar implementation
Next Post