1. REST API for Oracle CX Sales and B2B ServiceREST API for Sales and Fusion Service in Oracle Fusion Cloud Customer Experience
  2. Use Cases
  3. Import Data Using REST APIs

Import Data Using REST APIs

Suppose you need to import records from a third-party application frequently to update customer information in Oracle CX Sales and Fusion Service. You can go about it in two ways:
  • Use the Import Management work area, and create an import activity to import the data every time you need to.
  • Configure your REST client application to use REST APIs to import account information periodically.

When you call any of the Import or Export REST APIs, you have the ability to pass multiple records in the request payload. For example, if you're creating or updating the records then you can include multiple records in the request payload and only make one REST call from your client application. Hence sending multiple records in a single REST call is advantageous. You only authenticate once, but you can make the service act on multiple records.

Let's work through the following tasks to understand how to set up your REST client to perform periodic import using REST APIs:

  1. Identify the Objects to Import Your Data
  2. Get Object MetaData
  3. Select Required Object Attributes
  4. Download the Import Template for the Object
  5. Create Import Map
  6. Create Mapping Columns
  7. Upload the Source File to Oracle UCM
  8. Enable Survivorship (Optional)
  9. Activate the Import Activity
  10. Monitor the Import Status

Note:

If you're looking to import large amount of data, either because of an existing integration or data migration, you can use the High-Volume Import. For more information, see How You Use High Volume Import.

Identify the Objects to Import Your Data

First, let's get a list of objects in your instance of Oracle CX Sales and Fusion Service that support import through REST APIs.

Send a GET request using the following curl command for a list of supported objects.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importExportObjectMetadata

Example Response

Here's an example of the response body in JSON format.

{
  "items" : [ {
    "DisplayName" : "Account",
    "ObjectCode" : "Account",
    "PuidAttribute" : "PartyNumber",
    "KeyAttributes" : "PartyId",
    "RequiredFields" : "EmailAddress,URL,PartyNumberKey,AddressNumber,Country,PartyId,PartyNumber,OrganizationProfileId,OrganizationName,SalesProfileNumber",
   ...
     }, {
   "DisplayName" : "Contact",
   "ObjectCode" : "Contact",
   "PuidAttribute" : "PartyNumber",
   "KeyAttributes" : "PartyId",
   "RequiredFields" : "EmailAddress,PartyNumberKey,AddressNumber,Country,PartyId,PartyNumber,PersonProfileId,SalesProfileNumber,DeceasedFlag",
   ...
  }, {
    "DisplayName" : "Activity",
    "ObjectCode" : "Activity",
    "PuidAttribute" : "ActivityNumber",
    "KeyAttributes" : "ActivityId",
    "RequiredFields" : "OwnerId,ActivityId,ActivityNumber,ActivityFunctionCode,Subject,ConflictId",
    ...
    }
   ]
}

The response lists the objects that you can import using REST APIs. This will also tell you what kind of information each object imports.

Based on the response received in the previous section, you must select appropriate objects to import your data. For example, if you want to import customer account information then you need to select the Account or Contact objects, depending on the information you want to import.

Get Object MetaData

Suppose you want to use the Account object to import customer information, then you must use the following curl command to get metadata details of the object:

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importExportObjectMetadata/Account

Example of Response Body

The following shows an example of the response body in JSON format.

{
  "DisplayName" : "Account",
  "Description" : "An Organization Profile Includes Details About an Organization such as Organization Details, Additional Names, Additional Identifiers, Addresses, and Contact Points. Some Examples of Organizations are Customers, Sales Prospects, Competito   rs, and Partners.",
  "ObjectCode" : "Account",
   "PuidAttribute" : "PartyNumber",
  "KeyAttributes" : "PartyId",
   "RequiredFields" : "EmailAddress,URL,PartyNumberKey,AddressNumber,Country,PartyId,PartyNumber,OrganizationProfileId,OrganizationName,SalesProfileNumber",
...
  }

Select Required Object Attributes

You may need all the attributes of the Account object for your business case. To identify the attributes you need, you can use the GET method to list all the object attributes and choose the ones you wish to import.

We can use the GET method with the following curl command to get a list of all the object attributes of the Account object.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importExportObjectMetadata/Account/child/ObjectAttributes

Example of Response Body

Here's an example of the response body in JSON format.

