TL;DR: This post is part of a three-part series on building a custom AI agent for Joule, specialized in creating purchase requisitions in SAP S/4HANA Cloud Private Edition through a single prompt. In this first part, we walk through the steps to identify and enable APIs for consumption via the SAP Build suite.
A few days ago, the blog Adapting SAP Joule for Purchase Requisition Creation in SAP S/4HANA Cloud Private Edition was published, showing the execution of a custom Joule Agent capable of understanding, in a single prompt, the creation of a purchase requisition in SAP S/4HANA Cloud Private Edition. This use case was modeled using the SAP Build suite, more specifically Joule Studio, a low-code tool for building AI agents and capabilities in SAP Joule. The goal was to demonstrate that a wide variety of scenarios can be enabled in just a few steps using the tools provided by SAP BTP.
As a follow-up to the previous blog, this post is part of a series of 3 posts in which we describe the process that you and your team can follow to enable custom scenarios in Joule:
- In the first part, we walk through the steps to find APIs and enable them for consumption in the SAP Build suite.
- In the second part, we show how to build a Joule Skill and what to consider when creating it, all within Joule Studio. We will also build a process to support unit-of-measure mapping using SAP Build Process Automation.
- Finally, in the third part, we describe what to consider when building the Joule Agent for procurement.
It is important to note that, here, we are focused on this specific PR-creation use case, but the considerations are general and applicable to other scenarios. We also highlight that this series takes a more technical approach, explaining how to navigate between the tools.
Note: at SAP Sapphire 2026, the new Joule Studio was announced, making agent creation even easier. Stay tuned for more details soon.
Although a standard use case for PR creation exists, it covers specific scenarios. For example, the document type generated by this capability is always NB, which is not always suited to our customers. It can also be too verbose for certain users, as some back-and-forth messages are required to complete it. For this reason, based on internal discussions and customer feedback, we decided to demonstrate how to extend these scenarios to make them broader and more aligned, including even custom fields.
In our case, here are the requirements:
- That the agent be capable of identifying the request and generating the purchase requisition in SAP S/4HANA Cloud Private Edition with a single prompt, eliminating the need to go through multiple messages. The idea is to optimize the work of specialists who already know the material code, plant code, and other system information.
- That the agent be able to simultaneously handle the header and items in the same prompt, recognizing which fields belonged to the header, how many items there were, and what the values of the respective fields were.
- That the agent be capable of identifying, in this prompt, multiple fields, including a custom field called ZJoule, made available through a standard API via key user extensibility (Custom Fields app).
Note: if you are not familiar with the key user extensibility solution for extending the standard fields, we suggest reviewing some content related to the Custom Fields app, such as How to create custom fields in the Business Process with “Custom Field Fiori App ( ID F1481)”, Create Custom fields for Business Partner SAP Fiori screens in SAP S/4HANA and Adding Field in standard Fiori apps of S/4HANA with Custom Fields and Logic.
In our example, these requirements will be addressed on an SAP S/4HANA Cloud Private Edition 2025 FPS01 system.
This is a scenario that requires the involvement of multiple professional roles: system administrators, developers, and functional professionals. It is not a one-person guide, so at the beginning of each section, you will find the roles required to proceed to the next step.
Regarding the technical requirements, the following are needed: an SAP BTP subaccount with Cloud Foundry runtime enabled, an active SAP Build suite subscription (with SAP Build Process Automation and SAP Joule Studio), an SAP S/4HANA Cloud Private Edition system, a connection between this system and the SAP BTP subaccount, and a Joule service subscription. The initial provisioning configurations for these services must also be in place.
Note: Be aware of the supported data centers by Joule Studio to ensure access to the service via SAP Build.
Please note that the general purpose of this blog series is to serve as a guide presenting the steps to build your custom Joule Agent scenario, demonstrating, through an example, how you can attempt to run it. It is not, however, intended as a step-by-step tutorial, which means some prior knowledge is expected from the professionals who will execute each step.
Roles: functional consultants and developers.
Before any AI agent instructions or configurations, it is necessary to spend some time understanding how your scenario will be enabled for external consumption. The Joule Agent is a component that runs on top of the Joule service on SAP Business Technology Platform and, in some way, needs to connect to the SAP S/4HANA Cloud Private Edition to create the purchase requisition.
A very useful tool for finding this approach is the SAP Business Accelerator Hub, a catalog where all remote SAP APIs are published and documented. Here you will find everything you need to know about these connectors:
- Purpose
- Specification in various formats (OpenAPI, EDMX, SOAP, etc.)
- Supported authentication methods
- Configuration details
- Extensibility
- Product and release
- Reference for each operation
- Code samples for major programming languages
- Documentation and additional help pages.
Here you can explore the various APIs, reviewing their purpose and their ability to meet your business requirements.
Note: Use the APIs in accordance with their purpose, as described in the official documentation. In case of further doubts, review the API Policy.
In this use case scenario, we will use the OData V4 API API_PURCHASEREQUISITION_2 for Purchase Requisition. It can be found in the catalog by searching for the product SAP S/4HANA Cloud Private Edition and filtering by “Purchase requisitions”. The technical name of the service group can be found in the Overview tab, under the API Resources section.
Note that an OData V2 version exists but is already marked as “Deprecated”. Therefore, it is not recommended for new developments.
Note: always make sure to select the version that corresponds to your SAP S/4HANA Cloud Private Edition to ensure the API is available in your system. Use the “Select Release” dropdown to specify it.
Still in API Resources, you can find the path to call the service from SAP S/4HANA Cloud Private Edition. This path will be used later when we configure the destination in SAP BTP.
In the API Reference section, you can browse the various objects that can be read and manipulated by these APIs. When you select one of the objects, you will see the available operations, as well as the fields required for their execution. There is also the response structure, which shows which fields will be returned upon successful execution of the service. This view is particularly useful for functional colleagues, who can map names to fields found in SAP S/4HANA business objects.
For our scenario, we will use the Purchase Requisition object, with a POST operation on the OData entity /PurchaseReqn. This operation allows you to create a purchase requisition with all the required fields, including a structure to add items in the same call.
A characteristic of this API is the need to pass the base unit in ISO format (SAP note 3525094). Since this is not a commercial unit of measure code (the most commonly used), a second API will be required to retrieve it based on the material IDs indicated in the prompt. For this, we will use the API_PRODUCT API for Products, with a GET operation on the OData entity /Product.
Roles: system administrators.
After locating the API to be used, you must ensure that it is activated in the SAP S/4HANA Cloud Private Edition system. Depending on the type of API chosen, OData V2 or OData V4, different steps must be followed.
For OData V2 APIs, you can follow the documentation Activate and Maintain Services. There you will find details about the features of transaction /IWFND/MAINT_SERVICE and how to use it.
For OData V4 APIs, you can follow the documentation available in Service Group Publishing. This help page details the steps to publish and configure a service using transaction /IWFND/V4_ADMIN.
In our example, we used transaction /IWFND/V4_ADMIN to publish the service group API_PURCHASEREQUISITION_2. Keep in mind that your system may have different configurations for system alias.
After publishing the service, you can also test it using the SAP Gateway Client (transaction /IWFND/GW_CLIENT) or with any HTTP client of your choice, such as Postman, Insomnia, or Bruno.
Roles: system administrators.
Destinations are abstractions created to mask or hide addresses, keys, certificates, and other sensitive information. By using them, it is not necessary to store this information in your developments. As a best practice, let’s create a destination in SAP BTP to expose the URL of the newly published service. These activities are typically performed by system administrators, and the generated destinations are then shared with colleagues so they can proceed.
Before executing this step, your system must already be correctly exposed to SAP Business Technology Platform through a SAP Cloud Connector. You can check which systems are already exposed to SAP BTP in SAP BTP Cockpit, under Connectivity > Cloud Connectors.
To create the destination in SAP BTP Cockpit, go to the Connectivity > Destinations section and click the Create button. In the popup, select From Scratch. Then, fill in the fields according to the table below:
|
Field name |
Value |
||||||||||
|
Name |
|||||||||||
|
Type |
HTTP |
||||||||||
|
Description |
|||||||||||
|
Proxy Type |
OnPremise |
||||||||||
|
URL |
|||||||||||
|
Location ID |
|||||||||||
|
Authentication |
BasicAuthentication or PrincipalPropagation (productive scenario) |
||||||||||
|
User |
|||||||||||
|
Password |
|||||||||||
|
Additional Properties |
|
In our example, to expose the URL we found for Purchase Requisition, we used the following information:
|
Field name |
Value |
||||||||||
|
Name |
EasyPurchaseRequisitionV4 |
||||||||||
|
Type |
HTTP |
||||||||||
|
Description |
Easy Purchase Requisition on Joule |
||||||||||
|
Proxy Type |
OnPremise |
||||||||||
|
URL |
http:// |
||||||||||
|
Authentication |
BasicAuthentication |
||||||||||
|
User |
|||||||||||
|
Password |
|||||||||||
|
Additional Properties |
|
For exposing the URL for Products, we used the following information:
|
Field name |
Value |
||||||||||
|
Name |
EPRProductV4 |
||||||||||
|
Type |
HTTP |
||||||||||
|
Description |
Easy Purchase Requisition on Joule – Products |
||||||||||
|
Proxy Type |
OnPremise |
||||||||||
|
URL |
http:// |
||||||||||
|
Authentication |
BasicAuthentication |
||||||||||
|
User |
|||||||||||
|
Password |
|||||||||||
|
Additional Properties |
|
For further questions about destination management in SAP BTP, refer to the documentation Using the Destinations Editor in the Cockpit .
Roles: system administrators.
An environment is a functional area in which you deploy and run your SAP Build Process Automation and SAP Joule projects. It is a prerequisite for running your Joule Agent.
To create an environment, from the SAP Build Lobby, navigate to the Control Tower > Environments. Then, click Create and provide a name, an ID, and a description for your environment.
For this example, we created the environment Easy Purchase Requisition. This object will be used in part 2.
Roles: system administrators.
A second step is required for destinations created in SAP BTP Cockpit to become visible in SAP Build. After accessing the SAP Build Lobby, go to Control Tower > Destinations.
Clicking Add opens a pop-up window that lets you select the destination. Search for the destination you created and select it. Next, choose the environment in which you want the destination to be available. You can select specific environments or make it available to all environments at once. If you prefer a more granular selection, make sure the environment you created is selected.
More information on how to manage destinations in SAP Build can be found at Manage Destinations.
For the purchase requisition and product scenarios, we selected, respectively, the destinations EasyPurchaseRequisitionV4 and EPRProductV4 and enabled them for consumption across all environments, without any restrictions.
Roles: functional consultants and developers.
We have now reached the last step of our first part: creating Actions. An Action is a connector that encapsulates one or more APIs. It is the artifact that will later be invoked by the Joule Skill and the Process Automation we will build.
To create an action, you must first create a dedicated project. There are essentially two ways to obtain API contracts:
- Via Live API, using SAP Cloud Application Programming (CAP) service, ABAP Restful Application Programming Model (RAP) service, generic OData destinations, a system available through the Unified Customer Landscape, SAP Integration Suite APIs, or RFCs.
- Via static API specification, using definitions from the API Business Hub, uploading a specification, or creating a specification from scratch.
For this example, we will use the Live APIs from OData destinations.
From the SAP Build Lobby, in the Connectors section, click Actions to view all existing projects created to expose APIs for SAP Build developments. Click Create to open the pop-up window and choose your data source. Select OData Destinations. In the list, select the destination you published (e.g., EPRProductV4 or EasyPurchaseRequisitionV4).
If the configuration is correct, the service metadata will be loaded automatically, displaying all available operations from the selected APIs. This content is informational only and will be used shortly during modeling. Next, specify a name for your project, a brief description of the project, and the APIs that will be encapsulated.
Note: if you cannot find your API in the list, verify that the parameter “sap.build.usage” is set to “odata_gen” in your destination configuration in SAP BTP Cockpit.
In our procurement example, two projects were created:
- Easy Purchase Requisition – APIs v4 – project to encapsulate the API related to purchase requisition creation in SAP S/4HANA Cloud Private Edition.
- Easy Purchase Requisition – Product APIs v4 – project to encapsulate the APIs for material lookup in SAP S/4HANA Cloud Private Edition.
You will be redirected to the Actions modeler. From the API contract, select the operations identified during the requirements phase. There is a limit of 20 operations per project, so avoid selecting unnecessary operations.
For this example, we selected the POST operation for the entity /PurchaseReqn (Add new entity to PurchaseReqn).
After finalizing the selection, click Add. Then, you can now navigate through the structure of the selected operations.
In the Input tab, you will find the parameters and, when applicable, the request body required to make the call, including the navigations. You can make adjustments to data types and the mandatory status of fields.
Important: every Action containing a POST, PATCH, PUT, or DELETE operation (i.e., one that results in the creation, update, or deletion of data) targeting the SAP S/4HANA Cloud Private Edition system must have the CSRF token enabled. This is a mechanism to prevent malicious attacks known as Cross Site Request Forgery.
SAP Build includes a CSRF token fetch mechanism, however it is disabled by default. To enable it, click the gear icon in the top-right corner. Click the toggle switch to activate the mechanism. In the endpoint field, add the path “https://community.sap.com/”.
In the Output tab, you will find the response structures for success (2xx) and error (4xx or 5xx) scenarios.
In the Test tab, you can test the connectivity and execution of your Action. Select the destination corresponding to the action you want to execute and fill in the form with test data. Before proceeding to the next steps, it is important to ensure the API is working correctly. Be sure to test it so that, if there are integration failures, you know there are no connectivity issues and that your scenario was validated through a direct call.
In our example, we made a call to create the purchase requisition, validating connectivity and the minimum required values for the operation.
We also ran connectivity and consumption tests for the product API, validating the execution using a filter and checking the return of the corresponding ISO unit of measure.
After completing the required validations, you must Release the Action, followed by its publication. Do not forget this step. Without publishing, your Action will not be visible in the library, making it impossible to use it in the subsequent steps.
After going through all these steps, keep in mind the following points:
- Have a use case or scenario well discussed and defined before starting your API investigation. It will allow you to validate the best API option and build the new capability concisely and quickly. Prefer to start with smaller, quick-to-implement cases (quick wins).
- A multidisciplinary team is extremely valuable when working with generative AI agents and capabilities. You may have noticed that many of the steps in this process are shared by more than one professional role. Cross-team integration is a key success factor for deploying custom scenarios.
- Use the API Business Hub as your primary source for discovering public and remote APIs for S/4HANA Cloud Private Edition, paying attention to your system’s release. Also, ensure that the API usage is in compliance with its purpose. Then, enable the API in S/4HANA and run basic tests before investing more time in subsequent steps.
- SAP Build requires a series of steps before an API can be consumed:
- A destination must be created in SAP BTP Cockpit.
- An environment must be created in SAP Build.
- The destination must be published for consumption in the SAP Build environment.
- An Action is managed within a project. Do not forget to publish it. Without publishing, the action will not be visible in subsequent steps.
In the next post, we will cover the creation of the Joule Skill. There, we will use the artifacts from this guide to allow the Joule Agent to perform the desired operation. See you there!
Thanks,
Brought to you by the SAP S/4HANA RIG Team
