Read Data(Child-Parent Relation)

Operation Name

Read Data(Child-Parent Relation)

Function Overview

This operation is to read data, using the query() or queryAll() call of the SOAP API.

We will specify filter criteria with SOQL(Sforce Object Query Language) but with this component, you may set the filters without directly writing SOQL.
However, you can still directly write after the WHERE clause.

This component can make use of child-to-parent relationships and functions.
Furthermore, aggregate functions can be used in the items selected in the schema definition, and by using it in combination with aggregate conditions (GROUP BY clause, etc.), the results of the aggregate functions, based on the aggregate conditions, can be obtained.

child-to-parent relationships beyond 2 levels cannot be used.

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.  
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].
  • A global resource on API 18.0 or later versions can be specified.
Table Name Required Not Available Select the name of a table in Salesforce.  
Schema definition Required - Set items to be read from Salesforce.
  • Limiting the settings to only items needed in the subsequent processes (deleting unnecessary items from the Schema Definition) helps improve processing performance.
Schema definition/Label Required Not Available Display the lable name of the column of the table specified in [Table Name].  
Schema definition/API Required Not Available Display the API name of the column of the table specified in [Table Name].  
Schema definition/Type Required Not Available Display the data type of the column of the table specified in [Table Name].  
Schema definition/Function Required Not Available Specify an aggregate function in the column of the table specified in the [Table Name], or in the column of the parent table.
  • Should be configured as "SUM" for SUM function, and "MAX" in the case for MAX function.
  • In cases where the aggregate functions, such as the SUM function and AVG function, surpass the precision of numerical values, the values may not be obtained correctly.
SOQL(filter statement) Optional Available Specify the search conditions (Where sentence) for the table selected in the "Table Name."
    For syntax details, please refer to the Salesforce API documents.
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."		  
Create SOQL... The specification of the search conditions for the table selected in [Table Name] is supported.
For setting methods, please refer to "Create SOQL."		  
Extraction test A query is performed, based on the specified schema and search conditions. The number of results obtained will be displayed.
  • Cannot be performed in the following instances:
    • If the schema definition has not been specified.
    • If a variable has been used for the search conditions.
Option Settings
Item name Required/Optional Use of Variables Description Supplement
SOQL(group statement) Optional Available Specify the aggregate conditions (GROUP BY clause, etc.) for performing an aggregation, for the table selected in the [Table Name] or the parent table.
  • For example, when specifing the GROUP BY clause, the description needs to start with "GROUP BY".
  • For syntax details, please refer to the Salesforce API documents.
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.
  
Read records that have been deleted(queryAll) Required - Specify whether or not to read the data that has been deleted from Salesforce.
(If it is to be read, a reading, using the queryAll service, will take place.)
  • [Unread]:(default)
    Does not read the data deleted in Salesforce.
  • [Read]:
    Reads the data deleted in Salesforce.
  • Please be aware that, in the deleted record reading process by the data reading (query), data which has been deleted from the recycle bin can still be read for about 24 hours after deletion.
Batch size Required Available Enter the batch size for obtaining the data reading results from Salesforce.
  • The default value is "2000."
  • A number of 200 or greater, up to 2000, can be set. An error occurs if any number outside of this range is set.
  • API specification will not allow value less than 200. If the value is set, the behavior will depend on the specification of the API.
  • Depending on the operating environment, increasing the batch size generally helps improve the performance of the read data operation.
  • According to the Salesforce adapter 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

None.

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
count The number of data read 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.

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.

Create SOQL

The extraction condition of the data, to be read from the Salesforce, can be specified.



Number in the Image Name Description Supplement
(1) Selection of Condition fields This is the list for selecting the items to use for the search conditions.  
(2) Specification of the field Conditions Items to be used for the search conditions can be selected, and a condition expression can be specified for each item.  
(3) SOQL(filter statement: WHERE) The conditions specified in the [Specification of the field Conditions] are displayed.
  • The displayed conditions can be edited directly.

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.InvalidFieldFault The item included in the executed SOQL is invalid. Please check the ExceptionCode or error message, and check for error information in documents related to Salesforce.
com.sforce.soap.partner.fault.MalformedQueryFault The executed SOQL is invalid. Please check the ExceptionCode or error message, and check for error information in documents related to Salesforce.
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