High- Level Specification

Functional Overview

Ariba Guided Sourcing is used as the single entry point for all Sourcing Events. If the users can select the Keelvar template to create an Event in Ariba Guided Sourcing, the details of the Event are replicated to Keelvar and any change in Keelvar reflects the status of the Event in Ariba Guided Sourcing. When the user awards one or multiple Bidders or Suppliers in Keelvar, the awarded Bid(s) and Keelvar Bid Sheet must be sent back to Ariba Guided Sourcing.

Scope and Objectives

The scope of this Functional Specification is to describe the interface between Keelvar and Ariba Guided Sourcing. When an award scenario and awarded bid sheet(s) are created in Keelvar and the event is closed in Keelvar, a Webhook in Keelvar will notify SCPI about the award. After that, SCPI will send the award scenario and awarded bid sheet(s) back to the event in Ariba Guided Sourcing. If any new Bidder is added in Keelvar, the new Bidder and Bidder Contact must also be created in Ariba Guided Sourcing.

Process Flow Diagram

Assumptions

• When the event status changes to CLOSED in Keelvar, the same is notified in SCPI via Webhook API
• The users must not reopen the event after they have awarded the Event in Ariba Guided Sourcing. Otherwise, the new award cannot be linked to Ariba Guided Sourcing.
• Ariba APIs use Pacific Standard Time zone as the default time zone for all concerned APIs.

Dependencies

• Depending on the build of ERP-224 Supplier Data Synchronization from Ariba to Keelvar. This integration synchronises Supplier details between Ariba and Keelvar.
• Depending on the build of ERP-108 Integration Process - Sourcing event Creation and Update from Ariba Sourcing to Keelvar. This integration replicates Events created in Ariba into Keelvar, and initiates the creation process for Suppliers that are attached to the Event, if they do not exist in Keelvar
• Depending on the build of ERP-138 Event Status Update Interface between Keelvar and Ariba. This integration updates the Status of the Event in Ariba during the Awarding process progresses in Keelvar.

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 SAP Ariba API for Event Management, 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:

A webhook for Sourcing Event Feed must be created in Keelvar to receive of the following changes in Sourcing Event:

• The event is closed after all bidding rounds have been completed

A request must be sent to support@keelvar.com and make a whitelist request for the domain of the SCPI system to which the HTTP notifications will be sent.

Creation of Webhook in Keelvar for Sourcing Event Feed requires sending a request as under:

curl -X POST https://my.keelvar.app/api/webhooks \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -d '{
          "name": "Sourcing Event Feed Webhook",
          "description": "Keelvar Sourcing Event Feed Webhook",
          "signing_alg": "HMAC_SHA256",
          "signing_key": "(Signing Key)",
          "triggers": "[SOURCING_EVENTS_FEED_UPDATED]",
          "url": (SCPI webhook listener URL),
        }'

Keelvar will send the response with the Webhook UUID as under:

'description': 'Keelvar Sourcing Event Feed Webhook',
'name':        'Sourcing Event Feed Webhook',
'signing_alg': 'HMAC_SHA256',
'signing_key': '(Signing Key)',
'triggers':    '[SOURCING_EVENTS_FEED_UPDATED]',
'url':         (SCPI webhook listener URL),
'uuid':        '4a55a230-307b-4bab-ac53-e95186b88968'

Special Requirements

Not applicable

Design Rationale

Since Sourcing Events are originally initiated in SAP Ariba Guided Sourcing and integrated to Keelvar, when the award scenario is completed and awarded bid sheet are created in Keelvar, they must be sent back in SAP Ariba Guided Sourcing. To create the Award Scenario in Ariba, SAP CPI implements an orchestration consisting of multiple API calls, mapping and validation using two APIs in Ariba and one in Keelvar. Since Event Management Service is one of the Ariba APIs used, this orchestration utilises the JMS Queue Framework used in ERP-108 and ERP-138. 

The Orchestration consists of 3 main activities:

The following Flow Diagrams shows the integration steps that are executed to complete the Award through the above 3 steps.

IFlow to Get Keelvar Award Data

IFlow to Generate Bid Sheets

IFlow to Create Award Scenario

API use

Ariba API Specifications

Creation of API Applications in Ariba API is executed in the EU tenant. Ariba events are timestamped on Pacific Standard Time (PST), therefore time stamps selected 

SAP Ariba APIs Portal (Logon Required)

Data Structures

Event Status Update Mapping

Source Structure

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

Target Structure

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

Mapping and Calculation

The following Mapping Table is used to update the status of the Ariba Event. The Ariba Event Management API is used for all requests:

The following Mapping Table is used to add a new supplier invitation (new bidder) to the Ariba Event. The Ariba Event Management API is used for all requests:

The following Mapping Table is applicable to add Keelvar Bid Sheet Item to Ariba Guided Sourcing Event. The Ariba Event Management API is used for all requests:

The following Mapping Table is applicable to trigger a Job required to send a Surrogate Bid to Ariba Guided Sourcing Event. The Surrogate Bidding API is used for all requests:

