Testing of S/4HANA Inventory Management ODATA APIs via SAP API Hub

[christopher_thiele]

Overview

When you want to create your own app that consumes services offered by others, the initial step is always the hardest: How do these services work? Which input is required? Which data is returned?

The SAP API Hub lists (amongst others) all OData services that are available in S/4HANA Cloud. You could already execute GET requests via the API Hub in the past, and now the first services even offer write operations via this platform.

I've written a step-by-step description for three services from the development area I'm working in. This document describes how the following OData APIs from Inventory Management can be tested together from the API hub:

• Material Stock Display


• Process Material Documents


• Process Physical Inventory Documents

The test script below offers a guideline how available combinations of material, plant, storage location, and inventory stock type can be found. Subsequently, this information can be used to post material documents and physical inventory documents to change the book quantities.

Of course, the services offer more functionality than described here. At the end of this blog post you can find links to the complete documentation.

Part 1: Find Available Material Stocks

In later chapters, we will change the stock level of a single material / plant / storage location combination. So here in the first part, we will have a look at the sandbox system and check which master data is already in use in Inventory Management.

Figure 1: Response of Material Stock Display

 

Step	Description	Outcome
1.	Open the tab “Resource” of the “Material Stock Display” OData service in the S/4HANA Cloud section of API Hub .
2.	Under the resource “GET A_MaterialStock”, enter a value like “10” for the parameter “$top” to reduce the number of lines that will be later returned in the response.
3.	Select the value “to_MatlStkInAcctMod” for the parameter “$expand” to retrieve later the actual stock quantities.
4.	Click the button “Try it out!”	The request is executed and the response contains several materials including the current stock levels. See also Figure 1: Response of Material Stock Display.
5.	Select one result entity where the fields “InventoryStockType” equals “01”, “InventorySpecialStockType” equals “”, and “Batch” equals “”. Note the fields “Material”, “Plant”, “StorageLocation”, “MaterialBaseUnit”, and "MatlWrhsStkQtyInMatlBaseUnit".	The field "MatlWrhsStkQtyInMatlBaseUnit" shows the current quantity.

 

Part 2a: Get a X-CSRF-Token to Post a Goods Receipt Material Document

Without a valid X-CSRF-token, no changing operation on an OData service is possible. But with a simple GET request, we can ask the OData service to return such a token that we then use in subsequent POST or PATCH calls.

Step	Description	Outcome
6.	Open the tab “Resource” of the “Process Material Documents” OData service in API Hub.
7.	Under the resource “GET A_MaterialDocumentHeader”, create a new header parameter by clicking the button “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value “Fetch”.
8.	Enter a value of “10” for the parameter “$top”.
9.	Click the button “Try it out!”	The service returns 10 existing material documents. Under the section “Response Headers” the field “x-csrf-token” can be found.
10.	Note the content of the header “x-csrf-token” in the response. The brackets “[]” can be omitted.	The noted token looks like “rEZ8WXMxOtCbY9N3JnoGlA==”, it will be created newly for each session. This token will be needed to send data changing requests to the service.

 

Part 2b: Post a Goods Receipt Material Document

Now we are ready to request the first stock change: A goods receipt without purchase order (movement type "501") will increase the quantity of the material in the storage location.

Step	Description	Outcome
11.	Open the resource “POST A_MaterialDocumentHeader”.
12.	Add a new header parameter with “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value from step 10.).
13.	Add the following JSON fragment into the field “A_MaterialDocumentHeaderType” and replace the fields for material, plant, storage location, and material base unit with the content that has been noted in step 5.). Replace the field for the posting date with a current date and enter a small quantity into “QuantityInEntryUnit” (because of the material document created here, this quantity will be added to the stock quantity from step 5.): { "PostingDate": "2018-01-01T00:00:00", "GoodsMovementCode": "01", "to_MaterialDocumentItem": [{ "Material": "TG11", "Plant": "1710", "StorageLocation": "171A", "GoodsMovementType": "501", "EntryUnit": "PC", "QuantityInEntryUnit": "1" }] }
14.	Click the button “Try it out!”	After the material document is processed, a response code “201” is returned. The response body contains the key of the newly created document (fields “MaterialDocumentYear” and “MaterialDocument”).   If a return code “400” with the error code “M7/053”, error message “Posting only possible in periods … and … in company code …” is returned, the posting date in the request has to be changed to match the given periods. After a correction of the posting date, step 13.) can be repeated.

 

