SAP S/4HANA Read Custom Query

In this article

Overview

Use this Snap to retrieve multiple data objects from an entity in SAP S/4HANA applications using custom OData queries.

Prerequisites

Support for Ultra Pipelines

See Snap Support for Ultra Pipelines.

Limitations and Known Issues

  • SAP S/4HANA On-Premise does not support server-side pagination. As a result, the $skiptoken used for server-side pagination is not supported.

Snap Input and Output

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

Document

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

A document containing data that can be used to filter entities that need to be retrieved in SAP S/4HANA server. 


Output

Document

  • Min:1
  • Max:1
  • Mapper Snap
  • Copy Snap
  • XML Formatter
  • JSON Formatter

A document containing the data retrieved from an SAP S/4HANA 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

SAP S/4HANA Read Custom Query

API object

String

Required. Select the API that you want to access in SAP S/4HANA On-Premise. This drop-down list contains APIs available for the S/4HANA account configured in the Snap, each with a short description.

N/A

ZCRM_BUPA_OData_0001 (OData Services for Business Partner)

Entity

String

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

N/A

AccountCollection

Customized header

Use this field set to add customized HTTP request headers for implementing specific HTTP requests other than the ones listed in the Using Customized Headers section of SAP S/4HANA Read Snap. Only one customized header can be specified in each row. Click  to add a new row in this table and specify the values accordingly.

This field set comprises the following fields:

  • Field name
  • Field value 

Field name

StringThe field name of the customized HTTP request header.N/AIf-Match

Field value

StringThe field value of the customized HTTP request header. N/AW/"'82F636DC08F14D22260CE67E505C231D0D2ACD95'"

Key parameter

This field set enables you to specify the key parameters for a specific entity. Providing values for all key parameters in the drop-down list enables SAP S/4HANA to identify a unique record.

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.

Click + to add a new row in this table and define the values accordingly.

Field name

StringSpecify the reference parameter in this field.N/AaccountID

Field value

AnySpecify 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.N/ATEST_001
Customized queryString

This field enables you to enter your OData query.

SAP S/4HANA APIs follow the OData 2.0 protocol. To make the query request for API calls, the API query should obey the OData 2.0 protocol rules. For more information, see OData 2.0 Documentation. 

N/A$filter=accountID eq 'Test_123' and name1 eq 'testname'&$select=accountID,name1,name2&
orderby=name1 desc
CountCheck box

Select this check box to return only the total number of records retrieved in the API response.

No records retrieved

For all entities specified with this check box selected, the Snap returns ONLY the count of records matching the the respective entity criteria and DOES NOT return any records from the SAP S/4HANA instance (for those entities). If this check box is not selected for one or more entities, records matching each entity's criteria are returned.

Not selectedSelected

Allow empty result

Check box

Use this property to define whether output views can show empty result. If this check box is not selected, an error will be thrown when the output has no records.

Selected

Selected

Connection details

Use this field set to specify the connectivity parameters: timeout, retry count, and retry interval. 

This field set comprises the following fields:

  • TimeOut
  • Maximum request attempts
  • RetryInterval

TimeOut

Integer

Required. Enter, in seconds, the duration for which the Snap must try to establish connection with SAP S/4HANA On-Premise server. If the connection cannot be established within this duration, the Snap times out, writes the event to the log, and waits until the specified RetryInterval before attempting to reconnect.

300

120

Maximum request attempts

Integer

Required. Specify an integer value to set the maximum number of reconnection attempts that the Snap must perform, in case of connection failure or timeout.

3

5

RetryInterval

Integer

Required. Enter, in seconds, the duration for which the Snap must wait between two reconnection attempts, until the number of retries is reached.

1

10

Snap Execution

String

Specifies the execution type:

  • Validate & Execute: Performs limited execution of the Snap (up to 50 records) during Pipeline validation; performs full execution of the Snap (unlimited records) during Pipeline execution.

  • Execute only: Performs full execution of the Snap during Pipeline execution; does not execute the Snap during Pipeline validation.

  • Disabled: Disables the Snap and, by extension, its downstream Snaps.

Validate & Execute

N/A

Troubleshooting

ErrorReasonResolution

You have 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.

You have 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.

ResponseCode: 500; ErrorCode: SY/530;Draft 2.0 object <Service~Entity> requires selection condition on IsActiveEntity.Draft 2.0 object <Service~Entity> requires selection condition on IsActiveEntity For backend administrators: run transaction /IWFND/ERROR_LOG on SAP Gateway hub system and search for entries with the timestamp above for more details See SAP Note 1797736 for error analysis (https://service.sap.com/sap/support/notes/1797736)

Add the following query into the Customized query field: $filter=IsActiveEntity eq true or $filter=IsActiveEntity eq false. 


Empty result found.

There is no data coming back from the API call. Possible reasons:

  • No relevant data available in the API database
  • Filter setting is restrictive
  • URL parameter setting is restrictive

Select the Allow empty result check box.

API object does not exist.

Allowed API object format is <API ID>(Description).

Locate and select an API Object from the drop-down list.

Entity does not exist.

The entered Entity is not found in the server.

Locate and select the Entity from the drop-down list.

Additional information

The following contents provide some helpful information to assist you while using the SAP S/4HANA Read Custom Query Snap.

Snap General Behavior

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

  • GET operation to read data from the SAP S/4HANA server.
  • 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 check box).
  • 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. For more information, see Using Customized 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 field.

