SAP S/4HANA Cloud Read

Overview

The SAP S/4HANA Cloud Read Snap reads and retrieves data objects from the SAP S/4HANA Cloud instance.


SAP S/4HANA Cloud Read Snap dialog

Supported Accounts

Prerequisites

  • A valid account that supports SAP S/4HANA Cloud instance, with the appropriate access permissions. Learn more: SAP S/4HANA Cloud Accounts.

Snap views

Type Description Examples of upstream and downstream Snaps
Input

This Snap has at most one document input view.

A document with data that indicates the entities to be filtered and retrieved from the SAP S/4HANA Cloud instance.
Output

This Snap has at most one document output view.

A document containing the entity data retrieved from an SAP S/4HANA Cloud instance.
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: SAP S/4Hana Cloud Read

Example: SAP S/4Hana Cloud_Read
API Object*

String/Expression/ Suggestion

 Select the API that you want to access in SAP S/4HANA Cloud instance. This dropdown list contains APIs available for the S/4HANA account configured in the Snap, each with a short description.

Default value: N/A

Example: API_BUSINESS_PARTNER_0001 (Remote API for Business Partner)
Entity*

String/Suggestion

 Select a business object (the Entity or Endpoint) for the API Object chosen above.

Default value: N/A

Example: A_Supplier
Subentity

String

 Add a subentity for the entity chosen.

Default value: N/A

Example: to_SupplierCompany
Customized Header Use this field set to add customized HTTP request headers for implementing specific HTTP requests other than the ones listed in the Usage of Customized Header section of this page.
Field Name

String

 Specify the field name of the customized HTTP request header.

Default value: None

Example: If-Match
Field Value

String

 Specify the field value for the above field of the customized HTTP request header.

Default value: None

Example: '82F636DC08F14D22260CE67E505C231D0D2ACD95'
Key Parameter Use this field set to specify the key parameters for a specific entity. Providing values for all key parameters in the dropdown list allows SAP S/4HANA to identify a unique record.
Note: Key parameters are not the same as filters which can return multiple records. To use a filter like normal select, use the parameters at the Filter records section instead.

Only one key parameter can be specified in each row. Click plus to add a new row in this table and define the values accordingly.
Field Name

String

 Specify the reference parameter in this field.

Default value: None

Example: userId
Field Value

String

 Specify the value for the reference parameter in this field. The data type (String, Integer, Boolean, or any other) depends on the Field name you specified for the parameter.

Default value: None

Example: TestUser
Filter Records Use this field set to define how the response result should be filtered based on the specified parameters.
Field Name

String

 Specify the system parameter ($filter field) to filter the records in the output.

Default value: None

Example: userId
Operation

String

 Specify the comparison operator for the $filter field specified above from this dropdown list. Available options are:
  • Equals
  • Not Equals
  • Greater than or Equal
  • Greater than
  • Less than or Equal
  • Less than
  • Starts with
  • Ends with

Default value: Equals

Example: Equals
Field Value

String

 Specify the value with which the above $filter field must be compared. The data type (String, Integer, Boolean, or any other) depends on the $filter field you specified for the filter criterion.

Default value: None

Example: TestUser
Condition

String

 Select a value from this dropdown list to set the correlation between this filter criterion (row) and the next one (row), if being defined at all, to apply the filters for generating the final output. Available options are:
  • Or: To retrieve records that match either the current criterion or the next criterion.
  • And: To retrieve only those records that match both the current criterion and the next criterion.
  • None: To specify that the current and the next criteria can be evaluated independently of each other in retrieving the records.

Default value: None

Example: Or
Output Field Selection Use this field set to select the fields to be included in the output. Only one output field can be specified in each row.
Note: To return all available fields in the output, do not specify any output field.
Element

String

 Specify the fields from the result dataset to be populated in the output.

Default value: None

Example: name
Order by Use this field set to order the resulting records based on the specified element. The order types to be selected are either ascending or descending. Click plus to add a new row in this table and define the sort order criteria accordingly.
Element

String

 Specify the field that should be used for sorting by descending or ascending order.

Default value: None

Example: name
Order By Type

String

 Specify the Order Type (Ascending or Descending order).

Default value: Ascending

Example: Descending
Output Fields Advanced Options Use this field set to customize the output set: the number of output entries and the index of the starting entry.
Output Entry Limit

Integer

 Specify the maximum number of entries that SAP S/4 HANA Cloud must return in the output.

Default value: 500

Example: 20
Output Entry Offset

Integer

 Specify the record index starting from which SAP S/4 HANA Cloud must return records in the output. Use this field along with the Output entry limit to retrieve a specific set of entries in the output.

Default value: N/A

Example: 20
Is an Active Entity

Dropdown list

 Select a value from this dropdown list to get the records from active entities or from all entities. Available options are:
  • true: Select this option to get records only from the active SAP S/4HANA entity.
  • false: Select this option to get records from all entities.
  • not available: Select this option when you need to get the records from those entities where this field is not set.
Note: The SAP S/4 HANA entities require that you set the IsActiveEntity field to true or false. This parameter is added to the HTTP request and if this field is not set for an entity, then accessing the SAP S/4 HANA entity returns an error. For the entities that do not need this field, select the option not available.

