Analytics External Data API Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
External Data
Load External Data into a Dataset
External Data Metadata Overview
External Data Reference
The InsightsExternalData Object
The InsightsExternalDataPart Object
External Data Metadata Format Reference
Release Notes
PDF

The InsightsExternalData Object

With the InsightsExternalData object, you can configure and control external data uploads. You can use it to provide metadata, trigger the start of the upload process, check status, and request cancellation and cleanup.

The InsightsExternalData object is used with the InsightsExternalDataPart object, which holds the parts of the data to be uploaded. Together, they provide a programmatic way to upload a large file in parts and trigger a dataflow into a dataset. The first step is to insert a row into the InsightsExternalData object. Data parts are then uploaded to InsightsExternalDataPart objects. The Mode field is used to enable faster uploads. The Action field of the InsightsExternalData object is updated to start processing and request cancellations. After the Action field is updated to request processing, no user edits are allowed on the objects, except to request cancellation.

The standard system fields (CreatedById, CreatedDate, LastModifiedById, LastModifiedDate, and SystemModstamp) are documented in System Fields in the Salesforce Object Reference.

Note

The InsightsExternalData object is available in API version 31 and later.

Supported Calls

create(), delete(), describeSObjects(), query(), retrieve(), update(), upsert()

Fields

Field Details
Action
Type
Picklist
Properties
Create, Filter, Group, Sort, Update
Description

The action to perform on this data. Picklist values are:

Abort
Reserved for future use. The user no longer wants to upload the data and is requesting that the system stop processing, if possible.
Delete
Reserved for future use. The user wants to remove uploaded data parts as soon as possible. Implies that an Abort status is queued.
None
The user hasn’t completed the data upload. This value is the default when the object is created.
Process
The user completed the data upload and is requesting that the system process the data.
CompressedMetadataLength
Type
Int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The length of the compressed metadata .json file. This field is overwritten when data is uploaded. This system field isn’t editable.
Dataflow
Type
String
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
For dataflows that were created in API version 34.0 and later. The unique ID of the dataflow that was used to create the dataset. You can use this field to get the status of the dataflow. This system field isn’t editable.
Description
Type
String
Properties
Create, Filter, Nillable, Sort, Update
Description
The description of the dataset that is only used when creating the dataset.
EdgemartAlias
Type
String
Properties
Create, Filter, Group, Sort, Update
Description

The alias of a dataset, which must be unique across an organization. The alias must follow the same guidelines as other field names, except that they can’t end with “__c”. Can be up to 80 characters. For more information, see Field Names in the CRM Analytics External Data Format Developer Guide.
EdgemartContainer
Type
String
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The name of the app that contains the dataset.

  • If the name is omitted when you’re creating a dataset, the name of the user’s private app is used.
  • If the name is omitted for an existing dataset, the system resolves the app name.
  • If the name is specified for an existing dataset, the name is required to match the name of the current app that contains the dataset.

Use the developer name or the ID of the app for the name. To get the developer name or ID, run this query: 

SELECT Id,DeveloperName,Name, AccessType,CreatedDate,Type FROM Folder where Type = 'Insights'

For example, the display label of an app is Analytics Cloud Public Datasets, but the developer name is AnalyticsCloudPublicDatasets.

Note
EdgemartLabel
Type
String
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The display name for the dataset. Can be up to 255 characters.
FileName
Type
String
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Identifier of the external data file, such as the file name. A unique value isn’t required. It can contain only alphanumeric characters and underscores. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. The maximum file name is 255 characters.

CRM Analytics doesn’t populate this field. You can manually update it via the External Data API.

Note
Format
Type
Picklist
Properties
Create, Filter, Group, Sort, Update
Description
The format of the uploaded data. Picklist values are:
Csv
The data is in CSV format.
Binary
Reserved for Salesforce internal use.
isDependentOnLastUpload
Type
Boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description

Reserved for future use. When false, indicates that this upload depends on the previous upload to the same dataset name.
isIndependentParts
Type
Boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description

Reserved for future use. When true, indicates that file parts were divided on row boundaries and can be processed independently of each other. The default is false.
LicenseType
Type
picklist
Properties
Create, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
The license type of the external data file. Possible values are:
  • Aqs (Analytics Query Service)
  • Cdp (Data Cloud)
  • DataPipelineQuery (Data Pipeline Query)
  • EinsteinAnalytics (CRM Analytics)
  • IntelligentApps (Intelligent Apps)
  • Sonic (Salesforce Data Pipelines)
The default value is EinsteinAnalytics.
MetaDataLength
Type
Int
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The length of the metadata .json file. This field is overwritten when data is uploaded.

This system field isn’t editable.
MetadataJson
Type
Blob (Base64-encoded string)
Properties
Create, Nillable, Update
Description

Metadata in JSON format, which describes the structure of the uploaded file.

Mode
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
The upload mode for the data. Possible values are:
  • Incremental
  • None
The default value is None.
NotificationEmail
Type
String
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The email address to send notifications to. Can be up to 255 characters and can contain only one email address. Defaults to the current user’s email address.
NotificationSent
Type
Picklist
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

Indicates when to send notifications about the upload. Picklist values are:

Always
Always send notifications.
Never
Never send notifications.
Failures
Send notifications if the upload process failed.
Warnings
Send notifications if warnings occurred during the upload.
Success
Send notifications if the upload is successful.
SuccessFailures
Send notifications if the upload is successful or if the process failed.
WarningsFailures
Send notifications if warnings or failures occurred during the upload.
WarningsSuccess
Send notifications if the upload is successful or if warnings occurred during the upload.
The default value is 'WarningsFailures'.
Operation
Type
Picklist
Properties
Create, Filter, Group, Sort, Update
Description
Indicates which operation to use when you’re loading data into the dataset. Picklist values are:
Append
Append all data to the dataset. Creates a dataset if it doesn’t exist.

If the dataset or rows contain a unique identifier, the append operation isn’t allowed.

Note

Delete
Delete the rows from the dataset. The rows to delete must contain one (and only one) field with a unique identifier.
Overwrite
Create a dataset with the given data, and replace the dataset if it exists.
Upsert
Insert or update rows in the dataset. Creates a dataset if it doesn’t exist. The rows to upsert must contain one (and only one) field with a unique identifier. For more information about unique identifiers, see isUniqueId in the CRM Analytics External Data Format Developer Guide.

A metadata JSON file is required for the append, upsert, and delete operations. The data and metadata for the append and upsert operations must match the dataset on which the operation is happening. (All columns, dimensions, and measures must match exactly.) The metadata for the delete operation must be a subset of the dataset columns.

Note
Status
Type
Picklist
Properties
Create, Filter, Group, Sort, Update
Description
The status of this data upload. The initial value is null. Picklist values are:
Completed
The data upload job was completed successfully. Data parts are retained for 7 days after completion.
CompletedWithWarnings
The data upload job completed, but contains warnings. Data parts are retained for 7 days after completion.
Failed
The data upload job failed. Data parts are retained for 7 days after failure.
InProgress
The data upload job is in progress.
New
The data upload job has been created.
NotProcessed
The data upload job was aborted on user request. Data parts have been removed.
Queued
The data upload job has been scheduled. This system field isn’t editable.
The default value is New.
StatusMessage
Type
String
Properties
Create, Nillable, Update
Description
The reason for the file upload failed or has warnings. This system field isn’t editable.
SubmittedDate
Type
String
Properties
Create, Filter, Nillable, Sort, Update
Description
The time when the upload was submitted or set to Process. This system field isn’t editable.
Target
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description
The target for the external data. Valid values are Dataset.