SAP Learning Journey

Encapsulating the APIs of Remote Systems Using Actions Projects

Objectives
After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Encapsulate remote systems APIs using actions projects

Encapsulation of Remote Systems APIs using Actions Projects

As many business processes span across a multitude of different systems and applications, a means to interact with these systems and applications is required in the business process management system. In SAP Build Process Automation, you use Actions to accomplish the integration. Application Programming Interfaces (APIs) from the source and target systems to interact with, are encapsulated as Actions within Actions projects. Those Actions projects are then held in an Actions projects library and from there, can be integrated into the business processes. This approach offers various advantages compared to direct API integration into the respective process:

  • There is an abstraction of the API. The process developer does not need to know exactly about technical details of the API.
  • APIs can be adjusted to the process developers needs, only exposing endpoints and data that is required or safe to use by the process developers.
  • Actions can be configured once, and then be reused across different business process projects.
  • Actions projects allow versioning and thus, make it easier to deal with changing process requirements or changing API versions.

As Actions rely on the OpenAPI Specification standard (https://spec.openapis.org/oas/v3.1.0#openapi-specification) for API definition, they aren't limited to APIs from SAP systems, but provide the option to integrate any API that is or can be described in the OpenAPI Specification. A large number of API definitions, especially for but not limited to SAP solutions, can be found in the SAP Business Accelerator Hub.

Note
You'll find additional information on APIs, specifically on SAP Build Process Automation APIs, and how to interact with them on a more technical level in unit API Integration of SAP Build Process Automation.

Actions Editor

The Actions Editor lets you compose multiple Actions from an underlying API into an Actions project. Note that you don't have to include all possible parameters of an API endpoint as parameters in the respective Actions, and you also don't have to include all available response body fields in the response provided through the Action. By that, only information relevant to the business process can be included.

Once your Actions have been defined, the project needs to be released into a version and then published to the Actions library.

After APIs have been encapsulated in an Actions project and published to the library, adding them as action to a process is quite simple. Select the corresponding step type Actions and browse the Actions library. Select the action required in your process, and choose Add. Once the Action step is included in your process, make sure to define its parameters:

  • Destination variable: A process variable that will hold the technical SAP BTP destination name to be used for accessing the underlying API at process runtime. This variable can be filled with a destination name during deployment of the process.
  • Inputs: Mapping of process content to all parameters, that the action requires in order to be performed (for example, the Sales Order Number, when retrieving a Sales Order entry from an SAP S/4HANA system).
  • Outputs: Overview of the Actions call result, as defined in the respective action.

Encapsulate Remote Systems APIs using Actions Projects

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. Your are going to define all the SAP S/4HANA Sales Order API endpoints that shall be used in the process, as Actions in an Actions project. This procedure can also be described as encapsulating the APIs, because you're building a wrapper only around the specifically required API endpoints. By releasing and publishing the Actions project, the actions will be available in an Actions library for consumption within your processes.

To learn more about how to encapsulate remote systems APIs using Actions projects, follow this tutorial.

Exercise Options

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

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. 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

Task 1: Create and Configure the Required Objects

Steps

  1. Create an Actions project.

    Use the following data:

    FieldValue
    Project NameSAP S/4HANA Sales Order Actions
    Short DescriptionActions project to interact with Sales Orders in an SAP S/4HANA system

    1. Choose Instances and Subscriptions.

    2. Choose SAP Build Process Automation.

    3. Choose Create.

    4. Choose Build an Automated Process.

    5. Choose Actions.

    6. In the Project Name field, enter SAP S/4HANA Sales Order Actions.

    7. In the Short Description field, enter Actions project to interact with Sales Orders in an SAP S/4HANA system

    8. Result:

  2. Create a project in a new tab.

    1. Open a new tab and go to SAP Business Accelerator Hub. The URL is https://api.sap.com/. Note: the link will be replaced shortly.

    2. In the Search field, enter Sales Order (A2X) and choose Enter.

    3. To select SAP S/4HANA Cloud Sales Order (A2X) OData API, select the scroll bar to scroll down.

    4. Choose SAP S/4HANA Cloud Sales Order (A2X) OData API.

    5. To view API resources, select the scroll bar to scroll down.

    6. Choose API Specification.

    7. Choose Download.

    8. Go to Create an Action pop-up screen.

    9. Choose Browse.

    10. Choose API_SALES_ORDER_SRV.json.

    11. Choose Open.

    12. Choose Create.

    13. The project is being created.

  3. Configure required actions to your needs.

    In the following steps, you'll configure required Actions to your needs. The imported API specification from SAP Business Accelerator Hub may contain many endpoints that you don't need for your processes, or that might even be harmful to your business when being used in a wrong context. You can configure only the API endpoints that are required by the process developers, as Actions.

    1. Choose SAP S/4HANA Sales Order Actions.

      The figure shows S/4HANA Sales Order Actions only.

    2. To view GET /A_SalesOrder('{SalesOrder}'), select the scroll bar to scroll down.

    3. Select GET /A_SalesOrder('{SalesOrder}').

    4. Choose Add.

    5. Choose Output.

    6. To expand the pane, choose the arrow.

    7. Choose Select All.

    8. To view more output keys, select the scroll bar to scroll down.

    9. Clear OrganizationDivision.

    10. To view more output keys, select the scroll bar to scroll down.

    11. Clear DistributionChannel.

    12. Clear TotalNetAmount.

    13. Clear SalesOrderType.

    14. Clear SalesOrderDate.

    15. To view more output keys, select the scroll bar to scroll down.

    16. Clear PurchaseOrderByCustomer.

    17. Clear SalesOrganization.

    18. Clear RequestedDeliveryDate.

    19. To view the Remove button, select the scroll bar to scroll up.

    20. To remove most of the Sales Order info and only keep the subset that is relevant for the example process, choose Remove.

    21. Choose Remove.

    22. Choose Save.

Task 2: Test

Steps

  1. Test Actions.

    In the following steps, you'll test the actions.

    In order to test the configured actions, you need access to either a real or a test SAP S/4HANA Cloud system. For this exercise, you will make use of the API Sandbox environment in SAP Business Accelerator Hub.

    Use the following data:

    FieldValue
    Sales Order1

    1. Open a new tab and go to SAP Business Accelerator Hub. The URL is https://api.sap.com/. Note: the link will be updated.

    2. Choose Try Out.

    3. Choose /A_SalesOrder('{SalesOrder}').

    4. In the SalesOrder field, enter 1.

    5. Choose Run.

      Note

      Make sure, that you're logged in to SAP Business Accelerator Hub with the SAP user.

    6. When the request is successful, in the RESPONSES section, it displays an HTTP 200 code and the Response Body in JSON format.

      This response is the information that you want to get into the process using the Actions project.

    7. Choose Show API Key.

      The users unique API Key for the SAP Business Accelerator Hub sandbox environment of the SAP S/4HANA Sales Order API is displayed. Copy the key and save it for later use.

    8. Choose Copy Key and Close.

    9. Choose Overview

    10. To view the configuration details button, select the scroll bar to scroll down.

    11. Choose Configuration Details.

    12. You can now copy the Value of SANDBOX URL and save it for later use.

  2. Perform another test.

    Use the following data:

    FieldValue
    KeyAPIKey
    LabelAPIKey
    ValueGudHRL1UsdymnuoB6CUpDyzMAIfxPGw

    1. Go to SAP Action Editor.

    2. To add a new parameter, choose Add.

    3. Choose Add a Custom Parameter.

    4. In the Key field, enter APIKey.

    5. Open the Parameter list.

    6. Choose header.

    7. In the Label field, enter APIKey.

    8. In the Value field, enter GudHRL1UsdymnuoB6CUpDyzMAIfxPGw.

    9. Choose Add.

    10. Choose Save.

  3. Perform a manual test.

    Use the following data:

    FieldValue
    URLhttps://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV
    AuthenticationNo Authentication
    SalesOrder1

    1. Choose Test.

    2. Choose Manual.

    3. In the URL field, enter https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV and choose Enter.

      As Authentication Type select No Authentication.

    4. In the SalesOrder field, enter 1.

      The APIKey has already been entered.

    5. Choose Test.

    6. The Response Preview section will display the result, with a 200: OK HTTP code and a body in JSON format that only contains the previously configured subset of output parameters.

    7. Choose Save.

Task 3: Use Your Configured Actions

Steps

  1. Release and publish the Actions project.

    In order to use your configured Actions in an SAP Build process, the Actions project needs to be deployed and released to the Library. This procedure gives you governance over which APIs are ready to be used by process developers and which APIs still need refinement.

    Use the following data:

    FieldValue
    Release NotesReads the header of a sales order

    1. Choose Release.

    2. In the Release Notes field, enter Reads the header of a sales order.

    3. Choose Release.

    4. The released version of the project displays.

    5. In order to publish a specific version to the Library, you need to select the version.

      For this tutorial, this has already been selected.

    6. Choose Publish to Library.

    7. Choose Publish.

    8. The released version has been published.

    9. The configured Actions are now available for the process developers in their processes.

Result

You've successfully encapsulated remote systems APIs using Actions projects.

This concludes the tutorial.

Log in to track your progress & complete quizzes