In this article
| Table of Contents | ||||
|---|---|---|---|---|
|
Overview
Use this Snap to ...
Prerequisites
- Valid client ID
Noneretrieve multiple data objects from an entity in SAP S/4HANA applications using custom Odata queries.
Prerequisites
A valid account that supports SAP S/4HANA, with appropriate access permissions. See SAP S/4HANA Accounts.
Support for Ultra Pipelines
Capture if Ultra Mode is supported. If the Snap requires certain configurations to support Ultra mention those as well.
- Works in Ultra Pipelines.
- Works in Ultra Pipelines if ....
- Does not support Ultra Pipelines.
See Snap Support for Ultra Pipelines.
Limitations and Known Issues
- Supports reading from S3 only...
- ..SAP S/4HANA On-Premise does not support server-side pagination. As a result, the $skiptoken is not supported.
Snap Input and Output
| Input/Output | Type of View | Number of Views | Examples of Upstream and Downstream Snaps | Description | ||
|---|---|---|---|---|---|---|
| Input | Document Binary Binary or Document |
|
| A document containing data that can be used to filter entities that need to be retrieved in SAP S/4HANA server. | ||
| Output | DocumentBinary Binary or Document |
|
| The EDI transaction ID and order confirmation
|
| A document containing the data retrieved from an SAP S/4HANA entity. |
Snap Settings
...
| title | Documenting Fields Based On Data Type/UI Element |
|---|
**Delete Before Publishing**
Choose from the following sentences to document specific field types.
...
| 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 | 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 fieldset to add customized HTTP request headers for implementing specific HTTP requests other than the ones listed in the Using Customized Headers section of this page. Only one customized header can be specified in each row. Click This fieldset comprises the following fields:
| ||||||||
Field name | String | The field name of the customized HTTP request header. | N/A | If-Match | |||||
Field value | String | The field value of the customized HTTP request header. | N/A | W/"'82F636DC08F14D22260CE67E505C231D0D2ACD95'" | |||||
Key parameter | This property table 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.
Click + to add a new row in this table and define the values accordingly. | ||||||||
Field name | String | Specify the reference parameter in this field. | N/A | accountID | |||||
Field value | Any | 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. | N/A | TEST_001 | |||||
| Customized query | String | This field enables you to enter your Odata query.
| N/A | $filter=accountID eq 'Test_123' and name1 eq 'testname'&$select=accountID,name1,name2& orderby=name1 desc | |||||
| Count | Check box | Select this check box to return only the total number of records retrieved in the API response.
| Deselected | Selected | |||||
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 section of Snap Settings to specify the connectivity parameters: timeout, retry count, and retry interval. This fieldset comprises the following fields:
| ||||||||
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:
| |||||||
...
|
...
|
...
Check boxes:
- If selected, <Snap behavior>.
If selected, an empty file is written when the incoming document has no data. - If selected, <behavior>. If not selected/Otherwise, <behavior>
Use "If not selected" if the first sentence is long.
If selected, the Snap uses the file path value as is. Otherwise, the Snap uses the file path value in the URL.
If selected, an empty file is written when the incoming document has empty data. If there is no incoming document at the input view of the Snap, no file is written regardless of the value of the property.
- Select to <action>
Use this if the behavior is binary. Either this or that, where the converse behavior is apparent/obvious.
Select to execute the Pipeline during validation.
Text Fields
- Describe what the field represents/contains. Additional details, as applicable, in a separate sentence. Include caveats such as the field being conditionally mandatory, limitations, etc.
The name of the account.
The account ID that you want to use to log in to the endpoint.
Required if IAM Role is selected.
Do not use this field if you are using batch processing.
Numeric Text Fields
- Describe what the field represents/contains. Additional details, as applicable, in a separate sentence. Include caveats such as the field being conditionally mandatory, limitations, etc. Include special values that impact the field's behavior as a bullet list.
The number of records in a batch.
The number of seconds for which you want the Snap to wait between retries.
The number of seconds for which the Snap waits between retries.
Use the following special values:
* 0: Disables batching.
* 1: Includes all documents in a single request.
...
Field Sets
Specify advanced parameters that you want to include in the request.
This fieldset consists of the following fields:
- Field 1
- Field 2
- Field 3
Troubleshooting
...
Batch execution failed
...
The Pipeline ended before the batch could complete execution due to a connection error.
Verify that the Batch size field is configured to handle the inputs properly. If you are not sure when the input data is available, configure this field as zero to keep the connection always open.
Examples
Excluding Fields from the Input Data Stream
You can exclude the fields that you do not require from the input data stream by omitting them in the Input schema field set.
<screenshot of Pipeline/Snap>
...
Validate & Execute | N/A |
Troubleshooting
| Error | Reason | Resolution |
|---|---|---|
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) | Please 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:
| 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
For this release, the client-side pagination is supported and released by using the $top and $skip OData 2.0 operations. To do the pagination, you can add $top and $skip system parameters to the Customized query field. For details of OData 2.0 query operation, please see OData 2.0 Documentation. Here are a few examples for pagination setting:
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.
Examples
Snap Output Setting | Pagination result |
|---|---|
| Output entry limit: 100 |
|
| Output entry offset: 50 |
|
| Output entry offset: 100, and Output entry limit: 100 |
|
Using Customized Headers
See Using Customized Headers (in SAP S/4HANA Read Snap).
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.
| Info | ||
|---|---|---|
| ||
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.
|
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.
| Note |
|---|
The example assumes that you have configured and authorized a valid SAP S/4HANA Account (see Configuring SAP S/4HANA Accounts). |
| Expand | ||
|---|---|---|
| ||
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.
A successful validation or execution of the Snap gives the following output preview.
|
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
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
| Note | ||
|---|---|---|
| ||
|
| Attachments | ||
|---|---|---|
|
| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
...