The following Mapping Table is applicable to get the status of the Job required to send a Surrogate Bid to Ariba Guided Sourcing Event. The Ariba Event Management API is used for all requests:

The following Mapping Table is applicable to export the Surrogate Bid response file:

The following Mapping Table is applicable to create a manual Award Scenario in Ariba Guided Sourcing Event. The Ariba Event Management API is used for all requests:

Processing Logic

Processing within Source

A webhook should be triggered to complete Event closure activities which are described as under:

1. Unlock the Ariba Event. Set the status to draft (EDIT operation) to add the Keelvar Bid Sheet Item
2. Add the Supplier Invitation to the Ariba Event (if applicable)
3. Add Keelvar Bid Sheet to the Ariba Event
4. Set the status to publish  and reopen the event when the Bid Sheet Item have been added to the event
5. Submit the surrogate Bid(s)
6. Set the status to Pending Selection (STOP operation) once the Surrogate Bid has been submitted
7. Create award scenario in Ariba Guided Sourcing

Processing within Middleware

Trigger for Sourcing Event Feed Webhook in Keelvar

Once webhook is triggered in Keelvar, the SCPI should receive a notification as under:

{"trigger": "AWARD_FEED_UPDATED",
"timestamp": "2024-11-04T11:13:56.619494Z",
"payload": {
  "sourcing_event": "19e44441-81c1-11f0-b2f5-f884135dd221",
  "status": "CLOSED",
  "name": "My Event",
  "sourcing_requests": ["c819a007-bac7-4172-eb1d-272a9933f1a2"],
  "tags":[
    {
      "name": "Commodity",
      "value": "0005 OFFICE FURNITURE"
    },
    {
      "name": "GBU",
      "value": "TS & MATERIALS"
    },
    {
       "name": "Ariba Event ID",
       "value": "Doc123456789"
       }
  ]
}}

Then, a request has to be made to Keelvar to fetch Sourcing Event Details using the Sourcing Event UUID from the above notification as under:

curl --location 'https://test.keelvar.dev/api/feeds/sourcing-events?id= request UUID from above>' \
--header 'Authorization: Bearer YOUR_API_TOKEN';

The response from Keelvar should contain the Sourcing Event Details which will be used as source in the subsequent process.

Sample JSON for Payload is available here:

Edit Event Status in Ariba Guided Sourcing

SCPI must create a payload based on the Mapping Table above to update the status of the Ariba Guided Sourcing Event.

Sample JSON for Payload is available here:

Unlock -

Edit - 

Publish -

Stop -

Reopen -

 Then, a sample request to update the Job Status in Ariba Guided Sourcing is as below:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event/v2/prod//jobs?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apiKey: <API KEPY>' \
--header 'Authorization: Bearer ARIBA_TOKEN' \
--data 'based on JSON above'

Add Supplier Invitation to Event in Ariba Guided Sourcing

SCPI must create a payload based on the Mapping Table above to add the Supplier Invitation to the Ariba Guided Sourcing Event. This needs to be done only if the Bidder has been added to the Keelvar Event directly in Keelvar.

Sample JSON for Payload is available here:

Then, a sample request to add the supplier Invitation in Ariba Guided Sourcing is as below:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event/v2/prod/events/$eventID/items/supplierInvitations?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apiKey: <API KEPY>' \
--header 'Authorization: Bearer ARIBA_TOKEN' \
--data 'based on JSON above'

Add Keelvar Bid Sheet to Event in Ariba Guided Sourcing

SCPI must create a payload based on the Mapping Table above to add the Bid Sheet Item to the Ariba Guided Sourcing Event.

Sample JSON for Payload is available here:

Then, a request to add Bid Sheet Item to Ariba Guided Sourcing must be made as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event/v2/prod//events/Doc2698789795/items?showTotal=true&inheritTerms=false&inheritCommodityAndRegion=true&removeEmptyOwnerTerms=false&realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \

--header 'apiKey: ARIBA_API_KEY';

--header 'Authorization: Bearer ARIBA_TOKEN';
--data ' As per Payload above'

Download the Keelvar Bid Sheet and Convert it into csv file

A request is made to retrieve Award feed from Keelvar for the Sourcing Event from the Webhook Trigger Notification as under:

curl --location 'https://test.keelvar.dev/api/feeds/awards?sourcing_event=$event_uuid' \
--header 'Authorization: Bearer Bearer API_TOKEN';

The response from Keelvar is similar to this:

This response must be converted into a csv file. For each object in the award feed a row-entry should be added in the csv file. The CSV file should have following columns:

1. Awarded Supplier (The award feed contains only the UUID of the supplier. The external _id (Ariba ID) of the supplier should be retrieved from Sourcing Event feed response using the Supplier UUID)
2. share_awarded
3. Each column under the bid_sheet_values object

Calculation for multiple lots awarded to a Supplier

In the event of a split award, the split percentage is calculated per awarded supplier. The split percentage is the percentage amount of the cumulative award value per supplier divided by total award amount.

