Customer 360 Data ManagerData Jobs API Developer Guide

Version 52.0, Summer ’21

@salesforcedocsLast updated: April 22, 2021

© Copyright 2000–2021 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS

Chapter 1: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Data Jobs API FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Supported OAuth Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Call the Data Job API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Data Jobs API Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: Data Jobs API RAML Spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 3: Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 4: Troubleshooting Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

CHAPTER 1 Quick Start

Get started with the Customer 360 Data Manager Data Jobs API. Configure and run jobs for Customer360 Data Manager to automate data synchronization of your global profiles.

In this chapter ...

• Prerequisites1. In Customer 360 Data Manager, log in as a System Administrator.

• Data Jobs API FAQ2. To access the setup, click Configure Admin Settings.• Supported OAuth

Flows Note: This link isn’t visible for Standard users.• Call the Data Job API

3. Create a connected app for the Customer 360 Data Manager org.• Data Jobs APIImplementation 4. Enable OAuth settings for API integration for your connected app.

5. Follow the instructions to Call the Data Job API on page 3.

SEE ALSO:

Data Jobs API RAML Spec

1

Prerequisites

Complete these prerequisites before you begin the quick start.

You must have an org that has Customer 360 Data Manager provisioned to be able to use the API.

Become familiar with:

• Enabling an SSL endpoint in your application server.

• JavaScript Object Notation (JSON), which is the data format returned in the query response.

• cURL, the tool used to execute REST requests in this guide.

• OAuth 2.0, which requires some setup.

Data Jobs API FAQ

Learn the answers to frequently asked questions about the Customer 360 Data Manager Data Jobs API.

What Is the Data Jobs API (DJ API)?The Data Jobs API is a REST API that creates and runs Customer 360 Data Manager jobs.

The API allows you to:

• Create and run jobs

• Get information about jobs, files, and data sources.

• Upload. download, and delete data, configuration, and log files.

• Delete global profiles from your Customer 360 Data Manager environment.

What Do I Use the Data Jobs API For?Use the Customer 360 Data Manager Data Jobs API to integrate Customer 360 Data Manager with your data sources, so you can automatedata synchronization of your global profiles.

What Do I Need to Do to Run a Job?POST the Jobs resource.

What Information Does the Data Jobs API Retrieve?It returns information about data sources, jobs, and files.

How Do I Control How the Results Are Returned and Paginate ThroughThem?Specify these query parameters:

• resultsPerPage to specify the number of results to return per page.

• page to specify the number of pages to return.

2

PrerequisitesQuick Start

Supported OAuth Flows

Selected OAuth flows are supported for this API.

The following flows are supported:

• OAuth 2.0 Web Server Flow for Web App Integration

• OAuth 2.0 Username-Password Flow for Special Scenarios

IP range restriction features aren't supported for login or session usage.

Call the Data Job API

USER PERMISSIONS

API Enabled AND View All DataTo use the Developer Console:

View All DataTo view, retain, and delete debug logs:

Author ApexTo execute anonymous Apex:

API EnabledTo use code search and run SOQL or SOSL on the query tab:

Author ApexTo save changes to Apex classes and triggers:

Customize ApplicationTo save changes to Visualforce pages and components:

Customize ApplicationTo save changes to Lightning resources:

System AdministratorTo access the Customer 360 Data Manager org

Quick example of how to call the Data Job API.

To call the API, you must have already completed the other tasks in the Quick Start on page 1.

You can use any tool of your choice to call the API. The code examples in this guide use a command-line tool called cURL to simplifysending and receiving HTTP requests and responses.

cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When using HTTPS onWindows, ensure that your system meets the cURL requirements for SSL.

The Base URI includes the API Gateway FQDN and the product domain. The API Gateway FQDN depends on the region of the Customer360 Data Manager org.

Table 1: Regional FQDN

Base URIRegion

na.api-salesforce.comNorth America

eu.api-salesforce.comEurope

ap.api-salesforce.comAsia/Pacific

The required domain for the Data Jobs API is datamanager.

3

Supported OAuth FlowsQuick Start

Example: URL for the Jobs resource

