SAP Business ByDesign - OData API Examples

[knutheusermann]

The SAP Business ByDesign (ByD) provides REST/OData APIs to access ByD business objects, reports and data sources:

• The OData API for Reports is tailored for remote access to pre-processed and formatted analytical data (reports). The remote application may extract a ByD analytical model as a cube incl. semantics like key figures, language-dependent texts and aggregated data.


• The OData API for KPIs is tailored to access ByD KPIs incl. context information.


• The OData API for Data Sources is designed to extract analytical raw data (data sources) in flat tables, free of redundancies from ByD.


• The OData API for Business Objects is designed for UI-driven access to ByD business objects. A UI-like remote application or system interactively queries, reads, creates, updates, deletes or performs actions on ByD business objects and business documents. Using the work center "Application and User Management - OData Services", key users are empowered to decide which business objects, nodes, elements and actions are exposed via OData API.

You find more information about ByD APIs in blog post SAP Business ByDesign – API Overview.

Where do I get OData examples?

To get some hands-on experience using SAP Business ByDesign OData APIs you find a repository of API Examples on GitHub: SAP Business ByDesign - API Samples.

The GitHub repository provides sample ByD Custom OData Services for currently 44 business objects and 6 Postman collections with more than 600 example OData requests. The Postman collections illustrate hands-on how to access master data, business documents and analytical data in context of ByD business processes with a focus on ByD OData APIs.

All sample Postman collections are tailored to SAP Business ByDesign Partner Demo Tenants (Full scope US) with preconfigured and loaded sample data provided by SAP.

Nevertheless you can use the Postman collections and sample Custom OData Services in other ByD systems as well, if you adopt Postman environment variables and Postman requests according the business configuration and master data of your ByD system.

The GitHub repository contains the following Postman collecions:

• Analytics: Access ByD built-in analytics incl. KPIs, reports and data sources.


• Master Data: Access ByD master data objects using APIs.


• Reference Scenarios: Run ByD business processes using APIs to get insights how to create, change and read involved business documents and how to create business document relationships to achieve a meaningful document flow.


• Projects: Create, change and read cost collecting projects and customer projects.


• Sales and Commerce Scenarios: Run ByD sales and commerce processes using APIs to get insights how to create, change and read involved business documents and how to create business document relationships to achieve a meaningful document flow.


• Internal Logistics: Run internal logistical processes using APIs.


• New Business: Run processes to generate new business such as leads, opportunities and quotes.

Please check the descriptions of the respective Postman collections for further details.

How to run API examples?

The easiest way to run an API sample scenario would be using a SAP Business ByDesign Partner Demo Tenant (Full scope US) with preconfigured and loaded sample data provided by SAP.
The following example is based on such a tenant and I am running the scenario "Master Data - Service Product (write)":

1. Install the API sample package "Master Data" and configure your ByD system following the instructions in  chapters "Download and Installation" and "Configuration" of the GitHub repository readme file.


2. Open the Postman Runner and select the collection "Master Data", the collection folder "Service Product (write)" and the environment "Master Data":


3. Click on "Run Service Product (write)" and see the process flow:

For more detailed analysis you can open the Postman Console to log detailed traces or simply execute the requests one-by-one in the Postman collection itself.

By the way:
The sample Postman collections may serve as well as approach to create meaningful data along process chains to prepare a ByD system for demo purposes, or to run regression tests by processing end-to-end business processes.

Blog Posts with further Examples

• Extend SAP ByDesign using SAP Cloud Platform HTML5 Applications


• Configure OAuth 2.0 for SAP ByDesign OData Services


• OData Example: Read and Write Product Purchasing Data


• OData Example: Create and Update Product Data in ByD


• Create ByD Sales Orders using Alexa


• Alexa Meets SAP Business ByDesign


• SAP Business by Design – How to Create an OData Service (Youtube)


• SAP Business ByDesign Side-by-Side Extensions on SAP Cloud Platform

[ronald_vanherk]

Hi Knut,

Thank you for all your work in the API's documentation and examples.

We are looking into use this new introduced organizationalmanagement Odata API.