Submit a Surrogate Bid to the Event in Ariba Guided Sourcing

Surrogate Bids must be submitted for each of the Bidders that have been awarded in Keelver. The processing of a Surrogate Bid to Ariba is described below. The Ariba Event ID is needed for each of the following steps:

1. An Export Job must be created in Ariba to export the Bid response sheet. Ariba send the Export Job ID as the response
2. Check the status of the Export Job. Ariba sends the status of the Export Job ID as well as the File ID as the response
3. If the Job is completed, send a request to Download the Bid response sheet. This request requires the Export Job ID as well as File ID as a part of the request parameter. Ariba sends a Base 64 encoded file as response.
4. An Import Job must be created in Ariba to import the Bid response sheet. The above downloaded file must be added in the body of the request. Ariba sends the Import Job ID as the response.
5. Check the status of the Import Job. 
6. If the Job is completed, send a request to Add attachment to the Event Item. Send the Keelvar Bid Sheet which has been converted into a csv file as a part of the body of this request. Ariba sends the Add Attachment Job ID as the response.
7. Check the status of the Add AddAttachment Job
8. If the Job is completed, send a request to submit the Surrogate Bid. Ariba will send the Submit Job ID as response.
9. Check the status of the Submit Job.

 #1

The request for Export, Import, Add Attachment and Submit Jobs must be sent in a form format. The form details for each of the above steps are provided here:

The request for Jobs to be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';
--form 'form Data as described above';

In response, Ariba sends back the Id of the Job.

#2

The request for Job status can be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs/$jobId?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

 In response, Ariba send back the Id of the Job. It also includes the FileId if the operation of the Job request was Export.

#3

The request to download the Ariba Bid response sheet can be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs/$jobId/files/$fileId?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

#4

The request to Import Ariba Bid Response Sheet  must be sent in a form format. The form details for each of the above steps are provided here:

The request for Jobs to be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';
--form 'form Data as described above';

#5

The request for Job status can be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs/$jobId?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

 In response, Ariba send back the status of the Job. If the Import is successful, move on to the next step.

#6

The request to Add Attachment (Keelvar Bid Sheet) to Ariba Bid must be sent in a form format. The form details for each of the above steps are provided here:

The request for Jobs to be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';
--form 'form Data as described above';

In response, Ariba sends back the Id of the Job.

#7

The request for Job status can be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs/$jobId?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

 In response, Ariba send back the status of the Job. If the Import is successful, move on to the next step.

#8

The request to Submit Bid must be sent in a form format. The form details for each of the above steps are provided here:

The request for Jobs to be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';
--form 'form Data as described above';

In response, Ariba sends back the Id of the Job.

#9

The request for Job status can be sent as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/jobs/$jobId?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

 In response, Ariba send back the status of the Job. If the status is successful, the surrogate bid has been submitted

Create award scenario in Ariba Guided Sourcing

Then, the payload for Award Scenario creation must be done based on the Mapping Table above. The payload should be similar to this one:

In order to create an award scenario, a request must be sent to Ariba Event Management API as under:

curl --location 'https://eu.openapi.ariba.com/api/sourcing-event-bid/v1/prod/events/$eventId/scenarios?realm=$realmId&user=$aribaTechnicalUser&passwordAdapter=ThirdPartyUser' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';
--data 'as per payload described above';

Logic for calculation of winning split value

CPI will iterate through each and every lot which is awarded and group them by awarded suppliers

Winning split value per Supplier = Total award cost per supplier (Sum of cost of all the awarded lots)/(Total award cost) *100

Processing within Target

Not Applicable

Interface Dependency

• Depending on the build of ERP-108 Integration Process - Sourcing event Creation and Update from Ariba Sourcing to Keelvar
• Depending on the build of ERP-138 Event Status Update Interface between Keelvar and Ariba

Interface Constraints

Rate Limit for Ariba Surrogate Bid API - No specific API limits in place for this API but dynamic run time throttling is in effect.

Rate Limit for Ariba Event Management API - (Requests): 5/second, 80/minute, 3500/hour

Rate Limit for Keelvar api/feeds/awards - Burst (60/min), sustained (43,200/day)

Rate Limit for Keelvar api/feeds/sourcing-events - Burst (60/min), sustained (43,200/day)

Delivery Requirements

Not Applicable

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

10 events per day

Performance Consideration

Not Applicable

Error Handling

• SAP Cloud ALM (CALM) will be used to capture integration execution errors. 
• To correct the errors, the administrator must ensure that the data inconsistency is resolved in the concerned system and then must resend the request again to the target system.
• 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 and select Award Scenario in Keelvar
• Close event in Keelva

Test Conditions and Expected Results

Test Considerations/Dependencies

• Depends on the test condition of ERP - 108 Sourcing event creation and update integrated between Ariba and Keelvar
• Depends on the test condition of ERP - 137 Award Bid integrated from Keelvar to Ariba

Other Information

Not Applicable

Development Details

Package

Other Objects

Appendix

See also

Change log