PUBLIC
SAP Build Process Automation
Process Actions
Configuration Guide
Contents
Introduction ........................................................................................................................ 3
Purpose ......................................................................................................................................... 3
Action Details ................................................................................................................................ 3
Configuration Guide ........................................................................................................ 10
Setup SAP Business Technology Platform Cockpit ................................................................. 10
Destination Configuration .............................................................................................................................10
Support ............................................................................................................................. 13
2 / 13
© 2023 SAP SE or an SAP affiliate company. All rights reserved. See Legal Notice on [Link]/legal-notice for use terms, disclaimers, disclosures, or restrictions related to SAP Materials for general audiences.
Introduction
Purpose
This Action project contains APIs which can be used to manage process in SAP Build Process Automation
These APIs are published in SAP Build Store as action project so that it becomes easier for Citizen
Developer to discover and consume them easily instead of having direct API invocations.
These APIs are added in action project:
• GET - /public/workflow/rest/v1/workflow-instances/{workflowInstanceId}
• GET - /public/workflow/rest/v1/workflow-instances/{workflowInstanceId}/execution-logs
• PATCH - /public/workflow/rest/v1/workflow-instances/{workflowInstanceId}
Action Details
Actions and their purpose
1. Retrieve all instances by query parameters - GET - /v1/workflow-instances
Note: The user would require WorkflowViewer role to be assigned to access this API.
Retrieves process instances by parameters.
• If no parameters are specified, all RUNNING, or ERRONEOUS instances are returned.
• Parameters for different attributes of the instance are evaluated using the logical 'and' operator.
• If multiple parameters are specified for the same attribute or a parameter is specified multiple times,
results are matched using the logical 'or' operator, unless noted otherwise.
• Empty parameters are treated as if they were not given.
Input Parameters Description
$skip The number of records you want to skip from the beginning. You
can skip at most 4000 records. To indicate a result range that
starts, for example, at 1001, combine the $skip with the $top
parameter. If not specified, no records are skipped. You can use
this parameter only once. Refer also to the $top parameter
$top The number of records you want to show. You can get at most
1000 records per API call. To indicate a result range that starts, for
example, at 1001, combine the $top with the $skip parameter. If
not specified, 100 records are returned. You can use this
parameter only once. Refer also to the $skip parameter.
$orderby The attribute and direction by which process instances are sorted.
The sort attribute and direction are separated by a space.
3
The parameter value is case-sensitive.
You can only specify one ordering parameter, which contains
attribute and direction.
If sort by definitionVersion is enabled, then definitionId is also
added to the sorting query.
If not specified, the results are sorted by the 'startedAt' attribute, in
descending order.
• id asc - Ascending, from A to Z [Link] desc -
Descending, from Z to A case-sensitive.
• definitionId asc - Ascending, from A to Z case-sensitive.
• definitionId desc - Descending, from Z to A case-sensitive.
• definitionVersion asc - Ascending, from A to Z case-
sensitive.
• definitionVersion desc - Descending, from Z to A case-
sensitive.
• startedAt asc - Ascending, from A to Z case-sensitive.
• startedAt desc - Descending, from Z to A case-sensitive.
• completedAt asc - Ascending, process instance
completion or cancelation time from the oldest to the most
recent, not yet COMPLETED process instances first.
• completedAt desc - Descending, from the most recently
COMPLETED or CANCELED process instance to the
oldest ones, not yet COMPLETED process instances last.
• startedBy asc - Ascending, from A to Z case-sensitive.
• startedBy desc - Descending, from Z to A case-sensitive.
• subject asc - Ascending, from A to Z case-sensitive,
process instances without subject first.
• subject desc - Descending, from Z to A case-sensitive,
process instances without subject last.
• businessKey asc - Ascending, from A to Z case-sensitive,
process instances without business key first.
• businessKey desc - Descending, from Z to A case-
sensitive, process instances without business key last.
Available values: id asc, id desc, definitionId asc, definitionId desc,
definitionVersion asc, definitionVersion desc, startedAt asc,
startedAt desc, completedAt asc, completedAt desc, startedBy
asc, startedBy desc, subject asc, subject desc, businessKey asc,
businessKey desc
$inlinecount Specify whether the total count of the process instances, which
match the search criteria, should be returned as a value
of the X-Total-Count response header. To enable the header, use
the 'allpages' setting. To disable the header, use the 'none' setting.
The values are [Link] values: allpages, none
$expand You can request custom workflow attributes to become part of the
process instance output by specifying the value 'attributes' for the
'$expand' parameter.
Otherwise, if the '$expand' parameter is not specified, the
'attributes' field is not included in the output of the process
instance. Note that labels.
4
as well as the order of the custom process attributes in which they
are returned, are taken from the latest versions of the process
definitions where these attributes are [Link] values:
attributes
id Specify the process instance ID.
definitionId Specify the ID of the process.
definitionVersion Specify the version of the process definition.
status Specify the status of the process instance. The values are not
case-sensitive.
The status values as required by this API have the following
corresponding terms in user interfaces of SAP Build Process
Automation:
• RUNNING - Running
• ERRONEOUS - Error
• SUSPENDED - On Hold
• CANCELED - Canceled
• COMPLETED – Completed
Available values: RUNNING, ERRONEOUS, SUSPENDED,
CANCELED, COMPLETED
startedAt Specify at what time the process instance was started. Supports
two date formats.
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link].
Specify the beginning (inclusive) of the time range during which a
startedFrom
returned process was [Link] two date formats:
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link]
The parameter operates on the 'startedAt' attribute of a process
instance. It is combined with the following parameters, if available:
'startedUpTo' parameter using the logical 'and' operator; 'startedAt'
parameter using the logical 'or' operator.
startedUpTo Specify the end (inclusive) of the time range during which a
returned process was started.
Supports two date formats:
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link]
The parameter operates on the 'startedAt' attribute of a process
instance. It is combined with the following parameters,
if available: 'startedFrom' parameter using the logical 'and'
operator; 'startedAt' parameter using the logical 'or' operator.
5
completedAt Specify at what time the process instance was changed to status
COMPLETED or CANCELED.
Supports two date formats:
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link]
Specify the beginning (inclusive) of the time range during which a
completedFrom
returned process was changed to status COMPLETED or
CANCELED.
Supports two date formats:
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link]
The parameter operates on the 'completedAt' attribute of a
process instance. It is combined with the following parameters,
if available: 'completedUpTo' parameter using the logical 'and'
operator; 'completedAt' parameter using the logical 'or' operator.
completedUpTo Specify the end (inclusive) of the time range during which a
returned process was changed to status COMPLETED or
CANCELED.
Supports two date formats:
1. yyyy-MM-dd'T'HH:mm:[Link]'Z'
2. [Link]
The parameter operates on the 'completedAt' attribute of a
process instance. It is combined with the following parameters, if
available: 'completedFrom' parameter using the logical 'and'
operator; 'completedAt' parameter using the logical 'or' operator.
Specify the user who started the process instance, in UTF-8
startedBy
encoding. The user ID is at most 255 characters long.
Specify the subject of the process instance, in UTF-8 encoding.
subject
The subject of a process instance is limited to 255 characters.
containsText containsText
businessKey Specify the business key of the process instance, in UTF-8
encoding.
The business key of a process instance is limited to 255
characters.
Specify the process root instance ID.
rootInstanceId
The process root instance ID is 36 characters long.
Specify the process parent instance ID.
parentInstanceId
The process parent instance ID is 36 characters long or it can be
null.
Specify the SAP Build Process Automation project ID of the
projectId
process instance.
The project ID of a process instance is limited to 255 characters.
6
Specify the SAP Build Process Automation project version of the
projectVersion
process instance.
The project version of a process instance is limited to 64
characters.
Example of a parameter that filters process instances by the value
Attributes.
of the custom process attribute with the ID
'ExampleCustomAttribute'.
You can specify parameters for other attributes in an analogous
ExampleCustomAttribute way.
If you specify a parameter several times, the logical operators
apply as outlined in the overall description of this API.
If custom process attributes with different IDs are present in the
URL, only process instances which contain all of them with the
values specified will be returned as a response to the request.
If a query by custom process attributes matches too many process
definitions, you must limit the query further. Refer, for example, to
parameter 'definitionId'.
Action Project Response Code and Description
Success Outputs Description
200 Returns a list of process instances.
Action Project Error Response Code and Description
Error Outputs Description
401 Unauthorized. You have not provided valid authentication
credentials to access the resource
403 Access forbidden. You do not have the required permissions to
access the resource.
429 You have reached the usage limits that are configured for your
tenant. You are performing too many requests or consuming too
many resources.
500 Internal server error. The operation you requested led to an error
during execution.
2. Retrieve execution logs - Get - /v1/workflow-instances/{workflowInstanceId}/execution-logs
Retrieves execution logs for a given process instance.
Note: The user would require WorkflowViewer role to be assigned to access this API.
Input Parameters Description
Accept-Language Provide a preferred language. If a translation is available, relevant
texts are returned in this language.
workflowInstanceId(required field) The process instance ID for which the execution logs should be
retrieved. The process instance ID is 36 characters long.
7
Action Project Response Code and Description
Success Outputs Description
200 Returns a list of execution logs.
Action Project Error Response Code and Description
Error Outputs Description
401 Unauthorized. You have not provided valid authentication
credentials to access the resource.
403 Access forbidden. You do not have the required permissions to
access the resource.
404 URL not found. Check whether the URL is correct and whether
you refer to an existing process instance.
429 You have reached the usage limits that are configured for your
tenant. You are performing too many requests or consuming too
many resources.
500 Internal server error. The operation you requested led to an error
during execution.
3. Update instance - Patch - /v1/workflow-instances/{workflowInstanceId}
Note: The user would require WorkflowAdmin role to be assigned to access this API.
Modifies the properties of a given process instance, for example, sets its status to CANCELED or RUNNING.
Status changes may not take effect immediately, due to asynchronous processing of the request. When you
change the status to CANCELED, note the following:
• Process instances in CANCELED status are considered final, that is, no further changes are
allowed. This is valid as well for other APIs and the processing according to the process definition.
• Process instances in CANCELED status stop processing as soon as the system allows.
When you are changing the status to SUSPENDED, note the following:
• Status SUSPENDED manually and temporary suspends processing.
• You can choose to suspend the specified instance or the whole cascade by setting boolean
parameter "cascade". By default, the parameter is false. When set to true, the operation is cascaded
to its referenced subflow instances.
• Process instances in SUSPENDED status stop processing as soon as the system allows.
• Process instances remain in SUSPENDED status until a status change to RUNNING or CANCELED
is requested.
• While the Process instance status reported by the respective API might change with immediate
effect, follow-up actions might only be successful, after asynchronous processing within the Process
instance has stopped. To check whether asynchronous processing is ongoing, analyze the
execution logs or check the process definition structure.
8
When you are changing the status to RUNNING, note the following:
• For process instances in ERRONEOUS status, this retries the failed activities. If these activities
continue failing, the process instance automatically moves again into ERRONEOUS status.
• If the process instance had previously been suspended while in ERRONEOUS status, failed
activities, such as service tasks, are retried.
• You can choose to retry or resume the specified instance or the whole cascade by setting boolean
parameter "cascade". By default, the parameter is false. When set to true, the operation is cascaded
to its referenced subflow instances.
When you propagate the status change to subflow instances with the 'cascade' parameter, note the
following:
• The effects outlined above are appropriately applied to the subflow instances. For example,
instances in a final status like CANCELED are not changed by the API.
The status values in relation to this API have the following corresponding terms in user interfaces of SAP
Build Process Automation:
• RUNNING - Running
• ERRONEOUS - Error
• SUSPENDED - On Hold
• CANCELED - Canceled
• COMPLETED - Completed
Input parameter and Input Description
Body
Input Body (required field) Specify the request body according to the given schema. The
length of the request body is limited to ensure optimal operation of
Key: the service.
Cascade Example Value:
status {
"status": "CANCELED",
"cascade": false
}
workflowInstanceId (required The ID of the process instance, which should be modified. The
field) process instance ID is 36 characters long
Action Project Response Code and Description
Success Outputs Description
202 The request is successful, and the properties will be changed
asynchronously.
Action Project Error Response Code and Description
Error Outputs Description
400 Incorrect format or structure of the provided request body.
9
401 Unauthorized. You have not provided valid authentication
credentials to access the resource.
403 Access forbidden. You do not have the required permissions to
access the resource.
404 URL not found. Check whether the URL is correct and whether
you refer to an existing process instance.
409 The operation could not be executed because of another activity in
the background. Please try again later.
422 The status provided in the request body was invalid.
429 You have reached the usage limits that are configured for your
tenant. You are performing too many requests or consuming too
many resources.
500 Internal server error. The operation you requested led to an error
during execution.
Configuration Guide
Setup SAP Business Technology Platform Cockpit
Destination Configuration
To call these process actions, a HTTP destination is required in the SAP BTP account where the SAP Build
Process Automation is subscribed.
Prerequisite: SAP Build Process Automation subscription should be enabled, and a service instance must
be created with a service key. Please refer to service instance and service key page.
Create the destination:
Note: Please check if destination named sap_process_automation_service already exists, if not then
please follow below link.
Configure SAP Build Process Automation Destinations
Action Testing –
Once the destination is setup and the Actions are customized, Actions need to be tested to confirm that the
connectivity with a provider system works as expected.
To perform the test,
• open Test tab
• Select the destination
• Enter the needed values as header parameters and input body
• Click Test
o Check the response.
Sample requests and response payload are shared below for reference.
10
1. Retrieve all instances by query parameters - GET - /v1/workflow-instances
Sample Request:
Key Value
$top 100
$skip 0
$orderby startedAt desc
$inlinecount none
Response payload: Returns a list of process instances with all the properties included below
"responseArray": [
"rootInstanceId": "abcd1234",
"startedBy": "xyz@[Link]",
"definitionVersion": "7",
"subject": "TestForm",
"businessKey": "",
"startedAt": "2023-08-07T05:56:40.123Z",
"id": "1234abcd",
"projectId": "test",
"status": "ERRONEOUS",
"definitionId": "test",
"projectVersion": "1.1.9",
"applicationScope": "own"
2. Retrieve execution logs - Get - /v1/workflow-instances/{workflowInstanceId}/execution-logs
Sample Request:
Key Value
11
workflowInstanceId(required) Example:
Abcd1234
Note: this workflowInstanceId can be visible in
previous get call (Get workflow Instances) result
payload
Response payload: Returns a list of execution logs with below properties.
"responseArray": [
"referenceInstanceId": "abcd1234",
"id": "abcs",
"type": "WORKFLOW_STARTED",
"userId": "xyz@[Link]",
"timestamp": "2023-08-07T05:56:40.143Z"
3. Update instance - Patch - /v1/workflow-instances/{workflowInstanceId}
Sample Request:
Key Value
workflowInstanceId(required) Abcd1234
cascade False (By default, the parameter is false. When set
to true, the operation is cascaded to its referenced
subflow instances.)
status CANCELED
Response payload: Status had been updated successful, and the properties will be changed
asynchronously.
{}
This response is success with 202 code.
12
Support
There is no support available for template content. If you experience general issues with Action Project, raise
an incident via SAP Support Portal on CA-AP-ACT component.
For additional information about Actions refer to the Help Page
[Link]
13