https://na.api-salesforce.com/datamanager/datatools/v1.0/jobs

1. Open your command line.

2. To retrieve an access token, make an authentication call. Use the Customer 360 Data Manager org name as the instance_url.If you’re developing an app, the connected app provides this access token, this call is only necessary for the examples that use cURL.

• login_url: use the URL you use to log in to Salesforce.

• client_id: use the connected app consumer key.

• client_secret: use the connected app consumer secret.

• username: use the username you use to log in to Salesforce.

• password: use the password you use to log in to Salesforce.

curl -k https://instance_url.salesforce.com/services/oauth2/token \-d "grant_type=password" \-d "client_id=3MVG9qKMKuRGRcbuZ90BMXK_bF3MizRStXIw1gC7iPmpDmw5ScBvbCyZXJ7R2urNDRcwB3I7m9pt9qgd5ogMN"\-d "client_secret= F490545988E166F17B0A7317068FB2ED71E913FBF0C1F24A732E8BB9FC82ACED" \-d "username=admin@myapps.com" \-d "password=test4mB1riuD3n"

This result is an example:

{"access_token":"00DRM000000IeI2!AR4AQIJeeDdSm1eibRjSGn_qe4XOFG4_MUrRAo2RhA9WXWsQtWzRTxaAOdpwUYj7L21hqvI6lknfHc5Ua4Drf.GudSR82UXN",

"instance_url": "https://shadow-org.my.salesforce.com","id": "https://login.salesforce.com/id/00DRM000000IeI22AK/005RM000001yVhvYAE","token_type": "Bearer","issued_at": "1594662156814","signature": "Xik2Lq7n/1+F1S+aHF8kS7AeNQaQdLkRPG1pvsSP+8U="}

Note: The information in the token is required for calls to the DJ API.

3. Use one of the resources of the API. You need information for the headers, URI parameters, and authentication token. Thex-sfdc-domain header value is derived from the instance_url returned in the authentication token.

curl -vL -X GET \https://na.api-salesforce.com/datamanager/datatools/v1.0/data-sources \-H 'accept: application/json' \-H 'authorization: Bearer

00DRM000000IeI2!AR4AQIJeeDdSm1eibRjSGn_qe4XOFG4_MUrRAo2RhA9WXWsQtWzRTxaAOdpwUYj7L21hqvI6lknfHc5Ua4Drf.GudSR82UXN'\-H 'x-sfdc-domain: shadow-org.my.salesforce.com'

This result is an example:

[{"domain": "svc1597507920996","id": "core/stmfbna44ice1/00DRM000000Iw7n2AC",

4

Call the Data Job APIQuick Start

"name": "Service Org 2","type": "Core"

},{"domain": "svc1597507895985","id": "core/stmfbna44ice1/00DRM000000Iw7i2AC","name": "Service Org 1","type": "Core"

},{"domain": "stmfbna44ice1","id": "cre/stmfbna44ice1/creprd000003sej","name": "cre-creprd000003sej","type": "CRE"

}]

Data Jobs API Implementation

Understand how to use multiple jobs to create global profiles and add Global Party IDs into your orgs and B2C Commerce instances.

Global Profile Round TripCustomer 360 Data Manager imports data from connected data sources, creates global profiles, and exports global profile IDs. The globalprofile IDs are injected back into the original data sources. The global profile IDs can then be used to create Lightning Web Component(LWC) components or apps that can query customer data across data sources.

For example, assume that your organization that the customer has:

• Three records and addresses from B2C Commerce orders

• One record in your European org

• One record in your North American org.

If all three data sources are connected, you can create a global profile that identifies all the records with a single Global Party ID. Afterthe Global Party ID is injected back into the original systems, it identifies records belonging to a customer.

AuthorizeCreate a new connected app.

Note: Make sure to review information about which OAuth flows are supported for Data Manager APIs.

Identify Data SourcesUse the Data Sources resource to identify the data sources connected to Customer 360 that you can pull data from. If a data source isn’tavailable, ask your Customer 360 admin to connect it.

5

Data Jobs API ImplementationQuick Start