Part 3: Checking the Stock after the Posting of the Material Document

Did the goods receipt really work? Let's check it!

Step	Description	Outcome
15.	Return to the “Material Stock Display” OData service and expand the resource “GET /A_MaterialStock(‘{Material}’)”. Enter the name of the material from step 5.) as the “Material” parameter.
16.	Select the value “to_MatlStkInAcctMod” for the parameter “$expand”. Click the button “Try it out!”.	The quantity in field “MatlWrhsStkQtyInMatlBaseUnit” was increased by the quantity given in step 13.) compared to the stock quantity in step 5.). Note down the content of this quantity field.

 

Part 4: Check for Existing Physical Inventory Documents

Now we want to perform an inventory count for our material / plant / storage location combination. But since there can only be one inventory count for such a combination that is in process in the current fiscal year, we first have to check the current state of counts in the sandbox system.

Step	Description	Outcome
17.	Open the tab “Resource” of the “Process Physical Inventory Documents” OData service in the API hub.
18.	Expand the section “A_PhysInventoryDocItem” and then “GET /A_PhysInventoryDocItem”.
19.	Fill the “$filter” field with a search string like this:   “Material eq 'TG11' and Plant eq '1710' and StorageLocation eq '171A'”   The material, plant, and storage location are taken over from step 5.).	A response code “200” is returned together with a list of all matching physical inventory document items.   Please note: The list can be empty. In this case, no physical inventory document with a corresponding item was created yet, which is okay to continue this guideline.

 

Part 5: Creation of a Physical Inventory Document

If in step 19.) a response which contains the field "PhysInvtryDifferenceIsPosted”: “false” is found, this part can’t be processed yet because there is still an open physical inventory count in the system for this combination of material, plant, storage location, etc. This would result in the error code “M7/700” (cf. step 23).

If this is not the case, we are able to continue now with the creation of a small physical inventory document with one item.

Step	Description	Outcome
20.	Open the resource “POST  /A_PhysInventoryDocHeader”.
21.	Add a new header parameter with “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value from step 10.).
22.	Add the following JSON fragment into the field “A_PhysInventoryDocHeaderType” and replace the fields for material, plant, and storage location with the content that has been noted in step 5.). Replace the field for the document and planned count date with a current date:   { "Plant": "1710", "StorageLocation": "171A", "DocumentDate": "2018-01-01T00:00:00", "PhysInventoryPlannedCountDate": "2018-01-02T00:00:00", "to_PhysicalInventoryDocumentItem": [{ "Material": "TG11" }] }
23.	Click the button “Try it out!”.	After the physical inventory document has been created, a status code “201” is returned. In the response body, the identifier of the new physical inventory document can be found.   If the response code is “400” with the error code “M7/728", error message "Phys. inventory document can only be created for year …", repeat step 22.) with an adjusted document and planned count date.   An error code “M7/700" "Physical inventory for 1710 171A TG11” is already active" would be returned here if in step 19.) a physical inventory item which is not finished is found.
24.	Note down the content of the fields “PhysicalInventoryDocument” and “FiscalYear” in the response body. Additionally, the field “etag” is needed in the next steps.

 

Part 6: Enter a Count Result for the Created Physical Inventory Document

After the creation of the physical inventory document, we can now enter the count result into its item.

