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.