Investigate Data Quality by Pushing Global Profiles to an Analytics SnapshotAfter you create global profiles, you can run a job to push them to one of the two analytic snapshots. Use the Customer 360 Data Managerdashboards to evaluate data quality and the performance of the match rules.

1. For your data source, successfully complete the jobs necessary to create global profiles.

2. Push global profiles to the Customer 360 Data Manager analytics dashboard using the Jobs resource.

Add Global Party IDs to Commerce Cloud

To create global profiles and add their IDs back into your B2C Commerce instance, you create five jobs to run in the following order:

6

Data Jobs API ImplementationQuick Start

1. B2C Commerce to file staging. This job produces a Customer export file and an Order export file.

2. Create a file staging to global profile hub for each object data file.

• File staging to global profile hub for the Customer object export file.

• File staging to global profile hub for the Order object export file.

3. Global profile hub to file staging. This job produces a .json file that contains Global Party IDs.

4. File staging to B2C Commerce IDs. This job inserts the Global Party IDs back into the B2C Commerce instance.

To run any of these jobs, aside from the Bulk API job, use the Jobs resource POST method.

7

Data Jobs API ImplementationQuick Start

Add Global Party IDs to Service Cloud

To create global profiles and add their global party IDs back into your B2C Commerce instance, create jobs these jobs:

1. Bulk API data export for Accounts, Contacts, and Leads. This job produces a .csv export file for each object.

2. File upload to file staging. Running this job to upload all export files and the configuration files you create to map them.

3. File staging to global profile hub. This job processes data and configuration files into global profiles.

4. Global profile hub to file staging. This job exports a Global Party ID file for a specific data source into file staging.

5. File download from file staging. This job downloads the Global Party ID file to your local machine.

6. Bulk API data import for Global Party ID export files. Use the Bulk API documentation for more information about using the API toimport the Global Party ID file from your local machine into your org.

8

Data Jobs API ImplementationQuick Start

Note: Use the resources that monitor jobs to check the status of each job before continuing to the next job. You can also usethe resources to monitor files to make sure that the correct files are available for a job before running it.

To run any of these jobs, aside from the Bulk API job, use the Jobs resource POST method.

Monitor Jobs and FilesList all jobs and get information about a specific job or file.

1. List jobs. Use the resource GET method.

2. Get Information about specific jobs. Use the Job resource.

3. List files. Use the Files method for listing all files in the file staging area and the Job Files method for listing files associated with ajob.

4. Get information about a file. Use the Job File or File method to get information about a file.

Clean up FilesClean up jobs from a round-trip run.

1. Delete files. Use the Job File, Job Files, File, or Files DELETE method.

9

Data Jobs API ImplementationQuick Start

CHAPTER 2 Data Jobs API RAML Spec

RAML Specification

The Customer 360 Data Manager Data Jobs API is described in the RAML specification. It contains:

• the request properties for each endpoint

• examples of the request bodies

• examples of the response bodies

Salesforce Data Jobs API version v1.0

SEE ALSO:

Quick Start

10

CHAPTER 3 Status Codes and Error Responses

Each request returns a status code or error response to indicate whether the request was successful.

When an error occurs or when a response is successful, the response header contains an HTTP code, andthe response body usually contains:

• The HTTP response code

• The message accompanying the HTTP response code

DescriptionHTTPresponsecode

Query successfully executed and response data returned.2xx

(BAD_REQUEST) The argument or parameter you supplied in the request isn’t valid.400

The request was refused because the data source isn’t connected to Customer 360Data Manager or doesn’t allow data to be queried.

403

The job, file, or data source included in your query can’t be found.404

Too many requests being processed at the same time. Try again.429

An error has occurred, so the request couldn’t be completed. Try again or contactSalesforce Customer Support.

500

Either your data source is unavailable or the connection to it timed out.503

11

CHAPTER 4 Troubleshooting Error Codes

Troubleshoot error codes from the Data Federation API depending on how you’re using and configuringthe API.

Basic Troubleshooting Steps

Make sure:

• The DFS External Data Source and the DFS Named Credential are both configured correctly.

• The mapping version supports your query.

• The entities and attributes you want to query are mapped for the data source that makes the queryand the data source being queried.

12