Transcription
Tableau CRM External Data APIDeveloper GuideSalesforce, Spring ’[email protected] updated: February 24, 2022
Copyright 2000–2022 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.
CONTENTSExternal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Load External Data into a Dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1External Data API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
EXTERNAL DATAYou can integrate external data into Tableau CRM to make the data available for queries from explorer and designer.The External Data API enables you to upload external data files to Tableau CRM. The External Data API can upload .csv files, and you canoptionally specify the structure of your data by defining metadata in JSON format.The External Data API is available in API version 31 and later.The high-level steps for uploading external data by using the API are:1. Prepare your data in CSV format, and then create a metadata file to specify the structure of the data.2. Connect programmatically to your Salesforce organization.3. Configure the upload by inserting a row into the InsightsExternalData object, and then set input values such as the name of thedataset, the format of the data, and the operation to perform on the data.4. Split your data into 10-MB chunks, and then upload the chunks to InsightsExternalDataPart objects.5. Start the upload by updating the Action field in the InsightsExternalData object.6. Monitor the InsightsExternalData object for status updates, and then verify that the file upload was successful.Load External Data into a DatasetExternal Data API LimitsWhen working with the External Data API, consider the following limits, in addition to the general Tableau CRM limits.The following limits apply to all supported editions.LimitValueMaximum file size per external data uploads40 GBMaximum file size for all external data uploads in a rolling 24-hour 50 GBperiodMaximum number of external data jobs per dataset that can berun in a rolling 24-hour period50Maximum number of characters in a field32,000Maximum number of fields in a record5,000 (including up to 1,000 date fields)1
External DataPrepare Data FilesLimitValueMaximum number of characters for all fields in a record400,000Prepare Data FilesTo upload external data from .csv files into a dataset, first prepare your data files.External data can be loaded into a dataset by preparing two files. A data file, which contains the external data, in comma-separated value (CSV) format An optional metadata .json file, which describes the structure of the data fileNote: Providing a metadata file is recommended.The data and metadata files are used to populate a dataset with the external data. For detailed information about formatting CSV dataand JSON metadata, see the Tableau CRM Extended Metadata (XMD) Developer Guide.Connect to SalesforceAfter preparing your data files, the next step in loading external data into Tableau CRM is to connect to your Salesforce organization byusing standard Salesforce APIs.Note: The following examples use the SOAP API, but you can use any of the Salesforce APIs, such as the REST API or Apex. Theexamples assume that you’re using the Web Services Connector.To load external data into Tableau CRM, first connect to your Salesforce organization. Use the PartnerConnection object to log in to yourorganization, as shown in the following example. You’ll need to supply a username, password, and endpoint.ConnectorConfig config new ndpoint);PartnerConnection partnerConnection new PartnerConnection(config);For more information about the Web Services Connector (WSC), see Introduction to the Web Services Connectoron the SalesforceDevelopers website. For more information about user authentication, see Security and the API in the SOAP API Developer’s Guide.Configure the UploadConfigure the external data upload by inserting a row into the InsightsExternalData object and setting configuration values.After establishing a connection with Salesforce, insert a row into the InsightsExternalData object to configure and control the upload.The InsightsExternalData object provides a “header” that contains information about the upload, such as the name of the dataset, theformat of the data, and the operation to perform on the data. You can also provide the metadata file. The following example inserts arow into the InsightsExternalData object and sets configuration values.SObject sobj new Alias", Json);2
External DataAdd the tField("Action","None");SaveResult[] results partnerConnection.create(new SObject[] { sobj });for(SaveResult sv:results)if(sv.isSuccess())parentID sv.getId();Note: The WSC converts the metadata .json file to a Base64-encoded string, but if you’re using the REST API, you’ll need to makethis conversion yourself.For detailed information about the InsightsExternalData object, see InsightsExternalData.Add the DataWhen uploading external data files, you can use the InsightsExternalDataPart object to load the data in smaller chunks.After inserting a row into the InsightsExternalData (header) object, split your data into 10-MB chunks and upload the chunks toInsightsExternalDataPart objects. You associate the part objects with the header object by setting the InsightsExternalDataIdfield on the part objects to the ID of the header object. The part objects contain the bytes of data and must be assigned part numbersin a contiguous sequence, starting with 1.Ensure that the chunks of data are smaller than 10 MB. If the data is compressed, it must be compressed first and then split into 10-MBchunks. Only the gzip format is supported.The following example splits a file into 10-MB chunks, and then uploads the chunks to InsightsExternalDataPart objects.List File fileParts chunkBinary(dataFile); //Split the filefor(int i 0;i fileParts.size();i ){SObject sobj new ;sobj.setField("DataFile", obj.setField("InsightsExternalDataId", parentID);obj.setField("PartNumber",i 1); //Part numbers should start at 1SaveResult[] results partnerConnection.create(new SObject[] { sobj });for(SaveResult sv:results)if(sv.isSuccess())rowId sv.getId();}For detailed information about the InsightsExternalDataPart object, see InsightsExternalDataPart.Manage the UploadAfter you’ve created a header and uploaded the data parts by using the InsightsExternalData and InsightsExternalDataPartobjects, update the Action field on the header object to Process to start processing the data.The following example sets the Action field and updates the row in the InsightsExternalData object.SObject sobj new j.setField("Action","Process");3
External DataExternal Data API Referencesobj.setId(parentID); // This is the rowID from the previous example.SaveResult[] results partnerConnection.update(new SObject[] { sobj });for(SaveResult sv:results)if(sv.isSuccess())rowId sv.getId();When the Action field is set to Process, a dataflow job is created and marked active. You can monitor the Status field of theheader object to determine when the file upload is completed. After the Action field is updated to request processing, no user editsare allowed on the objects.External Data API ReferenceThe InsightsExternalData ObjectThe InsightsExternalData object enables you to configure and control external data uploads. You can use it to provide metadata, triggerthe start of the upload process, check status, and request cancelation 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 inserta row into the InsightsExternalData object. Data parts are then uploaded to InsightsExternalData objects. The Action field of theInsightsExternalData object is updated to start processing and request cancelations. After the Action field is updated to requestprocessing, no user edits are allowed on the objects, except to request cancelation.Note: The standard system fields (CreatedById, CreatedDate, LastModifiedById, LastModifiedDate, andSystemModstamp) are documented in “System Fields” in the SOAP API Developer’s Guide.The InsightsExternalData object is available in API version 31 and later.Supported Callscreate(), delete(), describeSObjects(), query(), retrieve(), update(), tiesCreate, Filter, Group, Sort, UpdateDescriptionThe action to perform on this data. Picklist values are:AbortReserved for future use. The user no longer wants to upload the data and is requestingthat the system stop processing, if possible.4
External DataFieldThe InsightsExternalData ObjectDetailsDeleteReserved for future use. The user wants to remove uploaded data parts as soon aspossible. Implies that an Abort status is queued.NoneThe user has not completed the data upload. This value is the default when the objectis created.ProcessThe user has completed the data upload and is requesting that the system process thedata.CompressedMetadataLength TypeIntPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe length of the compressed metadata .json file. This field is overwritten when data isuploaded. This system field is not editable.DataflowTypeStringPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionFor dataflows that were created in API version 34.0 and later. The unique ID of the dataflowthat was used to create the dataset. You can use this field to get the status of the dataflow.This system field is not editable.DescriptionTypeStringPropertiesCreate, Filter, Nillable, Sort, UpdateDescriptionThe description of the dataset that is only used when creating the dataset.EdgemartAliasTypeStringPropertiesCreate, Filter, Group, Sort, UpdateDescriptionThe alias of a dataset, which must be unique across an organization. The alias must followthe same guidelines as other field names, except that they can’t end with “ c”. Can be up5
External DataFieldThe InsightsExternalData ObjectDetailsto 80 characters. For more information, see Field Names in the Tableau CRM External DataFormat Developer Guide.EdgemartContainerTypeStringPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe 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 privateapp 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 nameof the current app that contains the dataset.Note: Use the developer name or the ID of the app for the name. To get the developername or ID, run the following query:SELECT Id,DeveloperName,Name, AccessType,CreatedDate,TypeFROM Folder where Type 'Insights'For example, the display label of an app is Analytics Cloud Public Datasets, but thedeveloper name is ngPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe display name for the dataset. Can be up to 255 characters.FileNameTypeStringPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionIdentifier of the external data file, such as the file name. The value does not have to be unique.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.Note: Tableau CRM doesn’t populate this field. You can manually update it via theExternal Data API.6
External DataThe InsightsExternalData te, Filter, Group, Sort, UpdateDescriptionThe format of the uploaded data. Picklist values are:CsvThe data is in CSV format.BinaryReserved for Salesforce internal use.isDependentOnLastUpload TypeBooleanPropertiesCreate, Defaulted on create, Filter, Group, Sort, UpdateDescriptionReserved for future use. When false, indicates that this upload depends on the previousupload to the same dataset , Defaulted on create, Filter, Group, Sort, UpdateDescriptionReserved for future use. When true, indicates that file parts have been divided on rowboundaries and can be processed independently of each other. The default is false.LicenseTypeTypepicklistPropertiesCreate, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort, UpdateDescriptionThe license type of the external data file. Possible values are: EinsteinAnalytics SonicThe default value is 'EinsteinAnalytics'.MetaDataLengthTypeInt7
External DataFieldThe InsightsExternalData ObjectDetailsPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe length of the metadata .json file. This field is overwritten when data is uploaded.This system field is not editable.MetadataJsonTypeBlob (Base64-encoded string)PropertiesCreate, Nillable, UpdateDescriptionMetadata in JSON format, which describes the structure of the uploaded file.NotificationEmailTypeStringPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe email address to send notifications to. Can be up to 255 characters and can contain onlyone email address. Defaults to the current user’s email te, Filter, Group, Nillable, Sort, UpdateDescriptionIndicates when to send notifications about the upload. Picklist values are:AlwaysAlways send notifications.NeverNever send notifications.FailuresSend notifications if the upload process failed.WarningsSend notifications if warnings occurred during the upload.SuccessSend notifications if the upload is successful.SuccessFailuresSend notifications if the upload is successful or if the process failed.8
External DataFieldThe InsightsExternalData ObjectDetailsWarningsFailuresSend notifications if warnings or failures occurred during the upload.WarningsSuccessSend notifications if the upload is successful or if warnings occurred during the upload.The default value is Create, Filter, Group, Sort, UpdateDescriptionIndicates which operation to use when you’re loading data into the dataset. Picklist valuesare:AppendAppend all data to the dataset. Creates a dataset if it doesn’t exist.Note: If the dataset or rows contain a unique identifier, the append operationis not allowed.DeleteDelete the rows from the dataset. The rows to delete must contain one (and only one)field with a unique identifier.OverwriteCreate a dataset with the given data, and replace the dataset if it exists.UpsertInsert or update rows in the dataset. Creates a dataset if it doesn’t exist. The rows toupsert must contain one (and only one) field with a unique identifier. For moreinformation about unique identifiers, see isUniqueId in the Tableau CRM External DataFormat Developer Guide.Note: 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 dataseton which the operation is happening. (All columns, dimensions, and measures mustmatch exactly.) The metadata for the delete operation must be a subset of the datasetcolumns.StatusTypePicklistPropertiesCreate, Filter, Group, Sort, UpdateDescriptionThe status of this data upload. The initial value is null. Picklist values are:9
External DataFieldThe InsightsExternalData ObjectDetailsCompletedThe data upload job was completed successfully. Data parts are retained for seven daysafter completion.CompletedWithWarningsThe data upload job completed, but contains warnings. Data parts are retained for sevendays after completion.FailedThe data upload job failed. Data parts are retained for seven days after failure.InProgressThe data upload job is in progress.NewThe data upload job has been created.NotProcessedThe data upload job was aborted on user request. Data parts have been removed.QueuedThe data upload job has been scheduled. This system field is not editable.The default value is 'New'.StatusMessageTypeStringPropertiesCreate, Nillable, UpdateDescriptionThe reason for the file upload failed or has warnings. This system field is not editable.SubmittedDateTypeStringPropertiesCreate, Filter, Nillable, Sort, UpdateDescriptionThe time when the upload was submitted or set to Process. This system field is not editable.TargetTypepicklistPropertiesCreate, Filter, Group, Nillable, Restricted picklist, Sort, UpdateDescriptionThe target for the external data. Valid values are Dataset.10
External DataThe InsightsExternalDataPart ObjectThe InsightsExternalDataPart ObjectThe InsightsExternalDataPart object enables you to upload an external data file that has been split into parts.The InsightsExternalDataPart object works with the InsightsExternalData object. After you insert a row into the InsightsExternalDataobject, you can create part objects to split up your data into parts. If your initial data file is larger than 10 MB, split your file into parts thatare smaller than 10 MB.Note: The standard system fields (CreatedById, CreatedDate, LastModifiedById, LastModifiedDate, andSystemModstamp) are documented in “System Fields” in the SOAP API Developer’s Guide.The InsightsExternalDataPart object is available in API version 31 and later.Supported Callscreate(), delete(), describeSObjects(), query(), retrieve(), update(), IntPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe length of the compressed data. This field is overwritten when data is uploaded.DataFileTypeBlob (Base64-encoded string)PropertiesCreate, Nillable, UpdateDescriptionThe data bytes. Parts are required to be smaller than 10 MB. For data greater than 10 MB,compress the file and then split it into parts. Only the gzip format is supported.DataLengthTypeIntPropertiesCreate, Filter, Group, Nillable, Sort, UpdateDescriptionThe length of the data. This field is overwritten when data is uploaded.InsightsExternalDataIdTypeString11
External DataFieldThe InsightsExternalDataPart ObjectDetailsPropertiesCreate, Filter, Group, SortDescriptionThe ID of the InsightsExternalData object that this part belongs to.PartNumberTypeIntPropertiesCreate, Filter, Group, Sort, UpdateDescriptionThe part number. Part numbers are required to be in a contiguous sequence, starting with1. (For example, 1, 2, 3, etc.)12
Note: Use the developer name or the ID of the app for the name. To get the developer name or ID, run the following 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 .
