High-Level Specification
| Application System (Source) | Ariba Guided Sourcing |
|---|---|
| Application System (Target) | Keelvar |
| Source System Interface | Standard webhooks and APIs |
| Target System Interface | Standard APIs |
| Business Process Reference | 03.03.03.01. Manage Sourcing Projects |
Functional Overview
Ariba Guided Sourcing is interfaced with SAP ECC system (PRS) to sync Supplier Master Data. Bidders and Supplier Contacts Master Data is maintained in Ariba Guided Sourcing directly. The Supplier Master Data (including Bidders) along with Supplier Contact information is interfaced with Keelvar as well to allow the Sourcing Specialists the flexibility to invite participants to Keelvar Event. Ariba Supplier ID (System ID) is maintained as External ID in Keelvar ensuring the sync between the two systems. Whenever a supplier or Bidder is deactivated in Ariba Guided Sourcing, the supplier is also archived in Keelvar.
Scope and Objectives
The scope of this Functional Specification is to describe the interface between Ariba and Keelvar for synchronizing Supplier Master Data. When a supplier/bidder is updated in Ariba, the Keelvar record will be updated via the Keelvar API. Similarly, whenever, a supplier/bidder is deactivated in Ariba, the Keelvar supplier record will be archived. Ariba Master Data API for Sourcing will be used to extract the data from Ariba Guided Sourcing. The supplier contact information is also push from Ariba Guided Sourcing to Keelvar. If a supplier is not present in Keelvar, the same will be created via the Event creation from Ariba to Keelvar (ERP-108)
Process Flow Diagram
Step | Description | Comment |
|---|---|---|
1 | Supplier is created or deactivated in Ariba Guided Sourcing based on SAP ECC details using an Integration Event. Alternatively, a Bidder is created/deactivated in Ariba Guided Sourcing by Sourcing Specialist. Supplier Contact can also be updated in Ariba Guided Sourcing. All of these constitute a change in Supplier/Bidder data in Ariba Guided Sourcing. | |
2 | A Scheduled Task picks up the list of all Suppliers or Contacts modified since the last run. Subsequent action depends on the type of change. | |
3 | If the Supplier active flag is false i.e the supplier has been deactivated, SPCPI send a request to Keelvar to archive the supplier records. | |
4 | If the Supplier active flag is true i.e the supplier has been created or updated, SCPI extracts the supplier details and creates a payload for Keelvar Supplier Management API and pushes it to Keelvar. | |
5 | If the Supplier Contacts which have been modified since the last run, SCPI extracts the corresponding supplier details and pushes the supplier contact details along with the contact ID to Keelvar. | |
6 | If the Supplier Contacts which have been deactivated since the last run, SCPI checks Ariba for other active contacts for the said supplier. If no contacts are found, a notification is triggered and the supplier record is archived. Otherwise, the supplier details along with an active contact ID is pushed to Keelvar. | |
7 | Based on the request from SCPI through Keelvar Supplier Management API, Keelvar updates the supplier record. |
Assumptions
- Following three fields have been added to the Supplier object in Keelvar:
| Field Name | Field Type | Required |
|---|---|---|
| Contact Name | Text | Yes |
| Contact Email | Text | Yes |
| Contact ID | Text | Yes |
Dependencies
- Depending on the build of ERP-116 Integration of Suppliers from SAP PRS (ECC) into Ariba
Security, Integrity and Controls
The following are the Security and Authorization considerations for this interface:
- Access to Ariba and Keelvar APIs is limited via a shared secret to secure End Point connection
- Access to API authorization in SAP Ariba Sourcing are being addressed by Ariba standard security controls. Only authorized persons with Ariba administrator’s role can access/ change API OAuth Keys.
- Similarly, access to API authorization in Keelvar are being addressed by Keelvar standard security controls. Only authorized persons with Keelvar Organization User role can access/ change the Keelvar authorization token.
Configuration Requirements
In order to activate the Master Data API for Sourcing, following steps need to be completed:
- Click Create application from the home page.
- Fill out the Create a new application form by entering an application name and description, then click Submit.
- This generates an Application key that identifies your application within the system. Every API request your application makes must include this key as the value of the apiKey parameter.
- Ask your organization admin to request API access for your application by displaying the application in My applications and clicking .
- A user with the Organization Admin role requests approval for API access.
- SAP Ariba assesses the request, and once processed and approved, the Organization Admin user receives email with an OAuth client ID for the application.
- A user with the Organization Admin role generates the OAuth secret and base64-encoded client and secret.
In order to activate Keelvar API, following steps need to be completed:
- Log into Keelvar Portal
- Go to Account settings and navigate to API Keys section
- Click New token button and provide the name and Expiration of the token. Click create to get the token details.
Ariba Guided Sourcing configuration details are described as under:
Supplementary | Test | Production | |
Ariba Technical User | R_BTP_ARB_ADMIN | ||
Ariba Realm ID | 745255310-SS-T | 745255310-T | 745255310 |
OAuth URL | |||
Request URL | https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod | https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod | https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod |
Keelvar configuration is described below:
Special Requirements
Not Applicable
Design Rationale
The Supplier Master Data along with Contact details must be in sync between Ariba Guided Sourcing and Keelvar.
Data Structure
Source Structure
The following fields will be used to provide the required information for this interface:
| Field | Description |
|---|---|
| organization - Name_en | The name of the Supplier Organization |
| organization - SystemID | The ERP vendor ID of the supplier or the Ariba System ID of the Bidder |
| organization - Active | The flag on organization indicating if the Supplier is active or not |
users - Name_en | The name of the Supplier Contact |
users - EmailAddress | The email address of the Supplier Contact |
users - UniqueName | The User ID of the Contact User. One Ariba Supplier can have multiple contacts and contact ID. But ID of any one of the active contacts is maintained in Keelvar at a time. |
users - Active | The flag on user (contact) indicating if the Supplier is active or not |
Target Structure
The following fields will be used to provide the required information for this interface:
| Field | Description |
|---|---|
| name | The name of the Supplier Organization |
| external_id | The ERP vendor ID of the supplier or the Ariba System ID of the Bidder |
| fields/Contact Name | The name of the Supplier Contact |
| fields/Contact Email | The email address of the Supplier Contact |
| fields/Contact ID | The User ID of the Contact User. The Contact ID of the supplier is used to push Surrogate Bid to Ariba which is described in ERP-137 |
| archived | The flag on Keelvar Supplier record indicating if the supplier is archived or not. |
Mapping and Calculation
| API or Portlet Name | Source Field | Required (Y/N) | Description | API or Portlet Name | Target Field | Required (Y/N) | Description | Rule Type | Rule Instruction |
|---|---|---|---|---|---|---|---|---|---|
| Entity Type - organizations | Name_en | Y | The name of the Supplier Organization | /manage/supplier_changes | name | N | The name of the Supplier Organization | Required only if Supplier is to be created/updated | |
| Entity Type - organizations | SystemID | Y | The ERP vendor ID of the supplier or the Ariba System ID of the Bidder | /manage/supplier_changes | external_id | Y | The ERP vendor ID of the supplier or the Ariba System ID of the Bidder | ||
| Entity Type - organizations | Name_en | Y | The name of the Supplier Contact | /manage/supplier_changes | fields/Contact Name | N | The name of the Supplier Contact | Required only if Supplier Contact is to be created/updated | |
| Entity Type - users | EmailAddress | Y | The email address of the Supplier Contact | /manage/supplier_changes | fields/Contact Email | N | The email address of the Supplier Contact | Required only if Supplier Contact is to be created/updated | |
| Entity Type - users | UniqueName | Y | The User ID of the Contact User | /manage/supplier_changes | fields/Contact ID | N | The User ID of the Contact User | Required only if Supplier Contact is to be created/updated | |
| Entity Type - organizations | Active | Y | The flag on organization indicating if the Supplier is active or not | /manage/supplier_changes | archived | N | The flag on organization indicating if the Supplier is active or not | Required if Supplier is to be archived |
Processing Logic
Processing within Source
Ariba Master Data Retrieval API does not provide notification of event changes via Webhook, the integration is triggered via a timer. Hence, for the integration to execute, no processing is required within the Source
Processing within Middleware
Due to rate-limit restrictions in Ariba and Keelvar APIs, a JMS Queue oriented integration pattern is used for the end-to-end synchronisation of Suppliers.
IFlows that use Ariba APIs are queued into a single-threaded processing Router, thereby reprocessing of failed API due to exceeded rate-limits ( i.e. HTTP 429 response ) in Ariba are avoided.
The outbound updates to Keelvar are extremely low and no orchestration is required, therefore the API limit control is not implicitly implemented using a separate Keelvar Connector. However, if under extreme conditions, the rate limits are reached in Keelvar, the failed messages are handled via the JMS Queue.
Sequence Diagram of processing in CPI
Sequence 1: Selection of Organizations and Users
| Description | Comments | |
|---|---|---|
| 1 | Integration Scheduler runs Ariba_to_JMS_InitiateSupplierDataReplication to initiate processing of Supplier Data | There is no transformation logic in this IFlow. However, the ProcessDirect path to the next IFlow is defined in the header field jmsProcessDirectPath. |
| 2 | The IFlow pushes a dummy message into aribaMasterDataQueue | |
| 3 | IFlow JMS_MasterData_Router reads the message from the Queue, | The Router checks whether the message is a Retry of a previously failed message and once the retry count has exceeded pushes them to a Dead Letter Queue |
| 4 | The Router forwards the messages to the iFlow JMS_to_JMS_SelectSupplierDataForProcessing to gather the changed Supplier Organisations and Users from Ariba end point defined in message header | The forwarded path is defined by the header field jmsProcessDirectPath |
| 5 | The processing is initiated by getting the last runtime from a saved Datastore as the start time and current time as the end time | The start and end times from the previous integration is saved in the Datastore. |
| 6 | The IFlow makes a Synchronous call to the Ariba Master Data Connector IFlow Ariba_Master_Data_API_Connector to retrieve Supplier Organisations that have changed - created, updated or archived - in the selected Interval | The filter parameter used in the API is TimeUpdated. The maximum number of records to be selected are defined by Externalised parameter Maximum Suppliers to Process ( default value 100 ). Header fields that are passed to the Connector are:
|
| 7 | The Connector IFlow calls the Ariba Master Data Retrieval API to get Supplier Organisations that have changed - created, updated or archived - in the selected Interval | The Connector IFlow reads OAuth credentials and API Key from Security Material in CPI |
| 8 | If the number of records retrieved is equal to the maximum number, the end time value is updated with the latest date stamp in the retrieved Supplier records | By changing the end time, and then persisting it, the next run of the Integration will then select the remaining changes up to the maximum limit |
| 9 | The IFlow makes a Synchronous call to the Ariba Master Data Connector IFlow Ariba_Master_Data_API_Connector to retrieve Users that have changed - created, updated and archived - in the selected interval | The filter parameter used in the API is the TimeUpdate. The maximum number of records to be selected are defined by the Externalised parameter Maximum Users to Process ( default value 1000 ) Header fields tha are passred to the Connector are:
|
| 10 | The Connector IFlow calls the Ariba Master Data Retrieval API to get Users that have changed - created, updated or archived - in the selected Interval | The maximum user count should be set to a significant higher number. A default value of 1000 is therefore set which is much higher than the number of records expected in a day (15) |
| 11 | Once Organisations and User details are received, the IFlow arranges the payload to wrap Users with Organisation data | The response can contain User records but not the Organisation that the User belongs to. Since the User record also contains the Supplier Id, this is used to arrange Users that belong to the same Organisation. |
| 12 | The payload is split by the Organisation ID, and each record is sent to the JMSQueue for Replication to Keelvar | The ProcessDirect path the IFlow to process the message is again defined by Header field jmsProcessDirectPath. See the Sequence Diagram below for the Replication Process. |
Sequence Diagram 2: Replicate to Keelvar
| Description | Comment | |
|---|---|---|
| 1 | IFlow JMS_MasterData_Router reads message containing Supplier Data | The Router checks if the message is a Retry, and if the Retry Counter is higher than the defined threshold, the message is pushed to the Dead Letter Queue |
| 2 | The Router fowards the message to the ProcessDirect path defined in IFlow JMS_to_Keelvar_ReplicateSupplierData | Header field is defined in jmsProcessDirectPath. |
| 3 | If the Organisation is flagged as Inactive, the IFlow prepares the archive payload and calls the Keelvar Supplier Management API | Same Keelvar Supplier Management API URL path is used in this IFlow. |
| 4 | If the Organisation is Active and if there are no Users associated or at lease one Active User, the IFlow prepares the Create/Update payload with the first Active User details as the Contact and calls the Keelvar Supplier Management API | Same Keelvar Supplier Management API URL path is used in this IFlow. |
| 5 | If the Organisation is Active and and the Payload contains only Inactive Users, the IFlow invokes the Ariba_Master_Data_API_Connector iFlow to get if there are any active Users in the Supplier in Ariba | Header fields that are passed to the Connector are:
|
| 6 | The Ariba Connector IFlow calls the Ariba Master Data Retrieval API to get Active Users defined for the Supplier Organisation | The Connector IFlow reads OAuth credentials and API Key from Security Material in CPI |
| 7 | If any Active Users are found, the IFlow prepares Supplier Update payload with the first Ariba User as the Contact, and calls the Keelvar Supplier Management API | Same Keelvar Supplier Management API URL path is used in this IFlow. |
| 8 | if no Active Users are found, the IFlow prepares the Supplier Update payload with the first Ariba User as the Contact, adds the prefix "Inactive_" to Contact ID, and calls the Keelvar Supplier Management API | In Keelvar, this prefix acts as an indication that the Supplier record's Contact details are deactivated in Ariba Same Keelvar Supplier Management API URL path is used in this IFlow. |
| 9 | The IFlow raises an exception | Notification of this exception should be used as |
Processing within Target
The Supplier details in Keelvar are updated as a background job.
Interface Dependency
Not ApplicableInterface Constraints
Rate Limit for Ariba Event Management API - (Requests): 5/second, 80/minute, 3500/hour
Rate Limit for Keelvar create/update Event API - Burst (120/hour), sustained (500/day)
Rate Limit for Keelvar Job API - Burst (30/min), sustained (600/hour)
Delivery Requirements
Scheduled task in CPI retrieves changes (new, updates and deactivations) ever every 10 minutes.
Delta or Full Load Requirements
All requests for creation and update of sourcing events are done via delta load since last run.
Interface Alert & Monitoring
The following should be monitored:
- API endpoints are available.
- Keelvar token expiration.
- Failures on inbound processing and outbound side need to be handled . Please check the Error Handling section.
- Messages are processed in reasonable time (XX elapse time).
Interface Reporting
Not Applicable
Language Requirements
Not Applicable
User Interface Requirements
Not Applicable
Volumetrics
Initial Load will have large data volume. Expected load for subsequent loads - 25 updates per day
Performance Consideration
Not Applicable
Error Handling
General error handling tips:
- SAP Cloud ALM (CALM) will be used to capture integration execution errors.
- To correct the error, the Ariba Administrator must ensure that the data inconsistency is resolved in the concerned system. Corrections done in Ariba Guided Sourcing will be picked up in the next Schedule Job cycle.
- Refer to this link for details on troubleshooting Error Messages Returned by the Event Management API: Error Messages Returned by the Event Management API
- Refer to this link for details on troubleshooting Error Messages Returned by Keelvar API: Open API specification
This integration has an Exception raised when there are no Active Users are maintained for a Supplier in Ariba - a rectification that needs to be done in Ariba. Once the Exception is raised
- Identify the Supplier ID from the Message Log in CPI
- Delete the message from JMS Queue
- Update the Supplier details in Ariba
Testing
How to Test
- Create/update a new Bidder and Bidder Contact in Ariba
- Deactivate a new Bidder and/or Bidder Contact in Ariba
Test Conditions and Expected Results
| ID | Condition | Expected Results |
|---|---|---|
| 1 | Create a new Bidder in Ariba | A Supplier record should be created in Keelvar |
| 2 | Update the Bidder name, Contact Name or Email Address | The Supplier record should be updated in Keelvar |
| 3 | Deactivate a Bidder in Ariba | The Supplier record should be archived in Keelvar |
| 4 | Choose a supplier/bidder in Ariba with two contacts. Deactivate a contact for which the contact ID is not maintained in Keelvar | The Supplier record should be updated with the Contact ID of the second contact |
| 5 | Deactivate all contacts for a supplier/bidder | The supplier record should be archived and the contact ID should be prefixed with the word Inactive |
Test Considerations/Dependencies
Not Applicable
Other Information
Development Details
Package
| Package Name | Parent Package |
|---|---|
| Ariba to Keelvar - Master Data Integration | N/A |
Other Objects
| Object Type | Object Name | Configuration Parameters | Comment | |||
|---|---|---|---|---|---|---|
| Name | Value - Development | Value - Test | Value - Production | |||
| IFlow | Ariba_Master_Data_API_Connector | Ariba Base URL | eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod | Configurable base URL for Master Data Retrieval API | ||
| Credential Name | OAuth_Ariba_Sourcing_MasterDataAPI | OAuth Credential for the Application created for Supplier Integration | ||||
| Ariba API Delay | 2 | Pause interval Rate-limit is reached | ||||
| Ariba Realm | 745255310-SS-T | Ariba Tenant Identifier | ||||
| Ariba API Key | APIKEY_AribaMasterData_CPI_Dev | API Key for the Application created for Supplier Integration | ||||
| IFlow | JMS_MasterData_Router | Queue Name | aribaMasterDataQueue | Main Processing JMS Queue Name | ||
| Maximum Retries Allowed | 5 | Maximum retries before moving to DLQ | ||||
| Dead Letter Queue | DLQ_aribaMasterDataQueue | Dead Letter Queue name | ||||
| IFlow | Ariba_to_JMS_InitiateSupplierDataReplication | Receiver IFlow Process Direct Path | /supplier-trigger | Path to the downstream IFlow that extracts changed data | ||
| Queue Name | aribaMasterDataQueue | Main Processing JMS Queue Name | ||||
| IFlow | JMS_to_JMS_SelectSupplierDataForProcessing | Data Store Name | Sourcing_Runtime_Collection | Data store containing the runtimes | ||
| Last Runtime Entry Name | Supplier_LastRun_Timeslice | Data Store entry for Master Data Integration Runtimes | ||||
| Queue Name | aribaMasterDataQueue | Main processing JMS Queue | ||||
| Ariba Master Data Connector ProcessDirect | /ariba/masterData/connector | Path to Ariba Master Data Connector IFlow | ||||
| Receiver ProcessDirect Path | /keelvar/supplier/update | Path the IFlow that updates Keelvar Suppliers | ||||
| Maximum Suppliers to Process | 100 | The maximum number of new and changed Suppliers to be selected per API | ||||
Maximum Users to Process | 1000 | The maximum number of new and changed Users to be selected per API | ||||
| Initial Starting DateTime | Example: 2025-10-29 05:47:02.402 | The datetime stamp for the initial run. This value will be used as the Last Runtime | ||||
| Time Zone Adjustments | -7:00 | The time difference between CPI and Ariba tenants. | ||||
| IFlow | JMS_to_Keelvar_ReplicateSupplierData | Ariba Master Data Connector Path | /ariba/masterData/connector | Path to Ariba Master Data Connector IFlow | ||
| Keelvar API Base Url | test.keelvar.dev/api | my.keelvar.dev/api | Keelvar Supplier Management API Base URL | |||
| Keelvar API Key Security Material | KeelvarToken | Security Material for the Keelvar API Key | ||||
Appendix
API Examples
| IFlow | Curl | Sample Payloads | |
|---|---|---|---|
| 1 | JMS_to_JMS_SelectSupplierDataForProcessing | curl --location 'https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod/entities/organizations?%24filter=((TimeUpdated%20gt%20dateTime))&%24includeInactive=true' \ --header 'Accept-Language: en' \ --header 'X-Realm: ARIBA_REALM_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ARIBA_TOKEN' \ --header 'apiKey: ARIBA_API_KEY' | N/A |
| 2 | curl --location 'https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod/entities/users?%24filter=(PasswordAdapter%20eq%20%27SourcingSupplierUser%27%20and%2TimeUpdated%20gt%20dateTime) \ --header 'Accept-Language: en' \ --header 'X-Realm: ARIBA_REALM_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 2ARIBA_TOKEN' \ --header 'apiKey: ARIBA_API_KEY' | N/A | |
| 3 | curl --location 'https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod/entities/users?%24filter=((PasswordAdapter%20eq%20%27SourcingSupplierUser%27%20andTimeUpdated%20gt%20dateTime))&%24includeInactive=true' \ --header 'Accept-Language: en' \ --header 'X-Realm: ARIBA_REALM_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ARIBA_TOKEN' \ --header 'apiKey: ARIBA_API_KEY' | N/A | |
| 4 | JMS_to_Keelvar_ReplicateSupplierData | curl --location 'https://test.keelvar.dev/api/manage/supplier_changes' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw 'PAYLOAD_CREATED_AS_ABOVE_JSON'; | |
| 5 | curl --location 'https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod/entities/users?%24filter=((PasswordAdapter%20eq%20%27SourcingSupplierUser%27%20andOrganization.SystemID%20eq%20%27<SystemID>%27))' \ --header 'Accept-Language: en' \ --header 'X-Realm: ARIBA_REALM_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ARIBA_TOKEN' \ --header 'apiKey: ARIBA_API_KEY' | N/A |