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

Context

Procedure

  1. 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 Start of the navigation pathSupplier and Customer Manager Next navigation step UsersEnd of the navigation path 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
  2. 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=realm
                      

    Consumes: 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=mySite

    Body:

    {
    	"operation": "EXPORT",
    	"eventId": "Doc6841882",
    	"supplierId": "aSupplier"
    }

    Response example:

    {
    	"operation": "EXPORT",
    	"jobId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213", 
    	"submittedBy": "aBuyer",
    	"submittedFor": "aSupplier"  
    }
  3. 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=realm
                      

    Produces: 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=mySite

    Response example:

    {
    	"jobId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213",
    	"operation": "EXPORT",
    	"jobStatus": "Success",
    	"submittedBy": "aBuyer",
    	"submittedFor": "aSupplier",
    	"fileId": "Doc6841882-_~EXPORT-_~aSupplier-_~1571880836213",
    	"messages": [
    		"Successfully completed export job."
    	]
    }
  4. 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=realm
                      

    Consumes: 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
  5. Save the response as a Microsoft Excel worksheet file, which is the bid response sheet. Enter responses (bids) in the bid response sheet.
  6. 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=realm
                   

    Consumes: 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=mySite				

    Body:

    {
    	"operation": "import",
    	"eventId": "Doc6841882",
    	"supplierId": "aSupplier",
    	"file" : {file}
    }
  7. 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.

  8. If the event includes questions or line item terms that accept attachments for responses, upload attachments on behalf of participants.
    1. 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=realm
                           

      Consumes: 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=mySite					
      Body:
      {
      	"operation": "add_attachment_response",
      	"eventId": "Doc6841882",
      	"supplierId": "aSupplier",
      	"file": "{file}",
      	"itemNumber": "3.2",
      	"termName": "Additional Information"
      }						

    2. 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.

  9. 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=realm
                      

    Consumes: 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=mySite				

    Body:

    {
    	"operation": "submit",
    	"eventId": "Doc6841882",
    	"supplierId": "aSupplier"
    }
  10. 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.