Skip to Content
Product Information
Author's profile photo Knut Heusermann

SAP Business ByDesign – API Overview

SAP Business ByDesign (ByD) is designed as open cloud solution with a comprehensive set of APIs. The API portfolio splits into multiple API types which are designed for specific integration rationales and API usage patterns.

This may raise two questions:

  1. Which APIs are available in SAP Business ByDesign?
  2. For which purpose shall I choose which API type?

Basically you could think about the ByD API portfolio as a “buffet”: Know want you want to have. Know the taste of the buffet offerings. And make a qualified choice.

In this blog post I want to give you an overview of the “API buffet”. I talk about typical API usage pattern, the “flavor” of API types in SAP ByDesign and give some guidance for a qualified choice to save costs and reduce complexity of your SAP ByDesign integration or extension project.

 

API Usage Pattern

Basically we have the following four integration rationales and 11 API usage patterns in mind when talking about SAP ByDesign APIs. Assiging your use case to one of the API usage pattern helps a lot to make a qualified choice later on.

Data Integration

Data integration empowers you to access business objects, the main carrier of business logic in ByD, and to extend ByD by your own innovations, applications and services.

API Usage Pattern:

  1. Remote Access to Business Objects
    A remote system queries, reads, creates, updates, deletes or performs actions on ByD business objects and business documents. Typically the remote system passes all relevant data in a single roundtrip using a technical user for authentication.
  2. Interactive Access to 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. The remote application orchestrates the access to the business objects for use cases like search business objects and business object nodes, navigate through the business object structure, and any operations on business object nodes following an interactive approach (read > update > follow association > read > update …).
  3. Subscribe to ByD Events
    A remote system subscribes to ByD events.

Process integration

Process integration enables you to automate business processes and business collaboration scenarios across system boundaries by connecting systems and business partners.

API Usage Pattern:

  1. Remote Access to Trigger a Business Process in ByD
    A remote system invokes a business process in ByD. The business process may represent the communication between a business partner and a company in ByD (business collaboration), as well as process chain that has been started in the remote system and shall be continued in ByD.
  2. ByD invokes a Business Process Task in a remote system
    ByD invokes a Business Process Task in a remote system. The business process may represent the communication between a company in ByD and a business partner (business collaboration), as well as process chain that includes a process step in a remote system.

Analytical integration

Analytical integration enables you connect ByD to digital board rooms, global business intelligence solutions and augmented analytics for insights-driven decision making and planning.

API Usage Pattern:

  1. Mass Data Extraction of Analytical Raw Data
    A remote system extracts analytical raw data free of redundancies in flat tables from ByD. The raw data is processed, combined and formatted in the remote system.
  2. Extend ByD built-in analytics by external data sources
    A remote system feeds ByD with external data to enhance ByD analytical data sources for ByD built-in analytics.
  3. Remote Access to pre-processed Analytical Data
    A remote system extracts formatted analytical data pre-processed by ByD. The remote system may extract a ByD analytical model as a cube incl. semantics like key figures and language-dependent texts, ready to be processed by 3rd-party clients, or the remote system extracts analytics result sets incl. aggregations and key figures, ready to be displayed for users.
  4. Live Access to Analytical Data
    A remote system has no own persistency and operates on ByD as persistency layer for analytical use cases.

UI integration

UI integration enables a seamless user experience across applications including navigation and mashups.

API Usage Pattern:

  1. Navigation ByD UI to 3rd-party UI
    Users navigate from a ByD screen to an external application UI incl. deep linking and parameterized URLs.
  2. Navigation 3rd-party UI to ByD UI
    Users navigate from an external application UI to a ByD UI screen.
  3. Embed 3rd-party web services, screens and information in ByD UIs
    Embed a 3rd-party screen, RSS feed, web service, media or other sources in a ByD screen and exchange data between the external service and ByD business object documents.

 

API Portfolio

SAP Business ByDesign provides APIs and integration capabilities for all API usage pattern. In the following I focus on APIs for server side integration scenarios.SAP%20Business%20ByDesign%20Web%20API%20Portfolio

Web Service APIs (SOAP)

Web service APIs enable read and write access to ByD business objects. Web service APIs are tailored to integrate systems using a minimal number of roundtrips. Sophisticated delta handling, concurrency controls and idem potency services supports you to ensure smooth system collaborations. All services are stateless, synchronous SOAP services.

Using query services you can query and read business objects and get business object data in an hierarchical xml format. You can specify the data to be returned in the query request using “Requested Elements”. Paging capabilities allow you to read large amounts of data in multiple packages.

Manage services can be used to create, update, delete and to invoke actions on multiple deeply structured business objects in a single web service request. Most manage services support a simulation mode (check) as separate operation as well.

Configuration and Authorization:

Web service APIs are configured using communication arrangements:

  1. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
  2. Work center view Application and User Management – Communication Scenarios: Create a communication scenario and add relevant web service APIs. The communication scenario generates an authorization role that is assigned to the communication user in the next step.
  3. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the communication scenario and communication system and enter the credentials of the communication user.
    As result the communication user is authorized to access all web service operations listed in the communication arrangement. The communication arrangement contains all information needed to consume the services incl. access URLs, WSDL downloads and service documentations.
  4. In the communication arrangement you can download the WSDL, display the web service documentation and change the service credentials.

Authentication:

  • User type: Technical user (communication user)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

Some web service APIs can be accessed using business users as well. Typically this is possible if the web service is used for user initiated remote interactions, such as Excel uploads or the Outlook integration. For such scenarios the web service authorization is linked to the work center view which contains the remote interaction. The authentication protocols are the same as for Custom Web Service APIs (see below).

Extensibility:

In general you can add extension fields to Web service APIs using the ByD adaptation mode (for extension fields added by key users) or the SAP Cloud Applications Studio (if the extension field itself has been added in the same SAP Cloud Applications Studio project). However, some Web Service APIs do not support extensibility; please check the specific Web Service API documentation for more details.

FAQ:

  • Does SAP plan to replace SOAP Web Service APIs by OData?
    No, we have no plans to replace SOAP Web Services APIs by OData. SOAP and OData services are designed for different usage pattern (as described in this blog post).
  • What shall I do in case of questions or if I look for some examples?
    Post your question in the SAP Business ByDesign Community (common user tags “byd api”, “byd web service” and “byd integration”).
  • What shall I do if a field is missing in a web service API?
    Open a ByD incident and request to add the missing field; refer to “solution completeness”.
  • What shall I do if an API is missing?
    Check possible alternatives such as Custom Web Service APIs or OData API for Business Objects or open an improvement request on the Customer Influence page for SAP ByDesign.

More information:

Examples:

 

OData API for Business Objects (REST)

The OData API for Business Objects is designed for user centric applications to access ByD business objects such as mobile apps or freestyle UIs using ByD as backend. The APIs provide you with additional metadata to ease UI development, such as localized field labels, code descriptions and value help support. In addition the API supports typical navigations between business object nodes like “from header to detail”, navigations to associated business objects (for example “from sales order item to product details”) and efficient fine grained data access. The authentication using business users enable you to combine frontend single sign-on and principal propagation using OAuth to benefit from the role-based authorization management of ByD.

Using the work center view OData Services, key users are empowered to decide which business objects, business object elements and actions are exposed via OData APIs. Using OData you can access the OData-enabled part of the public solution model of ByD, plus extension fields, add-on business object extensions, and custom business objects created using the SAP Cloud Applications Studio.

Configuration and Authorization:

Work center view Application and User Management – OData Services: Expose the ByD business object including nodes, elements and functions as Custom OData Service and assign your service to a work center view. As result all ByD users with access to the assigned work center view are authorized to access the OData service.

Authentication:

  • User type: Technical user (communication user)
    • Authentication protocols:
      • Basic authentication (user/password)
      • Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
  • User type: Business users (employees or service agents)
    • Authentication protocols:
      • Basic authentication (user/password)
      • Certificate (user logon certificate)
      • OAuth 2.0 SAML Bearer authentication
      • SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)

Extensibility:

Extension fields can be added to custom OData services using the work center view OData Services. Furthermore you can create custom OData services for custom business objects (created using the SAP Cloud Applications Studio) using work center view OData Services as well.

FAQ:

  • What shall I do if I need an example request or if I have questions?
    Check if you find a suitable example in the GitHub repository linked in blog post OData API Usage Samples. Post your question in the SAP Business ByDesign Community (common user tags “byd api”, “byd odata” and “byd integration”).
  • What shall I do if a property or function is not available in the Custom OData service modeler?
    Open a ByD incident and request to enhance the public solution model (see blog post SAP ByDesign Public Solution Model).

More information:

Examples:

 

Business Objects Events

As a key user you can configure event notifications such that external systems can subscribe to ByD business object events. In result ByD sends event messages to the specific endpoint of the external system.
Event subscriptions can be used for all kind of loosely coupled event-based integration scenarios such as event-driven side-by-side extensions, to trigger real-time data replication scenarios, or to trigger actors in IoT scenarios.

Event specification:

id:  Unique identifier of the event.
specversion:  The version of the event specification used by the event message.
source:  Identifies the instance the event originated in (contains the ByD tenant ID).
type:  Describes the type of the event related to the source the event originated in (the ByD business object, business object node and the event type).
datacontenttype: Content type of the event data.
time: Timestamp of when the event has been raised.
data: Object ID of the business object root node (root-entity-id) and object ID of the business object node (entity-id). These object IDs can be used to access the corresponding business object using the OData API for business objects.

Configuration and monitoring:

Using the work center view “Application and User Management – Event Notification” you can add subscribers and configure event subscriptions for create, update and delete events of business objects and business objects nodes that are released in the ByD public solution model.

Note: Almost all ByD business objects have administrative information like a last changed date/time on root level, which reflects all business object changes. This means subscribing to update-events on root level triggers an event message for all business object changes.

