SAP S/4HANA Read

 

Snap Type:

Read

Description:

This Snap provides the ability to retrieve data from SAP S/4 HANA application.

Prerequisites:

An SAP S/4HANA Basic Auth Account

Support and limitations:

Ultra pipelines: Supported in Ultra Pipelines.

Spark mode: Not supported in Spark mode.

Account:

This Snap uses account references created on the SAP S/4HANA Account page of SnapLogic Manager to access to the endpoint. See SAP S/4HANA Basic Auth Account for information on setting up this type of account.

Views:

Input
This Snap has at most one document input view.

Output
This snap has at least one document output view.

Error
This Snap has one optional error view and might produce documents in the view if errors are returned from the S/4HANA application.

Settings

Label:

Required. The name for the Snap. You can modify this to be more specific, especially if you have the same Snap more than once in your pipeline.

API object:

Required. This property enables you to define the API that you want to access. This field will be populated dynamically with the list of APIs available in the S/4HANA system configured in the account snap. Users are allowed to choose an API Object from suggestion dropdown. The entity is shown as API Object name (Short description) in the dropdown.

 

Example: ZCRM_BUPA_ODATA_0001 (Odata Services for Business Partner)

Default value: [None]

Entity:

Required. This property enables you to define the Entity or Endpoint of an API. This field will be populated dynamically based on the API Object that you selected.


Example: AccountCollection

Default value: [None]

Customized header:

Add customized HTTP request header to implement specific HTTP requests. For more details, please see the Additional Information - Usage of Customized header.

 

Example: If-Match: W/"'82F636DC08F14D22260CE67E505C231D0D2ACD95'"

Default value: [None]

Key parameter:

Required. This property enables you to specify the key fields to a specific entity.

IIn case you provide one key parameter, you need to provide them all if multiple keys are found in the dropdown list. Key parameters are only to be used for retrieving specific records. So all of them need to be provided. In case you want to a filter (e.g: normal select); then use filter instead.

 

Example: accountID

Default value: [None]

Filter records:

This property enables you to define the filter settings to filter the response from the API based on the customer-selected fields.

 

Example: accountID Equals ‘TEST-AC-01'

Default value: [None]

Output field selection:

This property enables you to select fields to be included in the output. If not selected, all fields will be returned.

 

Example: accountID, name1,name2

Default value: [None]

Order by:

This property enables you to order the resulting records based on specified elements. The order types to be selected are either ascending or descending.

 

Example: name1 descending

Default value: [None]

Output fields advanced options:

Output entry limit
This property enables you to define the number of entries to return in order of SAP S4 HANA Cloud API described entry index.

Example: 10

Default value: 500

 

Output entry offset
This property can be used with an output field limit to define a starting entry index for the output entries.

Example: 10

Default value: [None]

Is an active entity:

This property enables you to set the value of the field IsActiveEntity as true, false or nothing for the selected entities.

Example: Yes

Default value: [Not available]

There are many entities that require the field IsActiveEntity to be set as true or false and added to the HTTP request. If this field is not added for these entities, an error 'Draft 2.0 object <SERVICE~ENTITY> requires selection condition on IsActiveEntity' will be returned. If ‘true’ is selected, the IsActiveEntity will be set as true, vice versa. In order to refer to the entities which do not need this field, please select 'not available'.

Allow empty result:

This property enables you to determine if the empty result will be shown in the output views. If not selected, an error will be thrown when the empty result is found.

 

Default value: Selected

Pass through:

This property enables you to pass through” the data from an incoming document and merge it into the new document being written to the output. If selected, the input document will be passed through to the output view under the key 'original'.

 

Default value: Selected

Connection details:

Connection timeout
Required. This property enables you to set the connection timeout duration in seconds.
Default value: [300]

 

Number of retries
Required. This property enables you to set the maximum number of re-connections in case of connection failure or timeout.
Default value: [3]

 

Retry interval (seconds)
Required. This property enables you to set the time interval in seconds between reconnections.
Default value: [1]

For more information on how to define the Filter records, Output field selection and Order by in the OData based API, see OData Version 2.0 Protocol.