We can get all the OrgUnits objects but when we try to utilize the AssignedManager.__deferred.uri of the OrgUnits we do not get the actual assigned manager that we see on the Org Unit Details screen under General - Org Unit Manager. For the most we do not get any data

Example uri: https://xxxxxx.sapbydesign.com/sap/byd/odata/v1/organizationalmanagement/OrgUnitCollection('00163E0DDA7F1ED694EDCE017099E53B')/AssignedManager

For all the other __deferred.uri's like Definition, Function and Employee we do get the correct data

Is this not yet implemented in the API or could this be a bug?

Regards,
Ronald van Herk

[knutheusermann]

Hi Ronald,

this looks like a bug; please report the issue via incident.

Best regards,
Knut

[gerdb42]

Hi Knut,

 

thank you for this great blog post.

 

However, I'm trying to get the documents attached to an employee's record, but using the khemployee request, all I get for AttachmentFolder is an empty array. What am I missing?

[knutheusermann]

Hi Gerhard,

the attachment folder in my example "khemployee" refers to the business partner attachment such as for example the employee image.

If you want to get the attachments which you see in work center view "Personnel Administration - Employees" on sheet "Personnel File - Attachments", then you need to create a custom OData service for business object "Employment" and include the employment attachment folder.

Example request:

https://myXXXXXX.businessbydesign.cloud.sap/sap/byd/odata/cust/v1/kh_test/EmploymentCollection?$form... eq 'E0210'&$expand=EmploymentAttachmentFolder

Example response:

{

	"d": {

		"results": [

			{

				"ObjectID": "0000000000011DEFBAD7E4C8D50F8CD1",

				"EmployeeID": "E0210",

				"EmploymentAttachmentFolder": [

					{

						"ObjectID": "C939D739037D1EEDBBAFEE77699D4E8C",

						"ParentObjectID": "0000000000011DEFBAD7E4C8D50F8CD1",

						"UUID": "C939D739-037D-1EED-BBAF-EE77699D4E8C",

						"Name": "Employee-attachment.txt",

						"MimeType": "text/plain",

						"Binary": "VGhpcyBpcyBhbiBlbXBsb3llZS1yZWNvcmQgYXR0YWNobWVudCBmb3IgVmljdG9yaWEgQnJhbm5vbi4=",

						"SizeInkB": "59.00000000000000",

						"OutputRelevanceIndicator": false,

						"LinkWebURI": "",

						"TypeCode": "10001",

						"TypeCodeText": "Standard Attachment",

						"CategoryCode": "2",

						"CategoryCodeText": "Document",

						"Title": "Employee-attachment.txt"

					},

					{

						"ObjectID": "C939D739037D1EEDBBAFF25B577610DB",

						"ParentObjectID": "0000000000011DEFBAD7E4C8D50F8CD1",

						"UUID": "C939D739-037D-1EED-BBAF-F25B577610DB",

						"Name": "sap.com",

						"MimeType": "",

						"Binary": "",

						"SizeInkB": "0.00000000000000",

						"DocumentLink": "",

						"OutputRelevanceIndicator": false,

						"LinkWebURI": "https://sap.com",

						"TypeCode": "10021",

						"TypeCodeText": "Job Description",

						"CategoryCode": "3",

						"CategoryCodeText": "Link",

						"Title": "SAP Homepage"

					}

				]

			}

		]

	}

}

 

[gerdb42]

Hi Knut,

 

thank you for pointing me at the "Employment" BO. After fiddling out the required attributes I finally got what I need.

[dimitrijhilt]

Hi Knut

great work so far! Esp. because ByD needs more and more interaction with other SAP Systems. I'm wondering if it would be possible to create time records based on EmployeeID (not an WorkAgreement) and also directly as approved? We search for a solution for the synchronization from time off periods from our HR system SAP SuccessFactors to ByD and don't need and further approve in ByD. And unfortunately SAP SuccessFactors is only able to make a one Call for each Event. Right now we plan to user the SOAP webservice and Middleware because SAP SuccessFactors only can work with response on a REST (not SOAP) outgoing calls.

Any Idea?

Best