Using the work center view “Application and User Management – Event Notification Monitoring” you can monitor the status of event messages and resend or cancel event messages, and download event payloads.

Authentication:

  • Basic authentication (user ID and password)
  • Client certificate (download a PKCS#12 key pair file from ByD)
  • OAuth 2.0

Extensibility:

You can create event subscriptions for custom business objects (created using the SAP Cloud Applications Studio) using work center view Event Notification the same way as for standard business objects. Furthermore, business object events are raised in case of changes to key user or add-on extension fields as well.

Example event payload:

{
  "specversion": "1.0",
  "source": "/ROT/sap.byd/000000000123456789",
  "type": "sap.byd.SalesOrder.ItemProduct.Created.v1",
  "id": "00163e73-06a3-1eeb-addc-b49adfaf4097",
  "time": "2021-05-17T07:58:14Z",
  "datacontenttype": "application/json",
  "data": {
    "root-entity-id": "00163E7306A31EEBADDCB17C70E9204C",
    "entity-id": "00163E7306A31EEBADDCB32EB797A04C"
  }
}

More information:

 

B2B and A2A Interfaces (SOAP)

SAP Business ByDesign offers a set of business scenarios with remote communication capabilities to business partners or applications running on different systems. These capabilities are provided as pre-packaged communication scenarios in two flavors:

  • Application-to-Application (A2A) communication scenarios
  • Business-to- Business (B2B) communication scenarios

A2A and B2B interfaces are SOAP interfaces mostly using asynchronous messaging. Depending on the supported protocols on service interface level, standards-based XML communication can be conducted using multiple application protocols: SAP XI 3.0, SAP IDoc over SOAP, WSRM 1.1 and plain SOAP 1.1.

Inbound interfaces support parallelization, exactly once in order processing, idem potency and forward error and conflict handling to simplify the resolution of semantical communication issues.

Outbound interfaces provide predefine message types and interface signatures that have to be supported by the provider application; the definition WSDL can be downloaded in the ByD communication arrangement.

B2B communications are designed to exchange business documents between business partners, which means:

  • B2B outbound interfaces are embedded in the ByD output management.
  • B2B message types reflect the sender as well as receiver point of view. For example suppliers can be identified by the ByD internal ID, by a customer ID at supplier, by a Global Location Number (GLN) or by a tax number.
  • ByD B2B outbound and inbound interfaces are aligned such that two companies using ByD can easily communicate with each other without any middleware or message mappings.

Configuration and Authorization:

A2A and B2B interfaces are mostly available in context of a pre-packaged communication scenario.

  • A2A interfaces:
    1. Work center Business Configuration: Scope the pre-packaged communication scenario by activating the corresponding scoping question.
    2. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
    3. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the standard communication scenario and the communication system created in step 2, and enter the credentials of the communication user. For outbound communications you can additionally enter the service hostname, URL and credentials, and check the connection.
    4. In the communication arrangement you can download the WSDL, display the web service documentation and change the service credentials.
  • B2B interfaces: B2B configurations reflect a communication between a company and a business partner. Therefore any configuration is specific for those parties as well. The following tasks need to be done:
    1. Work center Business Configuration: Scope the pre-packaged communication scenario by activating the corresponding scoping question.
    2. Maintain the master data representing the company and the business partner (account or supplier). Enter standard IDs (Global Location Number or DUNS Number) for both communication parties.
    3. Create a communication arrangement for the technical communication setup between the communication parties. Use the standard communication scenario in the communication arrangement.
    4. For outbound communications select the “XML” as output channel in the business partner collaboration settings.

Authentication:

  • User type:
    • A2A inbound interfaces: Technical user (communication user associated to a communication system)
    • B2B inbound interfaces: Technical user (communication user associated to a business partner)
    • A2A and B2B outbound interfaces: User and credentials are maintained in the communication arrangement
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificate (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

More Information:

Examples:

 

OData API for Reports (REST)

The OData API for Reports is tailored for remote access to pre-processed analytical data: A remote system extracts formatted analytical data pre-processed by ByD. The remote system may extract a ByD analytical model incl. semantics like key figures and language-dependent texts, ready to be processed by clients, or the remote system extracts analytics result sets incl. aggregations and key figures, ready to be displayed for users.

Using the OData API for Reports you can access standard reports provided by SAP, reports created by key users and business users, and reports created as part of a ByD add-on using the SAP Cloud Applications Studio.

Configuration and Authorization:

All reports provided by SAP, Partners and key users can be accessed using OData without any configuration. The system verifies if the logon user is authorized to access the report and the data according the ByD role-based access management.

Authentication:

  • User type: Business users (employees or service agents)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificate (user logon certificate)
    • OAuth 2.0 SAML Bearer authentication
    • SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)

Extensibility:

The OData API for reports provides access to all standard and custom reports incl. extension fields that have been added to those reports out of the box.

More information:

Examples:

 

OData API for KPIs

The OData API for KPIs (Key Performance Indicator) is tailored for remote access to pre-processed analytical data: A remote system extracts current business KPI values from ByD including current values, target values, reference values, delta information as absolute value and percentage, thresholds, trend, and improvement direction.
The remote system may display the KPIs on a global analytical dashboard or use the included property Execution Date/Time to build a KPI history by periodically extracting KPI values.

Configuration and Authorization:

All KPIs provided by SAP, Partners and key users can be accessed using OData without any configuration. The system verifies if the logon user is authorized to access the KPI and the data according the ByD role-based access management.

Authentication:

  • User type: Business users (employees or service agents)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificate (user logon certificate)
    • OAuth 2.0 SAML Bearer authentication
    • SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)

