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/Output | Type of View | Number of Views | Examples of Upstream and Downstream Snaps | Description |
---|---|---|---|---|
Input | Document |
|
| A document containing data for filtering entities that need to be retrieved in SuccessFactors. |
Output | Document |
|
| A document containing the data retrieved from a SuccessFactors entity. |
Snap Settings
Parameter Name | Data Type | Description | Default Value | Example |
---|---|---|---|---|
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 | 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 name | String | The name of the key parameter (reference parameter) field. | N/A | userId |
Field value | Any | 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. | N/A | test_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 name | String | The name of the URL parameter. | fromDate | fromDate |
Parameter value | Any | 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. | N/A | 2019-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 name | String | The name of the field in the system parameter $filter, which is to be included in the output. | userId | |
Operation | String | The comparison operator for the system parameter $filter. | Equals | Equals |
Field value | Any | 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. | N?A | test123 |
Condition | String | The logical operator for the system parameter $filter. | Or | Or |
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 |
Element | String | The fields that will be displayed by descending or ascending order | N/A | country |
Order by type | String | The Order Type (Ascending or Descending order). | Ascending | descending |
Output fields advanced options | N/A | Add advanced options to define the limited number of output entries from a specific starting entry index. | N/A | N/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 ' | 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:
| 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
Error | Reason | 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. |
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 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 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.
Downloads
Important steps to successfully reuse Pipelines
- Download and import the Pipeline into SnapLogic.
- Configure Snap accounts as applicable.
- Furnish Pipeline parameters as applicable.
Snap Pack History
See Also
Have feedback? Email documentation@snaplogic.com | Ask a question in the SnapLogic Community
© 2017-2024 SnapLogic, Inc.