Default value: not available

Example: true
Count

Checkbox

 Select this checkbox to return the total number of records retrieved in the API response.

Default value: Deselected
Allow empty result

Checkbox

 Select this checkbox to define whether output views can show empty results. If this checkbox is not selected, the Snap displays an error when the output has no records.

Default value: Selected
Connection Details Use this field set to specify the connectivity parameters.
Connection Timeout

Integer

 Specify the duration in seconds for which the Snap must try to establish a connection with SAP S/4HANA Cloud. If the connection cannot be established within this duration, the Snap times out, writes the event to the log, and waits until the specified Retry Interval before attempting to reconnect.

Default value: 300

Example: 500
Maximum Retry Attempts

Integer

 Specify the maximum number of attempts the Snap should make to perform the selected operation in case of connection failure or timeout.

Default value: 3

Example: 5
Retry Interval

Integer

 Specify the time interval in seconds between the two successive retry requests. A retry happens only when the previous attempt resulted in an exception.

Default value: 1

Example: 2
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.

Default value: Validate & Execute

Example: Execute only

Snap General Behavior

The SAP S/4HANA Cloud Read Snap supports the following:

  • GET operation to read data from the SAP S/4HANA Cloud instance.
  • OData querying operations: $filter (Filter records), $select (Output field selection), $orderby (Order by), $top (Output entry limit), and $skip (Output entry offset).
  • OData operation $count (Count checkbox).
  • Connection-failed-retry mechanism.
  • Client-side pagination through $top (Output entry limit) and $skip (Output entry offset) mechanisms. For more information, see Pagination.
  • Customized HTTP Headers.
  • Dynamic loading of API metadata with a Parent-child dependency structure. This means that you can:
    • Select an API object from the API Object field to view only entities that are related to the API object and support GET queries (read operations). And then, select an entity to view and specify values for only read-compatible parameters related to this entity in Key parameter, Filter records, Output field selection, and Order by fields.

Pagination

Client-side pagination is supported through the use of the $top (Output entry limit) and $skip (Output entry offset) OData operations.

Type Description Examples of upstream and downstream Snaps
Output entry limit: 100
  • Retrieves the first 100 API response records from the server (if more than 100 records are present in the API response).
  • Retrieves all the available API response records from the server (if 100 or fewer records are present in the API response).
Output entry offset: 100
  • Retrieves API response records starting from index 101 from the server.
Output entry offset: 100 and Output entry limit: 100
  • Skips the first 100 records and collects records 101 through 200 in the API response from the server.

Usage of Customized Header

SAP S/4HANA Cloud contains a large number of API objects and entities. It also allows you to create and use customized API objects and entities as needed.

  • Some entities may require specific/customized HTTP headers like If-Match or Etag.
  • SAP S/4HANA Cloud Snap Pack supports the definition and usage of such customized HTTP headers.
  • This Snap Pack currently contains the following common HTTP headers pre-defined and ready to use. You can however add any custom or specific HTTP headers to fulfill your requirement:
    • Content-type
    • Cache-Control
    • Authorization
    • Accept
    • X-CSRF-Token
    • Cookie

The HTTP headers listed above are internally handled by the Snap and need NOT be defined again in the Customized header section. Below is an example of a custom HTTP header defined:


Example of a defined custom HTTP header

Accessing Related Entities from Snap Outputs for an Entity

Records in SAP S/4HANA Cloud Read Snap output may contain navigation properties, typically URI fields, belonging to some entities related to the entity specified in Snap Settings.

For example, the SAP S/4HANA Cloud Read Snap output for the ZCRM_BUPA_ODATA_0001 (Odata Services for Business Partner) API object and the AccountCollection entity contains navigation properties (of entities) like Contacts, Addresses, Logo, Attachments.

  • The navigation properties can be used to access specific details of these related entities.
  • In the API response, the navigation property values are displayed as URLs.

You can use one of the following methods to retrieve the details of each related entity returned in the output:

  • Pass the value (URL) from the Snap output as input to another SAP S/4HANA Cloud Read Snap to navigate to or access details of these related entities. OR
  • Parse the value (URL) from the Snap output and use it as input to the Service URL field of a REST Get Snap.

Both of these methods return the properties of the corresponding related entity.

Troubleshooting

Field/Field set Type Description
There is an empty value in the Output field selection table. The Output field selection table has an empty field. Provide a valid entry for the selected output field.
There is an empty value in the Order by table. The Order by table has an empty field. Enter a valid value to define sort order.
There is an empty value in the Field name field for the Key parameter. The Field name field must not be empty for the Key parameter. Enter a valid Field name for the Key parameter.
There is an empty field in the Field name/value field for the Customized header. The Field name/value field must not be empty for the Customized header. Enter a valid Field name/value for the Customized header.
Empty result found. API call does not return any data. Possible reasons:
  • No relevant data available in the API database
  • Filter setting is restrictive
  • URL parameter setting is restrictive
 Select the Allow empty result checkbox.
API object does not exist. Allowed API object format is <API ID>(Description). Locate and select an API Object from the dropdown list.
Entity does not exist. The entered Entity is not found in the server. Locate and select the Entity from the dropdown.