High- Level Specification
| Parameter | Value |
|---|---|
| Application System (Source) | Ariba Guided Sourcing |
| Application System ( Target) | Keelvar |
| 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. Whenever a supplier/bidder is created in Ariba Guided Sourcing, the supplier will be pushed to Keelvar using Keelvar Supplier Management 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.
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 implemented at Keelvar end. However, if under extreme conditions, the rate limits are reached in Keelvar, the failed messages are handled via the JMS Queue.
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
Following scheduled tasks should be configured to run every 10 minutes:
- Scheduled Task to retrieve changes to all Supplier created or updated since the last run.
- Scheduled Task to retrieve changes to all Supplier Users deactivated since the last run.
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
- 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 the link below to troubleshoot Error Messages Returned by the Event Management API.
Error Messages Returned by the Event Management API
- Refer to the Link below to troubleshoot Error Message Returned by Keelvar API
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 |