SuccessFactors Read

Overview

The SuccessFactors Read Snap retrieves data objects from the SuccessFactors Data Center.

For more information about SuccessFactors APIs, refer to SuccessFactors Documentation.

This is a Read-type Snap.
Works in Ultra Tasks

Supported Accounts

Prerequisites

A valid SuccessFactors host server.
A valid account with the roles required to perform the Read operation on the selected entity.

Snap views


Type	Description	Examples of upstream and downstream Snaps
Input	This Snap has at most one document input view. A document containing data for filtering entities that need to be retrieved in SuccessFactors.	Mapper Copy CSV Parser JSON Parser
Output	This Snap has exactly one document output view. A document containing the data retrieved from a SuccessFactors entity.	Mapper Copy CSV Parser JSON Parser
Learn more about Error handling.

Snap settings

Note: Learn about the common controls in the Snap settings dialog.


Field/Field set	Description
Label `String`	Specify a unique name for the Snap. Modify this to be more appropriate, especially if more than one of the same Snaps is in the pipeline. Default value: SuccessFactors Read
Entity `String/Expression/ Suggestion`	Required. Lets you select an entity (business object) from the list of entities defined for the API. You can either choose an entity from the suggestion drop-down or type an entity manually. The values in the suggestion drop-down are displayed dynamically based on different users' accounts. The entity is shown as `[category name] – [entity name]` in the drop-down; however, you can also type just the `[entity name]` in this field. Default value: N/A Example: Foundation/Platform (PLT) – User or User
Key parameter	Lets you specify the key fields for a specific entity, such as userId for the Foundation/Platform (PLT) – User entity.
Field name `String/Expression`	The name of the key parameter (reference parameter) field. Default value: N/A Example: userId
Field value `String/Expression`	The value of the key parameter (reference parameter) field. The data type of this field depends on the data type of the field name, such as String, Integer, or Boolean. Default value: N/A Example: test_id
URL parameters	Lets you specify the names and values of the parameters included in the URL.
Parameter name `String/Expression`	The name of the URL parameter. Default value: fromDate Example: fromDate
Parameter value `String/Expression`	The values of the URL parameter. The data type of this field depends on the data type of the field name, such as String, Integer, or Boolean. Default value: N/A Example: 2019-01-01
Filter records	Lets you filter the API response based on the customer selected fields.
Field name `String/Expression`	The name of the field in the system parameter $filter, which is to be included in the output. Default value: userId Example: userId
Operation `Dropdown list`	The comparison operator for the system parameter $filter. Default value: Equals Example: Equals
Field value `String/Expression`	The value of the specified $filter fields. The data type of this field depends on the data type of the field name, such as String, Integer, or Boolean. Default value: N/A Example: test123
Condition `Dropdown list`	The logical operator for the system parameter $filter. Default value: Or Example: Or
Output field selection	Lets you select the fields to be included in the output. If not selected, all fields are returned.
Order by	Lets you order the resulting records based on specified elements. The order types to be selected are either ascending or descending.
Element `String/Expression`	The fields that will be displayed by descending or ascending order. Default value: N/A Example: country
Order by type `Dropdown list`	The Order Type (Ascending or Descending order). Default value: Ascending Example: descending
Output fields advanced options	Add advanced options to define the limited number of output entries from a specific starting entry index.
Output entry limit `Integer/Expression`	The maximum number of output entries from a specific starting entry index. Default value: N/A Example: 10
Output entry offset `Integer/Expression`	The number of records the query must skip while fetching the results. Default value: N/A Example: 10
Automatic pagination `Checkbox`	By default, SuccessFactors returns a maximum of 1000 records per page. If this field is selected, all matching records will be automatically returned (beyond the 1000 records). Note: If the Automatic pagination field is selected, then the Output entry limit field should not be set or used. In case both fields are used, a validation exception occurs. Default value: Deselected
Allow empty query result `Checkbox`	If selected, empty results are also shown in the output views. Else, an error is displayed when an empty result is found. Default value: Selected
Refresh metadata `Checkbox`	If selected, the Snap refreshes the cache and shows the refreshed metadata results including any entities/parameters that were added or deleted. This is useful in cases where changes are made to the dataset outside of SnapLogic, such as when a dataset has been created or deleted, or when there are changes in the metadata of SuccessFactors. Note: After the first run and after the metadata has been refreshed, please deselect this checkbox. Default value: Deselected
Pass through `Checkbox`	If selected, lets the data from an incoming document "pass through" and merge into the new document being written to the output. The input document is passed through to the output view under the key '`original`'. Default value: Selected
Connection details	Required. Specify the Internet connection details.
Connection timeout `Integer/Expression`	Required. The connection timeout duration in seconds. Default value: 300
Number of retries `Integer/Expression`	Required. The maximum number of reconnection attempts if the connection fails or times out. Default value: 3
Retry interval (seconds) `Integer/Expression`	Required. The interval in seconds between reconnection attempts. Default value: 1
Snap execution `Dropdown list`	Choose one of the three modes in which the Snap executes. Available options are: `Validate & Execute`: Performs limited execution of the Snap and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime. `Execute only`: Performs full execution of the Snap during pipeline execution without generating preview data. `Disabled`: Disables the Snap and all Snaps that are downstream from it.

