- SAP Managed Tags:
This topic came up recently because of a blog series by @mohit_bansal3 and @Adwait_Fadnavis that explained how to implement approvals via email instead of the Inbox. So the topic of how to approve/reject an approval form via API came up.
Approval Forms
First, it's important to understand how approval forms are created. You can add buttons on approval or notification forms (up to 5 buttons).
And you name them whatever you want, both the label and identifier.
This forms are also know as user tasks, something that requires user intervention in the midst of the process.
APIs
Once a task has been triggered, you can then use an API to approve/reject it, or to simulate clicking one of the buttons. You can see when it's waiting to be executed in the Monitoring tab.
You can also see the Instance ID for the task when you expand it, as well as who was assigned it (this is important when we discuss permissions).
To execute (e.g., approve/reject) the task, you go to the Workflow API of SAP Build Process Automation, and then use the /task-instances PATCH call.
The URL path includes the instance ID for the task we saw above. Except for the instance ID, the rest of the URL is shared with everyone in that specific landscape (e.g., eu10). The following is an example URL:
https://spa-api-gateway-bpi-eu-prod.cfapps.eu10.hana.ondemand.com/workflow/rest
/v1/task-instances/4005b254-f789-11ef-9cea-eeee0a80bb17 And in the body, you specify the identifier of the button you want to execute. The status is always "COMPLETED".
{
"status": "COMPLETED",
"decision": "a"
}
You can also change other things, like the following (see the spec for the full request body):
- Due date
- Recipient of the task
- Priority
Once you execute the API, the task will be completed, just like as if someone pressed the button.
IMPORTANT: Who is listed as completing the task depends on how you authenticated when calling the API. More on that below.
Common Errors
401
Basically, the authorization token is messed up, perhaps because your credentials are wrong or the token got corrupted.
403
You do not have permission to perform this API (see below).
{
"error": {
"code": "bpm.workflowruntime.rest.user.not.sufficient.privileges",
"message": "User does not have sufficient privileges."
}
}
404
The Instance ID of the task does not exist.
{
"error": {
"code": "bpm.workflowruntime.rest.task.not.found",
"message": "Task not found",
"logId": "5f8e6171-4a26-428f-8627-f805b96-eu10"
}
}
400
You're trying to complete a task that is already completed.
{
"error": {
"code": "bpm.workflowruntime.rest.task.final.status",
"message": "Task is in final status",
"logId": "cfddd683-a061-4858-8f40-6eee397-eu10",
"details": [
{
"severity": "error",
"message": "You cannot update the properties of the task with ID 4005b254-e780-11ef-9cea-eeee0a80bb17, since it is in a final status COMPLETED."
}
]
}
}
422
You've given a wrong status (not COMPLETED).
{
"error": {
"code": "bpm.workflowruntime.rest.task.status.invalid",
"message": "Invalid status requested for task.",
"logId": "5b05c087-772c-4bee-8a83-ee5e519-eu10"
}
}
409
You've specified a button that does not exist (I assume "form_approval_1" is named that because it is a form, its identifier is "approval", and it is the first instance of that form in the process).
{
"error": {
"message": "No outgoing sequence flow of element 'form_approval_1' could be selected for continuing the process",
"logId": "ee563964-2dc2-40aa-b9a0-e65208f-eu10"
}
}
Other errors are shown in the API spec.
Permissions
If you authenticate in a way that requires an authenticated user (e.g., OAuth2UserTokenExchange), then the user must be either an admin or the user who is the current recipient of the form.
- An admin requires the ProcessAutomationAdmin role collection.
- The recipient user must also have the ProcessAutomationParticipant role collection.
In such a case you will the authenticated user as the person who completed the task.
If you authenticate using Client Credentials and just specify the client ID/secret for the API key for the service. you do not need any specific permissions or roles. The form will be shown as being approved by a generic user based on the client ID.