Step	Description	Outcome
25.	Open the resource “PATCH /A_PhysInventoryDocItem(FiscalYear='{FiscalYear}', PhysicalInventoryDocument='{PhysicalInventoryDocument}', PhysicalInventoryDocumentItem='{PhysicalInventoryDocumentItem}')”
26.	Add a new header parameter with “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value from step 10.).
27.	Add a new header parameter with “Add” -> “Header”. Enter the header name “If-Match” and the “etag”-value from step 24.) in the format “W/"datetimeoffset'2018-01-31T13%3A31%3A33.7933940Z'"”.
28.	Enter the values from step 24.) for the corresponding parameters “FiscalYear” and “PhysicalInventoryDocument”. Enter “001” in the parameter field “PhysicalInventoryDocumentItem”.
29.	Add the following JSON fragment into the field “A_PhysInventoryDocItemType” and replace the fields for material and material base unit with the content that has been noted in step 5.). Replace the field for the planned count date with a current date. Chose a quantity that is near the quantity from step 16.), but with a small difference:   { "Material": "TG11", "QuantityInUnitOfEntry": "12", "UnitOfEntry": "PC", "PhysicalInventoryLastCountDate": "2018-01-02T00:00:00" }
30.	Click the button “Try it out!”.	After the count result has been entered into the physical inventory document item, a status code “204” is returned. There is no response body.   Note down the new etag that can be found under the response headers.

 

Part 7: Post the Count Result

To complete the count process, we accept now the entered inventory difference from the previous part and post it. This will update the stock level accordingly.

Step	Description	Outcome
31.	Open the resource “POST /PostDifferencesOnItem”.
32.	Add a new header parameter with “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value from step 10.).
33.	Add a new header parameter with “Add” -> “Header”. Enter the header name “If-Match” and the “etag”-value from step 30.) in the format “W/"datetimeoffset'2018-01-31T13%3A31%3A33.7933940Z'"”.
34.	Enter the values from step 24.) for the corresponding parameters “FiscalYear” and “PhysicalInventoryDocument”. Enter “001” in the parameter field “PhysicalInventoryDocumentItem”.
35.	Enter the material from step 5.) in the parameter field “Material”.
36.	Enter a current date in the parameter field “PostingDate” in the format “datetime’2018-01-02T00:00:00’”
37.	Click the button “Try it out!”.	When the difference is posted, the service returns a status code of “200”.   The response body contains the field “BookQtyBfrCountInMatlBaseUnit”, which should show the quantity from step 16.).

 

Part 8: Checking the Stock after the Finished Inventory Count

Finally, we have a look at the quantity again!

Step	Description	Outcome
38.	Return to the “Material Stock Display” OData service and expand the resource “GET /A_MaterialStock(‘{Material}’)”. Enter the name of the material from step 5.) as the “Material” parameter.
39.	Select the value “to_MatlStkInAcctMod” for the parameter “$expand”. Click the button “Try it out!”.	The quantity in field “MatlWrhsStkQtyInMatlBaseUnit” was changed to the quantity given in step 29.). Thus the physical inventory count was posted successfully.

 

Further Information

You can find the documentation for the here used services via the following URLs:

• Material Stock Display:
  https://help.sap.com/viewer/41872f9177ce43b096e5f471797b574b/latest/en-US/f68f51a4dc2e46779877a10a30...


• Process Material Documents:
  https://help.sap.com/viewer/7760de6f44074d4994c4da9832f7bfca/latest/en-US/d4c919581bc30a02e10000000a...


• Process Physical Inventory Documents:
  https://help.sap.com/viewer/bdfa00ce3fa443e4b4ffa9b522a5b3cc/latest/en-US/58361658745b1f60e10000000a...

Summary

With the step-by-step description above, you should be able to try out the now released write operations in the SAP API Hub for the services "Process Material Documents" and "Process Physical Inventory Documents".

This can be your first learning steps before you implement your own app consuming these or other services!