...
| ID | NFR-2007 |
|---|---|
| Name | Ariba Event Management Orchestration Framework |
| Author | Kapila Epasinghe ( kapila.epasinghe-ext@syensqo.com ) |
| Approver | Sascha Wenninger ( sascha.wenninger-ext@syensqo.com ) |
| Status | Approved |
Summary
The integration solution is designed to solve a coordination and rate-limit management problem between Ariba API and Keelvar APIs used in Sourcing Processes.
During the implementation of Interfaces interfaces (see below) that require orchestration of the APIs between the two systems, it was discovered that strictly imposed rate-limits in Ariba APIs mainly, but also primarily, and to a lesser extent Keelvar Intake and Export APIs, are reached, causing Integrations to interfaces to fail.
To address this, an Integration Orchestration Solution is introduced using available tools in SAP CPI. The major aspects of the solution are:
- Use of JMS Queues, where required, shared by Interfaces utilising across interfaces using the mentioned APIs
- Use of singleton processing via a Router IFlows that process messages sequentially and synchronously process messages from each JMS Queue
- Use of dedicated "Connectors" to Ariba and Keelvar APIs that are rate-limit aware and pause if limits are reached.
Overall, this solution provides a robust, controlled, and extensible foundation for managing multiple API-based integrations between Ariba and Keelvar, ensuring operational stability and compliance with API usage policies in Ariba and Keelvar. Furthermore, this solution can be extended if and when further Integrations integrations need to be implemented that utilise Ariba and Keelvar APIs, in addition to the 4 four interfaces that currently (as of 09 - April - 2026) utilise this:
| ID | Description |
|---|---|
| ERP-108 | Synchronisation of Sourcing Events created and updated in Ariba to Keelvar |
| ERP-137 | Synchronisation of Award Bids and Bid Sheets from Keelvar to Ariba |
| ERP-138 | Notification of Keelvar Event Status changes to Ariba |
| ERP-224 | Synchronisation of Suppliers updated in Ariba to Keelvar |
...
Ariba APIs contain both intake and export endpoints supporting the Ariba Strategic Sourcing Platform to read, create and update Sourcing events, Scenarios, Awards and Suppliers.
Three Ariba APIs are part of this solution - Event Management API, Master Data Retrieval API for Sourcing, and Surrogate Bidding API. There is no documented rate-limit for Surrogate Bidding API; however, Event Management API and Master Data Retrieval API for Sourcing requests are rate-limit controlled as shown below:
...
- Master Data Retrieval API for Sourcing: Enables Supplier Data synchronisation with Keelvar
Time limits Number of Requests Per second 10 Per minute 40 Per Hour 200 Per Day 1000
Three Keelvar Intake and Export APIs are three different sets of API Services with their APIs are also used in these integrations, each with its own rate-limits:
- Intake APIs: Enables Sourcing Event read, reading, creation and update in updating of Sourcing Events in Keelvar. In addition, APIs also contain services to check the Event Processing background job status.
API Burst Sustained Sourcing Events 120 per hour 500 per day Process Job Status 30 per minute 600 per hour - Export APIs: Enables reading of Sourcing Events, Bids and Awards.
API Burst Sustained Awards 60 per minute 43,200 per day Bids 60 per minute 43,200 per day Events 60 per minute 43,200 per day - Supplier Management APIs
API Burst Sustained Suppliers 30 per minute 600 an hourper hour Supplier Changes ( Retrieve ) 30 per minute 600 an per hour Supplier Changes ( Update ) 60 per hour 500 per day
...
| Info | ||
|---|---|---|
| ||
| In addition, Keelvar provides a Webhook management API which is utilised in the Event Management Orchestration between Ariba and Keelvar. However, this set of APIs do API does not have a published Raterate-Limit controls limit control and is described in NFR-2006. |
To manage the constraint enforced by the rate-limits, this framework enables the orchestration of the APIs between the two systems, avoiding and recovering from rate-limiting exceptions as well as handling exceptions such as data errors , and service unavailability etc.
The following guiding principles need to be applied in the IFlows pertaining to the Integrationintegration:
- All requests to APIs from IFlows will be via use Request-Reply objects - this enables the ability to handle Exceptions by logging the response message bodies, return codes etc.
- The Processing process will be broken up into small Asynchronous sequential , asynchronous calls executed sequentially. This allows the integration to re-process only failed API calls and then, once successful, hand hands over to the next IFlow next IFlow seamlessly
- The IFlows will be designed in such a way as to reduce the number of API calls, ideally to contain only one API call for each system. Multiple Multiple APIs will orchestrate be orchestrated when strictly necessary, since this increases the chances of reaching the rate-limit during processing of subsequent messages from the JMS Queue.
- The IFlows will be designed so that re-processing via the JMS Queue will not affect the outcome expected.
- The IFlows will only use the Ariba and Keelvar Connector IFlows to access the APIs. This ensures that the API calls are sequential and each call is completed before the next occurs
- The IFlows will handle and log the exceptions and raise a new exception to push it the message back to the JMS Queue. This ensures that the Error error notification is captured in CPI.
- The Sequence sequence of the IFlows are via Process Direct direct is managed via ProcessDirect endpoints to allow the Router to identify the Processing IFlow once it is pushed into JMS Queuethe JMS Queue
Solution Overview
Process Flow
...
| Step | Function |
|---|---|
| 1 | Invoker IFlow initiates the processing. After defining the parameters (headers) necessary, including the Process Direct ProcessDirect path for processing at Provider IFlow, the message is passed to the JMS Queue. Ideally, this IFlow will not contain any calls to Ariba or Keelvar APIs. |
| 2 | The JMS Sender Adapter reads the messages and processes them synchronously. |
| 3 | Based on the Process Direct ProcessDirect path defined in the message parameters, the Router IFlow forwards the message directly to the Provider IFlow. |
| 4 | The Provider IFlow executes calls to Ariba APIs as required, using a dedicated Connector IFlowsIFlow. These This Provider IFlow sets the parameters required parameters required by the Connector to call the API |
| 5 | The Provider IFlow executes any API calls to Keelvar, using the Keelvar Connector IFlowsIFlow. These This Provider IFlow sets the parameters required by the Connector to call the API. |
| 6 | Optionally, the Provider IFlow triggers additional messages to the JMS Queue. |
...
IFlows that write entries into the JMS Queues need to provide the following parameters
| Object | Value | Description |
|---|---|---|
| Header Value | jmsProcessDirectPath | The ProcessDirect path of the Provider IFlow. Externalised field |
| Queue Name in JMS Receiver Adapter Configuration | aribaEventMgtQueue | Name of the JMS Events Queue. Externalisable field |
| aribaMasterDataQueue | Name of the JMS Supplier Queue. Externalisable field |
All IFlows that forwards the forward the processing to JMS Queue should have the following configuration settings in the JMS Receiver Adapter
| Object | Value | Description |
|---|---|---|
| Access Type | Non-Exclusive | Each JMS Queue entry will process independently of each other due to the Design Principles applied |
| Retention Threshold for Alerting | 2 days | The number of days to hold the message in the Queue queue to raise a Stale message alert. Default value of 2 days. In this solution, this has no relevance as the messages are pushed to DLQ after the defined number of retries |
| Expiration Period | 30 days | The period a message can be fetched and reprocessed from the queue. Default value of 30 days is used. In this solution, solution this the parameter has no relevance as the message messages are pushed to DLQ after the defined number of retries. |
JMS
...
Routers
Externalised Parameters
| Object | Value JMS Event Router | Value JMS Master Data Router | Description |
|---|---|---|---|
| Sender Queue Name | aribaEventMgtQueue | aribaMasterDataQueue | The source JMS Queue to retrieve messages |
| Maximum Retries Allowed | 5 | 5 | The messages are gracefully pushed to a defined separate "Dead Letter Queue" (DLQ) used for error handling. No further processing will be done after the configured number of retries. |
| Dead Letter Queue for Error Handling | DLQ_aribaEventMgtQueue | DLQ_aribaMasterDataQueue | The name of the Dead Letter Queue that persists messages when the number of processing times |
| reaches the maximum Retry Limit |
Sender Adapter JMS
...
Configurations - Common to both JMS Routers
| Object | Value | Description |
|---|---|---|
| Number of Concurrent Processes | 1 | Note: This value is important for Singleton Instance of singleton instance of the IFlow. This is vital for Serialised processing of the Queuequeue |
| Retry Interval | 1 minute | The initial duration between the retry attempts |
| Exponential Backoff | Ticked (true) | The retry interval is doubled with each subsequent attempt |
| Maximum Retry Interval | 60 minutes | The maximum allowed retry interval with exponential backoff. In this solution, this parameter is relevant if the number of allowed retried is retries is increased to over 7 |
| Dead Letter Queue | Ticked (true) | In case of out-of-memory issues by the Worker worker node, the messages are moved to a separate queue. If needed, the messages can be unlocked for reprocessing. Note: this Dead Letter Queue is the default JMS Sender behaviour. |
...
| Object | Value | Description |
|---|---|---|
| Access Type | Non-Exclusive | Since messages are not automatically reprocessed from this queue, this value is not relevant for the solution |
| Retention Threshold for Alerting | 2 days | The number of days to hold the message in the Queue queue to raise a Stale message alert. Default value of 2 days. An alert will be raised if the message is not removed within this period. |
| Expiration Period | 30 days | The period a message can be fetched and reprocessed from the queue. Default value of 30 days is used. |
| Compress Stored Messages | Ticked (true) | Messages are compressed to reduce memory usage, although the messages are atomic in nature. |
| Encrypt Stored Messages | Ticked (true) | Messages are encrypted in Datastore. |
| Transfer Exchange Properties | Ticked | The message properties are kept for error handling processes |
JMS Master Data Router
Externalised Parameters
...
Sender Adapter JMS Configuration
...
In case of out-of-memory issues by the Worker node, the messages are moved to a separate queue. If needed messages can be unlocked for reprocessing.
Note: this Dead Letter Queue is the default JMS Sender behaviour.
Receiver Adapter JMS Configuration - For Dead Letter Queue
...
Provider IFlows Configuration Requirements
- Provider IFlows Sender ProcessDirect Adapter path must be defined as the header parameter jmsProcessDirectPath in the Invoker IFlow.
- Header and Property definitions required for Ariba and Keelvar APIs must be defined as described below
- If the Provider IFlow injects any messages to the JMSQueue, then the parameters defined in the Invoker IFlow must also be defined
Ariba Event Management API Connector IFlow
The Ariba Connector constructs the URL and the Authentication Parameters based on values passed from the calling IFlow and configurable parameters in the Connector. The construct is shown below:
Ariba Event Management URL
Construction of the URL with an example:
| METHOD | https:// | <Ariba Base URL> | <Ariba URL Path> | ? | <Connector Defined Query Parameters> | & | <Received Query Parameters> |
|---|---|---|---|---|---|---|---|
| GET | https:// | eu.openapi.ariba.com/api/sourcing-events/v2/prod | /events/identifiers | ? | realm=7452####-SS-T&user=R_XXXXXXXX&passwordAdapter=XXXXXXXXX | & | $filter=(createDateFrom gt 1761418273 and createDateTo=1761464729) |
An IFlow calling the Adapter must provide the following Header Parameters to construct the API endpoint to Ariba
| Object | Header Name | Description |
|---|---|---|
| HTTP Method | aribaMethod | The HTTP Method for the API |
| Ariba Url Path | aribaUrlPath | The Path (i.e. the endpoint) that is combined with the Base URL to construct the API endpoint |
| Query Parameters | aribaUrlQuery | The additional Query Parameters that must be combined with the the common query parameters defined in the Adapter |
Additional Parameters
| Object | Description | Value Dev | Value Test | Value Prod |
|---|---|---|---|---|
| Ariba Base URL | Base URL to Ariba Event Management APIs. | eu.openapi.ariba.com/api/sourcing-event/v2/prod | ||
| Credential Name | OAuth Credential Name for Ariba Endpoint in SAP CPI | OAuth_Ariba_Sourcing_EventMgmtAPI | OAuth_Ariba_Sourcing_EventMgmtAPI | OAuth_Ariba_Sourcing_EventMgmtAPI |
| Ariba API Delay | The Delay to be implemented when the remaining API count is zero | 2 seconds | 2 seconds | 2 seconds |
| Ariba Password Adapter | Password Adapter defined for Technical Users in Ariba | ThirdPartyUser | ThirdPartyUser | ThirdPartyUser |
| Ariba Realm | Ariba tenant ID | 745255310-SS-T | 744368466-T | 744368466 |
| Ariba User | Technical User for SAP CPI to extract events | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN |
| Ariba API Key | Security Credential Name containing the API Key for Ariba Event Management | APIKEY_AribaEventManagement_CPI_Dev | APIKEY_AribaEventManagement_CPI_QA | APIKEY_AribaEventManagement_CPI_Prod |
Ariba Surrogate Bidding API Connector IFlow
Similar to Event Management API Connector, the Ariba Surrogate Bidding API Connector also
Provider IFlows Configuration Requirements
- Provider IFlows Sender ProcessDirector Adapter path must be defined as the header parameter jmsProcessDirectPath defined in the Invoker IFlow.
- Header and Property definitions required for Ariba and Keelvar APIs must be defined as described below in the Ariba Event Management API Connector IFlow and Keelvar API Connector IFlow
- If the Provider IFlow injects any messages to the JMSQueue, then the parameters defined in the Invoker IFlow must also be defined
Ariba Event Management API Connector IFlow
The Ariba Connector constructs the URL and the Authentication Parameters based on valued passed values passed from the calling IFlow and configurable parameters in the Connector. The construct is shown below:
Ariba
...
Surrogate Bidding URL
Construction of the URL with an example:
| METHOD | https:// | <Ariba Base URL> | <Ariba URL Path> | ? | <Connector Defined Query Parameters> |
|---|
| POST | https:// | eu.openapi.ariba.com/api/sourcing-event- |
| bid/ |
| v1/prod |
| / |
| jobs | ? | realm=7452####-SS-T&user=R_XXXXXXXX& |
| passwordAdapter=XXXXXXXXX |
An IFlow calling the Adapter must provide the following Header Parameters to construct the API endpoint to Ariba
| Object | Header Name | Description |
|---|---|---|
| HTTP Method | aribaMethod | The HTTP Method for the API |
| Ariba Url Path | aribaUrlPath | The Path (i.e. the endpoint) that is |
| combined with the Base URL to construct the API endpoint | Query Parameters | aribaUrlQuery | The additional Query Parameters that must be amalgamated with the the Common Query parameters defined in the Adapter
Additional Parameters
| Object | Description | Value Dev & Test | Value Test | Value Prod |
|---|---|---|---|---|
| Ariba Base URL | Base URL to Ariba Event Management APIs. | eu.openapi.ariba.com/api/sourcing-event/v2/prod | ||
| Credential Name | OAuth Credential | |||
| Name for Ariba Endpoint in SAP CPI | OAuth_Ariba_Sourcing_SurrogateBiddingAPI | OAuth_Ariba_Sourcing_SurrogateBiddingAPI | OAuth_Ariba_Sourcing_ |
| SurrogateBiddingAPI | ||||
| Ariba API Delay | The Delay to be implemented when the remaining API count is zero | 2 seconds | 2 seconds | 2 seconds |
| Ariba Password Adapter | Password Adapter defined for Technical Users in Ariba | ThirdPartyUser | ThirdPartyUser | ThirdPartyUser |
| Ariba Realm | Ariba tenant ID | 745255310-SS-T | 744368466-T | 744368466 |
| Ariba User | Technical User for SAP CPI to extract events | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN |
| Ariba API Key | Security Credential Name containing the API Key for Ariba Event Management | APIKEY |
...
| _AribaSurrogateBidding_CPI_Dev | APIKEY_AribaSurrogateBidding_CPI_QA | APIKEY_AribaSurrogateBidding_CPI_Prod |
Ariba Master Data API Connector IFlow
Similar to Event Management API Connector, the Ariba Surrogate Bidding AI Master Data API Connector also constructs the URL and the Authentication Parameters based on valued passed values passed from the calling IFlow and configurable parameters in the Connector. The construct is shown below:
Ariba
...
Master Data API for Sourcing URL
Construction of the URL with an example:
| METHOD | https:// | <Ariba Base URL> | <Ariba URL Path> | ? | <Connector Defined Query Parameters> | & | <Received Query Parameters> |
|---|
| GET | https:// | eu.openapi.ariba.com/api/sourcing- |
| mds- |
| search/v1/prod | /entities/ |
| organizations | ? | realm=7452####-SS-T&user |
| =R_XXXXXXXX&passwordAdapter=XXXXXXXXX | $top=500&$filter=(TimeUpdated gt '2026-04-15 17:12:25.000')&$includeInactive=true |
An IFlow calling the Adapter must provide the following Header Parameters to construct the API endpoint to Ariba
...
to construct the API
...
endpoint to Ariba
| Object | Header Name | Description |
|---|
Ariba Master Data API Connector IFlow
Similar to Event Management API Connector, the Ariba Master Data API Connector also constructs the URL and the Authentication Parameters based on valued passed from the calling IFlow and configurable parameters in the Connector. The construct is shown below:
Ariba Surrogate Bidding URL
Construction of the URL with an example:
...
An IFlow calling the Adapter must provide the following Header Parameters to construct the API endpoint to Ariba
...
Additional Parameters
...
| HTTP Method | aribaMethod | The HTTP Method for the API |
| Ariba Url Path | aribaUrlPath | The Path (i.e. the endpoint) that is combined with the Base URL to construct the API endpoint |
| Query Parameters | aribaUrlQuery | The additional Query Parameters that must be combined with the the Common Query parameters defined in the Adapter |
Additional Parameters
| Object | Description | Value Dev & Test | Value Test | Value Prod |
|---|---|---|---|---|
| Ariba Base URL | Base URL to Ariba Event Management APIs. | eu.openapi.ariba.com/api/sourcing-event/v2/prod | ||
| Credential Name | OAuth Credential Name for Ariba Endpoint in SAP CPI | OAuth_Ariba_Sourcing_MasterDataAPI | OAuth_Ariba_Sourcing_MasterDataAPI | OAuth_Ariba_Sourcing_MasterDataAPI |
| Ariba API Delay | The Delay to be implemented when the remaining API count is zero | 2 seconds | 2 seconds | 2 seconds |
| Ariba Password Adapter | Password Adapter defined for Technical Users in Ariba | ThirdPartyUser | ThirdPartyUser | ThirdPartyUser |
| Ariba Realm | Ariba tenant ID | 745255310-SS-T | 744368466-T | 744368466 |
| Ariba User | Technical User for SAP CPI to extract events | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN | R_BTP_ARB_ADMIN |
| Ariba API Key | Security Credential Name containing the API Key for Ariba Event Management | APIKEY_AribaMasterData_CPI_Dev | APIKEY_AribaMasterData_CPI_QA | APIKEY_AribaMasterData_CPI_Prod |
Keelvar Event API Connector IFlow
Keelvar URL
Similarly, the Keelvar Connector constructs the URL based on the values passed from the calling IFlow and configurable parameters in the Connector.
| METHOD | https:// | <Keelvar Base URL> | <Keelvar URL Path> | ? | <Query Parameters> |
|---|---|---|---|---|---|
| GET | https:// | test.keelvar.dev/api | /feeds/awards | ? | sourcing_event=$event_uuid |
An IFlow calling the Keelvar Connector must provide the following Header Parameters to construct the API endpoint to Keelvar
| Object | Header Name | Description |
|---|---|---|
| HTTP Method | keelvarVerb | The HTTP Method for the API |
| Keelvar Url Path | keelvarPath | The Path (i.e. the endpoint) that is combined with the Base URL to construct the API endpoint |
| Query Parameters | keelvarQuery | The Query Parameters |
Additional Parameters
| Object | Description | Value Dev & Test | Value Prod |
|---|---|---|---|
| Keelvar Host | Base URL for Keelvar API | test.keelvar.dev/api | my.keelvar.app/api |
| Keelvar API Key | Security Material in CPI containing the Keelvar API Key | KeelvarToken_Dev | KeelvarToken_Prod |
Keelvar Supplier
...
API Connector IFlow
Keelvar URL
Similarly, the Keelvar Connector constructs the URL based on the values passed from the calling IFlow and configurable parameters in the Connector.
| METHOD | https:// | <Keelvar Base URL> | <Keelvar URL Path> |
|---|
| GET | https:// | test.keelvar.dev/api | / |
| manage/suppliers |
An IFlow calling the Keelvar Connector must providefollowing provide the following Header Parameters to construct the API endpoint to Keelvar
| Object | Header Name | Description |
|---|---|---|
| HTTP Method | keelvarVerb | The HTTP Method for the API |
| Keelvar Url Path | keelvarPath | The Path (i.e. the endpoint) that is amalgamated with combined with the Base URL to construct the API endpoint |
| Query Parameters | keelvarQuery | The Query Parameters |
Additional Parameters
| Object | Description | Value Dev & Test | Value Prod |
|---|---|---|---|
| Keelvar Host | Base URL for Keelvar API | test.keelvar.dev/api | my.keelvar.app/api |
| Keelvar API Key | Security Material in CPI containing the Keelvar API Key | KeelvarToken_Dev | KeelvarToken_Prod |
Error Handling & Retry Strategy
...
| Scenario | Action |
|---|---|
| Retry Limit Reached | Pause for the configured length so that additional API calls are reachedduration until the rate-limits are reset |
| Permanent API Error (HTTP 400/401/404) | Provider IFlow logs the error in MPL and push back to the JMS Queue |
| JMS Retry Exhausted | Gracefully push the message to DLQ for analysis. |
...
For the current solution, based on the number of calls and the schedule, the configurable pause time limit provides adequate support for re-processing of messages. However, if further integrations are added to the package, further design analysis may be required to control the length of the pause
Reprocessing from Dead Letter Queue (DLQ)
At the moment, the DLQ is only used as a placeholder for any messages that have failed the number of retries configured. Currently, no retry from DLQ is enabled, and this solution may be enhanced to provide the ability to reprocess the messages in the DLQ back to the JMS Queue.
...