Document Approval API
Document Approval API
This guide is for a customer developer developing a client application that approves or denies requisitions, invoices,
and user profiles generated in a procurement solution, using the Document Approval API.
A customer developer creates a client application that makes queries to the endpoints included in the Document
Approval API to approve or deny requisitions, invoices, and user profiles generated in a procurement solution.
The client application can process a requisition, invoice, or user profile either manually, by presenting the decision
to an authorized user, or programmatically by providing the ID of a specific user authorized to approve, deny, or
comment on the approvable document.
Note
This API supports the requisition and invoice document types, not invoice reconciliation documents.
Prerequisites
• You must be registered with the SAP Ariba developer portal developer portal and have access to the Document
Approval API.
• To enable and configure this API in the Intelligent Configuration Manager, see Configuring Your Procurement
Solution to Use the Document Approval API [page 7].
Related guides
Frequently Asked Questions About Developing Document Approval API Applications [page 14]
Endpoint Description
Note
By default the return list may include unsubmitted
requisitions whose approver assignments have
changed. These requisitions can be excluded by set-
ting
theApplication.Approvable.IncludeComp
osingInChanges parameter in the Intelligent Con-
figuration Manager. For details, see Include unsubmit-
ted requisition changes in Document Approval API re-
sponses
GET /pendingApprovables Returns a list of all approvables. Use $filter to filter by ap-
provable type. The maximum number of documents that can
be returned per response is 100.
PATCH /{approvablType}/{approvableId} Changes the state of the specified approvable and/or adds a
comment.
For example:
PATCH {{runtime_url}}/requisitions/
Req123?showErrorDetails="true"&...
"error":
{
"code": "InternalServerError",
"message": "Internal Server Error",
"details":
[{
"code":
"internalCallReturnedError",
"message": "Localized internal
call error message"
}]
}
GET /groups/{groupId}/members Returns the list of users with membership in the specified
group.
Note
When an approver assigns another user as a delegate in the GUI of an SAP Ariba solution, the Document
Approval API allows that delegate to perform approval tasks assigned to the original approver or to any group to
which the original approver belongs, using the following endpoints:
• GET /pendingApprovables
1. The customer configures the installation to specify what approval node change types to track.
• The installation can track changes relevant to invoices or requisitions or both.
• The installation must also be specifically configured to track delegation changes, if such tracking is
desired.
2. The client application does one of the following:
• 1. Approval nodes change in the approval graph.
2. The client application requests a list of document IDs representing changed nodes.
• The client application requests a list of document IDs representing approvable documents that match a
specified user ID and/or approvable type.
3. The client application requests approvable documents based on document IDs returned. Optionally, the client
may download associated attachments as well.
4. The client application identifies eligible approvers for a document.
5. The document is presented to authorized approvers.
6. Approvers approve or deny the document.
7. The client application registers the approvers' actions.
Workflow to view and act on approvables in the user interface using the Full URL
If you prefer to view and act on an approvable in the user interface rather than programmatically via the API,
you can open the URL listed for the approvable in the fullURL field in the response to your GET /changes or
GET /pendingApprovables request.
1. The client application requests approvables using the GET /changes or GET /pendingApprovables
endpoint.
2. In the response, the client application or the user locates the fullURL field in the details block for the desired
approvable.
3. The client application or the user opens a browser to the URL listed in the fullURL field.
4. The client application or the user enters authentication credentials for the relevant SAP Ariba solution.
5. The authenticated user views the approval in the solution UI, and acts on the approvable as permitted based on
their group memberships.
Configuring Your Procurement Solution to Use the Document Approval API [page 7]
Context
When setting a configuration parameter in the Intelligent configuration manager, you must first make your
modifications in a test site, create a package, and test it. When your tests are successful and you are satisfied
with the results, push your new configuration into production. For details about this workflow, see Workflow for
Updating Configurations for the Site and Configuration Packages in Intelligent Configuration Manager in Intelligent
Configuration Manager Administration.
Procedure
Related Information
Use this procedure to write a client application to work with approvables, using the Document Approval API.
Prerequisites
Your SAP Ariba procurement solution must be configured to allow external approval. Contact your SAP Ariba
representative to configure your installation.
Context
This topic describes what queries to make, in what order, to identify, retrieve, and act on specific approvables,
providing examples for each query.
To prevent the responses to these queries from becoming too large, parameters are available to control pagination
and to filter the results set. When pagination is relevant, the sample query demonstrates how to use these
parameters:
$count Controls whether number of elements in a collection is returned with the response. When this
parameter is true, the count is returned inline, parallel to the value field that encloses the returned
approvables data, as part of the response containing the collection itself.
$filter Use of this parameter varies from endpoint to endpoint, always to filter the results set. Details for use
of $filter are provided with the examples for each endpoint.
$skip An offset from the beginning of the result set, used for pagination.
$top The maximum number of records to be returned in the response. This can be used in combination with
$skip for pagination purposes. For example, if $top=10 and the results set contains 100 records, the
response will contain the first 10 records. To retrieve the next set of records in the results set, submit a
new query with $skip=10. For the following page, $skip=20 and so on.
Note
The default value varies based on endpoint. If you do not specify $top, the default maximum will be
returned in the Preference-Applied response header. If you set $top higher than the default or
lower than zero, you will get an error response.
Note
In the sample URLs in this topic, replace {{runtime_url}} with the desired runtime URL from the
Environment Details table on the SAP Ariba developer portal discovery page for this API.
1. The client application requests a list of approvable documents by doing one of the following:
• When an approval node is activated, the SAP Ariba procurement solution records a change in the
document's state. For a list of events that cause an approval node to activate, see Events That Activate an
Approval Node [page 12].
The client application requests the list of approvables representing approvables whose state has changed,
using the GET /changes endpoint.
GET {{runtime_url}}/changes?$count={true|
false}&realm={realm}&skip={offset}&top={maxRecords}&$filter=changeSequenceId
gt '{ID}'
The changed approvables will be returned in a JSON "wrapper" that includes a value block and that may
include a count field. The value block lists information including the approvableID for each returned
approvable. The maximum number of approvables returned will be $top or fewer. If you set $count to
true, the count field will be included in the JSON response at the same level as value.
$filter Restrict the set of resources that is returned to include only the changes that occurred
after the last change processed by filtering the results on the changeSequenceId field. For
example, $filter="changeSequenceId gt 10" would ensure that changes #1 through
#10 would not be included in the response.
Note
To ensure that the current document is not included in the list of documents that require
processing, the client application should track the changeSequenceId of the last change
it processed.
• The client application requests a list of document IDs representing approvable documents that match
specified filter criteria, using the GET /pendingApprovables endpoint:
GET {{runtime_url}}/pendingApprovables?realm={realm}&$filter=approvableType
eq '{requisitions|invoices}' and user eq
'user'&skip={offset}&$top={maxRecords}
Note
If you filter on the user attribute but not on approvableType, the response includes approvables of
all types pending approval by the specified user. If you filter on approvableType but not user, the
response includes approvables of the specified type pending approval by any user in your realm. If you
don't filter on either attribute, the response includes all approvables awaiting approval. If you filter on
both, the response includes all approvables of the specified type pending approval by the specified
user.
If you prefer to view and act on an approvable in the user interface rather than programmatically via the
API, you can open the URL listed for the approvable in the fullURL attribute in the response to your
GET /changes or GET /pendingApprovables request. Skip the remaining steps in this list and execute
desired actions on the approvable in the user interface.
2. The client application requests the details of one or more identified approvables, as follows:
GET {{runtime_url}}/{requisitions|invoices|userprofiles}/{approvableId}?
realm={realm}
• To retrieve a single approvable based on the approvable's uniqueName, use the GET /
{approvableType} endpoint and pass the $filter parameter.
GET {{runtime_url}}/{requisitions|invoices|userprofiles}?
realm={realm}&$count={true|false}&$filter=uniqueName eq
'{uniqueName}'&$skip={offset}&$top={maxRecords}
$filter In this endpoint, only uniqueName can be filtered on, and the only supported operation is eq.
• To retrieve all approvables of the specified type, use the GET /{approvableType} endpoint and do not
pass the $filter parameter.
• GET {{runtime_url}}/{requisitions|invoices|userprofiles}?
realm={realm}&$count={true|false}&$skip={offset}&$top={maxRecords}
The response contains the details of the document or documents you requested. If the document has
associated attachments, a list of attachment IDs is included in the Attachments block.
Note
If no attachments are present, instead of an Attachments block, the response will include the following:
Attachments.Attachments: null.
3. Optionally, the client application can download an attachment associated with a document, using the GET /
{approvableType}/{approvableId}/attachments/{attachmentId} endpoint.
curl -o vz.pdf
{{runtime_url}}/{requisitions|invoices|userprofiles}/
{approvableId}/attachments/{attachmentId}?realm={realm}
4. The client application identifies users who are authorized to approve or deny the approvable. You can do this as
follows:
a. Optional. If you do not already have the ID of the group or groups authorized to act on the approvable,
use the GET /groups endpoint. If you know the group's uniqueName, you can use $filter to return the
specific groupId of that group. If you do not pass $filter, this endpont returns the groupId for every
group.
The group's readable name is case sensitive and must maintain all spaces from the original
group name. For example, if the group name is Purchase Managers, the filter syntax would be
$filter=uniqueName eq 'Purchase Managers'.
b. Retrieve the list of users with membership in the authorized group using the GET /groups/{groupId}/
members endpoint.
GET {{runtime_url}}/groups/{groupId}/members?realm={realm}
5. The client application presents the decision to one or more authorized approvers.
6. Either the client application or one or more approvers approve or deny the approval request, using the
PATCH /{approvableType}/{ApprovableId} endoint.
PATCH {{runtime_url}}/{requisitions|invoices|userprofiles}/{approvableId}?
realm={realm}&user={userID}&passwordadapter={passwordAdapter}
Body:
{
"state" : "{newState}",
"comment" : {
"text": "test comment",
"visibleToSupplier" : "true"
}
}
state Optional. If you specify an approvable state in this field, the PATCH request will change the
approvable's approval state to the value you specified.
text Optional. If you decide to add a comment, the text of the comment goes here.
visibleToSupplier If this is true, the supplier will be able to read your comment. To hide your comment from
the supplier, set this false.
showErrorDetails Optional. Default value is false. If true, error messages generated due to internal
integration errors are included in the error block of the response, localized to the internal
system's region, as part of a 500 internalServerError block, as follows:
"error":
{
"code": "InternalServerError",
"message": "Internal Server Error",
"details":
[{
"code": "internalCallReturnedError",
"message": "Localized internal call error message"
}]
}
Related Information
Frequently Asked Questions About Developing Document Approval API Applications [page 14]
Approval nodes are activated whenever one of the following events takes place:
ApprovableWithdrawn The approvable is withdrawn. This occurs not only when the approvable is withdrawn,
but also when the user edits the approvable. When the user edits an approvable, the
system withdraws the approvable first. After editing is complete, the approvable must
be resubmitted.
DelegationChanged Optional. There is a user profile change for delegation settings. Your installation must
be configured to track this event type.
Use this information to troubleshoot your queries to the Document Approval API.
HTTP
Code Response Code Message Additional Information
400 approvableTypeMisma Approvable type is not The query URL specifies one approvable
tch matching type, but the approvable ID is for an ap-
provable of a different type.
400 approvableTypeMissi Approvable type is missing The query does not specify what type
ng of approvable is relevant. Possibilities are
invoice and requisition.
400 badRequest Malformed syntax or bad query Check your query for typos and other
syntax errors.
400 badRequest Unrecognized field in request The request body refers to one or more
body invalid fields.
400 countNotBoolean $count parameter needs to be Make sure the $count parameter is
boolean boolean.
400 invalidEnumValue Invalid enum value in request Check the spelling and accuracy of
body enumerated values in the request body.
400 invalidRealm realm parameter is either Make sure the realm parameter accu-
invalid or does not exist rately specifies your site.
400 missingPasswordAdap PasswordAdapter parameter is Include the password adapter and resub-
ter missing for effective user mit your query.
400 missingUser user parameter is missing for Include the user parameter and resub-
effective user mit your query
400 payloadMissing Request body is missing The query must include a properly
formed JSON body.
400 skipNotNumeric $skip parameter needs to be Make sure the value of the $skip pa-
numeric rameter is numeric.
400 topLargerThanMax $top (limit) parameter is Make sure that the value of the $top is
larger than maximum allowed not too large.
value
400 topNotNumeric $top parameter needs to be Make sure the value of the $top param-
numeric eter is numeric.
400 unknownParameter Unknown parameter received. The query includes a parameter that the
system doesn't recognize. Check spelling
of all parameters, and make sure that all
parameters are valid for the endpoint in
use.
400 updateFailedUserUna Update failed. User The specified user does not have access
uthorized unauthorized to the desired resource.
400 userNotFound User for requested user and Double check that the user parameter
passwordAdapter pair not found and passwordAdapter parameters
are both correct.
400 userNotUnique Multiple users exist with Resubmit your query filtered on
this name, please add passwordAdapter.
passwordAdapter value in
$filter to disambiguate.
404 approvableNotFound Approvable not found The query refers to an approvable not
present in the system.
404 attachmentNotFound Attachment not found The query refers to an attachment not
present in the system.
404 groupNotFound Group not found The query refers to a user group not
present in the system.
404 notFound Requested resource not found The query requests a resource not
present in the system.
405 methodNotAllowed Operation (HTTP verb) is not You may have specified the incorrect
allowed on the resource HTTP verb for this query.
406 notAcceptable Requested representation The value passed in the Accept header
(content type as requested must be application/json
in the Accept header) not
available for the resource
500 internalServerError Internal Server Error The internal system may have thrown an
error.
How do I ensure that I am pulling all the changes since my last pull?
I need to pull my changes again. Can I use history to pull old records?
Yes, you can specify an older value for changeSequenceId to pull records from the past.
Note
By default, changes are purged from the system after 180 days.
No. The APIs are stateless and do not maintain records of data pulled by customers.
Yes, change events are logged in the system and kept for 180 days, after which they are purged. To change this
timespan, your administrator can change the value of the ExternalApprovableChangesDaysToKeep parameter
to the desired number of days.
The Document approval API has multiple versions, only one of which is active at this time. Previous versions are
deprecated and might be decommissioned at a later date.
Related Information
The SAP Ariba developer portal included in the SAP Ariba APIs product and the APIs made available on this site are
provided solely at the discretion of SAP without warranty of any kind, and SAP may change, suspend, or cancel any
or all features or functions of the SAP Ariba APIs product or revise the website at any time. Any production use of
or commercialization of applications containing any APIs provided on this website is prohibited without a written
agreement between your company and SAP governing such activities.
Access to this API is available to you as a subscriber to this solution as part of the SAP Cloud Service Level
Agreement. However, it is not considered part of the solution. Use of this API is purely optional and is subject to
restrictions stated in the documentation, including the Terms of Use and the documentation found at the SAP
Ariba developer portal (see https://developer.ariba.com/api ). If you wish to connect a third-party service using
this API, first confirm that the company is participating in the SAP partner program and is authorized to provide a
connection to this solution using this API. You will be required to submit written consent to SAP to authorize the
exchange of data with the third-party service.
Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:
• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements
with SAP) to this:
• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using such links,
you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and
phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example
code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders,
and abilities.