Calling APIs of Remote Systems Using Actions in a Process

Business Scenario

You and your colleagues are building a process that needs to read Sales Order data from your SAP S/4HANA system and at a later stage, also write Sales Order data back to the system. Now you're faced with the challenge of interacting with that SAP S/4HANA system in the process. As a solution to this challenge, SAP Build Process Automation provides the capability of Actions projects. You have already created an Actions project that encapsulates the Read Sales Order API endpoint of the SAP S/4HANA Sales Order API. Now you want to make use of the Action within a process. For that, you'll use the Action step type. As the process also needs technically to be able to reach the SAP S/4HANA system, a destination will be required too.

When connecting remote systems with your SAP BTP environment, it's vital to create a Destination for them. The Destination acts as sort of a technical address of the system to be connected. Destinations can include additional information such as credentials for access authentication and authorization.

In this example, you want to make use of the API Sandbox environment of the SAP Business Accelerator Hub as a proxy for an SAP S/4HANA Cloud system.

To learn more about how to call remote systems APIs using Actions in a process, follow this interactive tutorial.

Exercise Options

To carry out this exercise, you can choose from the following options:

Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
Platform Simulation: Follow the step-by-step instructions within the simulation.
Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.

ExerciseStart Exercise

Prerequisites

You have performed the exercise Encapsulate Remote Systems APIs Using Actions Projects.

Task 1: Prepare the Remote System and Create a Destination

Steps

Prepare the remote system connectivity via a destination.
1. To navigate to the API Business Hub, open https://api.sap.com/ in a separate tab.
2. In the Search field, enter Sales Order (A2X), and choose Enter.
3. Scroll down.
4. Choose SAP S/4HANA Cloud Sales Order (A2X) OData API.
5. To view configuration details, select the scroll bar to scroll down.
6. Choose Configuration Details.
  You can now copy the Value of SANDBOX URL and save it for later us.

Create a destination.

Use the following data:

Field	Value
Name	SalesOrderS4Sandbox
Type	HTTP
Description	Destination for SAP Business Accelerator Hub Sandbox API for SAP S/4HANA Cloud Sales Orders
URL	https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV
Proxy Type	Internet
Authentication	NoAuthentication
Key	sap.processautomation.enabled
Value	true

Open the SAP BTP cockpit for the subaccount where you use SAP Build Process Automation.
Choose Destinations.
Choose New Destination.
In the Name field, enter SalesOrderS4Sandbox.
As Type, choose HTTP.
In the Description field, enter Destination for SAP Business Accelerator Hub Sandbox API for SAP S/4HANA Cloud Sales Orders.
In the URL field, enter https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV.
As Proxy Type, choose Internet.
As Authentication, choose NoAuthentication.
Choose New Property.
In the Key field, enter sap.processautomation.enabled
In the Value field, enter true.
This property makes destinations configured in your SAP BTP subaccount visible to SAP Build Process Automation.
Choose Save.

Assign SalesOrderS4Sandbox to SAP Build Process Automation.
1. Open SAP Build Process Automation.
2. Choose Settings.
3. Choose Destinations.
4. Choose New Destination.
5. Select SalesOrderS4Sandbox.
6. Choose Add.
7. This destination is available for use within SAP Build Process Automation processes.

Task 2: Create a New Process and a Trigger Form for it

Steps

Create a new process to include an Action.

Use the following data:

Field	Value
Project Name	Read Sales Order info from SAP S/4HANA
Short Description	Exercise using actions to communicate with SAP S/4HANA Sandbox API
Name	GetSalesOrderInfo
Identifier	getSalesOrderInfo (auto filled)
Description	Process to read Sales Order info from SAP S/4HANA Sandbox API

Choose Lobby.
Choose Create.
Choose Build an Automated Process.
Choose Business Process.
In the Project Name field, enter Read Sales Order info from SAP S/4HANA
Note
The figure shows S/4HANA, only
In the Short Description field, enter Exercise using actions to communicate with SAP S/4HANA Sandbox API.
Choose Create.
Note
The figure shows S/4HANA, only.
In the Name field, enter GetSalesOrderInfo.
In the Identifier field, you do not have to enter anything.
In the Description field, enter Process to read Sales Order info from SAP S/4HANA Sandbox API.
Choose Create.

Create a trigger form for the process.

Use the following data:

Field	Value
(Form) Name	GetSalesOrderInfoForm
(Form) Identifier	getSalesOrderInfoForm (auto filled)
Header
Title	Enter the number of a Sales Order that needs to be checked
(Text) Title	Sales Order Number
Configuration	Required

Choose Add → Forms → New Form.
In the Name field, enter GetSalesOrderInfoForm.
In the Identifier field, you do not have to enter anything, it will be filled automatically.
Choose Create.
Choose Form.
Choose H1.
In the Title field, enter Enter the number of a Sales Order that needs to be checked.
Choose Text.
In the Title field, enter Sales Order Number.
Select Required.
Choose Save.

Task 3: Use Actions

Steps

