Read Data (Retrieve by ID)

Operation Name

Read Data (Retrieve by ID)

Function Overview

This operation is to read data which match the IDs specified by input data, using the retrieve() call of the SOAP API.

In general, when the ID of the record to be retrieved is known ahead of time, use retrieve().
When you do not know the ID or would like to specify additional filter criteria, use query() instead.
For the usage example of this operation, please refer to Usage Example of Retrieve by 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.

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].
  
Table Name Required Not Available Select the name of a table in Salesforce.  
Input Schema definition Required - The table ID specified by the Table Name is automatically selected.
Corresponding to the ID specified as Input Schema, the Salesforce ID will be passed from other operations.
  • This item is not editable.
Input Schema definition/Label Required Not Available Display the lable name of the column of the table specified in [Table Name].  
Input Schema definition/API Required Not Available Display the API name of the column of the table specified in [Table Name].  
Input Schema definition/Type Required Not Available Display the data type of the row of the table specified in [Table Name].  
Output Schema definition Required - Set items to be read from Salesforce.
  • Limiting the settings to only items needed in the subsequent processing (deleting unnecessary items from the Schema Definition) helps improve processing performance.
Output Schema definition/Label Required Not Available Display the lable name of the column of the table specified in [Table Name].  
Output Schema definition/API Required Not Available Display the API name of the column of the table specified in [Table Name].  
Output Schema definition/Type Required Not Available Display the data type of the row of the table specified in [Table Name].  
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
Column name type Required Not Available Choose the display type of the column name, for displaying the schema in mapping.
  • [Label]:
    The label name (item name) defined in Salesforce is displayed.
  • [API] :(default)
    The API reference name defined in Salesforce is displayed.
  
Batch size Required Available Specify a batch size for obtaining the data reading results from Salesforce.
  • The default value is "2000".
  • A number of 1 or greater, up to 2000, can be set. An error occurs if any number outside of this range is set.
  • Depending on the operating environment, increasing the batch size generally helps improve the performance of the read data operation.
  • According to the Salesforce API specifications, if you set a batch size to 2000 when reading 10,000 records, the result data set will be obtained in 5 parts.
Property Action
Item name Description Supplement
Display Table Information... You can check the table structure of the object you are operating.
For more information on how to view the table structure, please refer to Display Table Information		 Click [Load All Table Information....] if you would like to check the table structure of other objects.
Load All Table Information... Retrieve all possible table information
After running, you can verify the retrieved information from [Table Information].		  
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.
File Output Settings
Item name Required/Optional Use of Variables Description Supplement
Base64 field output form Required - Specify the data output format of fields with data type Base64.
  • [Base64 data]:(default)
    Pass the Base64 data read from the output schema as is.
  • [File output]:
    Output as a file.
    Pass the file path output in the output schema.
  • When the read schema does not contain Base64 data type fields, please select [Base64 Data].
Directory Optional Available Input the directory to which to output.
Click the [browse] button to open a directory selector to choose a directory.
Data Field Optional - Select fields of data type Base64 from the fields contained in the [schema definition].
  • Will be enabled when [File Output] is selected from [Base64 field output form].
  • When the [schema definition] does not contain Base64 data type fields, please select [Base64 Data]
How to set the File Name Optional - Select how to input the output file name.
  • [Select a field]:(default)
    Select the field to be used as the file name from the fields contained in the [schema definition].
  • [Enter String]:
    Input the string to be used as the file name.
  • Will be enabled when [File Output] is selected from [Base64 field output form].
File Name Optional - Specify the output file name.
  • Will be enabled when [File Output] is selected from [Base64 field output form].
  • When [How to set File Name] is set to [Select a field], this will become a selection list.
  • When [How to set File Name] is set to [Enter String], this will become a text field. In this case you can also use variables.
  • If characters are included that are incompatible with the DataSpider file system, they will be converted to underscores (_) at output time.
How to set an Additional String Optional - Select the method to append characters to the output file name.
  • [Do not add]:(default)
    Do not append characters to the output file name.
  • [Select a field]:
    Select the field to be used as appended characters from the fields contained in the [schema definition].
  • [Enter String]:
    Input the string to be used as the appended characters.
  • Will be enabled when [File Output] is selected from [Base64 field output form].
Additional String Optional - Specify the appended string to be added to the output file name.
  • Will be enabled when [File Output] is selected from [Base64 field output form] and [Select a field] or [Enter String] is selected from [How to set Additional String].
  • When [How to set Additional String] is set to [Select a field], this will become a selection list.
  • When [How to set Additional String] is set to [Enter String], this will become a text field. In this case you can also use variables.
  • If characters are included that are incompatible with the DataSpider file system, they will be converted to underscores (_) at output time.