The general behavior of SAP S/4HANA Read Snap

  • Supports GET operation to read data from the SAP S/4HANA Server.

  • Supports $filter (Filter records), $select (Output field selection), $orderby (Order by), $top (Output entry limit) and $skip (Output entry offset) Odata querying operations. For counting operations, SnapLogic statics will help to count.

  • Supports connection-failed-retry mechanism.

  • Supports client-side pagination by $top and $skip mechanisms. For details please see the Additional Information - Pagination.

  • Supports customized HTTP Headers. For details please see the Additional Information - Usage of Customized header.

  • Supports dynamic metadata loading, used to load the API metadata with a Parent-child dependency structure.
    Select an API object from the API Object field and only this selected API-object related and Read supported (GET operation supported) entities will be displayed. After selecting an entity, only this selected entity related and Read supported (GET operation supported) parameters will be shown in the fields of Key parameter, Filter records, Output field selection and Order by.

Additional Information

Pagination

For this release, the client-side pagination is supported and released by using the $top (Output entry limit) and $skip (Output entry offset) Odata operations. Here are a few examples for pagination setting:

  1. I would like to collect the first 100 API response records from the server.
    Output entry limit: 100

  2. I do not want to collect the first 100 API response records, but the rest of them from the server.
    Output entry offset: 100

  3. I would like to collect the 200 - 300 API response records from the server.
    Output entry offset: 100 (skip the first 100 records)
    Output entry limit: 100 (get the 200-300 records)

  4. I would like to get all the API response records from the server.
    Keep the default settings of the Output entry limit and Output entry offset.

  5. what happens if I only have 50 records but I give 100 to Output entry limit or Output entry offset?
    For the Output entry limit, only 50 records will be returned. And for the Output entry offset, an empty result will be returned.

$skiptoken is not supported for this release.

Usage of Customized header

For this Snap Pack, setting customized HTTP headers is allowed. SAP S/4HANA server is a huge system that contains a large number of different API objects and entities. And it is allowed to create customized API objects and entities in the server. For some entities, some specific HTTP headers might be required, If-Match and Etag, for instance. So to make it more flexible and dynamic, only a few commonly used HTTP headers are pre-defined and specific HTTP headers for specific entities are allowed. The following headers are already defined: Content-type, Cache-Control, Authorization, Accept, X-CSRF-Token, and Cookie.

Notice that:

  1. If you enter the same HTTP headers as the pre-defined ones, then the value entered in a snap will be ignored. For more questions and details please contact the support team.

  2. If you obtain the Customized header Field value from the up-stream snaps, please define the names of the fields in the former snaps as same as the names defined in the Customized header Field name. There is an example shown in the picture below.

Tips for navigation fields

In some cases, the output records of SAP S/4HANA Read Snap can contain navigation properties (displayed but only with an “uri” link). You can navigate to those entities using the uri links. In such a case, you can use another SAP S/4HANA 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 SAP S/4HANA Read Snap’s output to this Rest Get Snap Service URL field. This will return the properties of the entity returned as the “uri” link. To read more about the Rest Get Snap, please refer to the following link: REST Get.

Example

The example assumes that you have configured & authorized a valid SAP S/4HANA Basic Auth Account. The following SAP S/4HANA Read Snap and pipeline show how you can query and retrieve records from the SAP S/4HANA server. The following Snap queries the product data via API object ZSD_F2499_CUSTOMER_MATERIAL_SRV_0001 (Customer Material) and Entity C_CustomerMaterial_F2499T.

Configuring an SAP S/4HANA Read Snap to read records from an entity

The Snap specifies that the query results include only some of the columns such as salesOrganization, DistributionChannel, Customer and etc in the incident table for the selected API object ZSD_F2499_CUSTOMER_MATERIAL_SRV_0001 (Customer Material) and Entity C_CustomerMaterial_F2499. The response result is filtered by the SalesOrganization equaling '1710' and is ordered by the Customer as ascending order.

 

Implementing an example pipeline to retrieve data of an entity

The following pipeline shows how you can use SAP S/4HANA Read Snap to read material data via API object ZSD_F2499_CUSTOMER_MATERIAL_SRV_0001 (Customer Material) and Entity C_CustomerMaterial_F2499. A JSON Formatter snap and a File Writer snap are applied to format and record data in a new file.

A successful validation or execution of the Snap gives the following output preview showing the query results

Downloads

Snap Pack History

 

 

Have feedback? Email helpdesk@rojoconsultancy.com © Rojo Consultancy