Include an Action in the process to call the SAP S/4HANA Sandbox API for sales orders.
Use the following data:
Field Value
Action Identifier SalesOrderAPIDestination (auto filled)
Description Destination for the Sales Order API in an SAP S/4HANA Cloud system
1. Choose GetSalesOrderInfo.
2. Choose Add → Actions → Browser library.
3. Choose Add.
4. Choose Action.
5. Open the Destination variable list.
6. Select Create Destination Variable.
7. In the Identifier field, enter SalesOrderAPIDestination.
8. In the Description field, enter Destination for the Sales Order API in an SAP S/4HANA Cloud system.
9. Choose Create.
Use the destination variable.
You can now see that the destination variable was created as an environment variable in the project and can be managed via the project properties. This makes your process definition independent from the actual destination to be used, and lets you define it at each deployment of a new process version.
1. Choose Inputs.
2. Choose Select item for SalesOrder.
3. Choose Sales Order Number.
  In the API call performed with the Action, the SalesOrder URL parameter will be filled with the actual Sales Order Number given by the end user in the trigger form when starting the process. The APIKey parameter does not need any special assignment, as you have maintained the API key as a default value in the Actions project earlier.
  When using a real SAP S/4HANA Cloud system, the authentication and authorization are defined by the communication arrangement and the destination, thus, an APIKey will not be required in that case.
4. Choose Outputs.
5. To view the resulting data structure of the API call, choose the arrow.
6. You can now see the resulting data structure of the API call.
Create an approval form which displays the sales order data.
Use the following data:
Field Value
Name SalesOrderApprovalForm
Identifier salesOrderApprovalForm (auto filled)
1. Choose Add → Approvals → New Approval Form.
2. In the Name field, enter SalesOrderApprovalForm.
3. In the Identifier field, you do not have to make an entry. It will be filled automatically.
4. Choose Create.
5. Choose Select item for Subject.
6. Choose Sales Order Number.
7. Choose Select item for Subject.
8. Select the scroll bar to scroll down.
9. Choose Process Started By.
Configure the SalesOrderApprovalForm.
Use the following data:
Type Field Value Configuration
Header 1 Title Approval for Sales Order
Header 2 Title Sales Order Info
Text Title Sales Order Number Read Only
1. Choose Settings.
2. Choose Open Editor.
3. Choose H1.
4. In the Title field, enter Approval for Sales Order.
5. Choose H2.
6. In the Title field, enter Sales Order Info.
7. Choose Text.
8. In the Title field, enter Sales Order Number.
9. As Configuration, select Read Only.
10. This is the result:

Field	Value
Action Identifier	SalesOrderAPIDestination (auto filled)
Description	Destination for the Sales Order API in an SAP S/4HANA Cloud system

Field	Value
Name	SalesOrderApprovalForm
Identifier	salesOrderApprovalForm (auto filled)

Type	Field	Value	Configuration
Header 1	Title	Approval for Sales Order
Header 2	Title	Sales Order Info
Text	Title	Sales Order Number	Read Only

Create another form.

Use the following data:

Category	Element	Title	Setting
Inputs	Text	Sales Order Type	Read Only
Inputs	Text	Net Value	Read Only
Inputs	Text	Distribution Channel	Read Only
Inputs	Text	Division	Read Only
Inputs	Text	Sales Organization	Read Only
Inputs	Text	Sales Order Date	Read Only
Inputs	Text	Customer Reference	Read Only
Inputs	Text	Requested Delivery Date	Read Only

Create the form as explained earlier.

Configure the form.
Use the following data:
Field Value
(H2) Title Add your comment here and select Approve or Reject
(Text) Title Approval Comment
1. Choose H2.
2. In the Title field, enter Add your comment here and select Approve or Reject.
3. Choose Text Area.
4. In the Title field, enter Approval Comment.
5. Choose Save.
6. Choose Close.
7. Choose GetSalesOrderInfo.
8. Drag Reject, and drop on End.

Field	Value
(H2) Title	Add your comment here and select Approve or Reject
(Text) Title	Approval Comment

Match the result of the Action API call with the approval form elements.

Use the following data:

Field	Value
Distribution Channel	DistributionChannel
Division	OrganizationDivision
Net Value	TotalNetAmount
Requested Delivery Date	RequestedDeliveryDate
Sales Order Date	SalesOrderDate
Sales Order Number	GetSalesOrderInfoForm → Sales Order Number
Sales Order Type	SalesOrderNumber
Sales Organization	SalesOrganization

Choose SalesOrderApprovalForm.
Choose Inputs.
Choose Select item for Customer Reference.
Choose PurchaseOrderByCustomer.
Similarly, use the assignments above for the remaining fields.
Choose Save.
This is the result:

Task 4: Release, Deploy, and Test the Process

Steps

Release and deploy the process.
1. Choose Release.
2. In the Version Comment field, enter Reads Sales Order info from SAP S/4HANA.
3. Choose Release.
4. Choose Deploy.
5. Open the Destination list.
6. Select SalesOrderS4Sandbox.
7. Choose Confirm.
8. Choose Deploy.
Test the deployed process.
Use the following data:
Field Value
Approve Comment Approved
1. Choose GetSalesOrderInfo.
2. Choose GetSalesOrderInfoForm.
3. Choose Copy.
4. Open another tab in the browser and paste the copied link, then choose Enter.
  The trigger form of the deployed process displays.
5. In the Sales Order Number field, enter 1.
6. Choose Submit.
7. You can now see that a pop-up displays that the request was submitted successfully.
8. Open the SAP Build Lobby.
9. Choose MyInbox.
  You can now see a new workitem Sales Order 1.
10. Select the scroll bar to scroll down.
11. In the Approve Comment field, enter Approved.
12. Choose Approve.
  You now know how to create an Actions project for a selected API from SAP Business Accelerator Hub, how to include a published Action in your process, and how to connect the external system to be called via a destination. This gives you many possibilities when required to create new business processes based on the data in your enterprise's systems.