Awesome

Ballerina SAP Connector

SAP is a global leader in enterprise resource planning (ERP) software. Beyond ERP, SAP offers a diverse range of solutions including human capital management (HCM), customer relationship management (CRM), enterprise performance management (EPM), product lifecycle management (PLM), supplier relationship management (SRM), supply chain management (SCM), business technology platform (BTP), and the SAP AppGyver programming environment for businesses.

The ballerinax/sap package provides an HTTP client for interfacing with APIs across SAP's product suite. This client comes with built-in SAP system-compliant CSRF token authentication.

Setup guide

In this guide, we'll be utilizing the S/4HANA Sales Order API to showcase the capabilities of the SAP Client.

Step 1: Login

Step 2: Create a Communication System

Under the Communication Management section, click on the Display Communications Scenario title.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-1-communications-system.png alt="Communication Systems" width="50%">
In the top right corner of the screen, click New.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-2-create-new.png alt="Click New" width="50%">
Give a system id.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-3-system-id.png alt="System Id" width="50%">
Give the hostname as your S/4HANA hostname.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-4-give-hostname.png alt="Give Hostname" width="50%">
Add Users for Inbound Communication.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-5-add-user.png alt="Add User" width="50%">
Select the Authentication Method and User.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/2-6-select-user.png alt="Select User" width="50%">
Click Save.

Step 3: Create a Communication Arrangement

Under the Communication Management section, click on the Display Communications Scenario title.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-1-display-scenarios.png alt="Display Scenarios" width="50%">
In the search bar, type Sales Order Integration and select the corresponding scenario from the results.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-2-search-sales-order.png alt="Search Sales Order" width="50%">
In the top right corner of the screen, click on Create Communication Arrangement.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-3-click-create-arrangement.png alt="Click Create Arrangement" width="50%">
Enter a unique name for the arrangement.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-4-give-arrangement-name.png alt="Give Arrangement Name" width="50%">
Choose an existing Communication System from the dropdown menu and save your arrangement.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-5-select-communication-system.png alt="Select Existing Communication Arrangement" width="50%">
The hostname (<unique id>-api.s4hana.cloud.sap) will be displayed in the top right corner of the screen.

<img src=https://github.com/ballerina-platform/module-ballerinax-sap/blob/main/docs/setup/3-6-view-hostname.png alt="View Hostname" width="50%">

Quickstart

To use the sap connector in your Ballerina application, modify the .bal file as follows:

Step 1: Import the module

Import the sap module.

import ballerinax/sap;

Step 2: Instantiate a new connector

configurable string hostname = ?;
configurable string username = ?;
configurable string password = ?;

sap:Client sapClient = check new (string `https://${hostname}/sap/opu/odata/sap/API_SALES_ORDER_SRV`, {
    auth: {
        username,
        password
    }
});

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

json salesOrderList = check sapClient->/A_SalesOrder();

Step 4: Run the Ballerina application

bal run

Examples

The sap connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering use cases like accessing S/4HANA Sales Order (A2X) API.

Send a reminder on approval of pending orders - This example illustrates the use of the sap:Client in Ballerina to interact with S/4HANA APIs. Specifically, it demonstrates how to send a reminder email for sales orders that are pending approval.

Issues and projects

The Issues and Projects tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc., visit the Ballerina library parent repository.

This repository only contains the source code for the package.

Build from the source

Prerequisites

Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:
- Oracle JDK
- OpenJDK
Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.
Download and install Ballerina Swan Lake.
Download and install Docker.

Note: Ensure that the Docker daemon is running before executing any tests.

Build options

Execute the commands below to build from the source.

To build the package:
```
./gradlew clean build
```
To run the tests:
```
./gradlew clean test
```
To build the without the tests:
```
./gradlew clean build -x test
```
To run tests against different environment:
```
./gradlew clean test -Pgroups=<Comma separated groups/test cases>
```
Tip: For detailed information, please refer to the Tests_README document.

Groups Environment
mock Mock server
sap SAP S/4HANA API
To debug package with a remote debugger:
```
./gradlew clean build -Pdebug=<port>
```

Groups	Environment
mock	Mock server
sap	SAP S/4HANA API

To debug with the Ballerina language:

./gradlew clean build -PbalJavaDebug=<port>

Publish the generated artifacts to the local Ballerina Central repository:
```
./gradlew clean build -PpublishToLocalCentral=true
```
Publish the generated artifacts to the Ballerina Central repository:
```
./gradlew clean build -PpublishToCentral=true
```

Contribute to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

For more information go to the sap package.
For example demonstrations of the usage, go to Ballerina By Examples.
Chat live with us via our Discord server.
Post all technical questions on Stack Overflow with the #ballerina tag.