SAP Business ByDesign (ByD) is designed as open Cloud ERP solution that can be extended by “built-in extensions” (add-ins that are installed and operated on the ByD platform) as well as “side-by-side” applications operated on the SAP Cloud Platform (SCP) and connected to SAP Business ByDesign using ByD APIs.
This blog posts provides you with an introductive example to extend SAP Business ByDesign “side-by-side” using an HTML5 Application running on the SAP Cloud Platform and connected to ByD using OData services.
Example scenario:
Let’s assume you would like to create an application to display and browse your company address book and allow employees to change their workplace address information. Furthermore the hybrid application shall be available on mobile devices as well as in a browser.
In my example I’m using the following system setup:
The following descriptions guide you through the setup of the example HTML5 application and ByD OData services in 3 steps:
You can download the sources for the ByD OData service, the Postman collection and the HTML5 application from the SAP PartnerEdge - SAP Business ByDesign Learning Room (requires PartnerEdge login; if you need help to access SAPPartnerEdge.com or SAP PartnerEdge Learning Rooms the following blog may help: Need Help Getting Access).
SAP Business ByDesign provides 3 types of OData services:
Step 1 will be about exposing relevant parts of the ByD business object Employee via OData service.
Open work center view “Application and User Management - OData Services”, select “Custom OData Service” and upload the custom OData service file khemployee.xml provided in the download link in sub-folder "Custom OData Service".
Alternatively you can create your own custom OData service with name “khemployee” for business object “Employee” as well.
To serve my use case the custom OData service contains the following properties of business object Employee:
Assign the OData service to a work center view to ensure role-based authorization checks. As result the OData service can be access with any ByD business user who has access to the ByD work center view assigned in the OData editor.
Save and activate your custom OData service and note down the Service URL from the OData Editor. In my example the service URL is
https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/.
You get the OData service metadata using the URL:
https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/$metadata.
Let’s get familiar with the OData service. In my example I am using Postman (www.getpostman.com) as REST/OData test tool:
The Postman collection contains examples for all requests performed by the HTML5 applications as well:
Get OData metadata using the metadata URL:
GET /sap/byd/odata/cust/v1/khemployee/$metadata HTTP/1.1
Host: myXXXXXX.sapbydesign.com
Get a list of employees with ID and name:
GET /sap/byd/odata/cust/v1/khemployee/EmployeeCollection?$filter=EmployeeID eq '*'&$format=json&$inlinecount=allpages&$top=100 HTTP/1.1
Host: myXXXXXX.sapbydesign.com
x-csrf-token: fetch
Get employee including workplace address and employee picture:
GET /sap/byd/odata/cust/v1/khemployee/EmployeeCollection?$filter=EmployeeID eq '{{EmployeeID}}'&$expand=EmployeeEmployeeWorkplaceAddressInformation/EmployeeEmployeeWorkplaceAddressWorkplaceAddress&$format=json HTTP/1.1
Host: myXXXXXX.sapbydesign.com
x-csrf-token: fetch
Update employee workplace address:
POST /sap/byd/odata/cust/v1/khemployee/EmployeeEmployeeWorkplaceAddressWorkplaceAddressCollection('{{ObjectID}}') HTTP/1.1
Host: myXXXXXX.sapbydesign.com
Content-Type: application/json
x-csrf-token: {{x-csrf-token}}
x-http-method: MERGE
Body:
{
"ObjectID": "{{ObjectID}}",
"ParentObjectID": "{{ParentObjectID}}",
"Phone": "+1 216 399 3571-1",
"Email": "Edward.Black@us.almika-refsys.byd",
"Fax": "+1 216 399 3510",
"Mobile": "+1 123 456",
"Building": "WDF1",
"Floor": "4",
"Room": "42"
}
Import the sample HTML5 application:
Create a destination to connect the ByD OData service:
You can authenticate at ByD OData services using Basic Authentication (user/password) and OAuth 2.0 SAML Bearer authentication.
You find a description how to configure principal propagation using OAuth 2.0 SAML Bearer authentication in my subsequent blog post Configure OAuth 2.0 for SAP ByDesign OData Services.
Stay tuned 🙂
This blog posts provides you with an introductive example to extend SAP Business ByDesign “side-by-side” using an HTML5 Application running on the SAP Cloud Platform and connected to ByD using OData services.
Example scenario:
Let’s assume you would like to create an application to display and browse your company address book and allow employees to change their workplace address information. Furthermore the hybrid application shall be available on mobile devices as well as in a browser.
In my example I’m using the following system setup:
- SAP Business ByDesign
- SAP Cloud Platform sub-account to develop and run the HTML5 application
The following descriptions guide you through the setup of the example HTML5 application and ByD OData services in 3 steps:
- Configure OData Service in SAP Business ByDesign
- Test the OData Service using Postman (optional step to get familiar with the OData API)
- Create SAP Cloud Platform HTML5 Application connected to ByD.
You can download the sources for the ByD OData service, the Postman collection and the HTML5 application from the SAP PartnerEdge - SAP Business ByDesign Learning Room (requires PartnerEdge login; if you need help to access SAPPartnerEdge.com or SAP PartnerEdge Learning Rooms the following blog may help: Need Help Getting Access).
Step 1: Configure OData Service in SAP Business ByDesign
SAP Business ByDesign provides 3 types of OData services:
- OData for Reports to access pre-processed and formatted analytical data,
- OData for Data Sources is designed to extract analytical raw data, and
- OData for Business Objects designed for interactive read and write access to ByD business objects => the best fit for the use case in this blog post.
Step 1 will be about exposing relevant parts of the ByD business object Employee via OData service.
Open work center view “Application and User Management - OData Services”, select “Custom OData Service” and upload the custom OData service file khemployee.xml provided in the download link in sub-folder "Custom OData Service".
Alternatively you can create your own custom OData service with name “khemployee” for business object “Employee” as well.
To serve my use case the custom OData service contains the following properties of business object Employee:
- Entity Employee (Root):
- GivenName: CurrentCommon-Person/Name/GivenName
- FamilyName: CurrentCommon-Person/Name/FamilyName
- EmployeeID: IdentificationEmployeeID-EmployeeID/content
- FormattedName: CurrentCommon-BusinessPartnerFormattedName
- Entity EmployeeEmployeeWorkplaceAddressInformation
- Entity EmployeeEmployeeWorkplaceAddressWorkplaceAddress
- Phone
- Fax
- Mobile
- Building
- Floor
- Room
- Entity EmployeeAttachmentFolder (the attachment folder contains the picture of the employee that we display in our HTML5 application)
Assign the OData service to a work center view to ensure role-based authorization checks. As result the OData service can be access with any ByD business user who has access to the ByD work center view assigned in the OData editor.
Save and activate your custom OData service and note down the Service URL from the OData Editor. In my example the service URL is
https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/.
You get the OData service metadata using the URL:
https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/$metadata.
Step 2: Test the OData Service using Postman
Let’s get familiar with the OData service. In my example I am using Postman (www.getpostman.com) as REST/OData test tool:
- Open Postman and import the Postman collection and the Postman environment provided in the download link in sub-folder "Postman Collection".
- Edit the Postman environment and change the environment variable values according your ByD tenant setup:
- TenantHostname: <your ByD tenant hostname>
- User: <your ByD user – you should have access to the work center view assigned to the OData service in step 2>
- Password: <your ByD user password>
- EmployeeID: <any employee ID as displayed in work center view “Personnel Administration - Employees”>
- Select the Postman environment create in step 1-2.
- Run the requests included in the Postman collection "khemployee". Always run a GET request first to populate the x-csrf-token of the environment.
The Postman collection contains examples for all requests performed by the HTML5 applications as well:
Get OData metadata using the metadata URL:
GET /sap/byd/odata/cust/v1/khemployee/$metadata HTTP/1.1
Host: myXXXXXX.sapbydesign.com
Get a list of employees with ID and name:
GET /sap/byd/odata/cust/v1/khemployee/EmployeeCollection?$filter=EmployeeID eq '*'&$format=json&$inlinecount=allpages&$top=100 HTTP/1.1
Host: myXXXXXX.sapbydesign.com
x-csrf-token: fetch
Get employee including workplace address and employee picture:
GET /sap/byd/odata/cust/v1/khemployee/EmployeeCollection?$filter=EmployeeID eq '{{EmployeeID}}'&$expand=EmployeeEmployeeWorkplaceAddressInformation/EmployeeEmployeeWorkplaceAddressWorkplaceAddress&$format=json HTTP/1.1
Host: myXXXXXX.sapbydesign.com
x-csrf-token: fetch
Update employee workplace address:
POST /sap/byd/odata/cust/v1/khemployee/EmployeeEmployeeWorkplaceAddressWorkplaceAddressCollection('{{ObjectID}}') HTTP/1.1
Host: myXXXXXX.sapbydesign.com
Content-Type: application/json
x-csrf-token: {{x-csrf-token}}
x-http-method: MERGE
Body:
{
"ObjectID": "{{ObjectID}}",
"ParentObjectID": "{{ParentObjectID}}",
"Phone": "+1 216 399 3571-1",
"Email": "Edward.Black@us.almika-refsys.byd",
"Fax": "+1 216 399 3510",
"Mobile": "+1 123 456",
"Building": "WDF1",
"Floor": "4",
"Room": "42"
}
Step 3: Create SAP Cloud Platform HTML5 Application
Import the sample HTML5 application:
- Download the zip-file “demoemployee.zip” provided in the download link, sub-folder “SCP Demo App”.
- Open the SAP Cloud Platform Cockpit of your SAP Cloud Platform sub-account (Neo environment) and open Applications >> HTML5 Applications.
- Create a new HTML5 application and enter an application name (for example “demoemployee”).
- Click on “Action >> Edit the application online using the SAP Web IDE” of your new application.
- Web IDE: Open the context menu of your application (e.g. “demoemployee”) in your workspace and select “Import >> From file system”:
- File: Browse the zip-file with the HTML5 application downloaded in step 1a
- Import to: Select the folder with your application name (e.g. “demoemployee”)
- Web IDE: Open the context menu of your application (e.g. “demoemployee”) in your workspace and select “Deploy >> Deploy to SAP Cloud Platform”: Deploy and activate the app.
- Return to the SAP Cloud Platform Cockpit >> HTML5 Applications and check if the application has been started successfully.
Create a destination to connect the ByD OData service:
- Open SAP Cloud Platform Cockpit >> Connectivity >> Destinations and create a new destination:
- Name: <enter a destination name>
- Type: HTTP
- Description: <enter a destination description>
- URL: <enter the URL of your ByD OData service, for example “https://myXXXXXX.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/”>
- Proxy Type: Internet
- Authentication: BasicAuthentication
- User: <enter your user with authorization for the OData service>
- Password: <enter your password>
- SAP Cloud Platform Cockpit >> HTML5 Applications:
- Open your HTML5 application and edit the destination mapping: enter your destination as “Mapped Subaccount Destination”.
- Start your HTML5 application using the Application URL
You can authenticate at ByD OData services using Basic Authentication (user/password) and OAuth 2.0 SAML Bearer authentication.
You find a description how to configure principal propagation using OAuth 2.0 SAML Bearer authentication in my subsequent blog post Configure OAuth 2.0 for SAP ByDesign OData Services.
Stay tuned 🙂
- SAP Managed Tags:
4 Comments
