Skip to Content
Technical Articles

Testing of S/4HANA Financial Planning Data ODATA APIs via SAP API Hub

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 two services from the development area I’m working in. This document describes how the following OData APIs from Financial Planning can be tested together from the API hub:

  • Read Financial Planning Data
  • Write Financial Planning Data

The test script below offers a guideline how financial plan data can be found. Subsequently, this information can be used to post financial plan data.

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

Part 1: Find Available Financial Plan Data

  1. Open “Read Financial Planning Data Entry Item” OData service in the S/4HANA Cloud section of API Hub or directly open https://api.sap.com/api/API_FINPLANNINGENTRYITEM_SRV/resource?tag=A_FinPlanningEntryItem&path=get_A_FinPlanningEntryItem&method=get&opId=get_A_FinPlanningEntryItem
  2. 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 calls.
  3. Under the resource “GET A_FinPlanningEntryItem”, click the button “Try out”. Then create a new header parameter by clicking the button “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value “Fetch”.
  4. Under the resource “GET A_FinPlanningEntryItem”, click the button “Add” -> “Query”. Enter parameter “$filter” and value “PlanningCategory%20eq%20%27PLN%27″. Again click the button “Add” -> “Query” and enter a value like “10” for the parameter “$top” to reduce the number of lines that will be later returned in the response.
  5. Click the button “Execute”. The request is executed and the response contains several planning data records including the amounts in different currencies (see Figure 1).

Figure 1: Response of Read Financial Planning Data.

 

Part 2: Post Financial Plan Data

6. Under “Responses” you find in the response body the ten requested financial plan data entries. Look for the fields “Ledger”, “PlanningCategory”, “LedgerFiscalYear”, “GLAccount”, “CompanyCode”, “FiscalPeriod”, “FiscalYearPeriod” and the amount fields “AmountInTransactionCurrency”, “AmountInCompanyCodeCurrency”, “AmountInGlobalCurrency” with their corresponding currencies.

7. Under “Responses” you find in the response header section the “x-csrf-token” for example x-csrf-token: 1U9-osE5pwCzTRZBEaHzFg==. It will be created newly for each session. This token will be needed to send write data requests.

8. Copy the x-csrf-token and open OData service “Financial Planning Data: Write” in the S/4HANA Cloud section of API Hub or directly open https://api.sap.com/api/API_FINPLANNINGDATA_SRV/resource

9. Under the resource “POST FinancialPlanData”, click the button “Try out”. Add a new header parameter with “Add” -> “Header”. Enter the header name “X-CSRF-Token” and the value from step 7.

10. Add the following JSON fragment into the body of “FinancialPlanDataType” and replace the fields for “PlanningCategory”, “GLAccount” and “CompanyCode”, with the values that has been found in step 6. Adjust “LedgerFiscalYear”, “FiscalYearPeriod” and the amount in field “AmountInCompanyCodeCurrency”. Set the correct currency of the company code in field “CompanyCodeCurrency”.

“PlanDataAggrgnLvlFieldsStrings” describes the aggregation level that is posted (here Ledger Fiscal Year, Planning Categroy, Company Code, Fiscal Year Period, GL Account, Company Code Amount and Compnay Code Currency).

“PlanDataRplcScopeFieldsString” describes the replace scope and will be derived from the aggregation level if it is empty as in the example.

Example comprises 5 plan data records of planning category “PLN” that are posted on G/L account “41000000” in the first five periods of ledger fiscal year “2012” and company code “1710”.

{
  "PlanDataAggrgnLvlFieldsString" : "LedgerFiscalYear,PlanningCategory,CompanyCode,FiscalYearPeriod,GLAccount,AmountInCompanyCodeCurrency,CompanyCodeCurrency",
  "PlanDataRplcScopeFieldsString" : "",
 "to_FinPlanningEntryItemTP" : {
     "results" : [
       {
         "PlanningCategory" : "PLN",
         "LedgerFiscalYear" : "2012",
         "GLAccount" : "41000000",
         "CompanyCode" : "1710",
         "CompanyCodeCurrency" : "USD",
         "AmountInCompanyCodeCurrency" : "224501.00",
         "FiscalYearPeriod" : "001.2012"
       },
       {
         "PlanningCategory" : "PLN",
         "LedgerFiscalYear" : "2012",
         "GLAccount" : "41000000",
         "CompanyCode" : "1710",
         "CompanyCodeCurrency" : "USD",
         "AmountInCompanyCodeCurrency" : "424501.00",
         "FiscalYearPeriod" : "002.2012"
       },
       {
         "PlanningCategory" : "PLN",
         "LedgerFiscalYear" : "2012",
         "GLAccount" : "41000000",
         "CompanyCode" : "1710",
         "CompanyCodeCurrency" : "USD",
         "AmountInCompanyCodeCurrency" : "304501.00",
         "FiscalYearPeriod" : "003.2012"
       },
       {
         "PlanningCategory" : "PLN",
         "LedgerFiscalYear" : "2012",
         "GLAccount" : "41000000",
         "CompanyCode" : "1710",
         "CompanyCodeCurrency" : "USD",
         "AmountInCompanyCodeCurrency" : "104501.00",
         "FiscalYearPeriod" : "004.2012"
       },
       {
         "PlanningCategory" : "PLN",
         "LedgerFiscalYear" : "2012",
         "GLAccount" : "41000000",
         "CompanyCode" : "1710",
         "CompanyCodeCurrency" : "USD",
         "AmountInCompanyCodeCurrency" : "230000.00",
         "FiscalYearPeriod" : "005.2012"
       }
     ]
   }
 }

Figure 2: Request body of Write Financial Planning Data.

11. Click the button “Execute”. After the plan data is processed, a response code “201” is returned. The response body contains the posted plan data records.

In case of different return code than “201”  the posting request failed. See the response body for the returned errors. After correction step 11 can be repeated.

12. To verify your postings go back to OData service “Read Financial Planning Data Entry Item” (see step 3.)

Under the resource “GET A_FinPlanningEntryItem”, click the button “Add” -> “Query”. Enter parameter “$filter” and value that you have posted. In the example “PlanningCategory%20eq%20%27PLN%27%20and%20LedgerFiscalYear%20eq%20%272012%27”.

Click the button “Execute”. The request is executed and the response should contain the plan data records that you have posted in step 11.

 

Further Information

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

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 “Financial Planning Entry Item – Read” and “Financial Plan Data – Write”.

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

Be the first to leave a comment
You must be Logged on to comment or reply to a post.