For more information on how to define the Filter records, Output field selection and Order by settings in the OData based API, see OData Version 4.0 Documentation.

General Features of SuccessFactors

The following features of SuccessFactors are useful to know in order to most effectively use the SuccessFactors Read Snap:

All the dates returned by SuccessFactors are expressed in milliseconds. Example: Date(1420772453000+0000). This value represents the date Fri Jan 09 2015 04:00:53 GMT+0100.
By default, a maximum of 1000 records per page of the response are returned from SuccessFactors.
Some SuccessFactors entities require the Key parameter to be used to filter records, failing which, a 400 or 500 exception is thrown by SuccessFactors. This exception indicates which mandatory field is required. You must specify it in the Key parameter section.

Usage of Automatic Pagination

By default, a maximum of 1000 records per page are returned in the response from SuccessFactors. The records from 1001 onward, if any, are placed in subsequent pages. In this Snap, if you select the Automatic pagination checkbox, all the records are returned in the Snap's output. Else, only the records of the first page are returned in the output. This Snap decodes the JSON-formatted API response to split all the records into single output documents, which are shown in the output view of the Snap. To control the number of records, you can use the Output entry limit and Output entry offset fields.

For instance, if there are 5000 records stored in SAP SuccessFactors, and you need only records from 2001 to 4000. Set the Output entry offset to 2000 and the Output entry limit to 2000, and deselect Automatic pagination checkbox. Instead of the default 1000 records per page, the entire 2000 records are returned in the Snap's output.

Navigation Text

In some cases, the output records of the SuccessFactors Read Snap can contain navigation properties (recognized by the presence of an "uri" field and an associated link). You can navigate to those entities using the URI links. In such a case, you can use another SuccessFactors Read Snap to retrieve the entity returned as part of the "uri" links (from the previous Snap result).

Alternatively, it is possible to use the REST Get Snap. The navigation property URI link can be parsed from the upstream SuccessFactors Read Snap's output. This returns the properties of the entity returned as the "uri" link. To read more about the REST Get Snap, see REST Get .

Troubleshooting


Error	Cause	Resolution
`You have an empty value in the Key/Value field.`	Key/value parameters must not be empty.	Enter a valid value for key/value parameters.
`The input entity does not exist.`	An invalid entity has been entered.	Click the suggestion drop-down in the Entity field and select the entity.
`The fields "Automatic pagination" and "Output entry limit" cannot be used at the same time.`	The output entry limit cannot be implemented together with automatic pagination.	Either select the Automatic pagination field or specify a value in the Output entry limit field.
`Empty result found.`	There is no data fetched by the API call.	Select the Allow empty query result check box.
`<Entity> with key ('<key>') not found!`	The input key parameters entered for a specific entity does not exist in the system.	Specify key parameters that exist in the system.