{
  "items" : [ {
    "DisplayName" : "Home Country",
    "AttributeCode" : "HomeCountry",
    "ObjectName" : "Account",
   ...
  }, {
   "DisplayName" : "Do Not Confuse With",
   "AttributeCode" : "DoNotConfuseWith",
   "ObjectName" : "Account",
	...
	}, {
   "DisplayName" : "Local Activity Code",
   "AttributeCode" : "LocalActivityCode",
   "ObjectName" : "Account",
    ...
  }, ... ]
  }

Download the Import Template for the Object

You can download the template for the required object, in our case the Account object, by using the following curl command.

Example cURL

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importExportObjectMetadata/Account/enclosure/DownloadTemplate > ./asd.zip

Create Import Map

You must create an import map for mapping the source and target object attributes. You will need to specify an object code to identify the object you wish to import. You can find the object code by getting the list of all available objects.

We will use the POST method with the following curl command to create an import map.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d '{ "Name": "R3", "ObjectCode": "Account" }' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importMappings

Example Request

Here's an example of the request body in JSON format.

{
  "Name": "R3",
  "ObjectCode": "Account"
}

Example Response

Here's an example of the response body in JSON format.

{
  "MappingNumber" : "300100152098526",
  "Name" : "R3",
  "ObjectCode" : "Account",
   ...
}

We have created an import map R3 with the mapping number 300100152098526.

Create Mapping Columns

You must create the mapping columns as a child resource within the ImportMappings resource.

We will use the POST method with the following curl command and request payload to create the mapping columns for the import map we just created.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d '{
{
                             "ColumnHeader" : "OrganizationName",
                             "ExampleValue" : "Org",
                             "AttributeCode" : "OrganizationName"
                       }
    
                      {
                               "ColumnHeader" : "PartyNumber",
                               "ExampleValue" : "PNum",
                               "AttributeCode" : "PartyNumber"
                      }
    
                      {
                                "ColumnHeader" : "Comments",
                                "ExampleValue" : "Comm",
                                "AttributeCode" : "Comments"
                      }
}'
https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importMappings/300100152098526/child/ImportMappingColumns

You must execute the curl command to create a column mapping. In our example, we will create the three mapping columns below.

Example Request

Here's an example of the request body in JSON format.

{
{
                             "ColumnHeader" : "OrganizationName",
                             "ExampleValue" : "Org",
                             "AttributeCode" : "OrganizationName"
                       }
    
                      {
                               "ColumnHeader" : "PartyNumber",
                               "ExampleValue" : "PNum",
                               "AttributeCode" : "PartyNumber"
                      }
    
                      {
                                "ColumnHeader" : "Comments",
                                "ExampleValue" : "Comm",
                                "AttributeCode" : "Comments"
                      }
}

To verify the mapping columns you created, simply run the following curl command.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importMappings/300100152098526/child/ImportMappingColumns

Example Response

Here's an example of the response body in JSON format.

{
  "items" : [ {
    "ColumnHeader" : "OrganizationName",
    "ExampleValue" : "Org",
    "AttributeCode" : "OrganizationName",
    "AttributeDisplayName" : "OrganizationName",
    "MappingColumnNumber" : "300100152098528",
		...
    }, {
    "ColumnHeader" : "PartyNumber",
    "ExampleValue" : "PNum",
    "AttributeCode" : "PartyNumber",
    "AttributeDisplayName" : "PartyNumber",
    "MappingColumnNumber" : "300100152098530",
    ...
   }, {
    "ColumnHeader" : "Comments",
    "ExampleValue" : "Comm",
    "AttributeCode" : "Comments",
    "AttributeDisplayName" : "Comments",
    "MappingColumnNumber" : "300100152098532",
     ...
  } ]
}

Upload Source File to Oracle Universal Content Management (UCM)

We will run the following command to upload the source file to UCM.

Example cURL

Use this cURL format.

>java -classpath "oracle.ucm.fa_client_11.1.1.jar" oracle.ucm.client.UploadTool --url="https://servername.fa.us2.oraclecloud.com/dav/cs/idcplg" --username=username --password=password --primaryFile="D:/input/Account_Template.csv" --dDocTitle="AccountDemo1" -dDocAccount="crm/customer/import/" --proxyHost=www-proxy.us.oraclecloud.com --proxyPort=80

Enable Survivorship (Optional)