Examples:

  • Get metadata:
    myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/$metadata?sap-label=true&sap-language=de
  • Get KPI details:
    myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/Kpi?$format=json&sap-language=de
  • Get KPI value (Total Active Order Volume):
    myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/KpiValue?$format=json&$filter=Id eq ‘CRMSLOIB_Q0001_SOVOLUME’
  • Get KPI value (Overdue Receivables):
    myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/KpiValue?$format=json&$filter=Id eq ‘FINDUE0001’

 

OData API for Data Sources (REST)

The OData API for Data Sources is designed to extract analytical raw data. A remote system extracts ByD analytical raw data in flat tables, free of redundancies from ByD. The analytical raw data is then processed, combined and formatted in the remote system. Typically such remote systems are central business analytics application such as SAP Analytics Cloud.

Using the OData API for Data Sources you can extract standard basic and combined data sources provided by SAP, created by key users, and created as part of a ByD add-on using the SAP Cloud Applications Studio.

Configuration and Authorization:

  1. Work center view Business Configuration – Implementation Project: Activate the OData API for analytical data sources in the scoping questions: Built-in Services and Support >> System Management >> Analytics >> select the question Do you want to enable analytical OData services for data sources?
  2. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
  3. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics DataSources OData” and the communication system and enter the credentials of the communication user.
  4. Work center view Business Analytics – Data Sources: Select and expose the data sources which you want to extract.
  5. In the communication arrangement you can change the service credentials if needed.

Authentication:

  • User type: Technical user (communication user)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

Extensibility:

The OData API for data sources provides access to standard and custom data sources incl. extension fields that have been added to those data sources out of the box.

More information and examples:

 

Operational Data Provisioning API (SOAP)

Similar to the OData API for Data Sources, the ByD Operational Data Provisioning Interface (ODP interface) provides analytical raw data (data sources). The OPD interface is a SOAP API according the SAP BW/4HANA Operational Data Provisioning specification to extract data sources for the purpose to connect ByD with a SAP Business Warehouse (SAP BW). The ByD ODP interface supports the Fetch-Data-Direct pattern and the Open-Fetch-Close pattern (paging). Due to the fact that all ByD analytical data is live data without delta-stores, the ByD OPD interface does not support delta extractions.

Using the ODP Interface you can extract standard basic and combined data sources provided by SAP, created by key users, and created as part of a ByD add-on using the SAP Cloud Applications Studio.

Configuration and Authorization:

  1. Work center view Business Configuration – Implementation Project: Activate the ODP Interface in the scoping questions: Communication and Information Exchange >> Business Process Management >> Integration with SAP ERP for Subsidiaries >> select the question Do you want to make analytics data from the solution available to a central Business Warehouse system in SAP ERP?

If required you may additionally select the question Do you want to view text fields upto 1024 characters when making analytics data available to an SAP NetWeaver BW system?

  1. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
  2. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Integration” and the communication system and enter the credentials of the communication user.
  3. Work center view Business Analytics – Data Sources: Select and expose the data sources which you want to extract.
  4. In the communication arrangement you can download the WSDL and change the service credentials.

Extensibility:

The ODP interface provides access to standard and custom data sources incl. extension fields that have been added to those data sources out of the box.

Authentication:

  • User type: Technical user (communication user)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Client certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

More information and examples:

 

Analytical data upload into cloud data sources (SOAP)

In ByD you can create Cloud Data Sources to extend the ByD build-in analytics by external data sources. Cloud data sources can be combined with ByD data sources and used to create custom reports.

The SOAP API to upload external data into cloud data sources can be used to insert new data records, modify existing records, delete records, and replace all existing data of a cloud data source.

Configuration and Authorization:

  1. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
  2. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Data Upload” and the communication system and enter the credentials of the communication user.
  3. In the communication arrangement you can download the WSDL and change the service credentials.

Authentication:

  • User type: Technical user (communication user)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

More information:

 

Analytical data upload into cloud data sources (REST)

In ByD you can create Cloud Data Sources to extend the ByD build-in analytics by external data sources. Cloud data sources can be combined with ByD data sources and used to create custom reports.

The OData API to upload external data into cloud data sources basically serves the same purpose as the corresponding SOAP API.