Pagination

Client-side pagination is supported through the use of the $top (Output entry limit), and $skip (Output entry offset) OData 2.0 operations. You can add $top and $skip system parameters to the Customized query field. $skiptoken is not supported for this release. For details of OData 2.0 query operation, see OData 2.0 Documentation.

Examples

Snap Output Setting
Pagination result
Output entry limit: 100
  • Retrieves the first 100 API response records from the server (if more than 100 records are present in API response).
  • Retrieves all the available API response records from the server (if 100 or less records are present in API response).
Output entry offset: 50
  • Retrieves API response records starting from index 51 from the server (if more than 50 records are present in API response).
  • Retrieves all available records starting from index 51 (up to the last index/record).
  • Returns empty result (if 50 or less records are present in API response).
Output entry offset: 100, and 
Output entry limit: 100
  • Skips the first 100 records and collects the 200 - 300 records in the API response from the server.

Accessing Related Entities from Snap Outputs for an Entity

Records in SAP S/4HANA Read Custom Query Snap output may contain navigation properties, typically uri fields, pertaining to some entities related to the entity specified in Snap Settings.

For example, the SAP S/4HANA Read Custom Query 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 one of the three SAP S/4HANA Read Snaps 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 Service URL field of a REST Get Snap.

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

Example: Accessing related entities

While querying for AccountCollection entity in the API object ZCRM_BUPA_OData_0001 (OData Services for Business Partner), you can navigate to the Contacts property by connecting any one of the three Read Snaps from this Snap Pack in the downstream to call the ContactCollection entity in the API object ZCRM_BUPA_OData_0001 (OData Services for Business Partner) and filter with a specific accountId.

  • If using the SAP S/4HANA Read Custom Query Snap in the downstream, enhance the customized query by adding $expand=Contacts,Addresses to display the contents of these two properties in the API response of the entity AccountCollection.

Examples

Retrieve sales order data from SAP S/4HANA server

This Pipeline example demonstrates how to use a SAP S/4HANA Read Custom Query Snap to define a custom query for retrieving sales order records from the SAP S/4HANA On-Premise instance. The Snap queries the A_SalesOrder entity via API object ZAPI_SALES_ORDER_SRV_0001 (Remote API for SD Sales Order) for sales order data.

The example assumes that you have configured and authorized a valid SAP S/4HANA Account (see Configuring SAP S/4HANA Accounts).

Download this Pipeline.

SAP S/4HANA Read Custom Query Snap

The following settings are defined for the SAP S/4HANA Read Custom Query Snap to retrieve Sales order data from the SAP S/4HANA On-Premise instance it accesses.

  • API objectZAPI_SALES_ORDER_SRV_0001 (Remote API for SD Sales Order) 
  • EntityA_SalesOrder
  • Filter criterion: For Plant 0001 and no other filters (Plant value equals '0001' and Condition None)

A successful validation or execution of the Snap gives the following output preview.

JSON Formatter Snap

A JSON Formatter Snap is connected to the SAP S/4HANA Read Custom Query Snap to read and format its output data into standard JSON format.

File Writer Snap

A File Writer Snap is connected to the JSON Formatter Snap to save/write the JSON-formatted data into a file.

Output

To view the output JSON file, you must SSH to the target directory and open the newly-created JSON file. The preview of the output JSON file can be seen below:

Downloads

Important Steps to Successfully Reuse Pipelines

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

Snap Pack History

 Click here to expand...
Release Snap Pack VersionDateType  Updates
4.29main108 StableUpgraded with the latest SnapLogic Platform release.
4.28main100 StableUpgraded with the latest SnapLogic Platform release.
4.27 Patchmain95 Latest
  • Enhanced the SAP S/4 HANA Snaps to support sub-entities and pagination support.

  • Removed unnecessary datatype conversions.

  • Reduced metadata request volume.

  • Fixed issues in concurrency exception and potential Snap crashes.

4.27main93 StableUpgraded with the latest SnapLogic Platform release.
4.26main88 StableUpgraded with the latest SnapLogic Platform release.
4.25main73
 
StableUpgraded with the latest SnapLogic Platform release.
4.24main73
StableUpgraded with the latest SnapLogic Platform release.
4.23main7430
 
Stable

Enhances the Snap Pack to handle batch and custom query operations:

  • Introduces the SAP S/4HANA Batch Read Snap that enables retrieving batches of records from an SAP S/4HANA On-Premise instance.
  • Introduces the SAP S/4HANA Batch Write Snap that enables writing batches of records to an SAP S/4HANA On-Premise instance.
  • Introduces the SAP S/4HANA Read Custom Query Snap that enables retrieving multiple records from an SAP S/4HANA On-Premise instance, based on custom queries.
  • Introduces the SAP S/4HANA SSL Auth Account type to enable SSL-based authentication on an SAP S/4HANA On-Premise instance.
  • Adds the Count field to the SAP S/4HANA Read Snap to allow returning the total number of records retrieved.
4.22 Patch 422patches6973 Latest

Enhances the SAP S/4HANA Snap Pack with the following additions:

4.22main6403
 
StableUpgraded with the latest SnapLogic Platform release.
4.21snapsmrc542

 

StableInitial release.


See Also