You can enable survivorship using Import REST API. Survivorship rules are a collection of business rules that determine the master or surviving record, and its attributes, during a merge operation. The rules select the best version of a record, based on business rules, from multiple source systems. You must configure survivorship and agreement rules before processing merge requests. For more information on setting up survivorship, see Set Up Duplicate Resolution Using Oracle Business Rules in Implementing Customer Data Management (CDM) for CX Sales and Fusion Service guide.

Survivorship on update is available for Account, Hub Organization, Contact, and Hub Person. You can use high-volume import mode, only when the survivorship configuration uses Source Confidence. For more information on setting up survivorship, see the following sections in the Duplicate Resolution Setup chapter in Implementing Customer Data Management (CDM) for CX Sales and Fusion Service guide:

  • Set Up Duplicate Resolution Using Groovy Scripts
  • Set Up Duplicate Resolution Using Oracle Business Rules

You can determine the best attribute value instances for a golden master record when multiple value instances for a given attribute are available, by passing the Header Enable-Survivorship : true while performing your import using REST API.

Since the survivorship logic is available only for Accounts, Hub Organization, Contacts, and Hub Person, enabling the header leads to minimum change for the existing REST-based jobs created. You can enable the header for specific jobs if desired.

Here's an example on how you can do that:

Note:

You need to pass the "ImportMode" field as either "CREATE_RECORD" or "UPDATE_RECORD" in the request payload while submitting the import job to enable survivorship.

Headers:

Content-Type : application/vnd.oracle.adf.resourceitem+json

Enable-Survivorship : true

Example URL:

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/latest/importActivities

Example of Request Body

The following shows the contents of the request body in JSON format.

{
"Name": "Account_Rest_Survivorship",
"ObjectCode": "Account",
"ImportMode" : "CREATE_RECORD",
"HighVolume" : "NO",
"Activate": "YES",
"DataFiles" : [ { "InputFileContentId": "UCMFA00062572" } ]
}

Example of Response Body

The following shows the contents of the response body in JSON format.

