High- Level Specification

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

Assumptions

• Following three fields have been added to the Supplier object in Keelvar:

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:

1. Sign in to the SAP Ariba Developer Portal.
2. Click Create application from the home page.
3. Fill out the Create a new application form by entering an application name and description, then click Submit.
4. 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.
5. Ask your organization admin to request API access for your application by displaying the application in My applications and clicking Actions  Ask your admin to request API access.
6. A user with the Organization Admin role requests approval for API access.
7. SAP Ariba assesses the request, and once processed and approved, the Organization Admin user receives email with an OAuth client ID for the application.
8. 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:

1. Log into Keelvar Portal
2. Go to Account settings and navigate to API Keys section
3. 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:

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:

Target Structure

The following fields will be used to provide the required information for this interface:

Mapping and Calculation

Populate the table below to list the target / source data field mapping between the Source system and Target system

Processing Logic

Processing within Source

Not Applicable 

Processing within Middleware

Supplier Creation or Update

A Scheduled Task in SCPI should run and extract all supplier updated in Ariba since the last run as under:

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'

For the each supplier record retrieved, the logic is as under:

• If 'Active= true' the extracted Supplier has to be pushed to Keelvar as under:

Create a request payload to Keelvar as under:

Sample JSON for the payload is available here -

Then, a request to Manage Supplier Change request should be made as under:

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';

• If 'Active= false' the Keelvar supplier record must be archived. In order to archive a supplier records in Keelvar, a payload should be created with the Organization ID as under:

Sample JSON for the payload is available here -

Then, a request to Manage Supplier Change request should be made as under to archive the Keelvar Supplier record:

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';

Supplier Contact Creation or Update

SCPI should extract all supplier users updated in Ariba since the last run as under:

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'

Create a request payload to Keelvar as under:

The supplier contact should be add to the payload only if  there are no active contact.

Sample JSON for the payload (without contact) is available here -

Sample JSON for the payload (with contact) is available here -

Then, a request to Manage Supplier Change request should be made as under:

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';

Contact User Deletion

A Scheduled Task in SCPI should run and extract all contacts which have been deactivated in Ariba since the last run as under:

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'

For each of the supplier user records retrieved, the logic is as under:

• Check if there are any active Supplier User available for that Supplier as under:

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'

The Active Flag on the user object can be used to ensure the user is active

If there is an existing active user, the first user object available in the response payload along with the System ID should be used to create a request payload to Keelvar as under:

Sample JSON for the payload is available here -

Then, a request to Manage Supplier Change request should be made as under:

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';

• If there are no active Supplier Users for the said supplier, following should be done:

1. Trigger a notification via CALM that we have a supplier/bidder with no contacts
2. Archive the Keelvar vendor as described above
3. The integration scenario should fail
4. In Keelvar supplier record, field/Contact ID should be prefixed with the work inactive (inactive_Contact ID). In order to do that a payload must be created for the supplier using the field mapping described. 

Sample JSON for the payload is available here -

Then, a request to Manage Supplier Change request should be made as under:

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';

Processing within Target

Not Applicable

Interface Dependency

•  This schedule of this interface should always be aligned with the schedule of ERP-116 Integration of Suppliers from SAP PRS (ECC) into Ariba. ERP - 116 is scheduled in SAP ERP to push Supplier Data to Ariba Guided Sourcing. The Batch job schedule should be taking into consideration while scheduling this interface.

Interface 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:

1. Scheduled Task to retrieve changes to all Supplier created or updated since the last run.
2. 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

Open API specification

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

Test Considerations/Dependencies

Not Applicable

Other Information

Development Details

Package

Other Development Objects

Appendix

See also

Insert links and references to other documents which are relevant when trying to understand this decision and its implications. Other decisions are often impacted, so it's good to list them here with links. Attachments are also possible but dangerous as they are static documents and not updated by their authors.

Change log