File Upload

Operation Name

File Upload

Function Overview

This operation is upload/update a file to the ContentVersion.
After uploading, you can also retrieve the ContentDocument ID of the uploaded file.

You can retrieve the results of each record corresponding to the input data from the output schema.

Refer to File Upload usage example for an example of using this operation.

This operation uses the following API.

SOAP API
- login()
- retrieve()
REST API
- sObject Basic Information
- sObject Rows
- sObject Rows by External ID

With regarding to the API specification utilized by this operation, please refer to the version of the API document, selected for the global resource, in the below-mentioned link.

Salesforce Developer Documentation -(https://developer.salesforce.com/docs)
- SOAP API Developer's Guide
- REST API Developer's Guide

Data Model

The data model of this component is the Table Model type.

Properties

For information about using variables, refer to "variables".

Basic Settings

Item name	Required/Optional	Use of Variables	Description	Supplement
Name	Required	Not Available	Enter the name that appears on the script canvas.
Input Data	Required	Not Available	Select the component on the script canvas.

Required Settings

Item name	Required/Optional	Use of Variables	Description	Supplement
Destination	Required	Not Available	Select Global Resources. [Add...]: Add new global resource. [Edit...]: Global resource settings can be edited by [Edit Resource list].	Available for the resource type is API 43.0 or later. This component has global resource properties that are not affected. For details, please refer to Unaffected global resource property.
Schema definition	Required	-	Set items subject to writing to the ContentVersion of Salesforce.	Limiting the settings to only items needed to be written to Salesforce (deleting unnecessary items from the Schema Definition) helps improve processing performance. When [PATCH] is selected in [HTTP Method], the items selected in [External ID field] must be set. For a sample configuration, please refer to File Upload usage example.
Schema definition/Label	Required	Not Available	Display the lable name of the column.
Schema definition/API	Required	Not Available	Display the API name of the column.
Schema definition/Type	Required	Not Available	Display the data type of the column.
Relationship definition	Optional	-	In the case that relationship items exist in the Schema Definition, set items subject to updating by external key. By selecting the external key item of the relation counterpart object, it becomes possible to pass data with an established relationship.	For details, please refer to Relationship Definition.
Relationship definition/Base field	Required	Not Available	Display the API Name of the row of the relation item.
Relationship definition/Relationship name	Required	Not Available	Display the relationship name of the row of the relation item.
Relationship definition/Related Object	Optional	Not Available	Select the API Name of the relation counterpart object in the relation item column.
Relationship definition/Foreign key field	Optional	Not Available	Select the external key item of the relation counterpart object in the relation item column.	If omitted, the ID of the relevant record of the relation counterpart object will be passed.

Property Action

Item name	Description	Supplement
Create schema...	The items to be read from Salesforce can be added/deleted. For setting methods, please refer to "Create Schema."

Option Settings

Item name	Required/Optional	Use of Variables	Description	Supplement
HTTP Method	Required	Not Available	Select the HTTP method to use with the REST API. [POST]:(default) Execute the request using the HTTP POST method. [PATCH]: Execute the request using the HTTP PATCH method.	If you are creating a new record, select [POST]. Examples: Upload a new file Add a new version of a file If you want to update the record, select [PATCH]. Examples: Update file titles and descriptions Insert/Update(Upsert) Record using External ID (or ID) For a sample configuration, please refer to File Upload usage example.
External ID field	Optional	Not Available	Select the external ID field to be the key for the update process.	This becomes valid and required when [PATCH] is selected for the [HTTP Method]. Selected [External ID field] must be set to [Schema definition].
Handling of null values	Optional	Not Available	If the input data for the field to be updated is null, choose whether to overwrite with null or skip the update of that item. [Field value to null]:(default) If the input data is null, overwrite the field to be updated with null. [Skip null values]: If the input data is null, the update of the field to be updated is skipped and the state before the update is maintained. If the input data is not null, the field being updated is overwritten with the input data.	This becomes valid when [PATCH] is selected for the [HTTP Method].
Getting ContentDocumentId	Optional	Not Available	Select whether to get the ContentDocument ID of the uploaded file. [Checked]:(default) Get the ContentDocumentId. [Not Checked]: Do not get the ContentDocumentId.	If [Checked] was selected, the acquired ContentDocumentId can be passed onto the subsequent processing as Table Model type data. For details, please refer to Get ContentDocumentId.

Property Action

Item name	Description	Supplement
Read schema definition from file...	Select a file from the file chooser and read the name of field API on the first line of the file specified in the comma-separated values. Set this as the schema definition.	Please specify "UTF-8" encoding for the selected file.

Large Data Processing Settings

Item name	Required/Optional	Use of Variables	Description	Supplement
Large Data Processing	Required	Not Available	Select a Large Data Processing Settings. [Use the setting in the script]:(default) Apply Large Data Processing Settings settings of script property to adapter. [Disable Large Data Processing]: Large Data Processing is not performed. [Enable Large Data Processing]: Large Data Processing is performed.

Comment

Item name	Required/Optional	Use of Variables	Description	Supplement
Comment	Optional	Not Available	You can write a short description of this adapter. The description will be reflected in the specifications.

Schema

Input Schema

The number of columns varies depending on the [Schema definition] settings.

Output Schema

Information regarding the results of file upload will appear in the column, set in the [Schema definition].

<?xml version="1.0" encoding="UTF-8" ?>
<table>
  <row>
    <column>API set in the [Schema definition]</column>
       :
    <column>result_id</column>
    <column>result_is_success</column>
    <column>result_is_created</column>
    <column>result_error_status_code</column>
    <column>result_error_message</column>
    <column>result_row_number</column>
    <column>result_content_document_id</column>
  </row>
  <row>
    :
  </row>
</table>

Element Name	Column Name	Description	Supplement
row	-	Repeats as many times as the number of data given to the input schema.
column	result_id	ContentVersion ID is output.	Output only when a new record is created.
	result_is_success	Success Flag is output. [true]:Successfully processed [false]Process failedPlease check the[result_error_status_code] as well as [result_error_message].
	result_is_created	Create Flag is output. [true]:A record is created. [false]:No record is created.
	result_error_status_code	The status code, returned by the Salesforce API, is output.	In the below-mentioned case, the Salesforce adapter will output the code and message. SALESFORCE_ADAPTER_ILLEGAL_DATA_TYPE Set when the defined item type and input data type do not match. For example, if the item is defined as "date" but a character string is input (not a date).
	result_error_message	The message returned by the Salesforce API is output.
	result_row_number	Number is output based on the placement of the node within the data given to the input schema.
	result_content_document_id	Output the ContentDocumentId of the ContentVersion.	If [Getting ContentDocumentId] is [Not Checked], it will be null. Even if [Getting ContentDocumentId] is set to [Checked], it may be null. For details, please refer to Getting ContentDocumentId.

Reading Schema by Mapper

The schema will be read automatically.

Large Data Processing

Large Data Processing is supported.

Transaction

Transaction is not supported.

Usage on PSP Script

Cannot be used on PSP Script.

Available Component variables

Component Variable Name	Description	Supplement
insert_count	The number of data that was successful in the addition processing is stored.	The default value is null.
update_count	The number of data that was successful in the updating processing is stored.	The default value is null.
error_count	The number of data that was unsuccessful in the addition/updating processing is stored.	The default value is null.
read_count	The number of input data is stored.	The default value is null.
server_url	The end point URL after Login is stored.	The default value is null.
session_id	The session Id is stored.	The default value is null.
message_category	In the case that an error occurs, the category of the message code corresponding to the error is stored.	The default value is null.
message_code	In the case that an error occurs, the code of the message code corresponding to the error is stored.	The default value is null.
message_level	In the case that an error occurs, the importance of the message code corresponding to the error is stored.	The default value is null.
operation_error_message	If an error occurs, the error message of the occured error is stored.	The default value is null. The content to be stored may change according to the version of DataSpider Servista.
operation_error_trace	When an error occurs, the trace information of the occured error is stored.	The default value is null. The content to be stored may change according to the version of DataSpider Servista.

Relationship definition

By taking in this setting, the automatical obtainment and updating of the ID of the record which responds to the external key, becomes possible by passing the value of the external key item of the reference object.

Example: Updating (INSERT, UPDATE, UPSERT) the "ContentVersion"

Details of the example

Category	Description	Supplement
Specification Requirements	Regarding to the update processing of "ContentVersion", it needs to set the referring object ID in the the "Contact" ID item (Reference Item). As for the relationship to the referring "Contact", it needs to tie to the record according to the ContactCode of the input data.
Settings	Upon updating to "ContentVersion", by passing the value of the Contact Code (External key item created before hand: ContactCode__c) of the "Contact", which is the referred object, to Mapper, the ID of the corresponding referred object is automatically obtained and set the relationship to the "Contact" ID Item (Reference Item).	The items and some of the settings used in this description are usage examples. This is something that is not always in the Salesforce organization that you are using. Please use this function after adjusting and verifying your settings.

Coordination Image

Number in the Image	Name	Description	Supplement
(1)	The Data Image of the "Contact"	This is the data image of the object which is refered by the "ContentVersion".
(2)	The External Key of the "Contact"	Pre set "ContactCode__c" as external key.
(3)	Data Input Image	This is the data input image, for updating to the "ContentVersion".	This is the data which has the "ContactCode__c".
(4)	Settings for the updating (INSERT, UPDATE, UPSERT) to the "ContentVersion"	Here, the "Title", "Path On Client", "Version Data", "ContactId" are the four considered items for updating.
(5)	Relationship Definition Setting	The external key of the referred object in "Foreign key field" be selected. Here, the external key "Contact.ContactCode__c" is selected as the key item for setting the relationship.	If no value is selected, the ID of the corresponding record of the referred object will be passed to Mapper.
(6)	The Updating Results Data Image of the "ContentVersion"	This is the updating results data image of the "ContentVersion".	The relationship is correctly setup to accomodate the record that responded to the "ContactCode__c".

Create Schema

The data items to be written into Salesforce can be specified in the creation of a schema.
By specifying only the items indispensable for processing, the data traffic to Salesforce can be reduced, generally improving the processing performance.
When writing into Salesforce (adding or updating), it is necessary to make sure that the items "Not Creatable" and "Not Updatable" are not be chosen.

Number in the Image	Name	Description	Supplement
(1)	Selected Fields	Select items for writing to Salesforce.
(2)	UnSelected Fields	Select items not for writing to Salesforce.	You can filter fields by inputting or selecting values from the input above the column name. Text fields will be filtered as Starting With the input value.

File Upload usage example

An example is shown below.

For details on the ContentVersion object, please refer to the version of the API document, selected for the global resource, in the below-mentioned link.

Salesforce Developer Documentation -(https://developer.salesforce.com/docs)
- Object Reference for Salesforce and Lightning Platform

Example1: Upload a new file

Set the following items in [Schema definition].

Label	API	Type	Supplement
Title	Title	string	If not selected in [Schema definition] or selected in [Schema definition] and the input data is null, the file name is saved with the file path and extension excluded from the input data of the "PathOnClient" item.
Path On Client	PathOnClient	string	The file must include the extension in order to appear in the Salesforce [Preview] tab. Example: /data/file.txt
Version Data	VersionData	base64	Set the file path for the input data. Example: /data/file.txt Specify the file path with the absolute path of the DataSpider filesystem. restrictions on characters used in DataSpider filesystem other than the path delimiter '/' is not allowed.

Select [POST] for [HTTP Method].

Example2: Add a new version of a file

Set the following items in [Schema definition].

Label	API	Type	Supplement
Title	Title	string	If not selected in [Schema definition], the title before upgrading is retained. If you selected in [Schema definition] and the input data is null, the file name is automatically saved with the file path and extension excluded from the input data of the "PathOnClient" item.
Path On Client	PathOnClient	string	The file must include the extension in order to appear in the Salesforce [Preview] tab. Example: /data/file.txt
Version Data	VersionData	base64	Set the file path for the input data. Example: /data/file.txt Specify the file path with the absolute path of the DataSpider filesystem. restrictions on characters used in DataSpider filesystem other than the path delimiter '/' is not allowed.
ContentDocument ID	ContentDocumentId	reference	Set the ContentDocument ID of the file you want to version up to the input data.

Select [POST] for [HTTP Method].

Example3: Update file Title and Description

Set the following items in [Schema definition].

Label	API	Type	Supplement
ContentVersion ID	Id	id	Set the ContentVersion ID of the file in the input data.
Title	Title	string
Description	Description	textarea

Select [PATCH] for [HTTP Method].

Select [Id (ContentVersion ID)] for [External ID field].

Example4: Insert/Update(Upsert) Record using External ID (or ID)

If a line matching the value of the external ID (or ID) already exists in Salesforce, the line is updated, and if not, the line is added and updated (Update for ID) by Salesforce.
Depending on the [Schema definition] selection, Salesforce may encounter errors during the update. (For example, When trying to update "PathOnClient")

Set the following items in [Schema definition].

Label	API	Type	Supplement
Title	Title	string	Refer to Example1.
Path On Client	PathOnClient	string
Version Data	VersionData	base64
<External ID Item Label>	<External ID Item Label API>	<External ID Item Label Type>	When creating a schema, select the item with "External ID" checked. To select here, create an external ID field in advance using the Salesforce customization function. Check the External ID "Set this field as the unique record identifier from an external system" from the screen for entering details of creating a new item.

Select [PATCH] for [HTTP Method].

Select [<External ID Item Label API>] for [External ID field].

Getting ContentDocumentId

By doing this setting, you get the ContentDocumen ID of the uploaded file.
ContentDocumen ID is then stored in the [result_content_document_id] for the output schema and can be subsequently passed as data of the table model type.

If select [PATCH] for [HTTP Method] and an existing record is updated, [result_content_document_id] in the output schema will be null.

Example: Get the ContentDocumen ID of the uploaded file and link it to Contact

Number in the Image	Name	Description
(1)	Input Data Image	This is a sample image of data input, for updating to the "ContentVersion".
(2)	Setting whether to acquire ContentDocument ID	Set [Getting ContentDocumentId] in the [Option Settings] tab to [Checked].
(3)	Script Image	This is the script implementation image of this description.
(4)	File linking image	It is an image of the Salesforce details page of Contact that linked the file updated in ContentVersion.

Unaffected global resource property

This component refers to global resource property and uploads files using REST API.
The following settings are unaffected because they are properties related to the SOAP API.

For details, please refer toGlobal Resource Property.

Option Settings

Item name	Supplement
Field value truncation	It is not affected. If the input data is too large, the update will fail and print "STRING _TOO_LONG" to [result_error_status_code] in the output schema.

SOAP Header Setting

Item name	Supplement
AllOrNone Header (allOrNone)	It is not affected. File Upload executes one REST API for each input data. In case of multiple input data, input data without error is committed, but input data with error is stored in the output schema.
Email Header (triggerAutoResponseEmail)	It is not affected.
Email Header (triggerOtherEmail)
Email Header (triggerUserEmail)
Mru Header (updateMru)	It is not affected.
AssignmentRule Header (useDefaultRule)	It is not affected. File Upload executes the REST API so that a valid AssignmentRule is applied. Assignment rule ID cannot be specified. For details, please refer to the "AssignmentRuleHeader" page of the API document "REST API Developer's Guide".
AssignmentRule Header (assignmentRuleId)
DisableFeedTracking Header (disableFeedTracking)	It is not affected.
DuplicateRule Header (allowSave)	It is not affected.

Specification Limits

In order to perform data reading and writing with this adapter, API's of Salesforce organization must be published.

All permissions for reading/writing data and other operations, as well as data access control, depend upon the profile, shared rule setting and API specifications in Salesforce.

The objects and fields that can be used may differ by API version. For details, please refer to the Salesforce documentation.

The maximum size when uploading a file with the REST API is 2GB (including the header). For details, please refer to Salesforce documentation.

Main exceptions

Exception Name	Reason	Resolution
ResourceNotFoundException Resource Definition is Not Found. Name:[]	[Destination] is not specified.	Specify [Destination].
ResourceNotFoundException Resource Definition is Not Found. Name:[<Global Resource Name>]	The resource definition selected in [Destination] cannot be found.	Verify the global resource specified in [Destination]
java.net.UnknownHostException	This exception occurs when the PROXY server specified in the global resource cannot be found.	Verify the condition of the PROXY server. Or verify [Proxy host] of the global resource specified in the [Destination].
java.net.SocketTimeoutException connect timed out	A time-out has occurred while connecting to Salesforce.	Verify the network condition and Salesforce server condition. Or check [Connection timeout(sec)] of the global resource specified in the [Destination].
java.net.SocketTimeoutException Read timed out	A time-out has occurred while waiting for a responce from the server after connecting to Salesforce.	Verify the network condition and Salesforce server condition. Or check [Timeout(sec)] of the global resource specified in the [Destination].
jp.co.headsol.salesforce.adapter.exception.SalesforceAdapterIllegalArgumentException	Invalid value is set for the property of Salesforce adapter.	Check the error message, and verify the settings.
com.sforce.soap.partner.fault.LoginFault	Login to Salesforce has failed.	Check the ExceptionCode or error message, and refer to the information about this type of error in Salesforce-related documents etc.
com.sforce.soap.partner.fault.UnexpectedErrorFault	An unexpected error has occured while processing to Salesforce.	Check the ExceptionCode or error message, and refer to the information about this type of error in Salesforce-related documents etc.

Notes

This operation cannot perform a rollback when an error occurs, unlike the database adapters. Succeeded data are updated while error data are left not to be updated and the processing log in WARN level is output.
Therefore, if errors exist in units of data (constraint violation and invalid value, etc.), those errors cannot be detected by monitoring exceptions in a script.
If you want to use the error information for each data, then use the results data for handling error detection etc. in the subsequent processing.

If the Foreign key field in the relationship definition is specified as numeric type, and a value is written beyond the precision of the Java Double data type, the result value will be rounded.
Specify the field as text type to avoid the value from rounding off.

The data type is defined for the fields of the object. The API sends and receives data according to the defined data type format rules, but this adapter extends the rules for some data types.
For details, please refer to Data Type Format.