In this article
| Table of Contents | ||||
|---|---|---|---|---|
|
Overview
Use this Snap to retrieve multiple data objects in one HTTP request from SAP S/4HANA applications. The Snap returns a multipart binary stream document in its output. Depending on your requirement, it might be necessary to use a Multipart Reader Snap next to this Snap.
Prerequisites
- Valid client ID
None
Prerequisites
A valid account with appropriate access permissions to connect to the SAP S/4HANA On-Premise instance. 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 used for server-side pagination 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 orDocument |
|
|
Document
Binary
Binary or Document
- Min:
- Max:
- ..
- ..
The EDI transaction ID and order confirmation.
Snap Settings
...
| title | Documenting Fields Based On Data Type/UI Element |
|---|
**Delete Before Publishing**
Choose from the following sentences to document specific field types.
...
| A JSON document containing input data of the batch request and can be used to filter entities that need to be retrieved in SAP S/4HANA Server. | |||
| Output | Binary Document (default) |
|
| A document that contains the data retrieved from an SAP S/4HANA entity. The output document can be a multipart binary stream or a document stream.
|
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 | SAP S/4HANA Batch Read | ||||||||||
API object | String | Required. Select the API that you want to access in SAP S/4HANA On-Premise instance by clicking the | N/A | ZCRM_BUPA_ODATA_0001 (Odata Services for Business Partner) | ||||||||||
| Entities | Required. Use this field set to specify the different entities that you want to access.
You must specify each entity in a separate row. Click This field set comprises of the following fields:
| |||||||||||||
Entity | String | Required. Select a business object (the Entity or Endpoint) for the API object chosen above, by clicking the | N/A | AccountCollection | ||||||||||
Output entry limit | Integer | The maximum number of entries that you want to retrieve from SAP S/4 HANA On-Premise for the entity.
| N/A | 10 | ||||||||||
Output entry offset | Integer | The starting index, that can also be used with an Output entry limit, for the output.
| N/A | 10 | ||||||||||
Is an active entity | String | Specify the value for the IsActiveEntity field in the HTTP request. There are many SAP S/4HANA entities that require the field IsActiveEntity to be set to true or false and included in the HTTP request. The Snap displays the 'Draft 2.0 object <SERVICE~ENTITY> requires selection condition on IsActiveEntity', error if this field is not included for those entities. Available options are:
| not available | true | ||||||||||
| Count | Check box | Select this check box to return only the total number of records retrieved in the API response.
| Not 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 | Integer | Required. Specify the connection timeout duration in seconds, in this field. | 300 | 480 | ||||||||||
Maximum request attempts | Integer | Required. Specify the maximum number of re-connections in case of connection failure or timeout. | 3 | 5 | ||||||||||
RetryInterval | Integer | Required. Specify the time interval in seconds to be maintained between two reconnections. | 1 | 5 | ||||||||||
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 | Execute only |
Troubleshooting
| Error | Reason | Resolution |
|---|---|---|
The entered FilterRecords operator is not allowed for the batch input with Batch ID: <EntityName>_<BatchNumber> | The operator selected for FilterRecords is not allowed. | Select an operator field from the list: Equals, Not equals, Less than, Greater than, Less than or equal, Greater than or equal, Starts with, Ends with. |
The entered FilterRecords condition is not allowed for the batch input with Batch ID: <EntityName>_<BatchNumber> | The FilterRecords condition selected is not allowed. | Select one of the following values in the Condition field: And, Or, None. |
The entered OrderBy value is not allowed for the batch input with Batch ID: <EntityName>_<BatchNumber> | The OrderBy value entered is not allowed. | Enter one of the following values in the OrderBy field: Ascending, Descending. |
Entity is not existing. Batch Number: <BatchNumber>. | The entered entity is not found for the selected API object in the server. | Locate and select an appropriate entity from the drop-down list. |
API object is not existing. | Allowed API object format is <API ID>(Description). | Locate and select an appropriate API object from the drop-down list. |
Additional Information
Here is some information to assist you while using the SAP S/4HANA Batch Read Snap.
Snap General Behavior
The SAP S/4HANA Batch Read Snap supports the following:
- GET operation to read multiple data objects from the SAP S/4HANA server.
- OData querying operations: $filter (FilterRecords), $select (OutputFieldSelection), $orderby (OrderBy), $top (Output entry limit), and $skip (Output entry offset). FilterRecords, OutputFieldSelection, and OrderBy will be shown in the input schema for this Snap.
- OData operation $count (Count check box).
- Connection-failed-retry mechanism.
- Client-side pagination through $top (Output entry limit) and $skip (Output entry offset) mechanisms.
- 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).
Sending Batch Request
The SAP S/4HANA supports the OData 2.0 protocol. SAP S/4HANA APIs that support OData 2.0 can send batch requests with specific requirements and for specific operations. See the documentation at OData 2.0 batch request, for more details.
Batch Input Schema
The Input Schema (the Target Schema of the preceding Mapper Snap) enables you to define the input data for the Batch requests. For SAP S/4HANA Batch Read Snap, the $filter (FilterRecords), $select (OutputFieldSelection), $orderby (OrderBy), KeyParameter and CustomizedHeader can be defined using the Input Schema.
Schema settings
| Parameter Name | Data Type | Description | ||
|---|---|---|---|---|
CustomizedHeader | Use this property schema to add customized HTTP request headers for implementing specific HTTP requests other than the ones listed under Using Customized Headers section. | |||
name | String | The field name of the customized HTTP request header. | ||
value | String | The field value for the above field in the customized HTTP request header. | ||
FilterRecords | This property schema enables you to define how the response result be filtered based on the specified parameters. | |||
name | String | Specify the name of the system parameter $filter fields to be included in the output. | ||
operator | String | Specify the comparison operator for the system parameter $filter. | ||
value | Any | The values of specified input $filter fields. The data type of this field depends on what Field name you selected or entered which can be String, Integer, Boolean, etc. | ||
condition | String | Specify the logical operator for the system parameter $filter. | ||
| KeyParameter | This property schema enables you to specify the key parameters for a specific entity. Providing values for all key parameters represented in the schema list enables SAP S/4HANA to identify a unique record.
| |||
OrderBy | With this property schema, it is possible to order the resulting records based on the specified element. The order types to be selected are either ascending or descending. | |||
name | String | Specify the field that will be used for sorting by descending or ascending order. | ||
value | String | Specify the Order Type (Ascending or Descending order). | ||
| OutputFieldSelection | With this property schema, it is possible to select fields to be included in the output. If not selected, all fields of the selected entity will be returned. | |||
| name | String | The name of the entered field to be included in the output. | ||
Using Customized Headers
SAP S/4HANA On-Premise 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, Etag.
- SAP S/4HANA Snap Pack supports 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, and
- Cookie
| Info |
|---|
The HTTP headers listed above are internally handled by the Snap and need NOT be defined again in CustomizedHeader section. |
Accessing Related Entities from Snap Outputs for an Entity
Records in SAP S/4HANA Batch Read 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 Batch 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 any 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 multiple Account and Contact records from SAP S/4HANA server
This Pipeline example demonstrates using a SAP S/4HANA Batch Read Snap to query and retrieve multiple records from customer material data in SAP S/4HANA On-Premise and write it into a JSON file. The Snap queries the AccountCollection and ContactCollection entities via API object ZCRM_BUPA_ODATA_0001 (Odata Services for Business Partner).
| Note |
|---|
The example assumes that you have configured and authorized a valid SAP S/4HANA Account (see Configuring SAP S/4HANA Accounts). |
Mapper Snap
The Mapper Snap is configured to map the schema from its input JSON (coming from the upstream JSON Generator Snap) with the schema propagated backward by the SAP S/4HANA Read Batch Snap. It also outputs the Target Schema as the Input Schema for the SAP S/4HANA Batch Read Snap.
SAP S/4HANA Read Batch Snap
The following settings are defined for the SAP S/4HANA Batch Read Snap to retrieve Accounts and Contact data from the SAP S/4HANA On-Premise instance. The Snap is configured to send three HTTP API requests (one on AccountCollection and two on ContactCollection) in a single call to the SAP S/4HANA server.
- API object: ZCRM_BUPA_ODATA_0001 (Odata Services for Business Partner)
- Entities: AccountCollection and ContactCollection
A successful validation or execution of the Snap gives the following output preview.
The Binary output view:
JSON Document output view:
File Writer
The File Writer Snap is connected to the SAP S/4HANA Batch Read 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 containing the batch response data can be seen below:
Downloads
| Note | ||
|---|---|---|
| ||
|
| Attachments | ||
|---|---|---|
|
| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
...