Using the OData API you can create, change and delete cloud data source records. Furthermore you can clear the complete data source (delete all records).

Configuration and Authorization:

  1. Work center view Application and User Management – Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
  2. Work center view Application and User Management – Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Data Upload” and the communication system and enter the credentials of the communication user.
  3. In the communication arrangement you can change the service credentials if needed.

Authentication:

  • User type: Technical user (communication user)
  • Authentication protocols:
    • Basic authentication (user/password)
    • Client certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).

More information:

 

Custom Web Service APIs (SOAP)

The SAP Cloud Applications Studio provides a wizard to create custom web service interfaces with operations to create, read, update, delete, query and invoke actions on ByD business objects. Using custom web service APIs you can access business objects, nodes, elements, queries and actions that are exposed in the public solution model of ByD. Furthermore you can create custom web service APIs for custom business objects created using the SAP Cloud Applications Studio.

Similar to standard Web Service APIs, Custom Web Service APIs are stateless, synchronous SOAP services and support a sophisticated delta handling, concurrency controls and idem potency.

Configuration and Authorization:

The SAP Cloud Applications Studio provides a wizard to generate Custom Web Service APIs in 2 steps: 1. Create a view on the business object, 2. Create web service operations (create, update, delete, read, query and action) and refine the operations signature.

Authentication:

  • User type: Technical user (communication user)
    • Authentication protocols:
      • Basic authentication (user/password)
      • Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
  • User type: Business users (employees or service agents)
    • Authentication protocols:
      • Basic authentication (user/password)
      • Certificate (user logon certificate)
      • OAuth 2.0 SAML Bearer authentication (specific endpoint for access with security session: <hostname>/sap/ap/srt/scs/<service>)
      • SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for access with security session: <sso-hostname>/sap/ap/srt/scs/<service>)

Extensibility:

Custom Web Service APIs can include extension fields and custom business objects that have been created using the SAP Cloud Applications Studio.

More information:

 

External API Consumption (REST and SOAP)

Using the SAP Cloud Applications Studio you can embed the consumption of external REST and SOAP web services in the business logic of ByD. This provides you with the possibility to trigger external processes and to incorporate external web services in ByD in-application extensions.

If you combine external API consumption with the capability to create synchronous or asynchronous message-based communications between standard and custom business objects you get a very powerful and flexible tool to build integration scenarios initiated by ByD.

More information:

Examples:

 

“Make a qualified choice”

Chosing the “right” API is no binary thinking, but rather a qualified decision. Based on your use case there is a first choice (best-fit), a good alternative (good fit) and in some cases you have to understand the use case in detail to come to a conclusion (case-by-case decision). The following API map may help you to find the best API for your purpose or to find a good alternative in case the first choice API type does not provide the API you need.

Example 1: Mobile (hybrid) application for a company address book

  1. OData can be easily consumed by HTML5 applications (e.g. SAP Cloud Platform Fiori apps) with minimal overhead, excellent development tool support, business user logon, principal propagation and role-based authorization checks, and navigation along business object structures.
  2. Web service APIs can be used as well, but require a higher development effort and communication overhead because of the Soap protocol; furthermore authentication by technical user means less detailed authorization checks.

Example 2: Master data replication for products (external system to ByD)

  1. Web service API enable you to create and update products in a single roundtrip – the web service process agent in ByD takes over all parts of the choreography needed – just hand-over the xml with the target state of the object.
  2. OData can be used as well, but keep in mind that for updates many roundtrips are needed to address several business object nodes and actions. The communication choreography needs to be implemented on consumer side.

Example 3: Purchase order integration with a vendor

  1. The B2B interface for purchase order integration is designed for this purpose, integrated in the ByD output management with a business partner based receiver determination and forward error and conflict handling for purchase order acknowledgements.
  2. The 3rd-party A2A outbound interface supported by the output channel External System and communication scenario Output Management XML Integration can be used to delegate the communication with the customer to a middleware or 3rd-party output management system.
  3. Web service APIs might be an option as well, but requires a mediated pull/push and the communication is not displayed in the documents output history. Furthermore you may have to decide how to address the regular output management, which remains in place while using Web service APIs.

Example 4: You receive an invoice from your vendor as xml messages

  1. B2B is best fit and designed for this purpose.
  2. The web service API for supplier invoices can be used as well, because the business object itself supports forward error handling by supplier invoice exceptions, however the service consumer needs to provide error handling capabilities to manage rejected web service calls.

In general you may take into account the following API qualities to make a qualified choice:
Protocol (Soap or REST/OData), synchronous vs. asynchronous communication, idem potency, quality of service (EOIO, WSRM), state management, authentication, service orchestration and mediation, ID and key management, error and conflict handling, delta handling and concurrency control, data volumes, configuration (communication partner, receiver determination), …

 