Dimitrij

[former_member873559]

Hello Knut,

Thanks for this awesome job. I'm wondering if it would be possible for you to share with us a step-by-step tutorial to create or recreate a custom OData service like khproject, because I don't understand how you use the function import or navigation property options. The creating tutorials that I have found on this subject refer to the creation of a basic OData Service, but I would like to know how to create a complex one, similar to the aforementioned "khproject".

Thank you.

[gerdb42]

Hi Knut,

 

another question: At the moment I'm looking for a way to get some meta data like CashDiscountTermsCodes and ProductTaxationCharacteristicsCodes. I already know of QueryCodeLists, but that only gives IDs and descriptions. Is it possible to get some more data like percentages and time limits?

[raysap2022]

Happy 2024! Knut

May you kindly provide some guidance on the ManageSupplierInvoiceIn SOAP url service:

https://myxxxxxx.sapbydesign.com//sap/bc/srt/scs/sap/managesupplierinvoicein.

I am currently getting a 'Page not available - 415 Error Type, contact the provider' I raised an incident with SAP 8 weeks ago and have not got any traction.

is there a way to replicate this service using the CustomODATA modeler similar to the  khsupplierinvoice service url you have created or is there another option to resolve this?

I have imported the wsdl in Postman and I get similar error when i try and run the service to update supplier invoice data.

Thank you for keeping this blog alive. Hope you can shed some light on how else we can address this.

Thanks

 

Ray

 

 

[knutheusermann]

Hi Ray,

please check the access URL of the web service (it looks like you have a "/" too much in the URL). Additionally your ByD tenant may use a new hostname as well.

You find the correct access URL in the communication arrangement in ByD; it should be either https://myXXXXXX.businessbydesign.cloud.sap/sap/bc/srt/scs/sap/managesupplierinvoicein or https://myXXXXXX.sapbydesign.com/sap/bc/srt/scs/sap/managesupplierinvoicein.

Best regards, Knut

[raysap2022]

Hi Knut

Thanks for the speedy reply. I am still getting the same error. Is there a private way I can share my Test tenat url so you can try and reproduce what I am getting your end?

 

Thanks

 

Ray

[pierre_greillet]

Hello Knut,

First of all thank you for this helpful Odata API list sample. It helps us a lot.

However we are facing an issue we can't work around with the khemployeetime.
We have two ByDesign system with this API and for one of them we are able to retrieve the EmployeeTimeItemTypeCodeCollection but for the other the list is empty.
No errors of any kind or access rule raised, just an empty array.
Do you have an idea on what can cause this strange behaving between two systems with the same API ?

For informations, we are able to retrieve on both systems the list from EmployeeTimeItemApprovalStatusCodeCollection.

Kind regards,
Pierre

EDIT 2024-04-23 :

After checking without success the authorization as Knut was pointing out, we strarted a long exchange with the SAP Support.
Turn out that the difference between the two systems was in the scope configuration of the projet implementation.
To be able to retrieve the list of employee time item types, we had to follow those steps :

1. Go to Business Configuration Work Center
2. Open Implementation projects
3. Select First Implementation and click on Edit project Scope.
4. Click Next and go to Questions tab.
5. In questions tab expand "Human Resource"
6. Expand "Time and Labor Management"
7. Double click on "Time Accounts"
8. Scope In "Do you use international time accounts?"
9. Click on Next "Accept Preselected Answers"
10. Finish

Hope it can save some times to someone else.

[knutheusermann]

Hi Pierre,

sounds like an authorization issue. Please make sure the user has access to the work center view denoted in the header information of the custom OData service khemployeetime. If this does not help, then please open an incident to trace and check the issue in the backend.

Best regards, Knut

[carlonnheim]

Thanks @knutheusermann for your continuous effort to maintain this great reference!

We are trying to post Down Payments with reference to a Sales Order, i.e. this UI operation.

Do you have a working example on this, in particular we cannot see where to put the Sales Order Reference.

There is a "Maintain downpayment invoice request" SOAP service, maybe this is the way we need to go? We prefer oData if possible (principal propagation etc.).

Thanks in advance!