SAP Ariba APIs
Note: To view the entire list of SAP Ariba APIs, see SAP API Business Hub.
An API can include multiple sub-APIs. For instance, the Operational Reporting for Procurement API (ORP API) is made up of several sub-APIs. With the Fairmarkit integration, we use the Operational Reporting for Procurement - Synchronous API and Operational Reporting for Procurement - View Management API. In addition, an API can include a single sub-API. For example, the Document Approval API includes the Document Approval API: SAP API Business Hub sub-api, which we also use. Each API requires it’s own set of OAuth credentials to access the sub-APIs.
Ariba also has a set of SOAP web services (e.g., WSDL).
Realms
A particular SAP Ariba instance is identified by the realm. The realm is passed as a query parameter to all API endpoints. A realm that we might use in production will look like FairmarkitDSAPP. The corresponding child instance will usually look like FairmarkitDSAPP-1. The test instance will look like FairmarkitDSAPP-T. The test instance of the child instance will look like FairmarkitDSAPP-1-T.
Operational Reporting for Procurement API
With the Fairmarkit SAP Ariba integration, we use the ORP API to access requisitions. While there are five sub-APIs, we only use the Synchronous API and the View Management API.
In this API, a view is a way to list and filter certain objects in SAP Ariba. These can be created using the View Management API. The Synchronous API is used to get the objects from the view. When setting up a customer, we first create a view for requisitions that can filter by TimeUpdated and Status. During the integration, we query this view and pull requisitions in status Submitted and updated within some window.
View Management API
For more information, see Filter parameters for the Operational reporting API and View template structure.
The View Management API allows us to generate a view to get requisition data. To create a view, we need to specify the name of the view, the object we are viewing, the selected fields we are going to include from that object, and the filters we can include to query the object. The available fields and filters can be found by hitting the metadata endpoint for requisitions (this is setup in Postman). Some example fields are:
AmountAccepted
ApprovalRequests.AssignedDate
LineItems.Description.Description
Some example filters are:
UniqueName
StatusString
TimeUpdated
Once a view is created, it will be in draft status. We then need to publish it using the view name. Both of these requests are done in Postman.
Views can be created, but they can’t be edited or deleted. This means that if we have a standard view and name, we want to use it across all customers, making sure that it is available in all instances.
Synchronous API
We use the Synchronous API to get all recent requisitions. This API returns a page containing a list of requisitions. Each page can contain 40 requisitions. If there is another page, a page token is added in the response, and that can be used to get the next page.
The ORP API has a rate limit of 3/min, 300/day. This means we can get 120 requisitions before we need to wait for the rate limit to reset. Fetching attachments also counts towards this limit. Increasing the look back window or the frequency of scheduled runs will risk hitting the API rate limit. This may make it difficult to pick up any missed requisitions due to unknown errors.
Structure
The requisition data has a unique structure. For example, we have the fields LineItems.Description.Description and LineItems.Description.ShortName. You would think the . represent nested objects. And that’s true for objects that are lists, like LineItems and ApprovalRequests.
However, that structure that doesn’t work for json fields. So instead of looking like:
The requisition looks like:
Document Approval API
The Document Approval API can be used to get a requisition, check pending approvals of a user, comment on a requisition, and approve a requisition. We use it extensively during integration because it doesn’t have a low rate limit. The requisition data retrieved from the Document Approval API (in code, often referred to as document_details) looks cleaner than that of the ORP API. Additionally, it contains extra data that isn’t included from the ORP view, such as line comments.
The Document Approval API offers a simple way to add a comment by acting as a certain user. We often use this feature to indicate certain steps of an integration.
We also can approve the requisition as a certain user. We can only approve requisitions when we are the current approver. Otherwise, SAP Ariba will return a 400 error. An approval must contain an approval comment. We have a default message in the client.
RequisitionImportPull (SOAP Web Service)
While SAP Ariba has well-documented REST APIs to pull data, they are not great for pushing information back into SAP Ariba. So, the integration uses the RequisitionImportPull service to update requisition data. This service was designed to create requisitions and uses Basic Auth.
Importing requisitions
The following outlines how the APIs are used to import requisitions to create requests for quote in Fairmarkit.
Current flow
Hit an ORP API view that can be filtered by UpdatedFrom, UpdatedTo, and Status. We always filter status by Submitted.
On the client side, we filter out all requisitions where Fairmarkit is not the current approver.
Fetch the requisition from the Document Approval API (if available, this gives us two different versions of the same requisition).
Remap the two views of and import the request for quote event into Fairmarkit.
Fetch the attachment data from Ariba using the ORP API, and add the attachments and comments to the event.
Add a comment on the requisition in Ariba indicating the requisition was imported
Item titles
To format item titles, we use Description.Description and Description.ShortName. Description.Description is the main field that we use for the item title. However, sometimes Description.ShortName has an additional description for the item. When it has additional information, we will add it to the regular description. Otherwise, we ignore it.
Additionally, service line items will include start and end dates in the item title.
NumberInCollection
Items are identified by a NumberInCollection field, which is just the line number. When sending information back to SAP Ariba, this field is very important, so we save it in additional info.
Additionally, ParentLineNumber determines group items. If the value is 0, it is a parent item. Otherwise, the item is a child item, and the ParentLineNumber will be the NumberInCollection of its parent item. Only service items can have this parent-child structure. We import these as Group services. Though, since the group service itself isn’t awarded, only the subitems, we use the Parent item to populate the Group service information and the first subitem information.
Tax Items
SAP Ariba tracks taxes on items by creating an entirely new item on the requisition that is hidden on the user interface but exposed in the API. These hidden items have NumberInCollection 10000 greater than the original items. For instance, if the regular item has NumberInCollection 1, there will be a hidden number with mostly the same information, but with NumberInCollection 10001. We skip these items on import.
Exporting request for quote events
With the SAP Ariba RequisitionImportPull web service, you can create requisitions. By setting the header level UniqueName as an existing requisition, it will instead update that requisition. We use this method to update requisitions.
Deleting attachments
SAP Ariba does not have a way to add attachments to a requisition via API. Instead, we add a comment to the requisition indicating the number of supplier attachments.
The SOAP update will delete all line item attachments, so we skip any line item attachments. This is a condition we check on import and export. Header level attachments are preserved.
Deleting comments
The SOAP update will delete all comments, but we are able to pull all line item comments before updating. However, only one comment can be added to each line when updating. So, we pull all of the line comments, format them with the user, timestamp, and content, and then add our own comment.
If we have to update twice (e.g. first partial award, then fully award), we check if we made the line comment, and remap it accordingly. For example, if an item is not awarded in the first update, we roll up all existing comments, and add a note indicating the item hasn’t been awarded yet. When the item is awarded, we’d need to roll up all comments again, but we’d want to look out for the comment we already formatted. We’d want to take that comment, remove our original note about how the item hasn’t been awarded yet, roll up any new comments added between the two updates, and then add our regular note we add when awarding a line item.
Contracts that block updates
If a line item has an associated contract, we will send the same SOAP update twice. The first will remove the contract id, the second will update the price. This updates the price and removed the contract ID (as intended).
Awarding to Benchmark
When a request for quote event is exclusively awarded to the benchmark supplier, we don't update with SOAP. If the event is partially awarded, we leave a comment indicating this. If it is fully awarded, we approve and add a comment indicating it is awarded to the benchmark supplier.
Parent-Child Service Items
As part of integration, we do not send group services back to SAP Ariba because we don't always have the relevant fields to preserve a group service. We split the group service into separate line items.
Last updated
Was this helpful?