Assigned tags

      24 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Pierre HUGOT
      Pierre HUGOT

      Hello,

      This is a very nice and usefull publication (as some other you published) with a lot of informations for people wondering which tool to use for integrations with ByDesign. I'm working on interfaces with ByDesign since 3 years and I didn't know some entry points (concerning analytics mainly).

      I would also like to share some experience return on some topics, mainly in contexts of integrations through SCPI :

      • Concerning oData, it looks to be today more powerfull than web service as you can define more precisely which data to access/update and avoid useless network traffic/business object read, or some fields reset to blank if not provided in the web service. Maybe this last point is related to actionCode used in each node, but it is not always precisely documented which actioncode from 1 to 6 is supported for the current node. Furthermore, oData "seems" to be more efficient, but I didn't really measure it : just a feeling when using it... but you may have some input on this ?

       

      • oData request can be done on multi-level nodes so it can enable one request to create a complexe object including specific fields quite easily, often and in a more understandable language than tags used in Web services. You published very nice sample on this that help us to start using it.

       

      • Web Services often provide a "checkMaintain" operation very usefull to simulate creation/update, which cannot be done in oData : this kind of option (specific header parameter ?) would be very nice to propose in the oData framework of ByDesign !

       

      • ByDesign also propose XML file upload on some standard objects, but it looks quite simple to create new specific ones from SDK. There are very fiew blogs dealing with this topic and it would be interesting to know how to generate other XML input format taillored to business need? It offers simple WebDAV access (can be mounted as Windows drive to easily copy files) and schedule batch import integrated into byDesign with error management.

      OData is often simpler as you can build a oData service quickly, and read existing data to quickly have a good idea on what to provide for update/post. Webservice is sometime more tricky with action code/attribute combinations. But if you used once a web service, it is quicker to reuse in an other customer context

      I also met some web service where it was possible to use business user, and this was mandatory to save a supplierInvoice in a status "posted" (technical user is limited to save ready to be posted). Do you know what authorizations can prevent business users from calling web services directly ?

      My last point would concern licences and authentification : oData require business user, despite web service only require technical user (no licence fees) which could make a difference.

      Any roadmap on API/interfaces could aso be a good complement : is oData V4 going to be supported ? Are Excel/file upload templates going to be enriched, or a how-to guide to define a Excel for mass upload/mass change ?

      Lots of questions... but lots of opportunities too in moving Cloud environnements !

      Thanks again for your publication.

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Pierre,

      thanks a lot for your very comprehensive comments.

      Let me try to answer some of your questions:

      How to avoid to reset fields to blank if not provided in SOAP web service APIs?

      You can avoid to reset fields to blank by removing the corresponding xml element or attribute from the xml request. In general the following rule applies:

      1. xml request contans the element with initial value => set target BO element to initial value.
      2. The attribute xsi:nil is sent for an xml element => set target BO element to nil or initial value.
      3. The xml element is not part of the xml request => no changes to the target BO element (we assume the source system does not “know” the element and this helps us to extend APIs in a compatible way)

      Which action codes are supported in SOAP Web Service APIs?

      In general all action code are supported. Exceptions are possible if business logic does not allow changes of if technical constraints apply (e.g. if a BO does not have a unique key, then action codes 02 (update), and 03 (delete) are not feasible).

      What authorizations can prevent business users from calling SOAP Web Services?

      Some standard web services are used by business user functions, such as Excel upload and the Outlook plug-in. Access rights to those web services is assigned to the corresponding work center views and hence the only possibility to remove authorizations would be to remove the work center view from the user authorizations.

      Is OData more efficient than SOAP Web Service APIs?

      This strongly depends on the use case. If you run for example a master data replication scenario, then SOAP is more efficient, because you can submit xml requests with a target state and a mix of creations, changes and actions, and ByD takes care of any sequence of modifications to be processed and uses mass-processing whereever possible.
      On the other side, if you navigate UI-like through a business document, or if you perform fine granular changes to a business object, the SOAP protocol by its nature comes with a lot of overhead and OData is much easier and more efficient.

      Is oData V4 going to be supported?

      Already today we support some OData features beyond OData 2.0 … I would call it something like “OData V2+”. And yes longterm we plan to support OData V4 as well, but this may take a while because of other priorities in the upcoming releases.

      Are Excel/file upload templates going to be enriched, or a how-to guide to define a Excel for mass upload/mass change?

      At the moment we do not plan enhancements of Excel upload templates or mass uploads/changes. However, such scenarios can be solved by partners using Web Service APIs and OData.

      Best regards,
      Knut

      Author's profile photo Ronald van Herk
      Ronald van Herk

      Hi Knut,

      Thank you for this elaborate overview.

      We are looking into the option to add data to SAP Business ByDesign using webservices into extension fields.

      Are there any pre-requisites when creating an Extension Field to make it available for Update/Write using for example the Odata Editor or the further usage option in Adaptation Mode?

       

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Ronald,

      good point. I added remarks about extensibility to relevant API types in the blog post.

      Thanks for the feedback and best regards,
      Knut

      Author's profile photo Pierre HUGOT
      Pierre HUGOT

      Hi,

       

      We often have problems with interfaces SOAP or oData API when chaining multiple calls from SAP CPI (Cloud Platform Integration).

      As exemples :

      •  it is required to create a contract and then update prices details (as initial call cannot accept detailled price components) : update fails because contract is still locked by the user from previous call
      • we create service order and then chain with service confirmation creation based on service order : in this case the confirmation fails because service order is not yet "really" saved in database (error message not existing destipe success message on soap call for creation of service order)

      Is there any workaround or tip to avoid such issue ? Can SAP provide option to ensure synchronous call means object is saved and not locked anymore ?

      It would be very helpfull to avoid lots of temporizations...

      Thanks in advance.

      Pierre

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Pierre,

      we recently changed the customer contract web service such that it should now be possible to create contracts with price components in a single web service request. The pattern is the same as for sales orders (see my blog post https://blogs.sap.com/2017/08/10/create-byd-sales-orders-using-web-services/). Could you please check?

      With regards to your second issue it is difficult to say anything without access to the system. My first guess would be that this is rather a lock issue related to subsequent processes. However could you please open an incident to followup on this issue?

      Best regards,

      Knut

      Author's profile photo Kalin Damianov
      Kalin Damianov

      Hi Knit

      I want to integrate CAD system ( SolidWorks ) to ByD ( Product Design part ) .

      Please send to me more info how I can build such interface ?

       

      Best Regards

      Kalin Damianov

      Author's profile photo May Thitsa Oo
      May Thitsa Oo

      Hello Knut,

      When we consume SOAP services to create multiple instances in one Request (eg; create multiple Sales Order instances in one time Request via ManageSalesOrderIn),
      is there any limitation of instances or performance issue?
      (eg; max 100 instances in one request, etc..)

      Thanks and Regards,
      May

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Update ByD Release 21.02: Consumption of OData service with technical user.

      As you may have notified in the 21.02 release notes, you can now access OData services for business objects using technical users:

      1. Create a communication system that represents the external OData consumer.
        The system automatically creates a technical user dedicated to the specific external consumer.
      2. Create a communication arrangement for the communication system and select the OData services. Edit the credentials.
        The system assigns the authorizations to use the selected OData services to the technical user associated to the communication system.
      Author's profile photo Clément GROSSELIN
      Clément GROSSELIN

      Hello Knut,

      Is this also available for OData API for Reports ?
      If not, is this something planned and when would this be released in that case ?

      Thanks and Regards,

      Clément

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Clément,

      so far, the technical user access is available for the OData APIs for buisness objects and data sources. We did not yet plan to provide this for reports as well. Please feel welcome to submit a improvement request in Customer Influence.

      Best regards,
      Knut

      Author's profile photo Adrian van Oyen
      Adrian van Oyen

      Hi Clément,

      I would support this improvement request. In our customisation's we sometimes have to refer to reports instead of BO's. So having a Technical User for them as well would be very helpful.

      Regards

      Adrian

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Update ByD release 21.05: New OData API for KPIs and business object events.

      Business object events:

      With release 21.05 you can configure event notifications such that external systems can subscribe to ByD business object events.
      Event subscriptions can be used for all kind of loosely coupled event-based integration scenarios such as event-driven side-by-side extensions, to trigger real-time data replication scenarios, or to trigger actors in IoT scenarios.

      OData API for KPIs:

      Using the OData API for KPIs you can extract business KPI values from ByD including current values, target values, reference values, delta information as absolute value and percentage, thresholds, trend, and improvement direction.
      The remote system may display the KPIs on a global analytical dashboard or use the included property Execution Date/Time to build a KPI history by periodically extracting KPI values.

      Author's profile photo Richa Sharma
      Richa Sharma

      Hello Knut,

      In your blog, you have talked about ByDesign Event Notifications. We have a use case where we would like to use SAP custom ODATA service in the end point url of Event Notification Subscriber definition. When we try to do the same, we get a failed notification in Event Notification Monitoring with error 'csrf-token validation failed'

      We would like to understand if this is currently supported. Can we use a custom ODATA service in end point URL? If yes, can you please suggest the steps of doing the same.

      Thanks,

       

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Richa,

      the event notifications are http-POST requests with a predefined message (compare example in my blog post above).

      ByD custom OData services require a cross-site request forgery token for POST requests. You get this token via a GET request with http header "x-csrf-token = fetch".

      This means you can't send an event notification to an OData endpoint.

      The scenario would be rather to send the event notification to an event socket or event bus to trigger a process, which may then pull data from ByD using ByD OData services.

      Best regards, Knut

      Author's profile photo Richa Sharma
      Richa Sharma

      Hello Knut,

       

      Thanks a lot for your quick response 🙂 . This helps.

       

      Thanks,

      Richa

      Author's profile photo Pascal Markwalder
      Pascal Markwalder

      Hi Knut, I also have a question regarding the event notification. I would like to build an integration, where the event notification (on pricelist object) triggers an SAP CPI I-Flow to update a Webshop Pricelist. I have now the problem, that I cannot receive the event notification with the HTTPS Connector on the CPI as I do not get the Authentification running. Do you have any hint for me, how I can reveive the notifications in the CPI to build such I-Flows? The next step after receiving the notifcation is of course a get request on the respective OData Service.

      Best regards, Pascal

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Pascal,

      the following works for me:

      Design CPI Integration package, for example:

      1. Create artifact (iFlow), for example with the following components:
        • HTTPS Sender Adapter:
          • Direction: Sender
          • System: ByD
          • Adapter type: HTTPS
          • Transport protocol: HTTPS
          • Msg protocol: none
          • Address: <enter an endpoint path, e.g. /byd/events/salesorders>
          • Authorization: User role
          • User role: ESBMessaging.send (default role - you may configure a specific role as well)
          • CSRF Protected: no
        • Start message
        • Content modifier
        • End message
      2. Deploy the artifact

      Get endpoint from CPI:

      1. Monitor >> Manage integration content >> Choose your iFlow and get the endpoint
        (for example https://<my CPI>.hana.ondemand.com/http/<my sender adapter address, e.g.
        /byd/events/salesorders>)

      ByD event notification configuration:

      1. Work center view Application and User Management - Event Notification:
        • Create a subscriber representing the CPI endpoint:
          • Endpoint: Access URL taken from CPI >> Monitor >> Manage integration content >> Choose your iFlow and get the endpoint
            (for example https://<my CPI>.hana.ondemand.com/http/<my sender adapter address>, e.g.
            /byd/events/salesorders>)
          • Authentication method: User ID & Password 
          • User name/Password: Some valid CPI user with the user role as specified in the iFlow https sender adapter; this is not the users defined in the CPI Operations View >> Security Material
        • Create subscriptions for the subscriber

      Best regards,
      Knut

      Author's profile photo Pascal Markwalder
      Pascal Markwalder

      Hi Knut, thank you very much for the explanation. I did it exactly as described by you, but got some SSL errors. This is probably a tenant specific problem and I check this with the support. Did you maintain the browser certificate of the CPI in the certificate trus list in SAP ByD?

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Pascal,

      I my setup, the trust lists had been maintained before already, but SSL errors are definitely caused by a missing (or outdated) server certificate.

      As ByD acts as web service consumer (consuming the web service/endpoint provided by the external system), the external system sends its Server Certificate to ByD and ByD has to trust the CA which provided the external system server certificate.

      To solve that issue:

      1. Download Root Certificate of the CA used by External System
      2. Upload External System root certificate to ByD (work center view Application and User Management > Edit Certificate Trust List).
        There is a number of CA which ByD trusts by default (see ByD
        Certificate Trust List).

      Best regards,
      Knut

      Author's profile photo Isaac Mokoena
      Isaac Mokoena

      Hi Knut,

      I hope that you are well.

      We tried creating a custorm Odata to read the Stock Quantity on ByDesign but we couldn't find a business objects that allowed us to do so. The idea behind building that oData API is that we want to use it to build a Fiori List object Application.

      Can you please advice on what steps that we could follow to build that oData API ?

       

      kind regards

      Isaac

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Isaac,

      the required business object would be Inventory. However this object is not yet OData enabled; please see blog post ByD PSM for more details.

      Alternatively to the business object, I would suggest to consider using the OData API for reports. Suitable underling reports could be for example the reports Inventory Ageing, Inventory Balance or Inventory Report (report ID SCMINVV02_Q0001).
      For more details about OData for analytics see blog post: OData API for analytics/.
      Furthermore you find a stock overview example in the Github repository https://github.com/SAP-samples/byd-api-samples, in Postman collection "Analytics - Reports".

      Best regards,
      Knut

      Author's profile photo Isaac Mokoena
      Isaac Mokoena

      Hi Knut,

       

      I am using the Inventory Report (report ID SCMINVV02_Q0001) ODATA Query and trying to create a Fiori Application that must consume this ODATA query/service:

      /sap/byd/odata/ana_businessanalytics_analytics.svc/RPSCMINVV02_Q0001QueryResults?$select=CMATERIAL_UUID,KCON_HAND_STOCK,KCRESTRICTED_STOCK

      of this ODATA query what should be specified as a service Path when creating a Fiori Application on SAP Business Application Studio ?

      If this is the wrong approach can you perhaps send me the steps i should follow to create a Fiori App based on Inventory Report (report ID SCMINVV02_Q0001) ODATA Query ?

      I've exhausted all the avenues to my disposal, please if you can help i would appreciate it.

      Kind regards

      Isaac

       

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Update for release 21.08: Business object events now support authentication by client certificate and OAuth 2.0.

      This means with release 21.08 business object events support the authentication methods:

      • Basic authentication (user ID and password)
      • Client certificate (download a PKCS#12 key pair file from ByD)
      • OAuth 2.0