Developing an Application to Submit a Surrogate Bid
This procedure describes how to use the Surrogate Bid API to submit bids on behalf of participants.
Prerequisites
-
To create an application and request access to use the SAP Ariba APIs relevant to this feature, you must have access to the SAP Ariba Developer Portal. For details refer to Steps to Start Using the SAP Ariba APIs in Help for the SAP Ariba Developer Portal.
-
All queries made to this API must be authenticated using OAuth authentication. For details refer to SAP Ariba Developer Portal Authentication in Help for the SAP Ariba Developer Portal.
Context
Procedure
- Obtain the following information:
-
ID of the event for which the bid will be submitted (as shown next to the event name in the user interface), such as Doc12345.
-
ID of a buyer user authorized to submit a surrogate bid for the event (as entered in the User Name field on the SAP Ariba sign in page). The web service will submit the surrogate bid as this user.
-
ID (user ID) of the participant (supplier) for whom the surrogate bid will be submitted. This participant must be invited to the event and for the items that the responses will be submitted for.
To find the user ID of a participant, a member of at least one of the following groups can view participant user information by clicking
Supplier and Customer Manager
Users
from the Ariba Administrator page:
- Category Manager
- Commodity Manager
- Event Administrator
- Limited Event Administrator
- Sourcing Project Administrator
- Supplier/Customer Agent
- Supplier/Customer Agent
- Supplier/Customer Manager
- Supplier Project Administrator
-
- Create an export job to generate a bid response sheet for the event.
Use the Sourcing Surrogate Bid API jobs endpoint to post a request that creates an export job:
POST {{runtime_URL}}/jobs?user=user&passwordAdapter=passwordAdapter&realm=realmConsumes: multipart/form-data.
Produces: application/json.
Body:{ "operation": "export", "eventId": "eventId", "supplierId": "user" }Query String Parameters (Used in All Queries for This API) Query String Parameter
Description
user
User ID of the enterprise (buyer) who will submit the surrogate bid. This user must be authorized to submit a surrogate bid for the event.
passwordAdapter
Password adapter used to authenticate the enterprise user, such as PasswordAdapter1.
realm
Your site name.
Request Body Parameters Name
Required/Optional
Type
Description
operation
Required
string
The operation for which to create the job.
Valid values for bid response sheets:-
export: Create a job to generate a bid response sheet. When the job completes successfully, you can download the bid response sheet using the /jobs/{jobId}/files/{fileId} endpoint.
-
import: Create a job to import (upload) a bid response sheet.
Valid values for attachments:-
add_attachment_response: Create a job to upload and submit an attachment on behalf of a participant as a response to a question or a term in a line item.
-
delete_attachment_response: Create a job to delete an attachment from a participant's response. You can use this operation for an attachment that was submitted via the interactive user interface or this API.
-
download_attachment_response: Create a job to get an attachment from a participant's response. You can use this operation for an attachment that was submitted via the interactive user interface or this API.
When the job completes successfully, you can download the attachment using the /jobs/{jobId}/files/{fileId} endpoint.
-
replace_attachment_response: Create a job to replace an attachment in a participant's response. You can use this operation for an attachment that was submitted via the interactive user interface or this API.
Valid value for bid response sheet and attachments:-
submit: Create a job to submit a previously uploaded bid response sheet and attachments.
eventId
Required
string
ID of the event, such as Doc12345.
supplierId
Required
string
User ID of the participant (supplier) for whom the bids will be submitted.
useBuyerLocale
Optional
Boolean
Use this parameter to configure the buyer's locale for the bid response sheet.
Valid values for the export and import operations are:-
true: Enables you to export and import the bid response sheet in either the buyer's or the supplier's locale by using the Surrogate Bid API.
-
false: Disables the capability to export and import the bid response sheet in either the buyer's or the supplier's locale by using the Surrogate Bid API.
file
Optional
file with "x-mimetype": "application/vnd.ms-excel
This parameter is needed for import, add_attachment_response and replace_attachment_response operations; omit it for all other operations.
The bid response sheet to import.
itemNumber
Optional
string
This parameter is needed for add_attachment_response, delete_attachment_response, download_attachment_response, and replace_attachment_response operations; omit it for all other operations.
The number identifying the question or line item for the attachment. The value must match an entry in the Number column of the bid response sheet.
termName
Optional
string
This parameter is needed for add_attachment_response, delete_attachment_response, download_attachment_response, and replace_attachment_response operations when itemNumber refers to a line item; omit it for all other operations and when itemNumber refers to a question.
The name identifying the term in the line item for the attachment. The value must match the name for a term as specified in the first row of the bid response sheet.
Response Fields Field
Type
Description
operation
string
Type of operation for the job. Possible values:
-
ADD_ATTACHMENT_RESPONSE
-
DELETE_ATTACHMENT_RESPONSE
-
DOWNLOAD_ATTACHMENT_RESPONSE
-
EXPORT
-
IMPORT
-
REPLACE_ATTACHMENT_RESPONSE
-
SUBMIT
jobId
string
ID of the job created.
submittedBy
string
Enterprise (buyer) user who will submit the surrogate bid.
submittedFor
string
Participant (supplier) user for whom the surrogate bid will be submitted.
Retain the value of the jobId; you will need it to check the status of the job and to download the bid response sheet.
Request example:
POST {{runtime_URL}}/jobs?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=mySiteBody:
{ "operation": "EXPORT", "eventId": "Doc6841882", "supplierId": "aSupplier" }Response example:
{ "operation": "EXPORT", "jobId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213", "submittedBy": "aBuyer", "submittedFor": "aSupplier" } -
- Retrieve the status of the export job to determine if the job completed successfully and the bid response sheet is available for you to download.
Use the Sourcing Surrogate Bid API /jobs/{jobId} endpoint to retrieve the status of the export job:
GET {{runtime_URL}}/jobs/{jobId}?user=user&passwordAdapter=passwordAdapter&realm=realmProduces: application/json.
Consumes: multipart/form-data.
Path Parameters Path Parameter
Description
jobId
ID of the job for which you want status.
Response Fields Field
Type
Description
jobId
string
ID of the job.
operation
string
Type of operation for the job. Possible values:
-
ADD_ATTACHMENT_RESPONSE
-
DELETE_ATTACHMENT_RESPONSE
-
DOWNLOAD_ATTACHMENT_RESPONSE
-
EXPORT
-
IMPORT
-
REPLACE_ATTACHMENT_RESPONSE
-
SUBMIT
jobStatus
string
Job status. Possible values:
-
New
-
Pending
-
Success
-
Failure
-
Fatal
submittedBy
string
Enterprise (buyer) user who will submit the surrogate bid.
submittedFor
string
Participant (supplier) user for whom the surrogate bid will be submitted.
fileId
string
ID of the bid response sheet for the operation.
messages
string
Description or additional information for the job status.
Retain the value of the fileId field; you will need it to download the bid response sheet.
If jobStatus is New or Pending, repeat this step until the status is Success, Failure, or Fatal. If the status is Success, continue to the next step. If the status is Failure or Fatal, examine the messages for more information.
Request example:
GET {{runtime_URL}}/jobs/Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=mySiteResponse example:
{ "jobId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213", "operation": "EXPORT", "jobStatus": "Success", "submittedBy": "aBuyer", "submittedFor": "aSupplier", "fileId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213", "messages": [ "Successfully completed export job." ] } -
- Download the bid response sheet.
When the jobStatus from step 3 is Success, use the Sourcing Surrogate Bid API /jobs/{jobId}/files/{fileId} endpoint to download the bid response sheet.
GET {{runtime_URL}}/jobs/{jobId}/files/{fileId}?user=user&passwordAdapter=passwordAdapter&realm=realmConsumes: multipart/form-data.
Produces: application/octet-stream.
Path Parameters Path Parameter
Description
jobId
ID of the job used to export the bid response sheet.
fileId
ID of the bid response sheet, as returned in the response for step 3.
Request example:
GET {{runtime_URL}}/jobs/Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213/files/Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=myreal - Save the response as a Microsoft Excel worksheet file, which is the bid response sheet. Enter responses (bids) in the bid response sheet.
- Create an import job to upload your bid response sheet.
Use the Sourcing Surrogate Bid API /jobs endpoint and to post a request that creates an import job.
POST {{runtime_URL}}/jobs?user=user&passwordAdapter=passwordAdapter&realm=realmConsumes: multipart/form-data.
Produces: application/json.
Body:
{ "operation": "import", "eventId": "eventId", "supplierId": "user", "file": "{file}" }Retain the value of the jobId from the response; you will need it to check the status of the job.
POST {{runtime_URL}}/jobs?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=mySiteBody:
{ "operation": "import", "eventId": "Doc6841882", "supplierId": "aSupplier", "file" : {file} } - Retrieve the status of the import job to determine if the job completed successfully.
Use the Sourcing Surrogate Bid API /jobs/{jobId} endpoint to retrieve the status of the import job. Use the procedure described in step 3 with the job ID for the import job.
If jobStatus is New or Pending, repeat this step until the status is Success, Failure, or Fatal. If the status is Success, continue to the next step. If the status is Failure or Fatal, examine the messages for more information.
- If the event includes questions or line item terms that accept attachments for responses, upload attachments on behalf of participants.
- Use the Sourcing Surrogate Bid API /jobs endpoint to post a request that creates an add_attachment_response job. This uploads a file for an attachment.
POST {{runtime_URL}}/jobs?user=user&passwordAdapter=passwordAdapter&realm=realmConsumes: multipart/form-data.
Produces: application/json.
Body:{ "operation": "add_attachment_response", "eventId": "eventId", "supplierId": "user", "file": "file", "itemNumber": "itemNumber", "termName": "termName" }-
If the attachment is a response to a question, include the itemNumber body parameter.
-
If the attachment is a response to a line item term, include the itemNumber and termName body parameters.
-
The itemNumber must match a value in the Number column of the bid response sheet.
-
The termName parameter must match the name for a term as specified in the first row of the bid response sheet.
Retain the value of the jobId from the response; you will need it to check the status of the job.
Request example:
POST {{runtime_URL}}/jobs?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=mySiteBody:{ "operation": "add_attachment_response", "eventId": "Doc6841882", "supplierId": "aSupplier", "file": "{file}", "itemNumber": "3.2", "termName": "Additional Information" } -
- Use the Sourcing Surrogate Bid API /jobs/{jobId} endpoint to retrieve the status of the add_attachment_response job.
Use the procedure described in step 3 with the job ID for the add_attachment_response job.
If jobStatus is New or Pending, repeat this step until the status is Success, Failure, or Fatal. If the status is Success and you have an additional attachment to upload, repeat this step and create another add_attachment_response job; otherwise, continue to the next step. If the status is Failure or Fatal, examine the messages for more information.
- Use the Sourcing Surrogate Bid API /jobs endpoint to post a request that creates an add_attachment_response job. This uploads a file for an attachment.
- Create a submit job to submit the imported bid response sheet and any uploaded attachments.
When the jobStatus from the import job and all add_attachment_response jobs is Success, use the Sourcing Surrogate Bid API jobs endpoint to post a request that creates a submit job. This job submits a previously imported bid response sheet and any attachments on behalf of the participant.
POST {{runtime_URL}}/jobs?user=user&passwordAdapter=passwordAdapter&realm=realmConsumes: multipart/form-data.
Produces: application/json.
Body:{ "operation": "submit", "eventId": "eventId", "supplierId": "user" }Retain the value of the job ID from the response; you will use it to check the job status.
POST {{runtime_URL}}/jobs?user=aBuyer&passwordAdapter=PasswordAdapter1&realm=mySiteBody:
{ "operation": "submit", "eventId": "Doc6841882", "supplierId": "aSupplier" } - Use the Sourcing Surrogate Bid API /jobs/{jobId} endpoint to retrieve the status of the submit job.
Use the procedure described in step 3 with the job ID for the submit job.