{
    "ImportActivityId": 300100544033358,
    "Name": "Account_Rest_Survivorship",
    "Description": null,
    "ObjectCode": "Account",
    "AttachmentObjectCode": null,
    "DecimalSeparator": ".",
    "DateFormat": "ORA_ZCA_US_FORMAT",
    "ImportMode": "CREATE_RECORD",
    "TimestampFormat": "ORA_ZCA_US_FORMAT",
    "FileEncoding": "ORA_ZCA_UTF8_ENCODING",
    "Delimiter": "COMMA_DELIMITER",
    "NotificationEmail": null,
    "ImportMapping": null,
    "Schedule": "ONE_TIME_IMMEDIATE",
    "ScheduleTime": null,
    "Activate": "YES",
    "CreatedBy": "SALES_ADMIN",
    "CreationDate": "2021-09-08T09:42:11+00:00",
    "LastUpdateDate": "2021-09-08T09:42:21.316+00:00",
    "LastUpdatedBy": "SALES_ADMIN",
    "LastUpdateLogin": "CB3744259C54EBF4E053893AF80A24A8",
    "HighVolume": "NO",
    "EnableCustomBusinessLogic": "NO",
    "NoteObjectCode": null,
    "Cancel": "NO",
    "RestNotification": null,
    "DataFiles": [
        {
            "FileName": null,
            "Title": null,
            "Size": null,
            "Description": "User provided input data file",
            "InputFileContentId": "UCMFA00062572",
            "StartTime": null,
            "EndTime": null,
            "EstimatedCompletionTime": null,
            "Status": "ORA_MKT_QUEUED",
            "ReadFromFile": null,
            "LoadedSuccessfully": null,
            "SuccessReportContentId": null,
            "ErrorsReported": null,
            "Warnings": null,
            "Unprocessed": "0",
            "ErrorReportContentId": null,
            "ExceptionReportContentId": null,
            "CreatedBy": "SALES_ADMIN",
            "CreationDate": "2021-09-08T09:42:21.554+00:00",
            "LastUpdateDate": "2021-09-08T09:42:22.356+00:00",
            "LastUpdateLogin": "CB3744259C54EBF4E053893AF80A24A8",
            "LastUpdatedBy": "SALES_ADMIN",
            "CanceledBy": null,
            "MessageCode": null,
            "links": [
...
}

Activate the Import Activity

You run the following curl command to activate the import activity. Get the InputFileContentId from the previous step.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d '{ "Name": " RevDemo ", "ImportMapping": "300100152098526", "Activate": "YES", "DataFiles" : [ { "InputFileContentId": " UCMFA00007278" } ] }' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importActivities

Example Request

Here's an example of the request body in JSON format.

{
                                "Name": "RevDemo",
                                "ImportMapping": "300100152098526",
                                "Activate": "YES",
                                "DataFiles" : [
                                         {
                                              "InputFileContentId": "UCMFA00007278"
                                         }
                                               ]
 }

Example Response

Here's an example of the response body in JSON format.

{
  "ImportActivityId" :"300100152098535",
  "Name" : "RevDemo",
  "ObjectCode" : "Account",
  "ImportMapping" : "300100152098526",
  "Activate" : "YES",
  "DataFiles" : [ {
  "InputFileContentId" : "UCMFA00007278",
  "Status" : "ORA_MKT_QUEUED",
     ...
  } ],
 ...
}
You can use the following payloads for different scenarios of import activity:
  • Single File Import
                         							{ 
                                 "Name": "RevDemo", 
                                 "ImportMapping": "300100152098526", 
                                 "Activate": "YES", 
                                 "DataFiles" : [ 
                                         { 
                                  "InputFileContentId": UCMFA00007278" 
                                         } 
                                  ]
  • Auto Mapping
    																		 {
                                 "Name": "RevDemo",
                                 "ObjectCode": "Account",
                                 "Activate": "YES",
                                 "DataFiles" : [
                                         {
                                                   "InputFileContentId": "UCMFA00007278"
                                         }
                                  ]
                       							}

  • Attachment Import:

                           {
                                 "Name": "RevDemo",
                                 "ObjectCode" : "Attachment",
                                 "AttachmentObjectCode" : "Account",
                                 "Activate": "YES",
                                 "DataFiles" : [
                                         {
                                               "InputFileContentId": "UCMFA00001745"
                                         }
                                  ]
                       }

  • Scheduling an Import Job

    {
    "Name" : "SampletestD111E3",
    "Schedule" : "ONE_TIME_SCHEDULE",
    "ScheduleTime" : "2017-05-17T00:00:00+00:00",
    "ImportMapping" : "300100152098526",
    "Activate" : "YES",
    "DataFiles":[
       {
            "InputFileContentId" : "UCMFA00001745"
       }
    ]
}

  • Multi File Import Pattern

    Note that you can include a maximum of up to 10 source files.

    {
    "Name" : "SampleAccountImport16",
    "ImportMapping" : "300100152098526",
    "Activate" : "YES",
    "DataFiles":[
       {
            "InputFileContentId" : "UCMFA00016223"
       },
       {
            "InputFileContentId" : "UCMFA00016242"
       }
    ]
}

Monitor the Import Status

You can monitor the import status using the following curl command by providing the ImportActivityId and InputFileContentId.

Example cURL

Use this cURL format.

curl --silent --show-error --fail --user username:password https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/importActivities/ 300100152098535/child/DataFiles/UCMFA00007278

Example Response when the status is Queued

Here's an example of the response body in JSON format.

{
   "FileName" : "Consumer.csv",
   "Title" : "hvc",
   "Size" : "67 BYTES",
   "Description" : "User provided input data file",
   "InputFileContentId" : "UCMFA00007278",
   "Status" : "ORA_MKT_QUEUED",
		...
}

Example Response when the status is Complete

Here's an example of the response body in JSON format.

{
   "FileName" : "Consumer.csv",
   "Title" : "hvc",
   "Size" : "67 BYTES",
   "Description" : "User provided input data file",
   "InputFileContentId" : "UCMFA00007278",
   "Status" : "ORA_MKT_COMPLETING_IMPORT",
 	 ...
}

How You Use High Volume Import

You can use the high volume mode of import for importing large number of records. The following objects (and their child objects) support this mode:
  • Account
  • Classification Code
  • Consumer
  • Contact
  • Hierarchy
  • Hierarchy Member
  • Sales Territory Quota

To use the high volume import, set the HighVolume parameter to YES in the request payload. Here is an example request payload for high volume import.

Example Request

Here's an example of the request body in JSON format.

					{
         "Name": "RevDemo",
         "ImportMapping": "300100152098526",
         "Activate": "YES",
         "HighVolume":"YES",                                 
         "DataFiles" : [
                       {
                       "InputFileContentId": "UCMFA00007278"
                       }
                       ]
         }