SuccessFactors Read

In this article

Overview

You can use this Snap to retrieve data objects from the SuccessFactors Data Center. For more information about SuccessFactors APIs, refer to SuccessFactors Documentation.

Prerequisites

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

Supported Features

Works in Ultra Pipelines.

Limitations and Known Issues

None.

Snap Input and Output

Input/OutputType of ViewNumber of ViewsExamples of Upstream and Downstream SnapsDescription
Input 

Document

  • Min: 0
  • Max: 1
  • Mapper
  • Copy
  • CSV Parser
  • JSON Parser

A document containing data for filtering entities that need to be retrieved in SuccessFactors.

Output

Document

  • Min: 1
  • Max: 1
  • Mapper
  • Copy
  • CSV Parser
  • JSON Parser

A document containing the data retrieved from a SuccessFactors entity.

Snap Settings

Parameter NameData TypeDescriptionDefault ValueExample 

Label

String

Required. The name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your Pipeline.

N/A

N/A

Entity

String

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.

N/A

Foundation/Platform (PLT) User or User


Key parameter

Fieldset

Lets you specify the key fields for a specific entity, such as userId for the Foundation/Platform (PLT) – User entity.

N/A

userId

Field nameStringThe name of the key parameter (reference parameter) field.N/AuserId
Field valueAnyThe 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.N/Atest_id

URL parameters

Fieldset

Lets you specify the names and values of the parameters included in the URL.

N/A

fromDate=2019-01-01

Parameter nameStringThe name of the URL parameter.fromDatefromDate
Parameter valueAnyThe 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.N/A2019-01-01

Filter records

Fieldset

Lets you filter the API response based on the customer selected fields.

N/A

userId equals test123 or userId less than b

Field nameStringThe name of the field in the system parameter $filter, which is to be included in the output.
userId
OperationStringThe comparison operator for the system parameter $filter.EqualsEquals
Field valueAnyThe 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.N?Atest123
ConditionStringThe logical operator for the system parameter $filter.OrOr

Output field selection

Fieldset

Lets you select the fields to be included in the output. If not selected, all fields are returned.

N/A

userId, country

Order by

Fieldset


Lets you order the resulting records based on specified elements. The order types to be selected are either ascending or descending.

N/A

country descending

ElementStringThe fields that will be displayed by descending or ascending orderN/Acountry
Order by typeStringThe Order Type (Ascending or Descending order).Ascendingdescending
Output fields advanced optionsN/AAdd advanced options to define the limited number of output entries from a specific starting entry index.N/AN/A

Output entry limit

Integer

The maximum number of output entries from a specific starting entry index.

N/A

10

Output entry offset

Integer

The number of records the query must skip in the while fetching the results. 

N/A

10

Automatic pagination

String

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 that if the Automatic pagination field is selected, then the Output entry limit field should not be set or used. In case both field are used, a validation exception occurs. 

Deselected

N/A

Allow empty query result

Check box

If selected, empty result are also shown in the output views. Else, an error is displayed when an empty result is found.

Selected

N/A

Refresh metadata

Check box

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. 

After the first run and after the metadata has been refreshed, please deselect this checkbox.

Deselected

N/A

Pass through

Check box

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'.

Selected

N/A

Connection details

N/A

Required. Specify the Internet connection details.

N/A

N/A

Connection timeout

Integer

Required. The connection timeout duration in seconds.

300

N/A

Number of retries

Integer

Required. The maximum number of reconnection attempts if the connection fails or times out.

3

N/A

Retry interval (seconds)

Integer

Required. The interval in seconds between reconnection attempts.

1

N/A

Snap execution

Check box

Select 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.

Execute only

N/A

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.

Troubleshooting

ErrorReasonResolution

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. 

Additional information

The following content provides helpful information to assist you while using the SuccessFactors Read Snap.

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 millisecond. 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 checkboxInstead 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 up-stream 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, refer to the link: REST Get.

Examples

Retrieve User Data from SuccessFactors Data Center

This example illustrates how you can use the SuccessFactors Read Snap to read and retrieve user data from the Success Factors Data Center. It assumes that you have configured and authorized a valid SuccessFactors account. See SuccessFactors Basic Auth Account. 

In the sample Pipeline, the SuccessFactors Read Snap retrieves the user data via the Foundation/Platform (PLT) - User API entity. 

A successful validation of the Snap gives the following output preview, showing the query results.

An XML Formatter and a File Writer Snap is added downstream to format and save the returned data in a new file. In the image below, the output is written to the SuccessFactors_Read_VC1.xml file. 

You can view the newly created file in the target directory using SSH.

Download this Pipeline. 

Downloads

Important steps to successfully reuse Pipelines

  1. Download and import the Pipeline into SnapLogic.
  2. Configure Snap accounts as applicable.
  3. Furnish Pipeline parameters as applicable.

  File Modified

File SuccessFactors_1.0.0_Read_GetUser_Example.slp

Apr 23, 2020 by Ritu Sachdeva

Snap Pack History

 Click here to expand...

Release

Snap Pack Version 

Date

Type

Updates

August 2024main181 LatestEnhanced the SuccessFactors Read and Read Advanced Snaps to handle empty responses.

August 2024

main180

 


Stable

Updated and certified against the current SnapLogic Platform release.

May 2024

main172

 

Stable

Updated and certified against the current SnapLogic Platform release.

February 2024main168 StableUpdated and certified against the current SnapLogic Platform release.
November 2023main155 

Stable

Updated and certified against the current SnapLogic Platform release.

August 2023main150 LatestFixed an issue with the OAuth 2.0 account that was causing it to reload.
August 2023main138 

Stable

Updated and certified against the current SnapLogic Platform release.

May 2023main137 Latest

Introduced the SAP SuccessFactors Read Advanced Snap, which enables you to read objects recursively for objects containing links to traverse through the tree structure. 

May 2023

main130 

Stable

Upgraded with the latest SnapLogic Platform release.

February 2023main114 StableUpgraded with the latest SnapLogic Platform release.
November 2022main113 StableUpgraded with the latest SnapLogic Platform release.
August 2022

main111

 StableUpgraded with the latest SnapLogic Platform release.
4.29main108 

Stable

Upgraded with the latest SnapLogic Platform release.
4.28main100 StableAdded a new account type SuccessFactors OAuth2 that enables OAuth2 authentication for all the SuccessFactors Snaps.
4.27main12283  StableUpgraded with the latest SnapLogic Platform release.
4.26main88 StableUpgraded with the latest SnapLogic Platform release.
4.25main73
 
StableNo updates made.
4.24main73
StableNo updates made.
4.23main73 StableNo updates made.
4.22main6403
 
Stable[Docs Update] Adds a use case to automate asset management by integrating SAP SuccessFactors with ServiceNow.
4.21snapsmrc542 StableNo updates made.

4.20

snapsmrc535


Stable

Initial release (September 2019).


See Also