Additional Position Optional - Select the position of the string to be added to the output file name.
  • [Prefix]:(default)
    Add to the beginning of the file name.
  • [Suffix]:
    Add to the end of the file name. When the file contains an extension, add just before the dot (.).
  • Will be enabled when [File Output] is selected from [Base64 field output form] and [Select a field] or [Enter String] is selected from [How to set Additional String].
Delimiter Optional Available Input the delimiter between the output file name and the additional string.
When a delimiter is not necessary you can leave it out.
  • Will be enabled when [File Output] is selected from [Base64 field output form] and [Select a field] or [Enter String] is selected from [How to set Additional String].
  • If characters are included that are incompatible with the DataSpider file system, they will be converted to underscores (_) at output time.
How to set an Extention Optional - Select how to input the output file name extension.
  • [Include in file name]:(default)
    Specify the file name including extension.
  • [Select a field]:
    Select the field to be used as the file extension from the fields contained in the [schema definition].
  • [Enter String]:
    Input the string to be used as the file extension.
  • Will be enabled when [File Output] is selected from [Base64 field output form].
Extention Optional - Specify the extension of the output file name.
  • Will be enabled when [File Output] is selected from [Base64 field output form] and [Select a field] or [Enter String] is selected from [How to set Extension].
  • When [How to set Extension] is set to [Select a field], this will become a selection list.
  • When [How to set Extension] is set to [Enter String], this will become a text field. In this case you can also use variables.
  • If characters are included that are incompatible with the DataSpider file system, they will be converted to underscores (_) at output time.
  • Uppercase letters will be converted to lowercase at file output time.
  • When the specified string does not contain a dot (.), it will be added automatically.
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

<?xml version="1.0" encoding="UTF-8" ?>
<table>
  <row>
    <column>The ID items of the table specified by [Table Name]</column>
  </row>
  <row>
    :
  </row>
</table>
Element Name Column Name Description Supplement
row
-
 Repeats as many times as the number of input data.  
column The ID item of the table specified by [Table Name] Passes the Salesforce ID.  

Output Schema

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

Reading Schema by Mapper

The schema will be read automatically.

Large Data Processing

Large Data Processing is supported.

Usage on PSP Script

Cannot be used on PSP Script.

Available Component variables

Component Variable Name Description Supplement
input_count The number of IDs passed as input data is stored.
  • The default value is null.
output_count The number of data read is stored.
  • The default value is null.
error_count The number of data that were skipped as invalid data (such as null), out of IDs passed as 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_api_exception_code The ExceptionCode of the occured error, in a case of API error, is stored.
  • The default value is null.
  • For any error other than an API Error, the value is not stored.
  • The content to be stored may change according to the version of DataSpider Servista.
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.

Usage Example of Retrieve by ID

In cases where the Salesforce ID can be obtained from other operations, data can be effectively read from Salesforce by performing searches by ID.
Furthermore, by combining this operation with Read Data (Query) and Merge Mapper, processing results comparable to table-join can be obtained.


Number in the Image Name Description Supplement
(1) Data Reading (Query) Process Reads Opportunity data from Salesforce, using the data reading (query) process. (The Account ID is included in the items read).  
(2) Mapper Using Mapper, maps the Account ID of the Opportunity data read in (1), to a succeeding process.  
(3) Data Reading (Retrieve by ID) Using the data reading (search by ID) process, reads the Account data from Salesforce, based on the Account ID given by the Mapper in (2).  
(4) Merge Mapper Merges the Opportunity data, read in (1) and the Account data, read in (3), with the Account ID as a key.  
(5) Excel Writing Outputs the results, merged in (4), to an EXCEL file.  

Create Schema

The data items to be read from and/or 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.



Number in the Image Name Description Supplement
(1) Selected Fields Select items for reading from and/or writing to Salesforce.  
(2) UnSelected Fields Select items not for reading from and/or 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.

Display Table Information

This display shows the available operations on Salesforce tables as well as field properties of the tables.
Also, the field information can be printed out.



Number in the Image Name Description Supplement
(1) Table Name Select the table whose structure to be shown.  
(2) Table Information Display the available operations on the selected table.  
(3) Length Display the Number of Digit of item  
(4) External ID Display whether or not the object item is set as an external ID.  
(5) Createble Display whether or not it can be set a value when adding data.  
(6) Updatable Display whether or not it can be set a value when updating data.  
(7) Nullable Display whether or not it can be set NULL when adding or updating data.  
(8) Default value Display whether or not Salesforce automatically set a default value when adding data.  
(9) Reference To Display the referring object name if the item is in reference relationship or master-servant relationship.  

Specification Limits

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].
  • API 23.0 or earlier
    org.apache.commons.httpclient.HttpConnection$ConnectionTimeoutException
  • API 26.0 or later
    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].
  • API 23.0 or earlier
    org.apache.commons.httpclient.HttpRecoverableException
    java.net.SocketTimeoutException: Read timed out
  • API 26.0 or later
    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.InvalidIdFault The ID value passed to Salesfroce is invalid. 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