High- Level Specification

Functional Overview

Ariba Guided Sourcing is used as the single entry point for all Sourcing Events. If the users can select 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

Dependencies

• Depending on the build of ERP-108 Sourcing event creation and update integrated between Ariba and Keelvar
• Depending on the build of ERP-138 Event Status Update Interface between Keelvar and 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 person 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 person with Keelvar Organization User role can access/ change 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 in 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 event is originally initiated in SAP Ariba Guided Sourcing and integrated to Keelvar, when award scenario and awarded bid sheet are created in Keelvar, they must be automatically sent back in SAP Ariba Guided Sourcing.

API use

Creation of API Applications in Ariba API is executed in EU tenant.

SAP Ariba APIs Portal

Data Structure

Source Structure

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

Target Structure

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

Mapping and Calculation

The following Mapping Table is applicable to add Keelvar Bid Sheet Item to Ariba Guided Sourcing Event:

The following Mapping Table is applicable to trigger a Job required to send a Surrogate Bid to Ariba Guided Sourcing Event:

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

Processing Logic

Processing within Source

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

1. Create a New Bidder and Bidder contact (applicable only if a new bidder is awarded) - Part of this interface
2. Set the status to draft (EDIT operation) to add the Keelvar Bid Sheet Item and New Bidder (applicable only if a new bidder is awarded) - Described in Event Status Update Interface
3. Add Keelvar Bid Sheet and New Bidder (if only applicable) to the Ariba Event - Part of this interface
4. Set the status to publish when the Bid Sheet Item and New Bidder (if only applicable) have been added to the event - Described in Event Status Update Interface
5. Submit the surrogate Bid(s). - Part of this interface
6. Set the status to Pending Selection (STOP operation) once the Surrogate Bid has been submitted - Described in Event Status Update Interface
7. Create award scenario in Ariba Guided Sourcing. - Part of this interface

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": "SOURCING_EVENTS_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' \
--header 'Authorization: Bearer YOUR_API_TOKEN';

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

Sample JSON for Payload is available here:

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:

Theis 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. Lot Name
2. Awarded Supplier (The award feed contain 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)
3. share_awarded
4. Each column under the bid_sheet_values object (except the Lot Name)

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 a Surrogate Bid to Ariba is described as under. The Ariba Event ID is need for each of the following steps:

1. An Export Job must be made 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 requries the Export Job ID as well as File ID as a part of request parameter. Ariba send 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 send 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 send 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.

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 send back the Id of the Job.

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 'Content-Type: multipart/form-data' \
--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.

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 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'apiKey: ARIBA_API_KEY';
--header 'Authorization: Bearer ARIBA_TOKEN';

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

Processing within Target

Not Applicable

Interface Dependency

Please describe any dependency to other interfaces, e.g. messages of interface x need to be processed before message processing of interface y can start.

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 event is 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

Pagination can be done while retrieving Award Feed and Event Feed from Keelvar.

Performance Consideration

Not Applicable

Error Handling

• Configure email notification alerts on the SCPI to receive notification when an error occurs. This enables the administrator to log in to the SCPI to check the details of the errors.
• To correct the error, 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 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