SuccessFactors Read

On this page

Snap Type:

Read

Description:

This Snap provides the ability to retrieve data objects from your SuccessFactors instance.

Prerequisites:

None

Support and limitations:

Ultra pipelines: Works in Ultra Pipelines.

Spark mode: Not supported in Spark mode.

Account:

This Snap uses account references created on the Accounts page of SnapLogic Manager to access to the endpoint. See SuccessFactors Account for information on setting up this type of account.

Views:

Input
This Snap has at most one document input view.

Output
This snap has at most one document output view.

Error
This Snap has one optional error view and might produce documents in the view if the input data causes an error in the REST API.

Settings

Label:

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.

Entity:

Required. This property enables you to define an entity of the API. This field will be shown dynamically from different users’ accounts from the suggestion dropdown. Users are allowed either to choose an entity from suggestion dropdown or type an entity manually. The entity is shown as [category name] – [entity name] in the dropdown. But it is also allowed to type only [entity name] in this field.

Example: Foundation/Platform (PLT) – User or User

Default value: [None]

Key parameter:

This property enables you to specify the key fields to a specific entity such as userId for the Foundation/Platform (PLT) – User entity.

Example: userId

Default value: [None]

URL parameters:

This property enables you to Specify the names and values of the URL parameters.

Example: fromDate=’2019-01-01’

Default value: [None]

Filter records:

This property enables you to filter the results from the API response based on the customer selected fields.

Example: userId equals ‘test123’ or userId less than ‘b’

Default value: [None]

Output field selection:

This property enables you to select fields to be included in the output. If not selected, all fields will be returned.

Example: userId, country

Default value: [None]

Order by:

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

Example: country descending

Default value: [None]

Output fields advanced options

Output entry limit
This property enables you to select the number of records the query should return.

Example: 10

Default value: [None]

Output entry offset
This property enables you to skip the number of records the query should return.

Example: 10

Default value: [None]

Automatic pagination:

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 field fields “Automatic pagination” is selected, then the field “Output entry limit” should not be set or used. Either keep the field “Output entry limit”, or check the “Automatic pagination”. In case both are used, a validation exception will be thrown.

 

Default value: Not selected

Process empty result:

This property enables you to determine if the empty result will be shown in the output views. If not selected, an error will be thrown when the empty result is found.

Default value: Selected

Refresh metadata:

If selected, the Snap will refresh the cache and show refreshed metadata results including new entities/parameters added or old entities/parameters deleted. This is handy in cases where changes are made to the data set outside of SnapLogic, such as a new data set created, existing data set deleted, and so on. In such cases, enabling this property will refresh the cache and display updated content.Please be aware that after the first run and new metadata has been refreshed, please de-select this checkbox.

Default value: Not selected

Pass through:

This property enables you to "pass through" the data from an incoming document and merge it into the new document being written to the output. If selected, the input document will be passed through to the output view under the key 'original'.

Default value: Selected

Connection details:

Connection timeout
Required. This property enables you to set the connection timeout duration of seconds.
Default value: [300]

Number of retries
Required. This property enables you to set the maximum number of re-connections if the connection is failed or timeout.
Default value: [3]

Retry interval (seconds)
Required. This property enables you to set the interval in seconds between reconnections.
Default value: [1]

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

General behavior of SuccessFactors

The following behavior of SuccessFactors are useful to know in order to easily use the 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, there are maximum 1000 records being returned in the response for one page from SuccessFactors.

  • Some Entities of SuccessFactors required Key parameter to be use. Without which, a 400 or 500 exception is thrown by SuccessFactors. This exception will indicate which mandatory field is required. You will need to specify it in the Key parameter section.

Usage of Automatic Pagination

By default, there are maximum 1000 records being returned in the response for one page from SuccessFactors. If the number of records is larger than 1000, the records from 1001 would be direct to the next pages. In this snap, if the Automatic pagination is selected, all the records will be returned at once to the API json response. Otherwise, only the records in the first page will be returned to the API json response. This snap will decode the json-formatted API response to split all the records into single ones, which will be shown in the Outputview of the Snap. To control the pagination and get the demanded number of records, the Output entry limit and Output entry offset could be used together with Automatic pagination. For instance, there are 5000 records stored in the data center, but only the 2001st to 4000th records are demanded. The Output entry offset can be set as 1000 and Output entry limit can be set as 2000 and the Automatic pagination should be allowed. Finally, 2000 single API records will be collected through this snap.

Addition information

In some cases, the output records of SuccessFactors' Read Snap can contain navigation properties (displayed but only with an “uri” links). You can navigate to those entities using the uri links. In such a case,

you can use another Success Factors 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 Success Factors Read Snap’s output to this Rest Get Snap Service URL field. This will return the properties of the entity returned as the “uri” link. To read more about the Rest Get Snap, please refer to the following link: https://docs-snaplogic.atlassian.net/wiki/spaces/SD/pages/1438830/REST+Get .

Example

The example assumes that you have configured & authorized a valid SuccessFactors Account (see SuccessFactors Account). The following SuccessFactors Read Snap shows how you can query and retrieve records from SuccessFactors data center. The following Snap queries the users.

 

Configuring a SuccessFactors Read Snap to read records from an entity

The Snap specifies that the query results include only some of the columns (Such as userId, status, country, firstName) in the incident table for the selected API entity Foundation/Platform (PLT) – User. The response result is filtered by the userId greater than the letter ‘M’ and less the letter ‘U’ and is ordered by the firstName as descending order. Additionally, the first 11 to 50 records (select top 40 and skip the top 10 records) will be shown in the response.

 

 

 

 

 

Implementing an example pipeline to retrieve users data using the entity name “Foundation/Platform (PLT) - User”

The following pipeline shows how you can use SuccessFactors Read Snap to read user data via Foundation/Platform (PLT) - User API entity in the Success Factors data center. The SuccessFactors Read Snap is applied to retrieve the user data from the API. Then a JSON Formatter snap and a File Writer snap are applied to format and record data in a new file.

The SuccessFactors Read Snap specifies that the query results include only some of the columns (Such as userId, status, country, firstName) in the incident table for the selected API entity Foundation/Platform (PLT) – User. The response result is filtered by the userId greater than the letter ‘M’ and less the letter ‘U’ and is ordered by the firstName as descending order. Additionally, the first 11 to 50 records (select top 40 and skip the top 10 records) will be shown in the response. In case that the empty result error is thrown, the ‘Processing empty result’ checking box is selected. Additionally, to trace back the history data from the API, the fromDate and toDate URL parameters are given as 2019-01-01 and 2019-08-01.

 

A successful validation or execution of the Snap gives the following output preview showing the query results

Entities requiring Key parameter

As per the time of this release, the following standard entities need Key parameter(s):

Downloads

  File Modified

File SuccessFactors_1.0.0_Read_User_TC1_GetUser.slp

Nov 06, 2019 by Rojo Publisher

Snap Pack History

Initial Release (15/11/2019)

  • Introduced in this release

 

 

Have feedback? Email helpdesk@rojoconsultancy.com © Rojo Consultancy