PUBLIC

SAP Cloud Platform Workflow

Document Version: 1.0 – 2020-04-02

SAP Cloud Platform Workflow in the Neo

Environment
© 2020 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

1 Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Workflow Definition versus Workflow Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 Status Changes for Workflow Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Status Changes for Task Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 General. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 Conventions, Restrictions, and Limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.6 Supported Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.7 Browser Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

2 Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1 Getting Started with Workflow Service in the Neo Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Configuring SAP Fiori Launchpad Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Connect My Inbox On-Premise to SAP Cloud Platform Workflow. . . . . . . . . . . . . . . . . . . . . . . . . 21
Configure the Workflow Service Mail Destination with SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . 25
Configuring Principal Propagation for Service Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.2 Export Workflow Service Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3 Deactivate the Workflow Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3 Developing Applications with Workflow Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.1 Modeling a Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Enablе the Workflow Editor in SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Editor Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Define Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Configure Custom Workflow Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Transport Workflows between Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Build and Deploy Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Accelerated Modeling with Speed Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
3.2 Create a Workflow Sample Application with SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.3 Creating User Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Defining a User Interface for a Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Creating a Workflow Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3.4 Build and Deploy Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
3.5 Using Workflow APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Access Workflow APIs Using OAuth 2.0 Authentication (Client Credentials). . . . . . . . . . . . . . . . 126
Access Workflow APIs Using OAuth 2.0 Authentication (Authorization Code Grant). . . . . . . . . . 128
Determine the Service Host. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

SAP Cloud Platform Workflow in the Neo Environment

2 PUBLIC Content
 Modifying the Context of a Workflow Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Updating Task Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Workflow Execution Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

4 User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

4.1 Working with Tasks in My Inbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Access the My Inbox Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
My Inbox Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Expert View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Scenario-Specific Тiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

5 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.1 Architecture with SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.2 Identity Provider and Identity Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.3 Authorization Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.4 Destinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Configure a Service Task Destination with OAuth2 Client Credentials Flow. . . . . . . . . . . . . . . . . 154
Configure a Service Task Destination with OAuth2SAMLBearerAssertion for Principal
Propagation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.5 Data Protection and Data Privacy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Information Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Erasure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Change Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

6 Monitoring and Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

6.1 Managing Workflows Using the Monitor Workflows App with SAP Web IDE. . . . . . . . . . . . . . . . . . . 161
Managing Workflow Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Managing Task Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Managing Workflow Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Deep Linking in Monitor Workflows App. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
6.2 End Users Can't Open SAP Fiori Launchpad Tiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Clear the SAP Fiori Launchpad Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Change the SAPUI5 Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
6.3 Authentication and Authorization Issues with SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Failing Service Tasks and Principal Propagation After Name Change of Local Service Provider
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Authentication Issues when Using a Custom IDP and Basic Authentication. . . . . . . . . . . . . . . . 175
HTTP Status 403: User Doesn't Have Sufficient Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
No Permissions Granted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Communication Issues Between SAP Cloud Platform Workflow and an On-Premise Application
Server ABAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

SAP Cloud Platform Workflow in the Neo Environment

Content PUBLIC 3
 Intermittently Receiving 403 Status Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.4 Error When Clicking "Go to Service" on Portal Tile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
6.5 Tasks Not Appearing in My Inbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
6.6 Error During Workflow Deployment in SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.7 Workflow Service Cannot be Enabled in the Account. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
6.8 Unable to Open the Workflow Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
6.9 Unable to Find the Deploy Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.10 Cannot Deploy Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.11 Service Calls Fail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.12 My Inbox Features Not Active. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

SAP Cloud Platform Workflow in the Neo Environment

4 PUBLIC Content
1 Concepts

The SAP Cloud Platform Workflow offers modern process automation capabilities.

The Workflow Service in a Simplified Landscape

How the Workflow Service Is Embedded into the Landscape

The end user and the developer at the customer site work on subscriptions of the workflow service and SAP
Web IDE Full-Stack. The workflow service itself resides in the SAP Cloud Platform subaccount.

1. The developer at the customer site creates an application, which can include multiple services, in the SAP
Cloud Platform customer subaccount.
2. In the SAP Cloud Platform customer subaccount, the developer accesses the SAP Web IDE Full-Stack and
enables the workflow feature to create workflows.
3. The developer accesses his or her browser to define a start event in the editor and start the workflow using
the REST API or the Monitor Workflows app.
4. The end users at the customer site can access the workflow tasks in their My Inbox apps in the SAP Fiori
launchpad.

SAP Cloud Platform Workflow in the Neo Environment

Concepts PUBLIC 5
5. In general, the customer application can call the workflow service APIs, for example, to start a new
instance. At the same time, the workflow service can call the services of the application that is defined in
the customer subaccount.

Related Information

Business Process Model and Notation

1.1 Workflow Definition versus Workflow Instance

A workflow is a collection of linked automatic or human activities that serve a certain goal.

Example Workflow Depicted as a Diagram

The workflow service differentiates between workflow definitions and workflow instances. A workflow definition
specifies:

● Which actions should be performed

● When these actions should be performed
● The circumstances under which these actions should be performed

The actual execution of these actions is called a workflow instance. So, a single workflow definition can have
multiple workflow instances. This differentiation is essential for monitoring and troubleshooting. Additionally,
you can define a subject for a workflow that helps the business users to track these instances using monitoring
application. For more information, see Managing Workflows Using the Monitor Workflows App with SAP Web
IDE [page 161].

These different notions of "workflow"are both used in the workflow service. In the context of design time,
workflow relates to a workflow definition. In the runtime context, workflow refers to a workflow instance.

The same holds true for tasks. In the context of design time, "task" refers to the specification of a certain type
of activity. Whereas a runtime task, for example, a task in My Inbox, relates to a particular activity to be
performed instantiated from the corresponding specification.

 Note

Do not confuse "workflow instance" as described here in the workflow context with "workflow service
instance". The latter refers to the Cloud Foundry instance concept.

SAP Cloud Platform Workflow in the Neo Environment

6 PUBLIC Concepts
1.2 Status Changes for Workflow Instances

Workflow instances follow a status and action model.

A started workflow instance moves into the RUNNING status and that means:

● All execution branches can be executed.

● The workflow engine processes the next workflow elements unless the branch is asynchronously waiting
for external activation. This activation can be a user task completion, a message event, or a timer event.

If the execution of a workflow element fails, it is retried several times. After that, the workflow element is kept
but is not executed again. The workflow instance then changes to the ERRONEOUS status. However, only the
execution branches with failed workflow element executions are affected. Parallel branches without failures
continue to execute. For erroneous instances, you can reset the execution counter manually with the retry
action.

You can move an instance that cannot reach any end event or is no longer required to the CANCELED status.
You can also temporarily move an instance to the SUSPENDED status and resume it later. You can change the
status using the buttons on the Workflow Instances tile of the Monitor Workflows app. For more information, see
Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161].

An instance that reaches at least one terminating end event or all non-terminating events is moved to the
COMPLETED status.

Start status of an instance: RUNNING

Final status of an instance: CANCELED, COMPLETED

SAP Cloud Platform Workflow in the Neo Environment

Concepts PUBLIC 7
The status and action model for workflow instances is exposed for customer consumption in the REST API. For
more information, see Workflow Instance Status .

1.3 Status Changes for Task Instances

User tasks follow a status and action model, which is reflected in My Inbox as well as in the REST API.

When a new user task is created without a processor its status is READY. In My Inbox, all users who are listed as
recipient users or are assigned to at least one recipient group can see this task.

When a recipient claims the task, its status changes to RESERVED. When the user releases the task again, its
status reverts back to READY.

The REST API called from a custom task UI when the user completes a task sets its status to COMPLETED, see
Adding Task Completion Buttons [page 89].

A user task has the status CANCELED when a canceling boundary event on the user task triggers it or when the
workflow instance of the task is canceled. .

My Inbox does not display user tasks with status CANCELED or COMPLETED.

Start status of an instance: READY

SAP Cloud Platform Workflow in the Neo Environment

8 PUBLIC Concepts
Final status of an instance: CANCELED, COMPLETED

1.4 General

Related Information

Conventions, Restrictions, and Limits [page 9]

Supported Languages [page 13]
Browser Support [page 13]

1.5 Conventions, Restrictions, and Limits

These conventions, restrictions, and limits apply to the workflow service.

Considering this information during development, helps you to achieve an optimal use of the service.

 Note

Limits are, to the extent possible, subject to change.

SAP Cloud Platform Workflow in the Neo Environment

Concepts PUBLIC 9
Execution Limits

Value for
Standard
Value for Lite
Plan (Paid Plan (Trial Ac­
Area Limit Account) count) More Information

Workf Size of the 100 KB per workflow service in­ ● Applies also if exceeded only temporarily
low workflow stance ● Applies to any operation on the workflow context, that is, to all
con­ context types of tasks and all types of APIs.
text

API Request 150 re­ 30 requests per ● Using Workflow APIs [page 125]
rate limit quests per second and ten­ ● Includes requests triggered from user interfaces delivered by
second and ant SAP.
tenant ● In exceptional situations, requests are temporarily rate-limited
to a lower value than the given value.

Request 512,000 bytes n.a.

body size

Processing 30 seconds Includes response generation by the server

time

Scrip Execution 150 milliseconds

t time
task
s

Servi Connection 1 minute Time to establish the connection with the remote host
ce timeout
task
s Socket 3 minutes Maximum period between two data packets
timeout

Total execu­ 4 minutes

tion time

De­ Number of - 100 Counting the number of versions of all workflow definitions.
ploy­ deploy­
men ments per
ts tenant

Workf Number of - 250 All workflow instances in a tenant, regardless of the status.
low workflow in­
in­ stances
stan­
ces

SAP Cloud Platform Workflow in the Neo Environment

10 PUBLIC Concepts
UI5 Version Restriction

To render workflow forms (see Creating a Workflow Form [page 107]), you need UI5 version 1.60 or higher.
Ensure that your SAP Fiori launchpad is configured properly, see Configuring Site Settings.

Restrictions

● Variable Names
There are many ways to create, change, or delete variables in the context of a process. For example, when
starting the process, using script tasks, updating the process context manually. In all cases, the names of
the variables in the process context must adhere to the following rules:
○ Must not start with "SAP_WFS".
○ Must start with a letter (latin alphabet, or A-Z, a-z).
○ Can contain additional letters, digits, and underscores.
● Duration
When expressions are used to specify duration, they must resolve to ISO 8601 format during runtime. For
more information, see ISO 8601 .
However, you must consider the following:
○ The smallest units, which the duration specification supports are minutes.
○ The "Week" unit ("W") isn’t supported.
○ The duration specification supports integers only. Also, while using the static mode, the value of the
duration field must be less than 2147483647.

Model Limits

The following model limits apply to the workflow service.

Common Properties

Property Name Limit

Name 64 characters

Documentation 2000 characters

Workflow Properties

Property Name Limit

Subject 255 characters

Business Key 255 characters

SAP Cloud Platform Workflow in the Neo Environment

Concepts PUBLIC 11
Property Name Limit

Custom Workflow Attribute 15 custom workflow attributes per workflow definition at a time.

30 unique attributes per custom workflow attributes across all workflow versions.

Currently, only type string is supported.

The ID and the label of an attribute can be 255 characters long. The definition of the
value in the model can’t exceed 4000 characters. Also, after expression evaluation at
runtime, the value of an attribute can’t exceed 4000 characters.

Flow Element Properties

Flow Element Property Name Limit

Intermediate Message Event Message Name 128 characters

Response Variable 255 characters

User Task Subject 255 characters

Description 2000 characters

Users Maximum of 100 users, maximum of 255 char­

acters per user

Groups Maximum of 100 users, maximum of 255 char­

acters per user

Custom Attribute 15 custom attributes per user task at a time, 30

unique attributes per user task across all work­
flow versions

Currently, only type string is supported.

The ID and the label of an attribute can be 255

characters long. The definition of the value in
the model can’t exceed 4000 characters. Also,
after expression evaluation at runtime, the value
of an attribute can’t exceed 4000 characters.

Service Task Destination 200 characters

Path 7000 characters

Path to XSRF Token 7000 characters

Request Variable 255 characters

Response Variable 255 characters

Script Task Script File 10000 characters

SAP Cloud Platform Workflow in the Neo Environment

12 PUBLIC Concepts
 Flow Element Property Name Limit

Mail Task To, Cc, Bcc Maximum of 100 e-mail addresses that can con­
tain a maximum of 5000 characters

Subject 1000 characters

Mail Body (Plain or HTML) 10000 characters

1.6 Supported Languages

The workflow service is available in the following languages.

● Workflow documentation:
○ Chinese (Simplified)
○ English
○ Japanese
● Workflow application: English

To activate the translations for each required language in SAP Fiori launchpad, see Working with Business
Content.

1.7 Browser Support

For the UIs of the workflow service, the following browsers are supported on Microsoft Windows PCs and where
mentioned on Mac OS X.

Supported Browsers

Browser Versions

Microsoft Internet Explorer 11

Mozilla Firefox Extended Support Release (ESR) and latest version

Google Chrome Latest version

Safari 7.0 and upwards (for Mac OS X only)

For a detailed list of SAPUI5 supported browsers and platforms, see Browser and Platform Support - SAPUI5.

SAP Cloud Platform Workflow in the Neo Environment

Concepts PUBLIC 13
2 Administration

Configuration tasks for the SAP Cloud Platform Workflow service.

Related Information

Getting Started with Workflow Service in the Neo Environment [page 14]
Configuring Principal Propagation for Service Tasks [page 27]
Configure the Workflow Service Mail Destination with SAP Web IDE [page 25]
Deactivate the Workflow Service [page 32]

2.1 Getting Started with Workflow Service in the Neo

Environment

Before you can use the workflow service, meet the prerequisites and execute the basic setup.

Prerequisites

● A global account in your respective region.

For more information, see Getting a Global Account.
● Your user is a member of the subaccount and is assigned to the Administrator role for the subaccount. You
need this role to execute the following configuration steps.
For more information, see Subaccount Member Roles.

Procedure

1. In the SAP Cloud Platform cockpit, enable the SAP Cloud Platform Portal, SAP Web IDE Full-Stack, and
SAP Cloud Platform Workflow services for your subaccount.
a. In the navigation area, choose Services.
b. Search for SAP Cloud Platform Portal.
c. On the Portal tile, choose Enable.
d. Go back to Services and search and enable the SAP Web IDE Full-Stack.
e. Go back to Services and search and enable the SAP Cloud Platform Workflow service.

This automatically performs the following:

SAP Cloud Platform Workflow in the Neo Environment

14 PUBLIC Administration
 ○ Enables principal propagation. Please don’t disable it. For more information, see Principal
Propagation [page 152].
○ Creates the destination bpmworkflowruntime. Please don’t change it.

 Note

Both configurations are required to run the workflow service.

2. Decide which roles or permissions your users need, then assign those roles and permissions.

For more information about the available roles and permissions, see Authorization Configuration [page
150].

Assign your users to workflow roles.

1. On the Workflow tile, choose Configure Service.
2. In the navigation area, choose Roles.
3. In the Roles table, select the role that you want to assign to one or more users.
4. You have the following options:
○ To assign the role to an individual user, choose Assign in the Individual Users table.
○ To assign the role to a group of users, choose Assign in the Groups table, and enter the name of a
group.
3. Configure SAP Fiori launchpad for My Inbox.

For more information, see Configuring SAP Fiori Launchpad Objects [page 15].

Related Information

SAP Cloud Platform Portal documentation

2.1.1 Configuring SAP Fiori Launchpad Objects

As an administrator, you can import SAP Fiori launchpad objects shared by the workflow service. These objects
include the Workflow and My Inbox catalogs.

Prerequisites

● The TENANT_ADMIN role assigned to your user.

To check which roles are assigned to you, see Check the Roles Assigned to You [page 17].
For more information, see Services in the Cockpit in the SAP Cloud Platform documentation.
● An SAP Fiori launchpad site on your subaccount.
For more information about creating sites, see the SAP Fiori Launchpad Sites documentation.
For more information about creating content, see Add content to the page Typical Workflow of an
Administrator in the SAP Cloud Platform, portal service documentation.

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 15
Context

The configuration used for this procedure is only a sample. Depending on your requirements, the catalog
assignments and groups created might look different.

Procedure

1. Choose or create a site and prepare it to use standard workflow service content.

a. In the navigation area of the SAP Cloud Platform cockpit, choose Services Portal Service .
b. On the Portal Service tile, choose Enable, and then Go to Service.
c. In the navigation area, choose Site Directory.
d. Hover over the existing SAP Fiori launchpad site, and choose Edit.
2. To distribute the apps to all users, assign a role, for example, Everyone to the existing workflow catalog.

You can restrict access to apps using groups, so that, for example, only administrators can access the
Monitor Workflow and all users can access My Inbox.
a. In the navigation area, choose Content Management.
b. In the navigation area, choose Catalogs.
c. Select your Workflow Catalog, and choose Edit.
d. Choose Roles, and then choose the plus icon.
e. Select a role from the dropdown list, for example, Everyone.

For more information, see Creating and Configuring Roles in the SAP Cloud Platform documentation.
f. Confirm with OK, and choose Save.

3. For your users to see the newly created content, publish your site by choosing (Publish Site) in the
upper right corner.
4. To open the newly configured site, choose Site Directory, hover over the SAP Fiori launchpad site, and then
select the link on the site tile.

This is the link you typically share with your users so they can access the apps.

Results

The selected or created group name along with the app appears on the home page of the site.

SAP Cloud Platform Workflow in the Neo Environment

16 PUBLIC Administration
2.1.1.1 Check the Roles Assigned to You
To configure the SAP Fiori launchpad objects you need the TENANT_ADMIN role.

Procedure

1. In the navigation area of the SAP Cloud Platform cockpit, choose Services Portal Service .
2. Under Service Configuration, choose Configure Portal Service.
3. In the navigation area, choose Roles.
4. Select the TENANT_ADMIN role, and verify that your user is listed under User ID.
5. If your user ID is not listed, then assign this role to your user.

2.1.1.2 Configure My Inbox to Consume Tasks from

Another TCM-Compliant OData Provider

Context

By default, the My Inbox application, as part of SAP Cloud Platform Workflow, is preconfigured to consume
tasks from the workflow service.

You can configure My Inbox to connect to another TCM-compliant OData service, different from the SAP Cloud
Platform Workflow service.

This can be achieved by adding a new My Inbox application in the SAP Fiori launchpad configuration cockpit
and maintaining the respective tcmURL parameter.

 Note

Please note that the URL parameter name is case sensitive.

Example

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 17
You can expose this application as an SAP Fiori launchpad tile, which launches a separate instance of the My
Inbox application connected to the configured TCM-compliant OData service.

2.1.1.3 Define Scenario-Specific Tiles in My Inbox

A scenario is an aggregation of predefined task types exposed in a tile. In a scenario-specific tile the business
users are able to work only on tasks which are of specific, preconfigured task types. Whereas in the All Items
tile, business users see all the tasks they are responsible for regardless of the type of the tasks.

Context

With SAP Cloud Platform Workflow you can define scenario-specific tiles for My Inbox using the taskDefinitions
app parameter, so that the business users in your organization work more effectively with My Inbox. For more
information, see: Scenario-Specific Тiles [page 146].

Procedure

1. Open your SAP Cloud Platform subaccount, and go to Services.

2. Click the Portal Service tile and choose Go to Service. The SAP Fiori Configuration Cockpit opens.
3. Navigate to Site Directory and choose Edit for your site.

4. Navigate to Content Management Apps . Search for My Inbox and duplicate the My Inbox default app,
or create a new one that has the same properties.
5. Select the newly created tile and fill in the following information.
○ In the Properties tab:
○ In the General section, add an App Resource by choosing from the uploading list Cloud Platform,
Backend System, or Other Solutions.
○ In the General section, enter an App Title for your workflow scenario, for example, My Tasks
Scenario-specific tile.
○ In the General section, App Subtitle field, enter the subtitle of your workflow scenario, for example,
Employee Onboarding related tasks
○ In the Intent Navigation section, Semantic Object field, enter WorkflowTask.
○ In the Intent Navigation section, Action field, enter DisplayMyInbox.
○ In the App Resource Details section, enter a value in the SAPUI5 Component field, for example,
cross.fnd.fiori.inbox.
○ In the Catalogs tab, add a Catalog to your app, for example Workflow.
○ In the Visualization tab:
○ In the Tile Properties section, choose Dynamic App Launcher for the Tile Type.
○ In the Tile Properties section, choose a Title, for example, Employee Onboarding.

SAP Cloud Platform Workflow in the Neo Environment

18 PUBLIC Administration
 ○ Navigate to Dynamic Data Service URL and enter the service URL extended with the task
definitions.
○ Without any filters applied, the Service URL should look like as follows:

/bpmworkflowruntime/odata/v1/tcm/TaskCollection/$count/?
$filter=Status eq 'READY' or Status eq 'RESERVED' or Status eq
'IN_PROGRESS' or Status eq 'EXECUTED'

○ 1. Get the TaskDefinitionID of the tasks you would like to configure in the tile.

 Tip

To get the TaskDefinitionID, execute one of the following options:

1. From the All Items Tile in My Inbox select the task, which you would like to see in
the scenario-specific tile.
2. Go to the user menu and navigate to More Support Information , and
capture the TaskDefinitionID value.

2. Extend the Service URL in the following way using TaskDefinitionID parameter.
For example:

/bpmworkflowruntime/odata/v1/tcm/TaskCollection/$count/?
$filter=((Status eq 'READY' or Status eq 'RESERVED' or Status eq
'IN_PROGRESS' or Status eq 'EXECUTED') and (TaskDefinitionID eq
'usertask1@step1employeeonboarding' or TaskDefinitionID eq
'usertask2@step2employeeonboarding'))

○  Note

The list of TaskDefinitionIDs in the Service URL newly added task-based filter must
match the TaskDefinitionIDs in the TaskDefinitions parameter, so the tile counter
of the scenario-specific tile to match the number of tasks displayed after the application is
opened.

○ Icon: Use any of the available icons.

After you edit the Service URL parameter, it should look as follows:

○ Go to the Parameters tab of the newly created app and choose Edit. To configure a scenario-specific
tile, add taskDefinitions as parameter. Its value must be a comma-separated list of
TaskDefinitionIDs in the Launcher Value column. For example:

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 19
 ○
Parameter Default Value Launcher Value

massAction false -

substitution false -

tcmUrl /bpmworkflowruntime/ -
odata/v1/tcm

listSize 100 -

taskDefinitions - usertask1@step1employee
onboarding,usertask2@st
ep2employeeonboarding

 Note

○ If you duplicate the default My Inbox tile as described in step 4, make sure to place the
values of the parameters of the newly created tile in the Launcher Value column. This is
necessary because tiles with the same Intent are distinguished by the parameter values in
the Launcher Value column.

 Info

○ Please note that URLs consisting of more than 2000 characters might not work properly in
the most popular web browsers. Therefore, since the value of the taskDefinitions
parameter is included in the URL, it is recommended that its total length should not
exceed 1000 characters.
○ You can also configure the tcmUrl parameter with a different TCM-compliant task
provider. For more information, see Configure My Inbox to Consume Tasks from Another
TCM-Compliant OData Provider [page 17].

SAP Cloud Platform Workflow in the Neo Environment

20 PUBLIC Administration
 For reference, please, see the screenshot:

6. Save your newly created tile.

7. Publish the site by following the steps below:
○ Select the Publish Site from the right side of the Fiori Configuration Cockpit header.
○ Select the option Clear HTML5 application cache in the Publish Site dialog.
○ Click Publish and Open.

2.1.2 Connect My Inbox On-Premise to SAP Cloud Platform

Workflow

As an Administrator, you can connect SAP Cloud Platform Workflow to My Inbox on-premise, running on the
Gateway Hub system, so that the business users are able to work in a single My Inbox to manage all their tasks.

Prerequisites

● You have installed and configured My Inbox on-premise on a Gateway Hub system to support task
federation. For more information, see Central Hub Deployment and Task Gateway Service Configuration.
● You have installed SAP Web Dispatcher on-premise on the Gateway Hub system. For more information, see
SAP Note 908097 .

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 21
  Note

The SAP Web Dispatcher can be installed on a dedicated on-premise system as well without any
restrictions to end-to-end functionality.

Context

Connect SAP Cloud Platform Workflow to My Inbox on-premise so that the business users in your company can
use it as the single entry point for managing all their tasks - both those from your on-premise task provider
systems across your landscape and the ones from SAP Cloud Platform Workflow. The connection between the
on-premise Gateway Hub and SAP Cloud Platform for this setup is ensured by SAP Web Dispatcher, which acts
as a proxy server. It handles all browser requests from My Inbox on-premise. Based on predefined rules, SAP
Web Dispatcher routes synchronous requests to the SAP Cloud Platform to load the relevant task UI resources,
custom or standard actions, and task properties for the SAP Cloud Platform Workflow tasks.

 Note

Only one SAP Cloud Platform account can be added to My Inbox on-premise as a task provider for SAP
Cloud Platform Workflow.

To enable My Inbox on-premise to consume tasks from SAP Cloud Platform Workflow, do the following:

Procedure

1. Configure SAP Web Dispatcher

SAP Web Dispatcher comes with a .pfl file. The file provides options to configure hosts, ports, rules, and
so on, so that you can define how the SAP Web Dispatcher handles each request that it intercepts. Open
the .pfl file of SAP Web Dispatcher and change the default values of the properties as follows:
a. Configure the port that SAP Web Dispatcher listens to.
icm/server_port_<xx> = PROT=HTTPS,PORT=<port_number>

 Note

The <port_number> can be any open port. <xx> stands for a number. The numbers must start
from 0 and must be used in ascending order.

 Example

icm/server_port_2 = PROT=HTTPS,PORT=2080

b. Configure the path to the SAP Cloud Platform system.

wdisp/system_0 = SID=<Cloud Platfrom SID>,

EXTSRV=<absolute URL path to Cloud Platform Fiori Launchpad>,
SRCSRV=*:<port_number>, SRCURL=/html5apps/;
/sap/fiori/, SAML_IDP_SYSTEM=<SID of Gateway Hub system>,

SAP Cloud Platform Workflow in the Neo Environment

22 PUBLIC Administration
 SAML_SP_ENTITY_ID=<absolute URL path to Cloud Platform account>

 Example

wdisp/system_0 = SID=CAN,
EXTSRV=https://flpsandbox-
abcsampleaccount.dispatcher.int.sap.eu2.hana.ondemand.com,
SRCSRV=*:2080, SRCURL=/html5apps/;
/sap/fiori/, SAML_IDP_SYSTEM=XYZ,
SAML_SP_ENTITY_ID=https://int.sap.eu2.hana.ondemand.com/abcsampleaccount

c. Configure on-premise Gateway Hub system properties.

wdisp/system_1 = SID=<SID of Gateway Hub system>,

MSHOST=<Message Server host of Gateway Hub system>,
MSPORT=<Message Server port of Gateway Hub system>,
SRCSRV=*:<port_number>, SRCURL=/,
CLIENT=<SID of Gateway Hub system>, SSL_ENCRYPT=2

 Example

wdisp/system_1 = SID=XYZ,
MSHOST=ldcsxyz.mo.sap.corp,
MSPORT=8101,
SRCSRV=*:2080, SRCURL=/,
CLIENT=000, SSL_ENCRYPT=2

d. Configure the "first match” semantics.

If a matching conflict occurs, then the request is routed to the first configured system, that is wdisp/
system_0. In this case, this would be SAP Cloud Platform Workflow. For more information, see the
wdisp/system_0 descriptor in the final .pfl file provided as an example below.

wdisp/system_conflict_resolution = 1

e. Specify the location of rules file

icm/HTTP/mod_0 = PREFIX=/,FILE=<file path to rules.txt>

 Example

icm/HTTP/mod_0 = PREFIX=/,FILE=C:\webdispatcher_7.73\rules.txt

After the configuration is complete, the .pfl file should look similar to this example:

# Profile generated by sapwebdisp bootstrap

# unique instance identifier
SAPSYSTEMNAME = WDP
# unique instance number
SAPSYSTEM = 00
# add default directory settings
DIR_INSTANCE = C:\webdispatcher_7.73
DIR_EXECUTABLE = $(DIR_INSTANCE)
DIR_PROFILE = $(DIR_INSTANCE)
DIR_HOME = $(DIR_INSTANCE)
DIR_GLOBAL = $(DIR_HOME)
DIR_LOGGING = $(DIR_HOME)
Autostart = 1
Restart_Program_00 = local $(DIR_EXECUTABLE)\sapwebdisp$(FT_EXE) pf=$
(DIR_PROFILE)\sapwebdisp.pfl

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 23
 # SAP Web Dispatcher Ports
icm/server_port_0 = PROT=HTTP,PORT=1080
icm/server_port_1 = PROT=HTTPS,PORT=4300
icm/server_port_2 = PROT=HTTPS,PORT=2080
wdisp/system_conflict_resolution = 1
is/HTTP/show_detailed_errors = TRUE
icm/HTTP/trace_info=TRUE
wdisp/system_0 = SID=CAN, EXTSRV=https://flpsandbox-
abcsampleaccount.dispatcher.int.sap.eu2.hana.ondemand.com, SRCSRV=*:2080,
SRCURL=/html5apps/;/sap/fiori/, SAML_IDP_SYSTEM=XYZ,
SAML_SP_ENTITY_ID=https://int.sap.eu2.hana.ondemand.com/abcsampleaccount
wdisp/system_1 = SID=XYZ, MSHOST=ldcsxyz.mo.sap.corp, MSPORT=8101, SRCSRV=*:
2080, SRCURL=/, CLIENT=000, SSL_ENCRYPT=2
# number of parallel connections
icm/max_conn = 2000
# SAP Web Dispatcher Web Administration
icm/authfile = $(DIR_PROFILE)/icmauth.txt
icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,DOCROOT=./admin,AUTHFILE=$(icm/
authfile)
icm/HTTP/mod_0 = PREFIX=/,FILE=C:\webdispatcher_7.73\rules.txt

2. Configure the SAP Web Dispatcher rules.txt file.

This file informs SAP Web Dispatcher which requests should be redirected and how.

For this scenario, a prefix should be added for the requests that contain /html5apps or /
bpmworkflowruntime. My Inbox delivers these routes and appends them to the URL for SAP Cloud
Platform Workflow tasks. This way, the relevant requests are properly redirected to the SAP Cloud
Platform. This makes it possible to load task resources available on the SAP Cloud Platform, such as
custom task UIs, custom defined actions via API, standard actions, or task properties.

To configure the rules.txt file, copy and paste the following rules:

if %{PATH} RegIMatch ^/html5apps(.*)

RegIRedirectUrl ^/html5apps(.*) /sap/fiori/bpmmyinbox/html5apps$1
if %{PATH} RegIMatch ^/bpmworkflowruntime(.*)
RegIRedirectUrl ^/bpmworkflowruntime(.*) /sap/fiori/bpmmyinbox/
bpmworkflowruntime$1

3. Assign an alias for SAP Cloud Platform to the Gateway Hub.

To show SAP Cloud Platform Workflow tasks in My Inbox on-premise, a system alias has to be added to the
Task Gateway. This ensures that the requests from My Inbox on-premise are properly redirected to SAP
Cloud Platform. This configuration is done on the Gateway Hub system.

 Caution

The value of SAP System Alias must be NA.

To create an alias, follow the procedure described in Creating a System Alias.

SAP Cloud Platform Workflow in the Neo Environment

24 PUBLIC Administration
  Note

You may have already configured aliases in the Gateway Hub deployment option. In this case, just add a
new alias as described above.

4. Configure trust between the on-premise Gateway Hub and SAP Cloud Platform.

Configure SAML2 authentication between the systems. For more information, see Configure
Authentication. Perform the configuration described in all subtopics of the documentation structure.

 Note

Disregard the references to SAP CoPilot. The configuration is not restricted to SAP CoPilot.

5. Register the SAP Web Dispatcher as a proxy

For more information, see Register the SAP Web Dispatcher as a Proxy.

 Example

neo map-proxy-host --account abcsampleaccount --app-host flpsandbox-

abcsampleaccount.dispatcher.int.sap.eu2.hana.ondemand.com --proxy <WD
host>:2080 -h int.sap.eu2.hana.ondemand.com -u <username>

Results

As a result of the configuration, you can address My Inbox running on the SAP Gateway Hub on-premise
system via the SAP Web Dispatcher. In addition, the workflow tasks generated by SAP Cloud Platform
Workflow are provisioned to My Inbox, running on the SAP Gateway Hub system, together with all related
resources, such as custom task UIs and custom actions defined using the My Inbox API.

2.1.3 Configure the Workflow Service Mail Destination with

SAP Web IDE

Before you can send notification e-mails for service tasks, you must first configure a mail destination.

Prerequisites

● You have the details for configuring SMTP e-mail for your scenario.
● Your mail server has the following characteristics:
○ It supports the SMTP STARTTLS command on ports 587 or 465, because the workflow service
supports only STARTTLS on these ports.
○ It requires authentication, because the workflow service doesn't support unauthenticated logins.

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 25
Procedure

Create a destination in the SAP Cloud Platform cockpit.

For more information, see Configuring Destinations from the Cockpit.

○ To import a destination:
1. Save the template as a file.

Type=MAIL

Name=bpmworkflowruntime_mail

mail.user=
mail.password=

mail.smtp.host=mail.example.com
mail.smtp.port=587
mail.transport.protocol=smtp
mail.smtp.starttls.required=true
mail.smtp.starttls.enable=true
mail.smtp.auth=true

mail.smtp.from=cpworkflow@example.com
mail.smtp.ssl.checkserveridentity=true

mail.bpm.send.disabled=false

2. Import the destination from the file, and set the values for user, password, host, port, and from
address.
○ To create a destination, use the following data and properties.

Field Value

Name bpmworkflowruntime_mail

Type Mail

Description Text that describes the destination, for example, Workflow service mail
destination

User User for logging in to the mail server

Password Password for logging in to the mail server

Property Value

mail.transport.protocol smtp

mail.smtp.auth true

mail.smtp.starttls.require true
d

SAP Cloud Platform Workflow in the Neo Environment

26 PUBLIC Administration
 Property Value

mail.smtp.host Host name of your mail server

mail.smtp.port Port on which your mail server listens for connections (typically 587, in rare cases
465)

mail.smtp.from Mail address to use as the "From" address of mails sent by the workflow service,
for example, cpworkflow@example.com.

This address must belong to an existing mailbox because it receives the replies to
mails that the workflow service sends.

mail.smtp.ssl.checkserveri (Optional) true or false; default is true if no value is provided.

dentity

mail.smtp.ssl.trust * or a space-separated list of acceptable host names.

If you don't provide a value, trust is based on the certificate provided by the server,
which must be part of the SAP JVM default truststore. For more information, see
Trusted Certificate Authorities for Outbound SSL Connections.

mail.bpm.send.disabled ○ true
Turns off interaction with the mail server, for example, temporarily while you
develop a workflow.
○ false

For more information about the properties, see the JavaMail API documentation.

 Note

Only the above properties are evaluated. Other properties that are configured in the mail destination
have no effect. However, for an optimal operation of the mail functionality, the workflow service might
apply additional properties, such as connection timeouts.

2.1.4 Configuring Principal Propagation for Service Tasks

When starting a workflow or completing a task of a particular workflow instance, you can use principal
propagation to forward the information about who is logged on to the services. The information is propagated
throughout the workflow.

Before you can use principal propagation, the following one-time configurations are required:

● An OAuth 2.0 client with Authorization Code Grant. For more information, see Create an OAuth 2.0 Client
with Authorization Code Grant [page 28].
● A destination that uses the OAuth credentials of the configuration parameters for the workflow service. For
more information, see Create an OAuth Destination [page 29].

One destination for each service that is called. For more information, see Destinations [page 152].

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 27
2.1.4.1 Create an OAuth 2.0 Client with Authorization Code
Grant

To use principal propagation to forward the information about who is logged on to the services, you first need to
create an OAuth client.

Procedure

1. Register a new OAuth client as described in OAuth 2.0 Configuration.

2. Make note of the Authorization Endpoint and the Token Endpoint URLs, as you'll need them later for other
configurations.
3. Specify the client configuration as follows:

Field Comment

Name Enter a name, for example Cloud Platform Workflow OAuth

Client for Principal Propagation.

Subscription Choose your SAP Cloud Platform Workflow subscription. That is, the entry
that ends with bpmworkflowruntime.

ID Use the client ID that's automatically assigned, or regenerate a new one.

Make note of this ID, as you'll need it for other configurations.

Authorization Grant Authorization Code

Confidential Select this option.

Secret Enter the secret, for example, a password. Make note of this, as you'll need it
for other configurations.

Skip Consent Screen Select this option.

Redirect URI Enter the service host, ending in /workflow-service.

Example: bpmworkflowruntime<providerid>-
<subscriberaccountid>.<region>.hana.ondemand.com/
workflow-service

For more information, see Determine the Service Host [page 130].

Token Lifetime 5 minutes

SAP Cloud Platform Workflow in the Neo Environment

28 PUBLIC Administration
 Field Comment

Refresh Token Lifetime Leave empty for unlimited lifetime.

This configuration setting is mandatory. Otherwise, that is, if the lifetime of

the refresh token is not set to unlimited, long running workflow instances
with principal propagation might fail.

2.1.4.2 Create an OAuth Destination

To use principal propagation to forward the information about who is logged on to the services, you first need to
create an OAuth destination.

Prerequisites

To configure destinations, use the standard SAP Cloud Platform mechanisms in the SAP Cloud Platform
cockpit. For more information, see Configuring Destinations from the Cockpit.

Log in to the cockpit and open the Destinations editor.

Context

 Note

If there are running, erroneous, or suspended workflow instances with principal propagation, changes to
the OAuth client mentioned in the previous step and the corresponding bpmworkflowruntimeoauth
destination make these instances fail as soon as service tasks are reached. It’s extremely costly to recover
such instances.

Procedure

Create an OAuth destination named bpmworkflowruntimeoauth for the SAP Cloud Platform Workflow
runtime using the following values:

Field Value

Type HTTP

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 29
Field Value

Description Enter a text, for example, Cloud Platform Workflow OAuth

Destination for Principal Propagation.

URL Set the destination URL to the authorization endpoint URL from (Create an OAuth 2.0
Client with Authorization Code Grant [page 28]) and remove the path parts. Enter, for
example, a URL that is similar to https://oauthasservices-
<accountid>.<region>.hana.ondemand.com.

Proxy Internet

Authentication Basic Authentication

User Set the user to the client ID from Create an OAuth 2.0 Client with Authorization Code
Grant [page 28].

Password Set the password to the secret from Create an OAuth 2.0 Client with Authorization
Code Grant [page 28].

2.2 Export Workflow Service Data

The export provides access to your business data stored within the workflow. You can use this data to address,
for example, audit needs.

Prerequisites

You have the WorkflowTenantOperator role that allows you to export runtime data related to workflow
definitions, form definitions, workflow instances, and task instances.

Context

 Caution

The export doesn’t contain technical details that are required to reimport the data to the workflow service.

You can export the following types of data from the workflow service:

● Design time or modeling artifacts from the workflow editor.

For more information, see Transport Workflows between Accounts [page 75] in the Neo environment.
● Runtime artifacts from the workflow service using the workflow service API.

SAP Cloud Platform Workflow in the Neo Environment

30 PUBLIC Administration
 You export data related to a workflow definition, form definition, a workflow instance, or a task instance.
The exported data and format is based on the workflow service REST APIs, see Using Workflow APIs [page
125].

The following procedure describes the export of the runtime artifacts.

Procedure

To export the data, enter the following URL: https://<host>/workflow-service/rest/v1/export.

For more information, see Determine the Service Host [page 130].

Results

 Caution

To verify that the export completed successfully, please check that you can extract the zip archive. The
archive shouldn’t contain a file named error-log.txt. If there’s an error-log.txt file, the exported
data might be corrupt. Check the file for details.

The export call returns a zip file that contains the following:

● A readme.txt file that contains meta information about this specific export.
● A form-definitions.json file that contains a list of the latest deployed form definitions.
● A workflow-definitions.json file that contains a list of the latest deployed workflow definitions.
● A workflow-instances.json file that contains a list of all workflow instances available on the system.
The custom workflow attributes are contained in each entry of the list.
● A workflow-instance-data folder: For each workflow instance on the system one file (<workflow-
instance-ID>.json) is written. It contains the latest details related to this instance including, for
example, context data and the execution log.
● A task-instances.json file that contains a list of all task instances available on the system.
The custom task attributes are contained in each entry of the list.
● A form-definition-data folder: For each form definition on the system one file (<form-definition-
ID>.json) is written. It contains form definition metadata of all versions deployed.

SAP Cloud Platform Workflow in the Neo Environment

Administration PUBLIC 31
2.3 Deactivate the Workflow Service

Administrators of the SAP Cloud Platform account can disable the SAP Cloud Platform Workflow.

Prerequisites

● A global account in your respective region.

For more information, see Getting a Global Account.
● Your user is a member of the subaccount and is assigned to the Administrator role for the subaccount. You
need this role to execute the following configuration steps.
For more information, see Subaccount Member Roles.

Context

 Caution

If you deactivate your workflow service, you also delete all data from the database, the subscription, and
the database bindings.

Currently, deactivating the service does not delete:

● The assignment between users and workflow service roles

● HTTP destinations
● Portal content

 Note

If you later reenable the workflow service, the items that were not deleted become active again.

Procedure

In the SAP Cloud Platform cockpit, disable the SAP Cloud Platform Workflow service for your subaccount.
a. In the navigation area, choose Services.
b. Search for SAP Cloud Platform Workflow.
c. On the Workflow tile, choose Disable.

SAP Cloud Platform Workflow in the Neo Environment

32 PUBLIC Administration
3 Developing Applications with Workflow
Service

Developer tasks for the SAP Cloud Platform Workflow service that are executed in the workflow editor or in the
workflow runtime.

Related Information

Concepts [page 5]
Modeling a Workflow [page 33]
Create a Workflow Sample Application with SAP Web IDE [page 82]
Creating User Interfaces [page 83]
Build and Deploy Workflows [page 76]
Using Workflow APIs [page 125]

3.1 Modeling a Workflow

You can model a workflow using the workflow editor in SAP Web IDE Full-Stack. The editor enables IT
specialists to create workflows using SAP Web IDE Full-Stack.

 Note

● The workflow editor is available only in Neo regions where the SAP Cloud Platform Workflow service is
offered.
● The workflow editor does not support Safari browser.

Modeling a workflow includes the following steps, which you can perform using the workflow editor in SAP Web
IDE Full-Stack:

● Defining a start point of the workflow: Define a start point of the workflow using the start event. For more
information, see Events [page 67].
● Defining workflow steps and their sequence: Define the process steps using the following graphical objects:
○ Tasks: There are user tasks that are performed by a human or a mail program, service or script tasks
that are performed by the system. For more information, see Tasks [page 39].
○ Gateways: Gateways control the flow of execution in a workflow. For more information, see Gateways
[page 71].
● Defining an endpoint of the process: Defines an endpoint of the process using end event or terminate end
event. For more information, see Events [page 67].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 33
Related Information

Enablе the Workflow Editor in SAP Web IDE [page 34]

Create a New Workflow Project with SAP Web IDE [page 34]
Build and Deploy Workflows [page 76]
Accelerated Modeling with Speed Buttons [page 77]
Expressions [page 79]

3.1.1 Enablе the Workflow Editor in SAP Web IDE

You must enable the workflow editor extension to model workflows in SAP Web IDE Full-Stack.

Prerequisites

You have enabled the SAP Web IDE Full-Stack version. You must use the SAP Web IDE Full-Stack version. For
more information, see Opening SAP Web IDE.

Procedure

1. Log in to the SAP Web IDE application.

2. From the left sidebar, open the Preferences perspective by choosing  (Preferences).
3. Choose Extensions.
4. Enable the Workflow Editor extension by using the toggle.
5. Choose Save.
6. Reload SAP Web IDE by choosing Refresh.

3.1.1.1 Create a New Workflow Project with SAP Web IDE

Context

A workflow project can hold one or more workflows. We recommend that you package all workflows for one
scenario into a single project. You can only deploy workflows created within this project; that is, you cannot
deploy the workflow project itself.

SAP Cloud Platform Workflow in the Neo Environment

34 PUBLIC Developing Applications with Workflow Service
Procedure

1. Log in to the SAP Web IDE Full-Stack application.

2. From the left pane, choose  (Development) and navigate to the Workspace folder.

3. Choose File New Project from Template .

4. On the Template Selection screen, choose Category as Business Process Management.
5. Choose the Workflow Project tile, then choose Next.
6. On the Basic Information screen, enter a project name, then choose Next.
7. On the Workflow Details screen, provide a workflow name and optional description.
8. Choose Finish.

 Note

To create multiple workflows, you can select a workflow project or the workflow folder and choose
New Workflow . By providing the name for the workflow, you can create another workflow within a
project or the workflow folder.

 Recommendation

We recommend that you create workflows in the workflow folder.

Results

The project wizard creates a project structure in the workspace. The project contains a workflow folder with a
new sample workflow file. The workflow file contains the name that you have provided in the previous steps.

3.1.1.2 Open Workflow Files in the Workflow Editor with

SAP Web IDE

Open existing workflow files in the workflow editor to view or modify them.

Procedure

1. Log in to the SAP Web IDE application.

2. From the navigation pane, choose  (Development), and navigate to the Workspace folder.
3. Select the multitarget application (MTA) project, and navigate to the workflow module.
4. Navigate to the workflows folder in the context menu of your workflow file, and choose Workflow Editor.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 35
3.1.2 Editor Layout

The workflow editor consists of the following areas:

● Canvas: The canvas renders and models the workflow, which connects flow objects such as events, tasks,
and gateways.
● Palette: The palette contains flow objects, for example, events, tasks, and gateways. You can easily model
your workflow by selecting the required flow object in the palette and placing it on the canvas using click
and drop.
● Toolbar: The toolbar contains tools such as undo, redo, delete and auto layout options.
● Properties: The properties view provides configuration options for flow objects.
● Diagram Overview: When a workflow model is bigger than the canvas layout, diagram overview can help
you visualize where the current view is in the diagram. Also, you can navigate to the required part of the
workflow.

3.1.3 Define Workflows

You use this procedure to define workflows.

Context

As an alternative to defining workflows step-by-step, you can use a sample application. For more information,
see the Related Links.

Procedure

1. Open the workflow with the Workflow Editor.

SAP Cloud Platform Workflow in the Neo Environment

36 PUBLIC Developing Applications with Workflow Service
 For more information, see Open Workflow Files in the Workflow Editor with SAP Web IDE [page 35].
2. In the Subject field of Workflow Properties pane, provide the text that helps you identify the workflow
instances started for this workflow definition.

 Example

For the employee onboarding process, you can consider a Subject like “Employee onboarding
process initiated for ${context.employeename}”. For more information, see Expressions
[page 79].

 Note

○ For more information on character limits for workflow service, see Conventions, Restrictions, and
Limits [page 9].
○ The data accessed in expressions must be available at the latest when the expression is resolved,
for example, when creating a user task. If the data isn’t available, some parts of the expression, or
the whole expression won't be resolved. For more information, see Workflow Definition versus
Workflow Instance [page 6].
○ A workflow definition ID is generated for every workflow that you model. This ID is used when you
start a new workflow instance. For more information, see the Workflow Instances section in Using
Workflow APIs [page 125].

3. In the Business Key field under the General tab of the Workflow Properties pane, provide an optional
identifier for workflow instances based on business data.

The business key can include static text as well as expressions similar to the workflow subject. With the
business key, you can later identify a workflow instance without knowing the technical instance ID.

 Example

For the employee onboarding process, you can consider a business key based on the unique employee
ID, for example, "${context.employeeid}". With this you can, for example, search for a specific workflow
instance using the employee ID instead of the technical workflow instance ID.

 Note

In SAP Cloud Platform Workflow uniqueness isn’t enforced for business keys neither globally nor within
a specific workflow definition. If you require a one-to-one relationship between a business key value
and a workflow instance, make sure that you use business data within your business key expression
that uniquely identifies the entities processed within the workflow. You can, for example, use the order
ID or the employee ID.

4. Navigate to the Attributes tab under Workflow Properties pane to add the attributes for a workflow. To
configure these attributes, see Configure Custom Workflow Attributes [page 74].

 Note

Workflow attributes can only be used in combination with the SAP Cloud Platform Process Visibility
service and with the workflow service REST API.

5. To model the start event of a workflow, select  Events Start Event and drop it onto the canvas from
the palette.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 37
6. In the Start Event Properties pane, provide a name and documentation for the start event.

 Note

A unique ID gets generated for every workflow artifact. This ID is in read-only mode.

7. (Optional) Configure a sample context while modeling a start event. After the deployment of the workflow,
the sample context is displayed in the Monitor Workflows app while starting a new workflow instance. For
more information, see Configure Start Events [page 67].

You can also retrieve the configured sample context using the Public API. For more information, see SAP
Cloud Platform Workflow API
8. To add a task to the workflow, see Tasks [page 39].
9. To add a gateway to the workflow, see Gateways [page 71].
10. To add an intermediate message event, see Configure Intermediate Message Events [page 69].
11. To add an intermediate timer event, see Configure Intermediate Timer Events [page 70].

12. To connect two flow elements, choose the icon.

 Note

If you choose a flow element using the speed button, the connection automatically appears. In this

case, the above step isn’t required. To connect two flow elements, choose the icon, keep the
mouse button pressed on the required flow element and move your cursor to the next flow element
that needs to be connected in the workflow.

For more information about speed buttons, see Accelerated Modeling with Speed Buttons [page 77].

13. To model the end event of a workflow, choose  Events End Event and drop it onto the canvas from
the palette.
14. In the End Event Properties pane from the first flow pane, provide a name and documentation for the end
event.

15. To model the end of a workflow as a terminate end event, choose  Events Terminate End Event and
drop it onto the canvas from the palette.
For more information on the terminate end event, see Events [page 67].

 Note

You can also model a terminate end event using the speed buttons. For more information, see
Accelerated Modeling with Speed Buttons [page 77].

16. In the Terminate End Event Properties Properties pane, provide a name and description for terminate end
event.
17. To format the workflow model, choose  Arrange Horizontally or  Arrange Vertically from the toolbar.
18. Choose Save.

 Recommendation

○ We recommend that you save the changes before exiting. If you don’t, your changes are lost.
○ Each time you change the properties of flow elements, make sure that you press the ENTER key.

SAP Cloud Platform Workflow in the Neo Environment

38 PUBLIC Developing Applications with Workflow Service
3.1.3.1 Tasks

SAP Cloud Platform Workflow editor supports the following tasks:

● User Task: A flow object that illustrates a task that a human performs. User tasks appear in My Inbox where
the processor of the task can complete the task instance, and view its description.
● Service Task: A flow object that illustrates a system task, for example, calling an external service. A service
task is performed immediately, when the process execution arrives at it.
● Script Task: A flow object that illustrates a script that gets executed when the process execution arrives at
it. This is an automated activity.
● Mail Task: A flow object that you configure to send e-mails to one or more recipients.

Related Information

Configure User Tasks [page 39]

Configure Service Tasks [page 50]
Configure Script Tasks [page 55]
Configure Mail Tasks [page 64]

3.1.3.1.1 Configure User Tasks

You must use this procedure when you want a user to perform a particular task in the workflow.

Prerequisites

To ensure that end users can view tasks in custom UIs in My Inbox, the following configuration steps are
required:

● Deploy a custom task UI application and ensure that it is up and running in the consumer subaccount. See
Creating a Workflow Form [page 107].
● Ensure that the application contains the SAPUI5 component, which is used as custom task UI.

Context

As a workflow developer, you must be able to associate a custom task UI in the customer application with a
workflow user task. In this way, when an end user opens his or her task on My Inbox, the custom task UI is
rendered.

You can propagate the user who completes a task to a service called later by a service task in the same
workflow instance. For more information, see Configure Service Tasks [page 50].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 39
Procedure

1. Choose (Tasks), then User Task from the palette and drop it on to the canvas.
2. Select the user task icon that you dropped on the canvas.
3. In the User Task Properties area, choose the General tab.
4. Provide a Name and Documentation for the user task.

 Note

○ For more information on character limits for workflow service, see Conventions, Restrictions, and
Limits [page 9].
○ A unique ID gets generated for every workflow artifact. This ID is in read-only mode.
○ Ensure the Name field is short, precise, and contains a sufficiently unique identifier, as it is
displayed to the end users. For example, in My Inbox.

5. (Optional) To display information about the task execution in the inbox workflow log, select Show in inbox
workflow log.
6. From User Task Properties area, choose the Details tab.
7. Depending on the priority of the user task, choose one of the following options from the Priority menu:
○ Low
○ Medium (default)
○ High
○ Very High

 Note

Priority is reflected in My Inbox using which the end user can sort, filter, and group the tasks. For more
information, see Working with Tasks in My Inbox [page 140].

8. In the Display Texts section, provide the following details:

○ Subject: Title of the task instance.

○ Description: Any additional information.
9. In the Recipients section, provide the unique IDs of the users or name of groups of users in Users or Groups
who should process the task.

 Note

○ Subject, Description, Users, and Groups can also refer to the dynamic workflow context. For
example, if you want to provide a Subject that references a variable from dynamic context, you can
specify the expression in Subject field as "Approval for ${context.employee.name}". For
more information, see Expressions [page 79].
For users and groups, either use a context reference that resolves to a string with different users or
groups separated by commas or a context reference that resolves to an array of strings.
○ To provide multiple users or groups of users to process the task, separate each unique ID with a
comma.
○ You can assign a maximum number of 100 users or groups as recipients to a user task.
○ Recipients can view these tasks in My Inbox. They can also complete these tasks, which further
proceed the workflow execution.

SAP Cloud Platform Workflow in the Neo Environment

40 PUBLIC Developing Applications with Workflow Service
 10. To configure the duration by when the task is due (date relative to the task creation time), select the
Configure Due Date checkbox.
You must configure the due date using the following substeps:
a. To provide a duration for the due date as an expression, choose Expression from the Due Date Based
On dropdown. Now, provide the due date in the Duration field as an expression.

 Note

You must provide an expression in the Duration field using a subset of the ISO 8601 format. For
example, PT${context.minutes}M. The JUEL expression ${context.minutes} is evaluated at
runtime. You can provide multiple duration attributes by using multiple JUEL expressions. For more
information about the duration formats that are supported in ISO 8601, see Conventions,
Restrictions, and Limits [page 9].

b. To provide a duration for the due date as a static value, choose Static Value from the Due Date Based
On dropdown. Now, provide the due date in the Duration field as a numeric value, and choose a Unit of
Time.

 Note

Due date is reflected in My Inbox using which the end user can sort and filter the tasks. For more
information, see Working with Tasks in My Inbox [page 140].

11. Configure a custom task user interface.

You have the following options:

○ Configure a User Task UI Using Workflow Forms [page 44]
12. Assign custom attributes to a user task. For more information, see Configure Custom Task Attributes
[page 45].
13. (Optional) To include a timer for the user task, add a boundary timer event. For more information, see
Configure Boundary Timer Events [page 42].
14. Connect the user task to the required flow elements.
15. Choose Save.

Related Information

Accelerated Modeling with Speed Buttons [page 77]

Configure Boundary Timer Events [page 42]
Conventions, Restrictions, and Limits [page 9]

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 41
3.1.3.1.1.1 Configure Boundary Timer Events

Configure a boundary timer event to trigger an alternative flow if a user task doesn't finish within a specified
time duration.

Context

Boundary timer events are attached to a user task. Some user tasks may need to be completed during a
certain time interval. You can add a boundary timer event to define the duration of time for which the flow can
wait at the user task before starting an alternative flow. There are two types of boundary timer events:

● Canceling Boundary Event: When this event is triggered, it cancels the user task it is attached to.
● Non-Canceling Boundary Event: When this activity is triggered, it does not cancel the user task it is
attached to.

 Example

In an employee onboarding scenario, the equipment assignment to a new hire must be confirmed by
the buddy assigned to the new hire. The buddy is responsible for confirming the equipment that needs
to be procured for the new hire.

A non-canceling boundary timer event can be modeled on the "Confirm or Change Equipment" user
task to send a reminder mail to the buddy if the task is not completed in three days. Similarly, a
canceling boundary timer event can be modeled where the duration is such that the timer elapses two
days before the joining date of new hire. Additionally, an alternative escalation flow, such as an
escalation email, must be sent to the manager of the buddy to take required action; in this case, the
original "Confirm or Change Equipment" task becomes irrelevant. Hence, the 'Confirm or Change
Equipment' user task is canceled.

Procedure

1. Choose Boundary Timer from the speed button of the required user task.
2. Provide a Name and Documentation for the boundary timer event.
3. In the Boundary Timer Event Properties area, choose the Details tab.
4. Provide the waiting duration for the flow in the Duration (date field relative to the task creation time). You
can use one of the following ways to configure this field:
○ To use expressions, choose Expression from the Duration Based On dropdown.

 Note

You must provide an expression in the Duration field using a subset of the ISO 8601. For example,
PT${context.minutes}M. The JUEL expression ${context.minutes} is evaluated at runtime.
Consider specifying an expression that evaluates to a string containing only digits. This avoids
ambiguous data type conversions. You can provide multiple duration attributes by using multiple

SAP Cloud Platform Workflow in the Neo Environment

42 PUBLIC Developing Applications with Workflow Service
 JUEL expressions. For more information about the duration formats that are supported in ISO
8601, see Conventions, Restrictions, and Limits [page 9].

○ To use a static value, choose Static Value from the Duration Based On dropdown. Now, provide the
Duration as a numeric value, and choose a Unit of Time.
○ To use the due date value as the duration, choose Task Due Date from the Duration Based On
dropdown.

 Note

Duration for the boundary timer event is set to the due date value provided in the respective user
task.

5. To define the boundary timer event as canceling, select the Cancel Task checkbox.
6. Choose Save.

 Note

○ You can add multiple boundary timer events to a user task, which gets triggered when the
corresponding timers are fired. When a canceling boundary event is triggered, any boundary
events attached to the same task that haven't yet triggered are canceled.
○ One specific case needs to be taken into account: namely, suspending and resuming a workflow
instance with several boundary timer events on an active user task. If such an instance is resumed
and it has been suspended for a time period longer than the corresponding timer durations, there
is no deterministic order in which the events are triggered.
○ When you add multiple boundary timer events, they are placed on the same position at the bottom
of the user task. This may lead to several events on top of each other. However, these events can be
moved along the boundary of the user task.

3.1.3.1.1.2 Create a Basic Task User Interface for a User Task

You can create a basic task user interface that can be customized for your use case.

Context

After customizing the basic task UI, you can deploy the same and use it while configuring a user task.

Procedure

1. Log in to the SAP Web IDE Full-Stack application.

2. From the left pane, choose  (Development).

3. In the context menu of the required workflow project, choose New Workflow Task UI .

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 43
4. In the Component Information screen, provide a name for the SAPUI5 component.

 Note

This is the folder name for a particular task UI.

5. Choose Next.
6. In the confirmation tab, choose Finish.

Results

A new folder is created under the workflow project, which contains the generated SAPUI5 Component. You can
modify this as per your requirement.

3.1.3.1.1.3 Configure a User Task UI Using Workflow Forms

Procedure

1. In the workflow editor, select the user task and choose User Interface.
2. Under Type, choose Form.
3. Under Form Details, choose one of the following options:

○ Create File
On the New Form dialog, enter the following data:

Field Description

Name Name of the form you create

ID Identifier of the new form

Revision Revision of the form

For more information, see Versioning Forms [page 121].

○ Select
On the Select Form dialog, enter the following data:

SAP Cloud Platform Workflow in the Neo Environment

44 PUBLIC Developing Applications with Workflow Service
 Field Description

Project Name Name of the project. The name is preset to the current project and you cannot
change it.

File Name Name of the form from the list of forms that are available in the current project
only

Form Revision Revision of the form

For more information, see Versioning Forms [page 121].

For more information on forms, see Creating a Workflow Form [page 107].

4. Save the workflow.

The form is created in a separate forms folder within the workflow project in a folder named exactly like the
workflow for which the form is created.

Related Information

Configure User Tasks [page 39]

3.1.3.1.1.4 Configure Custom Task Attributes

You can assign custom task attributes to user tasks.

Context

With custom task attributes, you can define business-related properties and assign them to user tasks, such as
project ID or project name.

At runtime, you can use the respective workflow service API or Inbox API to search for custom task attributes
or to find the respective task instances. For more information about the characteristics of the various APIs, see
Using Workflow APIs [page 125].

Procedure

1. Choose the Attributes tab.

2. To add a row, choose Add.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 45
  Note

You can reorder the added custom attributes by using Move Up or Move Down.

3. Provide the following details in the table:

Name Description

ID A unique identifier of the attribute within a user task.

 Note
You can only use alphanumeric characters as ID and it must only start with an alphabet.

Label A human readable name of the attribute, which appropriate user interfaces can use to label
the attribute.

Type Data type of the attribute.

 Note
Currently, only the data type string is supported.

Value A constant or an expression, which gets resolved upon task creation.

For JUEL expressions, only the ${context.xyz} subset is supported. ${info}, ${roles},
and ${usertasks} aren’t supported.

A complete array isn’t resolved in JUEL expressions. For ${context.aArray}, for example,
values of that kind of expression always resolve to null. However, for a single array element it
resolves, for example, ${context.aArray[0]}.

A complex object is also not resolved in JUEL expressions. For ${context.complexObject},

for example, values of that kind of expression always resolve to null. However, for a single ob­
ject element it resolves. For example, ${context.complexObject.primitiveProperty}
resolves to the value of the primitive property.

${context} doesn’t contain any node. It’s also not supported and its value always resolves to
null.

 Note

Labels as well as the order, in which the corresponding APIs return the task attributes, are taken from
the latest versions of the workflow definition where these attributes are present.

A user task can contain up to 15 attributes at a time. For more information, see Conventions,
Restrictions, and Limits [page 9].

4. Save the changes.

SAP Cloud Platform Workflow in the Neo Environment

46 PUBLIC Developing Applications with Workflow Service
Related Information

Configure User Tasks [page 39]

Display Custom Attributes in My Inbox [page 47]

3.1.3.1.1.4.1 Display Custom Attributes in My Inbox

You can display business-related data that is assigned to your tasks, also known as "custom attributes", in My
Inbox, for example, the project ID or project name. These can be custom attributes with predefined names or
other custom attributes assigned to your tasks.

Context

The custom attributes with predefined names allow you to replace the task title or the task creator information,
display a KPI indicator, display a KPI unit, and display an additional custom attribute. This data is displayed in
specific places , reserved explicitly for this type of data, in My Inbox.

With the default UI of My Inbox, the custom attributes that are visible in the Task List are also displayed in the
Details View header data or in the Workflow Log tab, depending on their relevance.

 Note

If you are using a custom UI and you have replaced the default UI of My Inbox, the custom attributes with
predefined names will only be visible in the Task List or the Workflow Log of My Inbox.

The predefined custom attributes are CustomTaskTitle, CustomNumberValue, CustomNumberUnitValue,

CustomObjectAttributeValue, and CustomCreatedBy.

Custom Attribute Usage Visualization

CustomTaskTitle Customizes the task title ● Task List

● Details view header of the standard
My Inbox Task UI
● Title column in the Expert view

CustomNumberValue Displays a KPI indicator ● Task List

● Details view header of the standard
My Inbox Task UI

CustomNumberUnitValue Displays a KPI unit ● Task List

● Details view header of the standard
My Inbox Task UI

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 47
Custom Attribute Usage Visualization

CustomObjectAttributeValue Displays additional contextual informa­ ● Task List

tion
● Details view header of the standard
My Inbox Task UI

CustomCreatedBy Customizes the name of the task crea­ ● Task List

tor ● Details view header of the standard
My Inbox Task UI
● Workflow Log tab - only in the task
creation record
● Created by column in the Expert
view

To use custom attributes with predefined names or other custom attributes assigned to your tasks, do the
following:

Procedure

1. To create a custom attribute with a predefined name, use one of the following titles as the attribute ID:
○ CustomTaskTitle
○ CustomNumberValue
○ CustomNumberUnitValue
○ CustomObjectAttributeValue
○ CustomCreatedBy

My Inbox maps the predefined names to the specific locations in the Task List. For more information, see
Configure Custom Task Attributes [page 45].

If you are using the default UI of My Inbox, the predefined custom attributes are displayed in the Task List
and in the Details view header.

The predefined custom attributes are not displayed in the Description tab of the Details view of the selected
task. This area is reserved for the visualization of general custom attributes. For more information, see
Step 2.

 Note

This feature is disabled by default in My Inbox. To enable it, the administrator has to configure the
additional showAdditionalAttributes=true parameter in the app configuration of My Inbox.

When CustomCreatedBy is used, the profile link and profile picture of the user in the Workflow Log tab are
disabled.

 Note

The value of CustomObjectAttributeValue may be truncated in the Task List. Its entire value is
shown in a tooltip when you hover over the object.

SAP Cloud Platform Workflow in the Neo Environment

48 PUBLIC Developing Applications with Workflow Service
  Example

2. (Optional) To assign custom attributes to your tasks, see Configure Custom Task Attributes [page 45].

With the default task UI of My Inbox, the custom attributes are shown in the task description.

 Note

A fallback UI is created if the UI designated at design time fails to render due to textual errors, or if the
MTA containing the SAPUI5 elements is not deployed.

 Example

 Note

You can define up to 15 other custom attributes per task, which are displayed in the information tab of
the default task UI of My Inbox (if no custom UI is configured). If you use a custom task UI, these

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 49
 custom attributes are not displayed. In this case, at runtime, you can use the respective Workflow
ServiceAPI or Task Consumption ModelAPI to search for custom attributes or to find the respective
task instances. For more information about the APIs, see Using Workflow APIs [page 125].

3. Display custom attributes in the Expert View of My Inbox.

All custom attributes, besides the predefined custom attributes, are displayed as columns in Expert View
whenever you filter the task list by task type.

 Note

Different set of tasks might expose different set of custom attributes. The table will contain columns for
each custom attribute.

You can also sort and filter the task list based on custom attributes.

To display custom attributes, follow the steps below:

○ Choose Filters button to open the Filters dialog
○ Select at least one Task Type from the dropdown menu.
○ (Optional) To filter the task list by a custom attribute, use the value help to provide a value for the
selected field.
○ (Optional) To display a search box in the Filter Bar of the Expert View for a given entry in the Filters
Dialog, select the Show on Filter Bar checkbox for the selected entry.
○ Choose Go button to apply your changes.
○ The custom attributes, configured for the chosen Task Types will be added as columns in the table.

 Note

To sort by custom attribute value, use the Sort button available in the table header.

3.1.3.1.2 Configure Service Tasks

If you want the system to perform a particular task in the workflow, configure a service task.

Context

The execution of service tasks is subject to resource limits, for example, with respect to network timeouts. If
the target service doesn’t comply with the time restrictions described in Conventions, Restrictions, and Limits
[page 9], the connection with the target service is aborted, the service task fails, and the workflow instance is
put into the ERRONEOUS state.

Long execution times negatively impact the execution of other tasks of a specific tenant, because there’s only a
limited number of parallel executions allowed for a tenant. The resource limits enforced by the workflow service
therefore have the purpose of freeing up resources as early as possible for other tasks.

 Tip

We recommend that the service execution time is much less than the limits documented in Conventions,
Restrictions, and Limits [page 9]. If high execution times are common, consider building an intermediate

SAP Cloud Platform Workflow in the Neo Environment

50 PUBLIC Developing Applications with Workflow Service
 service that initiates asynchronous processing of the actual service call and returns quickly. It can report
back the execution result with the help of Configure Intermediate Message Events [page 69].

 Note

Workflow service executes automatic retries when a service task fails. Ensure that these retries can
complete successfully, for example, after administrative intervention and even in case of communication
failures. Such cases may occur, for example, when the client doesn’t receive the information about the
actual server-side success of the call. If the called services aren’t appropriately implemented, that is, they
aren’t idempotent, the retries from the workflow service might fail permanently or create duplicate entities.

Note that certain workflow service REST APIs aren’t idempotent and shouldn’t be called to modify the
currently running workflow instance. See 2884301 for more information and recommendations.

Procedure

1. Choose (Tasks), then Service Task from the palette and drop it on to the canvas.
2. Select the service task icon that you dropped on the canvas.
3. In the Service Task Properties area, choose the General tab.
4. Provide a Name and, optionally, a description in the Documentation field for the service task.

 Note

A unique read-only ID is generated for every workflow artifact.

5. In the Service Task Properties area, choose the Details tab.

6. Provide the Destination.

 Note

○ The destination you provide here is the destination specified in the consumer subaccount, which
determines the host to connect to at runtime. For more information about the supported feature
set of destinations, see Destinations [page 152].
○ For more information on character limits for SAP Cloud Platform Workflow, see Conventions,
Restrictions, and Limits [page 9].

7. Select one of the following options from the Choose a Service From list:
○ SAP API Business Hub
○ Others (default)

 Note

SAP API Business Hub is the central catalog, hosted by SAP to discover, explore, and test the SAP and
partner APIs that are required to build extensions, or process integrations using SAP Cloud Platform.
For more information, see SAP API Business Hub.

8. If you have chosen SAP API Business Hub, perform the following procedure Configure a Service from SAP
API Business Hub [page 54].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 51
9. If you selected Others, provide the following details:
a. Path: Resource path that appends to the URL of the specified destination while calling the service.

 Note

○ Path can consist of variables. For more information, see the below example.
○ Services that are called from a service task must support the JSON format for request and
response body. Consequently, the workflow service sends the <Content-Type:
application/json> header in every HTTP request, and expects the service to return
<Accept: application/json>. Other responses are declined by the workflow service
runtime, which can lead to a runtime error.
○ Ensure the URL that is concatenated from the Destination and the Path are valid.
○ The workflow service runtime ensures proper encoding of the final URL that is invoked. To
avoid a double encoding, don’t enter the URL specified at the destination, the value for the
path property, and xsrf path property in an encoded format.

b. HTTP Method: Specify one of the following HTTP methods: GET, POST, PATCH, PUT, or DELETE.

 Note

If the HTTP method is POST, DELETE, PATCH, or PUT, then the Path to XSRF Token field appears.
XSRF token is used for modifying operations that are protected against XSRF (cross-site request
forgery) attacks. For more information, see SAP Cloud Platform.

c. Path to XSRF Token: The resource path that must be appended to a specified destination, while calling
the service to fetch an XSRF token. If the authentication type of the specified destination is OAuth
related, you probably don't need to enter a value here.
d. Request Variable: Link to a workflow context node that populates the body of the HTTP request.

 Note

○ The referenced node is used 1:1 as content for the request body.
○ The complete context can be referenced in the request body as follows: ${context}.
○ If the request variable contains a primitive JSON type (number or string) or literal (null, true, or
false), the service must accept an HTTP body following RFC 8259 instead of the older RFC
4627.
○ If the HTTP method is POST, PATCH, or PUT, then you see the Path to XSRF Token field.

e. Response Variable: Link to a workflow context node that is created or overwritten to finally store the
body of the HTTP response.

 Note

○ The referenced node stores the response body.

○ The complete context can’t be overwritten by the contents of the response body. As a result,
the expression ${context} can’t be used in the response variable. A variable within the
context must be specified to be used as a response variable. For example, $
{context.leaveRequest} or ${context.leaveRequest.response} are valid response
variables.

SAP Cloud Platform Workflow in the Neo Environment

52 PUBLIC Developing Applications with Workflow Service
  Example

This example shows how to call a REST service to store employee's leave requests. This service is
XSRF protected.

The service URL for this example is https://{host}/leaverequest.

○ Destination is created in the SAP Cloud Platform subaccount with the following URL: http://
<host>:<port>.
○ Path: /leaverequest
○ HTTP Method: POST
○ Path to XSRF Token: /leaverequest/v1/xsrf-token
○ Request variable: ${context.leaveRequest.request}
○ Response Variable: ${context.leaveRequest.response}

This code represents the sample payload.

 Sample Code

leaverequest
{
"request":
{
"employeeId":"000001",
"startDate": "2016-10-10T00:00:00.000Z",
"endDate": "2016-10-19T00:00:00.000Z",
"reason":"vacation"
}
}

At runtime, context is added with the response variable when the service task is invoked. Once the
service task is invoked, the context is appended with the response variable and looks like:

 Sample Code

leaverequest
{
"request":
{
"employeeId":"000001",
"startDate": "2016-10-10T00:00:00.000Z",
"endDate": "2016-10-19T00:00:00.000Z",
"reason":"vacation"
}
"response":
{
status: "Successfully stored"
}
}

10. Enable principal propagation.

a. Select Principal Propagation for the service task.

For more information, see Configuring Principal Propagation for Service Tasks [page 27].
b. In the Flow Element section, choose Select.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 53
  Note

This field is available only if principal propagation is active. Then, it’s a mandatory field.

c. To search for the start event or a user task in the workflow, use Select Flow Element.

 Note

○ To propagate the user who started the workflow instance, browse for the start event in the
same workflow model.
○ To propagate the user who completed a user task instance, browse for the user task in the
same workflow model.
○ If a user task is located in a loop, the last completion action of a corresponding task instance in
a workflow instance defines the actual user that is propagated.

d. Choose OK.
11. Connect the service task to the required flow elements.
12. Choose Save.

Next Steps

In the Neo environment, the workflow developer can deploy the workflow model into the workflow service
runtime.

To make the workflow operational, an administrator must create and configure the destination mentioned by
the workflow developer. For more information, see Destinations [page 152].

Related Information

Accelerated Modeling with Speed Buttons [page 77]

Connectivity Options with SAP Cloud Platform Workflow Service
Consume SAP Gateway OData Service in SAP Cloud Platform Workflow

3.1.3.1.2.1 Configure a Service from SAP API Business Hub

You use this procedure to call an API from SAP API Business Hub in the service task properties.

Procedure

1. In the Service section, choose Select to browse for a required API.

SAP Cloud Platform Workflow in the Neo Environment

54 PUBLIC Developing Applications with Workflow Service
 2. In the Select API from Business Hub popup, select the required API from the table.
3. Choose Next.
4. Choose a resource from the Resources section.
5. Based on the resource selected, choose a method from the table.
6. Choose Next.

 Note

If you choose the method type as POST, PATCH, or PUT, then the Request Variable field appears. This
field is auto populated, but it can also be edited.

7. From the Response Variable field, you can modify or keep the auto populated response name.

 Note

The Request Parameters and the Response sections are read-only.

8. Choose Finish.

 Note

HTTP method type, path, request/response variables are populated based on the selection. The Path
to XSRF Token field is auto populated, if the APIs pushed to SAP API Business Hub have the x-sap-
csrf-token-path attribute configured.

3.1.3.1.3 Configure Script Tasks

A script task is an automatic activity. When a workflow execution arrives at the script task, the corresponding
script is executed.

Context

 Note

If you have previously modeled a script task using the workflow editor, then your existing script files are
converted into .js files automatically. Create a JavaScript file only for new script tasks you want to model.

 Recommendation

We recommend that you export and import workflow projects, rather than individual workflows, as
additional script resources are added to the workflow project.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 55
Procedure

1. Choose (Tasks), then Script Task from the palette and drop it on to the canvas.
2. In the Script Task Properties area, provide a name and documentation (optional) for the script task.

 Note

A unique read-only ID is automatically generated for every workflow artifact.

3. To add JavaScript files, perform one of the following steps:

○ Choose Select to browse for the JavaScript file in the current project.
○ To create a JavaScript file, perform the following steps:
1. Choose the Create File link.
2. In the Create New File window, provide a file name.
3. Choose Create.
4. In the JavaScript file, provide the script.

 Note

○ You can view and or edit the JavaScript file by selecting the Script File link.
○ You can find the JavaScript file in the following location: <workflow-project>/scripts/
<workflow-name>/<script-file-name>.js.
○ For more information about Code Editor, see Developing Applications.
○ The provided APIs, as well as the objects and arrays stored in the workflow context, are non-native
JavaScript objects; that is, ECMAScript host objects. Their behavior might differ from that of the
native objects. For more information about supported APIs, see:
○ Creating and Reading Workflow Context Structures [page 57]
○ Accessing Contextual Information During Execution of Script Tasks [page 61]
○ The script must be in JavaScript that is based on ECMAScript 5.1. For more information, see the
Ecma Web page . Restrictions: 'eval' and 'Function' are not supported for script tasks.
Using the function keyword is supported, but you cannot assign functions to workflow context
variables.
○ The execution of script tasks is subject to resource limits, for example, with respect to processing
time or memory usage. The limits enforced by the workflow service have the purpose of freeing up
resources as early as possible for other tasks. The limits protect against excessive usage, for
example, caused by in-efficient programming or unexpected input sizes. If the limits are exceeded,
the corresponding workflow instance is put into the ERRONEOUS state. The error is written to the
error logs of the workflow instance. You can retrieve the error logs using the REST API or the
Monitor Workflows app. If your scripts reach the resource limits, analyze the reasons, for example,
large input data. Try to reduce the input size or the complexity of the transformations executed on
it.
For the specific limits that apply to script tasks, see Conventions, Restrictions, and Limits [page 9].

4. Save the workflow.

SAP Cloud Platform Workflow in the Neo Environment

56 PUBLIC Developing Applications with Workflow Service
Related Information

Accelerated Modeling with Speed Buttons [page 77]

Transport Workflows between Accounts [page 75]
Conventions, Restrictions, and Limits [page 9]

3.1.3.1.3.1 Creating and Reading Workflow Context Structures

You can insert scripts to use library functions to manipulate the workflow context.

To interact with the workflow context, use the predefined identifier '$.context'. Data that is stored in the
workflow context, for example, during the workflow start or from a previous script task, can be read, modified,
or enhanced using a dot-notation as shown in the examples below. Such data might consist of either primitive
data types that are supported by JavaScript (for example, a string or numeric value), or complex structures
(for example, objects or arrays).

In general, the workflow context can only contain data that can also be represented using the JavaScript Object
Notation (JSON). That is, the workflow context cannot store:

● Functions
● Prototype objects
● Special numbers, such as NaN (Not a Number), positive infinity, or negative infinity

 Note

In general, do not store large objects in the workflow context, but only the keys to more appropriate
storages. See the “Claim Check” integration pattern. For data privacy reasons, we recommend deleting
data, especially personal data, as soon as it is no longer needed.

Context changes are committed at the end of the script execution. Therefore, if the execution of the script task
runs into an error, data that has been modified before within the same script task is not visible to subsequent
activities in the workflow. This section describes how to interact with primitive variables in the workflow
context. For complex structures, see Related Information.

Reading Variables

// variables are accessible as properties of $.context

var myAlias = $.context.myString;
// reading a not-existing variable returns null
if ($.context.myVariable === undefined)
{
// initialize myVariable lazy
}

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 57
Setting Variables

// variables have to be assigned to $.context to be persisted

$.context.myString = myValue;
// variable assignments can also be chained
$.context.newString = $.context.newString2 = "new field value";
// variables of primitive type have a "copy-by-value" behavior
// $.context.myString will keep the value 'hello' after the following code
var myNewValue = "hello";
$.context.myString = myNewValue;
myNewvalue = "goodbye";
// myString will not be accessible in later steps of the workflow,
// if set as follows (but only as a local variable within the same Script Task)
myString = "myValue";
// a date object can be created from context variables
var myDate = new Date($.context.myDate);
// persisting the date back to the context will store it in ISO 8601 format
$.context.myNewDate = myDate;

Removing Variables

// the following will remove the variable from the context

delete $.context.myString;

Manipulating the Context Directly

// The workflow context can be cleared completely. The $.context API will
continue to exist, but all variables will have been removed.
$.context = null.
// The workflow context can be completely overwritten, by setting it to an
object, whose properties are becoming the new context variables.
$.context = {newField: "new value"};

Complex structures can be, for example, objects and arrays and you can create and use to manipulate such
structured data. For more information, see the Related Links.

Related Information

Modifying the Workflow Context with Objects [page 59]

Modifying the Workflow Context with Arrays [page 60]

SAP Cloud Platform Workflow in the Neo Environment

58 PUBLIC Developing Applications with Workflow Service
3.1.3.1.3.1.1 Modifying the Workflow Context with Objects

You can insert scripts to modify the workflow context, for example, to transform data from one representation
to another, and also to read and set values.

For working with objects in JavaScript, the following sample scripts are available:

Constructing Objects

// Create a new object with a simple property and persist it

$.context.myObject = {newField: "new value"};
// You can also assign a local object
var obj = {newField: "new value"};
$.context.myObject2 = obj;

Object Property Access

//the following access to objects and their properties are equal

var myObject = $.context.myObject;
var prop = myObject.myProperty;
var prop2 = $.context.myObject.myProperty;
// Objects are accessed by "reference", myNumber will be stored directly in the
workflow context
// the local variable 'myNumber' will have the value 42
var obj = {newField: "new value"};
$.context.myObject2 = obj;
obj.myNumber = 42;
var myNumber = $.context.myObject2.myNumber

Object Conversions

var prop = $.context.myObject.myProperty;

if (typeof prop === 'number') {
// ... use JavaScript data type conversions
}
else if (typeof prop === 'object') {
var propAsInt = parseInt(prop.stringProperty); // for example, "42"
}

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 59
3.1.3.1.3.1.2 Modifying the Workflow Context with Arrays

You can insert scripts to modify the workflow context, for example, to transform data from one representation
to another, and also to read and set values.

For working with arrays, the following sample scripts are available:

Constructing Array

// Create a new array with three entries

var array= ["one", "two", "three"];
array.push("four");
$.context.myArray = array; // stores array [one, two, three, four] in the context
array.push("five"); // adds five to the context

Manipulating Array

// Insert entries into array at specific positions

var array = $.context.myArray;
if (array.length == 0) {
array.push("first"); // adds a new element at the end of the array
array.splice(1,1); // removes entry at position 1, the one that was previously
the first
array.unshift("new first"); // adds a new element at the beginning of the array
// array.splice(-1, 1); // out of bounds deletions
// array.splice(42, 1); // resp. at the last position
}
if (array.length == 1) {
var el = array.shift(); // returns the first element of the array and deletes it
from the array
array.unshift("new first"); // adds a new element at the beginning of the array
}
var idx = array.indexOf("new first"); // returns the index of the first
occurrence of the passed value
// all JavaScript ECMA 5.1 array functions are supported (http://ecma-
international.org/ecma-262/5.1/)

Array Index Access

var arr = $.context.myArray;

var entry = arr[0]; // first entry in array

SAP Cloud Platform Workflow in the Neo Environment

60 PUBLIC Developing Applications with Workflow Service
3.1.3.1.3.2 Accessing Contextual Information During
Execution of Script Tasks

You can insert scripts to allow access to identifiers of the current task or the exact execution. Unique identifiers
are, for example, necessary to propagate calls to external services.

Getting Information About the Environment

var workflowInstanceId = $.info.workflowInstanceId ; // for example,

"336963b0-3726-49fa-bf0c-87a8f7aabaf8"
var workflowDefinitionId= $.info.workflowDefinitionId; // for example,
"scripttaskprocess"
var startedByUserId = $.info.startedBy; // for example, "John"

Getting Information About User Task Instances

To allow access to properties of user task instances, you can insert scripts. Use the $.usertasks object as an
entry point followed by the user task definition ID from the workflow model: $.usertasks.<User Task
Definition ID>. For example, if the ID of a user task is usertask1, then use
$.usertasks.usertask1.last.priority to point to the priority of the instance of the corresponding task
definition, which was created last.

The following properties are available for the objects that refer to user task instances:

Property Name Type in Script Task Task Status READY Task Status RESERVED Task Status COMPLETED

id String Available Available Available

createdAt Date* Available Available Available

createdBy String Available Available Available

priority String Available Available Available

dueDate Date* Available Available Available

status String Available Available Available

subject String Available Available Available

description String Available Available Available

recipientUsers Array of strings Available Available Available

recipientGroups Array of strings Available Available Available

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 61
Property Name Type in Script Task Task Status READY Task Status RESERVED Task Status COMPLETED

processor String null Available Available

claimedAt Date* null Available Available

completedAt Date* null null Available

* Please note that dates are represented as strings in expressions. For more information, see Expressions
[page 79].

In the following code snippet, the processor of the last created instance of the usertask1 is written into the
context variable taskProcessor.

$.context.taskProcessor = $.usertasks.usertask1.last.processor;

Script tasks cannot modify the $.usertasks API. All its properties are provided by SAP Cloud Platform
Workflow and are read-only.

Saving Contextual Information in the Workflow Context

You can save an object that refers to the last instance of a user task in the workflow context.

$.context.lastUserTask1 = $.usertasks.usertasks1.last;

So, at the time a script is executed, a snapshot of the last user task instance is created and persisted in the
context.

Please note that, as of now, this is the only complex nested property of the $ object that can be stored in the
workflow context.

If you try to save one of the following objects into context, an error occurs when the workflow instance is
executed.

$.context.variable = $.context;
$.context.variable = $.info;
$.context.variable = $.usertasks;
$.context.variable = $.usertasks.usertasks1;

There is no limitation on saving primitive values in the workflow context and the following code is absolutely
valid:

$.context.variable = $.info.workflowInstanceId;

SAP Cloud Platform Workflow in the Neo Environment

62 PUBLIC Developing Applications with Workflow Service
3.1.3.1.3.3 Get and Set Instance-Specific Roles

In script tasks, you can access instance-specific roles of the current workflow instance.

Use the $.roles object as an entry point followed by the type of the role you want to read from or write to. For
example, in a script task for a given workflow instance, you can access the current list of admin users through
$.roles.adminUsers.

The following variants are available for the $.roles object that refers to the instance’s roles:

Script Task Object/Property

Type (Read/Write Access) JUEL Expression (Read-only)

Array of Strings of viewer users $.roles.viewerUsers ${roles.viewerUsers}

Array of Strings of viewer groups $.roles.viewerGroups ${roles.viewerGroups}

Array of Strings of context viewer $.roles.contextViewerUsers ${roles.contextViewerUsers}

users

Array of Strings of context viewer $.roles.contextViewerGroups ${roles.contextViewerGroups}

groups

Array of Strings of admin users $.roles.adminUsers ${roles.adminUsers}

Array of Strings of admin groups $.roles.adminGroups ${roles.adminGroups}

Array of Strings of context admin $.roles.contextAdminUsers ${roles.contextAdminUsers}

users

Array of Strings of context admin $.roles.contextAdminGroups ${roles.contextAdminGroups}

groups

 Note

If no user or group is or should be set for the given role, an empty array is used.

Assign Roles to User

In this example, you assign the admin role to the user Julie.

 Sample Code

var admins = $.roles.adminUsers;

admins.push('Julie');

In this example, you assign the viewer role to the users John, Michael, and Richard.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 63
  Sample Code

var viewers = ['Michael', 'Richard'];

$.roles.viewerUsers = viewers;
// ...
viewers.push('John');

Retrieve Users Assigned to a Role

In this example, you can read which users are assigned to the viewer role.

 Sample Code

var instanceViewers = $.roles.viewerUsers; // for example, ["John",

"Michael", "Richard"]
// single access
if (instanceViewers.length > 0) {
var firstViewer = instanceViewers[0]; // for example, "John"
// do something with firstViewer
}
// iteration
instanceViewers.forEach(function (viewer) {/* do something with ‘viewer’, for
example, John, Michael, and then Richard */});

Unassign Users From Roles

In this example, you unassign all users from the viewer role.

 Sample Code

$.roles.viewerUsers = []; // clears only viewer users, but not any other roles

3.1.3.1.4 Configure Mail Tasks

A mail task is a flow object that can be configured to send e-mails to one or more recipients.

Prerequisites

Configure a mail destination. See Configure the Workflow Service Mail Destination with SAP Web IDE [page 25].

SAP Cloud Platform Workflow in the Neo Environment

64 PUBLIC Developing Applications with Workflow Service
Procedure

1. Choose (Tasks), then Mail Task from the palette and drop it on to the canvas.
2. In the Mail Task Properties area, choose the General tab.
3. Provide a Name and Documentation.

 Note

A unique, read-only ID is generated for every workflow artifact.

4. From Mail Task Properties area, choose the Details tab.

5. In the To field, provide a list of comma-separated mail addresses to which to send the mail.

 Note

For more information about character limits for SAP Cloud Platform Workflow, see Conventions,
Restrictions, and Limits [page 9].

6. (Optional) Add mail addresses to the Cc for the mail and Bcc fields.

 Note

If there is a syntax error in any of the To, Cc, or Bcc fields, the mail task execution is aborted and the
workflow instance changes to an error status.

7. Choose Ignore Invalid Recipients to ignore any invalid e-mail addresses.

 Note

○ If you select this option, e-mail addresses that are syntactically incorrect or that are caused by
unresolvable expressions won't cause the task to fail, provided at least one recipient can be
determined. The ignored recipients list appears in the Monitoring Workflows app
○ If the option is disabled, mail task fails when at least one invalid recipient is determined.
○

8. Provide a Subject

 Note

Subject, Cc, Bcc, and To fields can contain JUEL expressions. For more information, see Expressions
[page 79].

Except for the Subject field, you can use either a context reference that resolves to a string, with
different mail addresses separated by commas, or a context reference that resolves to an array of mail
addresses.

9. From the Configure Mail Body list, choose one of the following:
○ Plain Text: Provide the message in the form of text.
○ HTML: Create a new or choose an existing HTML file for the mail content.
To create a new HTML file, perform the following steps:
1. In the HTML Body section, choose the Create file link.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 65
 2. In the Create New File window, provide a file name.
3. Choose Create.
4. In the HTML file, provide the mail content.

 Note

○ If you have set the Mail Body to HTML, the text representation of the emails that are sent is
derived from the HTML content and specified as an alternative representation of the HTML
content in the e-mail. E-mail clients typically display the text representation in text-only
mode. However, it is at your discretion to use text-only mode.
○ In many cases, the derived text is suitable to be shown to end users. However, in cases of
complex HTML structures, the text representation might not be optimal. If the text
representation is important to you, simplify the HTML code to use mostly simple, semantic
mark-up or specify the mail body directly as text.
○ You can use expressions in the mail body and the subject. However, you cannot add HTML
tags in the HTML mail body using expressions, because special characters in the
expression results are escaped for security reasons.
○ An example HTML mail body is shown below.

 Sample Code

<!doctype html>
<html>
<head>
<title>Workflow Service Email Notification</title>
<style>
h3 {
font-family: serif;
}
p, dl, dd, dt {
font-family: sans-serif;
}
dt {
text-indent: 5em;
}
</style>
</head>
<body>
<h3>Employee onboarding completed</h3>
<p>Dear ${context.initiatorName},</p>
<p>The employee onboarding that you triggered has been
successfully completed.
<p>Sincerely yours,</p>
<p>Cloud Platform Workflow</p>
</body>
</html>

5. Save and close the HTML file.

 Note

○ You can find the HTML file in the following location: <workflow-project>/webcontent/
<workflow-name>/<html-file-name>.html.
○ The list of e-mail addresses and JUEL expressions can contain a maximum of 5000 characters and
100 e-mail addresses.
○ Subject can be a maximum of 1000 characters long. We recommend that you use far fewer
characters because mail clients can show only a limited subject length.

SAP Cloud Platform Workflow in the Neo Environment

66 PUBLIC Developing Applications with Workflow Service
 ○ Mail Body can contain a maximum of 10000 characters.

10. Connect the mail task to the required flow elements.

11. Choose Save.

Related Information

Conventions, Restrictions, and Limits [page 9]

3.1.3.2 Events

An event affects the flow of the process.

SAP Cloud Platform Workflow editor supports the following events:

Start event: It indicates where a workflow starts and what triggers a workflow. Start events have no incoming
sequence flow. Each workflow has one start event.

Intermediate Message Event: Intermediate message events are process steps where the respective workflow
instance waits for a message before the flow commences in the respective control flow branch.

Intermediate Timer Event: It allows a workflow to pause and resume after a specified interval of time.

End event: An end event means that this event has no specific result. End events have no outgoing sequence
flow. Consider a workflow that has several branches, the workflow terminates only after all the branches gets
executed.

Terminate end event: The terminate event ends the workflow in a regular way. But, consider a workflow
consists of multiple branches and you choose one branch as a terminate end event. The workflow terminates
when the branch marked as terminate end is executed without waiting for other branches to get executed.

3.1.3.2.1 Configure Start Events

You can configure a sample context while modeling a start event.

Prerequisites

You are in the process of modeling a start event. For more information, see Define Workflows [page 36].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 67
Context

After the deployment of the workflow, the sample context is displayed in the Monitor Workflows app while
starting a new workflow instance. For more information, see Managing Workflow Definitions [page 166].

Alternatively, you can use the API to retrieve the sample start context. For more information, see Using
Workflow APIs [page 125].

You can propagate the user who starts a workflow instance to a service called later by a service task in the
same workflow instance. For more information, see Configure Service Tasks [page 50].

Procedure

1. Choose the Details tab of the start event.

2. Select the Configure sample context checkbox.
3. To browse for a JSON file in the current project, choose Select.
4. To create a JSON file, perform the following substeps:
a. Choose the Create file link.
b. In the Create New File window, provide a file name with .json extension.
c. Choose Create.
d. In the JSON file, provide the context.

 Note

○ You can view or edit the JSON file by selecting the File link.
○ For more information about Code Editor, see Developing Applications.

5. Save the workflow.

Related Information

Define Workflows [page 36]

SAP Cloud Platform Workflow in the Neo Environment

68 PUBLIC Developing Applications with Workflow Service
3.1.3.2.2 Configure Intermediate Message Events

Intermediate message events occur when a workflow instance waits for a message before the flow commences
in the respective control flow branch.

Prerequisites

Configure a business key for your workflow. For more information about business keys, see Define Workflows
[page 36].

Context

Clients can send messages using the REST endpoint. For more information about how to send messages, refer
to Workflow Service API documentation at Using Workflow APIs [page 125].

The messages received through this endpoint are synchronously correlated to workflow instances based on the
business key. The message can be delivered to one or more instances of the same workflow definition, which
has a matching business key and an active execution branch waiting at the intermediate message event.

Procedure

1. Select  Events Intermediate Message , and drop it onto the canvas from the palette.
2. In the Intermediate Message Event Properties area, choose the General tab.
3. Fill in the Name and Documentation fields for the intermediate message event.
4. In the Intermediate Message Event Properties area, choose the Details tab.
5. In the Message Name field, provide a name of the message.

 Note

For more information about character limits for SAP Cloud Platform Workflow, see Conventions,
Restrictions, and Limits [page 9].

6. (Optional) Provide a Response Variable link to a workflow context node, which holds the context data
passed by the incoming message.

 Note

○ If you use a response variable, it must adhere to the syntax defined by the Java Unified Expression
Language (JUEL). You can only use expressions that reference the workflow context. For more
information, see Expressions [page 79].
○ If you don't provide a response variable, the message is consumed by matching workflow
instances. However, the context data passed by the message is not considered.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 69
7. Choose Save.

 Example

Equipment must be procured for a new hire. In this case, the employeeID of the new hire can be
configured as business key. The workflow calls an external service to trigger the asynchronous
procurement process. The workflow instance must wait until the procurement process is completed.

You can model an intermediate message event, which blocks the execution of the workflow in this
branch until a message is received. When the procurement process completes, the external system can
send a message that includes details about the equipment ordered. This message is then delivered to
one of the waiting workflow instances, and the execution moves to the next flow step.

Related Information

Conventions, Restrictions, and Limits [page 9]

3.1.3.2.3 Configure Intermediate Timer Events

Configure an intermediate timer event to allow a workflow to pause and resume after a specified interval of
time.

Context

In a few business scenarios, a workflow may need to wait for a certain interval of time before proceeding with
the flow; for example, a workflow that updates multiple systems of record. You can add an intermediate timer
event that delays the workflow for a few minutes, to ensure that all records have been updated before the
workflow continues.

Procedure

1. Select  Events Intermediate Timer and drop it onto the canvas from the palette.
2. Fill in the Name and Documentation fields for the intermediate timer event.
3. In the Intermediate Timer Event Properties area, choose the Details tab.
4. Provide the waiting time interval in the Duration field.
○ To use expressions, choose Expression from the Duration Based On dropdown.

 Note

Provide an expression in the Duration field using ISO 8601 format. For example, PT$
{context.minutes}M. The JUEL expression ${context.minutes} is evaluated at runtime. You

SAP Cloud Platform Workflow in the Neo Environment

70 PUBLIC Developing Applications with Workflow Service
 can provide multiple duration attributes by using multiple JUEL expressions. For more information
about the duration formats that are supported in ISO 8601, see Conventions, Restrictions, and
Limits [page 9].

○ To use a static value, choose Static Value from the Duration Based On dropdown. Now, provide the
Duration as a numeric value, and choose a Unit of Time.
5. Choose Save.

3.1.3.3 Gateways

A gateway controls the flow of execution, and is represented visually as a diamond shape with an icon inside.
The icon shows the type of gateway.

SAP Cloud Platform Workflow editor supports the following gateway types:

● Exclusive gateway: Use an exclusive gateway to model a decision in the process. When the execution
arrives at this gateway, all outgoing sequence flows are evaluated in the order in which they are defined.
The sequence flow with a condition that evaluates to true is selected for continuing the process.
If multiple sequence flow have a condition that evaluates to true, the first one defined is selected for
continuing the process. If none of the conditions defined for the sequence flow evaluate to true, then the
one marked as default flow is selected and the execution proceeds along that path.

 Note

If you use an exclusive gateway to split flow into multiple sequence flows, then the same type of
gateway should be used to merge as well.

For more information, see Configure an Exclusive Gateway [page 72].

● Parallel gateway: Use a parallel gateway to split into multiple paths of execution or merge multiple
incoming paths of execution. The functionality of the parallel gateway is based on the following incoming
and outgoing sequence flow:
○ Split: All outgoing sequence flows are executed in parallel; there is one concurrent execution for each
sequence flow.
○ Join: All concurrent executions arriving at the parallel gateway wait in the gateway until an execution
has arrived for each incoming sequence flow. Then the process continues past the joining gateway.

 Note

Parallel gateway works on a logical level, it does not speed up the technical execution.

For example, consider a scenario where an employee approaches the travel desk to book flight and hotel
accommodation for a business trip. With a parallel gateway, both the flight arrangement and hotel
accommodation can happen in parallel. Once the booking is successful, email notification can be sent to
the employee.

 Note

If you use a parallel gateway to split flow into multiple paths, then the same type of gateway should be
used to merge as well.

For more information, see Configure a Parallel Gateway [page 73].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 71
3.1.3.3.1 Configure an Exclusive Gateway

You use this procedure to configure an exclusive gateway in workflow editor.

Procedure

1. From the palette, choose  Gateways Exclusive Gateway drop it on to the canvas.
2. In the Exclusive Gateway Properties area, provide a Name and Documentation for the gateway.

 Note

A unique ID gets generated for every workflow artifact. This ID is in read-only mode.

3. On the canvas, create a sequence flow from the Exclusive Gateway icon to other flow objects.

 Note

If there are more than one outgoing sequence flows from an exclusive gateway, then it is considered as
a split in the flow. Only in this case, you can view and configure the Sequence Flow Properties . The next
step of configuring a condition is only possible in case of a split scenario.

4. Configure a condition for a sequence flow.

For more information, see Configure a Sequence Flow [page 72].
5. Choose Save.

Related Information

Accelerated Modeling with Speed Buttons [page 77]

3.1.3.3.1.1 Configure a Sequence Flow

Procedure

1. On the canvas, choose the sequence flow you want to configure.

2. In the Sequence Flow Properties section provide a Name and Documentation for the flow object .

 Note

A unique ID gets generated for every workflow artifact. This ID is in read-only mode.

SAP Cloud Platform Workflow in the Neo Environment

72 PUBLIC Developing Applications with Workflow Service
 3. From an exclusive gateway, provide a Condition to the outgoing sequence flow or mark the sequence flow
as Default.

 Note

○ You can mark only one outgoing sequence flow as the default.
○ If you want a certain path to execute, for example, only if an employee does not belong to Germany.
You need to configure the sequence flow condition as ${context.employee.region!= “Germany”}. For
more information, see Expressions [page 79].

4. Choose Save.

3.1.3.3.2 Configure a Parallel Gateway

You use this procedure to configure a parallel gateway in workflow editor.

Procedure

1. From the palette, choose  Gateways Parallel Gateway , and drop the icon on to canvas.
2. In the Parallel Gateway Properties area, provide a name and documentation for the gateway.

 Note

A unique ID gets generated for every workflow artifact. This ID is in read-only mode.

3. If you are creating a split, then create multiple outgoing sequence flows from the parallel gateway.
4. If you are creating a join, then create multiple incoming sequence flows to the parallel gateway.
5. Choose Save.

Related Information

Accelerated Modeling with Speed Buttons [page 77]

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 73
3.1.4 Configure Custom Workflow Attributes

You can assign custom workflow attributes to your workflow.

Context

With custom workflow attributes, you can define business-related properties and assign them to workflows
such as project ID or project name.

At runtime, you can use the respective workflow service API to search for custom workflow attributes or to find
the respective workflow instances. For more information about the characteristics of the various APIs, see
Using Workflow APIs [page 125].

Procedure

1. Choose the Attributes tab.

2. To add a row, choose Add.

You can reorder the added custom workflow attributes by using Move Up or Move Down.
3. Provide the following details in the table:

Name Description

ID A unique identifier of the attribute within a workflow.

 Note
You can only use alphanumeric characters as ID and it must only start with an alphabet.

Label A human readable name of the attribute, which appropriate user interfaces can use to label
the attribute.

Type Data type of the attribute.

 Note
Currently, only the data type string is supported.

SAP Cloud Platform Workflow in the Neo Environment

74 PUBLIC Developing Applications with Workflow Service
 Name Description

Value A constant, a JUEL expression, or a mixture of constants and JUEL expressions. It gets re­
solved upon workflow creation and on every change to the context, for example, through serv­
ice or script tasks.

For JUEL expressions, only the ${context.xyz} subset is supported. ${info}, ${roles},
and ${usertasks} aren’t supported.

 Example
USR_${context.user.userId}

A complete array isn’t resolved in JUEL expressions. For ${context.aArray}, for example,
values of that kind of expression always resolve to null. However, for a single array element it
resolves, for example, ${context.aArray[0]}.

A complex object is also not resolved in JUEL expressions. For ${context.complexObject},

for example, values of that kind of expression always resolve to null. However, for a single ob­
ject element it resolves. For example, ${context.complexObject.primitiveProperty}
resolves to the value of the primitive property.

${context} doesn’t contain any node. It’s also not supported and its value always resolves to
null.

 Note

A workflow can contain up to 15 attributes at a time. For more information, see Conventions,
Restrictions, and Limits [page 9].

4. Save the changes.

3.1.5 Transport Workflows between Accounts

Transport workflows from one subaccount to another account.

Procedure

1. In your workspace, choose Export from the context menu of the workflow project.

A local .zip file is created for your project.

2. Import the workflow projects to the target account.

For more information, see Importing Projects from an Archive.

3. Deploy all the workflows in the workflow project. For more information, see Build and Deploy Workflows
[page 76].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 75
  Note

You must also use this procedure to import any custom task UIs that are used in workflows.

3.1.6 Build and Deploy Workflows

Prerequisites

You’re assigned the Space Developer role.

 Recommendation

● Create a workflow instance and then reuse in the mta.yaml file.

● Enable parallel deployment of application modules in the multitarget application (MTA) deployment
descriptor (mta.yaml). For more information, see Parallel Deployment section in Order of Deployment
and Modules.

Context

To deploy your workflow-related artifacts such as the workflow and form definitions, you must build and deploy
the containing project.

Procedure

1. Save any workflows and forms you've modified.

2. Modify the multitarget application (MTA) module types by providing either of the following resources types
and parameters in the MTA deployment descriptor (mta.yaml).
○ To use an existing instance of workflow service, define it by using org.cloudfoundry.existing-
service resource type along with the existing resource name.

 Recommendation

Use this approach to modify the descriptor (mta.yaml) file.

You can find the existing instance name of workflow service by navigating to Services Service
Instances in the cockpit.

 Sample Code

resources:
- name: <existing_workflow_service_instance_name>

SAP Cloud Platform Workflow in the Neo Environment

76 PUBLIC Developing Applications with Workflow Service
 type: org.cloudfoundry.existing-service

○ If there’s no workflow service instance created, create a new workflow service instance. Define it using
the org.cloudfoundry.managed-service resource type along with the resource name provided by
the user.

 Sample Code

resources:
- name: <workflow_service_instance_name>
type: org.cloudfoundry.managed-service
parameters:
service-plan: standard
service: workflow

For more information about resources types and parameters, see MTA Module Types, Resource Types, and
Parameters for Applications in the Cloud Foundry Environment.
3. Add dependency to the workflow service instance in the requires section of the workflow module.
4. Build and deploy your project.

For more information, see the following:

○ With SAP Web IDE: Packaging and Deploying Applications to Production Systems
○ With SAP Business Application Studio: Build Your Application and Deploy Your Application

3.1.7 Accelerated Modeling with Speed Buttons

In addition to the palette, you can use the speed buttons for quick and easy modeling. The speed buttons are
displayed around the flow objects. In the following figure you see a start event with the speed buttons around it.
The number and type of speed buttons that are displayed vary depending on the model element.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 77
The following table contains all the different types of speed buttons and explains their function:

Speed Button Description

This speed button allows you to model the following events:

● : Creates an end event.

● : Creates an intermediate message event.

● :Creates an intermediate timer event.

This speed button allows you to model the following tasks:

● : Creates a user task.

● : Creates a service task.

● : Creates a script task.

● : Creates a mail task.

This speed button allows you to model the following gateways:

● : Creates an exclusive gateway.

● : Creates a parallel gateway.

Creates a sequence flow from one flow element to another.

 Note
When you select the sequence flow speed button, you must drag it on the element that you
want to connect to. If the area is highlighted in green, then the element can be connected us­
ing a sequence flow. If the area is not highligted, then the element cannot be connected using
the sequence flow.

Allows you to create a boundary timer event on a user task.

Allows you to delete a flow element.

SAP Cloud Platform Workflow in the Neo Environment

78 PUBLIC Developing Applications with Workflow Service
3.1.8 Expressions

There are several places in the editor where you can enter expressions to extract data from the workflow
context.

Expressions are mainly used for the following purposes:

● To combine static texts and variables. These are, for example, shown as texts to the user to provide
contextual information (text expressions).
● To determine major task properties dynamically (property navigation)
● To determine the next steps when the control flow arrives at gateways (conditions)

The expressions you use must adhere to the syntax defined by the Java Unified Expression Language (JUEL).
You can access data stored in the workflow context, for example, ${context.variablename}) as well as
data that refers to the current task or workflow, for example, ${info.workflowInstanceId}). The syntaxes
to access this data within a JUEL expression and using the script task API are aligned. The following statements
address the same attribute:

Functionality Example of JUEL Expression Example of Script Task API More Information

Workflow instance $ $.context.employee.fir Creating and Reading Work­

context {context.employee.firs stname flow Context Structures
tname} [page 57]

Workflow instance $ $.info.workflowInstanc Getting Information About

information {info.workflowInstance eId the Environment inAccessing
Id} Contextual Information Dur­
ing Execution of Script Tasks
[page 61]

Workflow instance ${roles.adminGroups} $.roles.adminGroups Get and Set Instance-Spe­

roles cific Roles [page 63]

User task properties ${usertasks.<User Task $.usertasks.<User Task Getting Information About
Definition Definition User Task Instances in Ac­
ID>.last.processor} ID>.last.processor cessing Contextual Informa­
tion During Execution of
Script Tasks [page 61]

Property Navigation and Text Expression

Property navigation and text expressions typically occur in user tasks. See Configure User Tasks [page 39].

 Example

 Sample Code

{
"context": {

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 79
 "employee": {
"name" : "Peter",
"peers" : [
{
"name": "Mary"
}
],
"region": "Germany",
"userId": "9899"
}
}
}

Examples that are supported by expression syntax include the following:

● Property navigation (including text expressions without static texts)

○ Accessing the name property of the employee context variable (dot notation): $
{context.employee.name}
○ Accessing the name property of the first entry in the peers array property of the employee
context variable: ${context.employee.peers[0].name}
● Text expressions
Combining static with dynamic content: Dear ${context.employee.name}
● Conditions
Applying Boolean operators to form a condition:
${context.employee.region!= “Germany” && context.employee.isManager == true}

Conditions and Variable Specifications

Besides the already described types of expression, there are several other types:

● Condition expressions have to evaluate to a Boolean value, that is true or false.

● You must specify conditions like the ones used in the example in Configure a Sequence Flow [page 72] as
follows:
${context.employee.region!= “Germany” && context.employee.isManager == true}
● You must specify the variable to retrieve the request body when calling external services (see Configure
Service Tasks [page 50]) as follows:
${context.employee.oldEmpData}
● Expressions that create new structures within context variables support only the dot notation of the JUEL
language. You must, for example, specify the expression to store the response from an external service
(see Configure Service Tasks [page 50]) as follows:
${context.employee.empData}

Notices

● When there are multiple expressions in a single field: if one of the expressions is incorrect or refers to a field
that does not exist, then none of the expressions in that field are replaced. For example, in the text
expression "Approval for ${context.employee.firstname} $

SAP Cloud Platform Workflow in the Neo Environment

80 PUBLIC Developing Applications with Workflow Service
 {context.employee.lastname}", if the employee's last name field does not exist, none of the
expression is replaced.
● Once expressions in texts are resolved, that is, they are replaced with the actual text at runtime, the texts
are not changed if the process context changes at later point in time.

Overview of Properties Supporting JUEL Expressions

 Note

All task-related properties of ${info} are only available on JUEL-enabled properties of service and user
tasks.

Elements and Properties Using JUEL Expressions

Workflow Model JUEL-Enabled

Element Type Property Required Data Type

Sequence flow Condition Boolean

originating from
an exclusive
gateway

Service task Path String

Path to XSRF token String

User task Subject String

Recipient users Comma-separated string or array of strings

Recipient groups Comma-separated string or array of strings

HTML5 app String

Component URL String

SAPUI5 compo­ String

nent

Mail task To Comma-separated string or array of strings

Cc Comma-separated string or array of strings

Bcc Comma-separated string or array of strings

Subject String

HTML / plain text String

body

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 81
Workflow Model JUEL-Enabled
Element Type Property Required Data Type

Workflow model Subject String

Business key String

Handling of the Date-Related Objects

Dates are handled differently in script tasks and in expressions. In script tasks, the JavaScript date is used to
represent date-related properties of workflow service APIs, for example, the createdAt , claimedAt , and
completedAt properties of user tasks. However, in expressions, the corresponding properties are represented
as strings.

In addition, all values saved in the context as dates in script tasks are converted to the corresponding strings at
the end of the script task execution. They are available as strings in subsequent JUEL expressions and script
tasks.

Related Information

JUEL Tutorial - Expression Language

3.2 Create a Workflow Sample Application with SAP Web

IDE

You can use the sample application to experience the workflow service offering on SAP Cloud Platform.

Context

You can create a sample application containing workflows and task user interfaces for the following scenarios:

● Employee onboarding scenario

● Document audit scenario

SAP Cloud Platform Workflow in the Neo Environment

82 PUBLIC Developing Applications with Workflow Service
Procedure

1. Log in to the SAP Web IDE Full-Stack application.

2. From the left pane, choose  (Development) and navigate to the Workspace folder.

3. Choose File New Project from Sample Application .

4. From the Sample Application Selection screen, choose Category as Workflow Sample Application.
5. Choose one of the following tiles:
○ Employee Onboarding Extension Workflow for Neo
○ Collaborative Approval Workflow Using SAP Jam
6. Choose Next.
7. Select the checkbox and provide your consent to create the application.
8. Choose Finish.

Results

A workflow project containing the sample application is created in your workspace.

Next Steps

Using the readme.txt file in the project, you can configure, deploy, and run the workflow sample application.

For more information, see the following:

● Sample Application for Employee Onboarding Extension Workflow

● Sample Application for Collaboration in SAP Cloud Platform Workflow with SAP Jam

3.3 Creating User Interfaces

With SAP Cloud Platform Workflow you can create user interfaces for workflows.

You have the following options:

● Defining a User Interface for a Workflow [page 84]

With SAPUI5, this option gives you a high control of the UI.
● Creating a Workflow Form [page 107]
This option enables you to create a simple straightforward UI using predefined elements.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 83
3.3.1 Defining a User Interface for a Workflow

As the workflow service includes REST-based APIs that let you access the workflow service runtime, you can
develop scenario-specific user interfaces (UIs) on top of these APIs.

The main use cases for such UIs include the following:

● Start UI: Triggers new workflow instance for a defined workflow definition.
● Task UI: Is plugged into My Inbox to represent a user task in the workflow definition.

Both types of UIs can be developed and deployed as HTML5 applications on SAP Cloud Platform. For more
information about developing HTML5 applications using the workflow editor, see SAP Web IDE.

The following diagram depicts the relationships between the involved HTML5 applications and the respective
subscriptions for My Inbox and the workflow service runtime. The different applications and subscriptions are
wired using destinations.

My Inbox includes two predefined routes, which you can use when developing UIs:

● /bpmworkflowruntime
/bpmworkflowruntime maps to the bpmworkflowruntime destination, which is configured by default
for your subaccount.
For more information, see Read Task Context Data [page 88].
For more information about routes, see Application Descriptor File.
● /html5apps
You can integrate the UIs into any HTML5 app and access them using /html5apps/<name_of_app>.

Custom UI Overview

Related Information

Building a Custom Task UI [page 85]

Creating a Start UI [page 97]

SAP Cloud Platform Workflow in the Neo Environment

84 PUBLIC Developing Applications with Workflow Service
3.3.1.1 Building a Custom Task UI

With the custom task user interface (UI), end users can access their workflow tasks in their inboxes.

Context

You can either define the task UI using an existing SAPUI5 component or using a form.

To build a custom task UI, execute the following steps:

Procedure

1. Creating an HTML5 Application for the Custom Task UI [page 85]

2. Deploy an HTML5 Application [page 97]

Related Information

SAP Web IDE Full-Stack Documentation

HTML5: Getting Started
Using Workflow APIs [page 125]
Creating a Workflow Form [page 107]

3.3.1.1.1 Creating an HTML5 Application for the Custom

Task UI

This is an overview of the series of steps you have to execute to create the custom task UI.

Procedure

1. Create an HTML5 application.

For more information, see Creating an HTML5 Application in the SAP Cloud Platform documentation.
2. Create a project using the SAPUI5 Application template.

For more information, see Create a Project in the SAP Cloud Platform documentation but use XML as view
type.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 85
3. Extend the application by modifying the webapp/Component.js file by doing the following:
a. Get the Task Instance ID [page 87]
b. Read Task Context Data [page 88]
c. Bind a UI Element to an Attribute of the Task Context JSON Model [page 89]
d. Adding Task Completion Buttons [page 89]
e. Get the Task Description [page 92]
f. (Optional) Retrieve Parameters in Custom Task UI [page 93]
g. (Optional) Show and Hidе Footer [page 93]
h. (Optional) Show and Hide the Back Navigation Button [page 93]
i. (Optional) Call an External Service from a Custom Task UI [page 96]

Results

The page element of the webapp/view/<view name>.view.xml should look similar to the following:

 Sample Code

<Page showHeader="false" showFooter="false">

<content>
<Text text="{/context/text}" maxLines="0" id="__text0"/>
</content>
</Page>

The init function of webapp/Component.js should look similar to the following:

 Sample Code

init: function() {
UIComponent.prototype.init.apply(this, arguments);
this.setModel(models.createDeviceModel(), "device");

var startupParameters = this.getComponentData().startupParameters;

var taskModel = startupParameters.taskModel;
var taskId = taskModel.getData().InstanceID;

var contextModel = new sap.ui.model.json.JSONModel("/bpmworkflowruntime/

rest/v1/task-instances/" + taskId + "/context");
contextModel.setDefaultBindingMode(sap.ui.model.BindingMode.OneWay);
this.setModel(contextModel);

startupParameters.inboxAPI.addAction({
action: "Reject",
label: "Reject"
}, function(button) {
this._completeTask(taskId, false);
}, this);

startupParameters.inboxAPI.addAction({
action: "Approve",
label: "Approve"
}, function(button) {
this._completeTask(taskId, true);
}, this);
},

SAP Cloud Platform Workflow in the Neo Environment

86 PUBLIC Developing Applications with Workflow Service
Below this function, there should be previously created functions:

 Sample Code

_completeTask: function(taskId, approvalStatus) {

var token = this._fetchToken();
$.ajax({
url: "/bpmworkflowruntime/rest/v1/task-instances/" + taskId,
method: "PATCH",
contentType: "application/json",
async: false,
data: "{\"status\": \"COMPLETED\", \"context\": {\"approved\":\"" +
approvalStatus + "\"}}",
headers: {
"X-CSRF-Token": token
}
});
this._refreshTask(taskId);
},

_fetchToken: function() {
var token;
$.ajax({
url: "/bpmworkflowruntime/rest/v1/xsrf-token",
method: "GET",
async: false,
headers: {
"X-CSRF-Token": "Fetch"
},
success: function(result, xhr, data) {
token = data.getResponseHeader("X-CSRF-Token");
}
});
return token;
},

_refreshTask: function(taskId) {
this.getComponentData().startupParameters.inboxAPI.updateTask("NA",
taskId);
}

3.3.1.1.1.1 Get the Task Instance ID

Procedure

To get the task ID, add the following lines to the init function:

 Sample Code

var startupParameters = this.getComponentData().startupParameters;

var taskModel = startupParameters.taskModel;
var taskId = taskModel.getData().InstanceID;

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 87
3.3.1.1.1.2 Read Task Context Data

Procedure

1. Read the task context data via a REST service and create a JSON model from it.

For more information, see Using Workflow APIs [page 125].

2. After the model has been created, set it as default model of the component so it can be used for data
binding.

 Sample Code

var contextModel = new sap.ui.model.json.JSONModel("/bpmworkflowruntime/

rest/v1/task-instances/" + taskId + "/context");
contextModel.setDefaultBindingMode(sap.ui.model.BindingMode.OneWay);
this.setModel(contextModel);

3.3.1.1.1.3 Writе Task Instance Data

Procedure

1. Write the task context data via a REST service and create a JSON model from it.

For more information, see Task Data in the Workflow Service API Documentation at Using Workflow APIs
[page 125].
2. After the model has been created, set it as default model of the component so it can be used for data
binding.

SAP Cloud Platform Workflow in the Neo Environment

88 PUBLIC Developing Applications with Workflow Service
3.3.1.1.1.4 Bind a UI Element to an Attribute of the Task
Context JSON Model

Procedure

1. To display a field of the task context on the custom task UI, add a text element to webapp/view/<view
name>.view.xml and bind it to the text attribute of the JSON model.
2. Replace the page element with this content:

 Sample Code

<Page showHeader="false" showFooter="false">

<content>
<Text text="{/text}" maxLines="0" id="__text0"/>
</content>
</Page>

3.3.1.1.1.5 Adding Task Completion Buttons

This is an overview of the series of steps you have to execute to add task completion buttons.

Context

To add these buttons, execute the following steps:

Procedure

1. Fetch an XSRF Token [page 90].

2. Call the Task Completion REST API [page 90].
3. Add Custom Action Buttons [page 91].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 89
3.3.1.1.1.5.1 Fetch an XSRF Token

Procedure

To call the task completion REST API, you have to retrieve an XSRF token first. You could, for example, use the
following function:

 Sample Code

_fetchToken: function() {
var token;
$.ajax({
url: "/bpmworkflowruntime/rest/v1/xsrf-token",
method: "GET",
async: false,
headers: {
"X-CSRF-Token": "Fetch"
},
success: function(result, xhr, data) {
token = data.getResponseHeader("X-CSRF-Token");
}
});
return token;
}

3.3.1.1.1.5.2 Call the Task Completion REST API

Procedure

1. Call the previously created _fetchToken function. For more information, see Fetch an XSRF Token [page
90].
2. Using this token, call the completion API with data, which will be written into the task or workflow context.

 Example

In this example, the data contains a field named approved to indicate whether the task was approved
or rejected.

 Sample Code

_completeTask: function(taskId, approvalStatus) {

var token = this._fetchToken();
$.ajax({
url: "/bpmworkflowruntime/rest/v1/task-instances/" + taskId,

SAP Cloud Platform Workflow in the Neo Environment

90 PUBLIC Developing Applications with Workflow Service
 method: "PATCH",
contentType: "application/json",
async: false,
data: "{\"status\": \"COMPLETED\", \"context\": {\"approved\":"
+ approvalStatus + "}}",
headers: {
"X-CSRF-Token": token
}
});
}

3.3.1.1.1.5.3 Add Custom Action Buttons

Procedure

1. To add buttons to the footer of the custom task UI, add these lines to the init function of webapp/
Component.js. For example, to add Approve or Reject buttons, use:

 Sample Code

startupParameters.inboxAPI.addAction({
action: "REJECT",
label: "Reject"
}, function(button) {
this._completeTask(taskId, false);
}, this);

startupParameters.inboxAPI.addAction({
action: "APPROVE",
label: "Approve"
}, function(button) {
this._completeTask(taskId, true);
}, this);

The previously created function _completeTask is called in both actions but with different approval
status.
2. (Optional) You can define the appearance of one or multiple custom action buttons as positive or negative.
To do so, use the additional type parameter as in the following code sample:

 Sample Code

startupParameters.inboxAPI.addAction({
action: "REJECT",
label: "Reject",
type: "reject" // or "negative"// For negative appearance.
}, function(button) {
this._completeTask(taskId, false);
}, this);

startupParameters.inboxAPI.addAction({
action: "APPROVE",

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 91
 label: "Approve",
type: "accept" // or "positive"// For positive appearance.
}, function(button) {
this._completeTask(taskId, true);
}, this);
startupParameters.inboxAPI.addAction({
action: "APPROVE_ALT",
label: "Alternative Approve",
type: "accept" // or "positive"// For positive appearance.
}, function(button) {
this._completeTaskAlternative(taskId, true);
}, this);

In the example above, you create one negative and two positive custom action buttons.

In case you haven’t specified the additional type parameter, the custom action button appears as Default.
3. (Optional) You can refresh the tasks list once a task is completed. Add the following function as well as a
call to it in the last line of the _completeTask function:

 Sample Code

_refreshTask: function(taskId) {
this.getComponentData().startupParameters.inboxAPI.updateTask("NA",
taskId);
}

3.3.1.1.1.6 Get the Task Description

To retrieve the task description:

The page element of the webapp/view/<view name>.view.xml should include this:

 Sample Code

<ObjectAttribute title="Description" text="{/context/task/Description}"/>

The init function of webapp/Component.js should be like this:

 Sample Code

init: function() {
UIComponent.prototype.init.apply(this, arguments);
this.setModel(models.createDeviceModel(), "device");

var startupParameters = this.getComponentData().startupParameters;

var taskModel = startupParameters.taskModel;
var taskId = taskModel.getData().InstanceID;

var contextModel = new sap.ui.model.json.JSONModel("/

bpmworkflowruntime/rest/v1/task-instances/" + taskId + "/context");
contextModel.setDefaultBindingMode(sap.ui.model.BindingMode.OneWay);
this.setModel(contextModel);

startupParameters.inboxAPI.getDescription("NA",
taskId).done(function(dataDescr){

SAP Cloud Platform Workflow in the Neo Environment

92 PUBLIC Developing Applications with Workflow Service
 contextModel.setProperty("/context/task/Description",
dataDescr.Description);
}).
fail(function(errorText){
contextModel.setProperty("/context/task/Description", "");
jQuery.sap.require("sap.m.MessageBox");
sap.m.MessageBox.error(errorText, { title: "Error"});
});

},

3.3.1.1.1.7 Retrieve Parameters in Custom Task UI

To retrieve the parameters, add the following lines:

 Sample Code

var startupParameters = this.getComponentData().startupParameters;

var queryParameters = startupParameters.oParameters.oQueryParameters

3.3.1.1.1.8 Show and Hidе Footer

To hide footer within the page:

The onInit function of the view controller should be like this:

 Sample Code

onInit: function() {
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.setShowFooter(false);
},

3.3.1.1.1.9 Show and Hide the Back Navigation Button

You can show, hide, and customize the Back navigation button in the header of a custom task UI.

● To show the Back navigation button in the header of a custom task UI, your onInit function of the View
controller should be the following:

 Sample Code

onInit: function() {
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.setShowNavButton(true);
},

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 93
 Passing only the first parameter true will start the default button handler, which will execute
window.history.back().
In some cases, this does not lead to the desired behavior. Therefore, you need to provide a custom handler,
as shown in the next example
○ If you want to further customize your back navigation handler, you can edit your onInit function of
the View controller as follows:

 Sample Code

onInit: function() {
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.setShowNavButton(true, function(){
alert("You are about to leave this
task");
window.history.back();
});
},

● To hide the Back navigation button in the header of a custom task UI, your onInit function of the View
controller should be the following:

 Sample Code

onInit: function() {
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.setShowNavButton(false);
},

3.3.1.1.1.10 Disable and Enable Custom Action Buttons

Prerequisites

● You have implemented a custom task UI and the target SAPUI5 application is embedded into the detail
view of My Inbox.
● You have added custom action buttons via addAction method available in the My Inbox API. For more
information, see Add Custom Action Buttons [page 91]

Context

For example, you have implemented validation logic for user input data. Based on the validation result, you may
wish to disable or enable the action buttons, available in the My Inbox button bar, added in the prerequisites.

SAP Cloud Platform Workflow in the Neo Environment

94 PUBLIC Developing Applications with Workflow Service
Procedure

1. To disable a single custom action button available in the My Inbox button bar, you can use the
disableAction() method of My Inbox API. The method disableAction() expects as parameter the
value of the action parameter used in the addAction() method. For example, if you have added a button
via addAction({action: “APPROVE”, label: “Approve”}), you can disable it via
disableAction(“APPROVE”). In this case the implementation for your event handler should look like
this:

 Sample Code

onEventHandler: function(){
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.disableAction( "APPROVE" );
},

2. To enable a single custom action button available in the My Inbox button bar, you can use the
enableAction() method of My Inbox API. The method enableAction() expects as parameter the
value of the action parameter used in the addAction() method. For example, if you have added a button
via addAction({action: “APPROVE”, label: “Approve”}), you can enable it via
enableAction(“APPROVE”). In this case the implementation for your event handler should look like this:

 Sample Code

onEventHandler: function(){
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.enableAction ( "APPROVE" );
},

3. To disable all custom action buttons available in the My Inbox button bar, the implementation for your
event handler should be the following:

 Sample Code

onEventHandler: function(){
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.disableAllActions();
},

4. To enable all custom action buttons available in the My Inbox button bar, the implementation for your event
handler should be the following:

 Sample Code

onEventHandler: function(){
var startupParameters = this.getComponentData().startupParameters;
startupParameters.inboxAPI.enableAllActions();
},

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 95
Results

The buttons available in the My Inbox button bar become disabled or enabled as per your implementation.

3.3.1.1.1.11 Call an External Service from a Custom Task UI

To show, for example, contextual information that is not available in the workflow context, you want to call the
REST service, which you developed yourself, from within a custom task UI.

Prerequisites

Your REST service is deployed on SAP Cloud Platform or is reachable from your customer account.

Procedure

1. In your HTML5 application containing the custom task UI, define an additional route in the neo-app.json
file. This route targets a destination pointing to your service, for example, deployed as a Java application on
SAP Cloud Platform.

 Sample Code

…
{
"path": "/external-service",
"target": {
"type": "destination",
"name": "external-service",
"entryPath": "/"
},
"description": "External Service"
}
…

2. In your account that is subscribed to the workflow service, create a new destination with the name you
specified in the previous step.

For more information, see Configuring Destinations from the Cockpit.

3. Configure the destination against your deployed service.

 Note

If you want to propagate the user from My Inbox to your REST service, select App2App SSO as the
authentication type to use.

SAP Cloud Platform Workflow in the Neo Environment

96 PUBLIC Developing Applications with Workflow Service
 4. In your custom task UI application, call your REST service using an Ajax call. The service is then available at
the following URL: /html5apps/<taskui_application>/<destination_name>/
<relative_api_path>

 Sample Code

_callService: function() {
$.ajax({
url: "/html5apps/custtakui/external-service/v1/external-data",
method: "GET",
contentType: "application/json",
async: false,
data: ""
});
}

3.3.1.1.2 Deploy an HTML5 Application

You deploy your HTML5 app using standard SAP Cloud Platform procedures.

Procedure

To activate your application deploy it to SAP Cloud Platform.

For more information, see Deploying Your App to SAP Cloud Platform in the SAP Cloud Platform
documentation.

3.3.1.2 Creating a Start UI

Create a sample UI for starting workflow instances.

Prerequisites

A workflow definition (for which the start UI is developed) is deployed into the workflow service runtime.

Context

The use case here is as follows. There is a particular workflow definition deployed into the workflow service
runtime. A user interface is needed which would allow the end users to start the instances of the corresponding

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 97
workflow. In addition, the users must be able to specify some arbitrary values that will be used in the contexts
of the started instances.

Procedure

1. Create an HTML5 Application for the Start UI [page 98].

2. Define the Destination Route [page 99]
3. Extend the View [page 99]
4. Extend the Controller [page 100]

Related Information

SAP Web IDE Full-Stack Documentation

HTML5: Getting Started

3.3.1.2.1 Create an HTML5 Application for the Start UI

You create your HTML5 app using standard SAP Cloud Platform procedures.

Procedure

1. Create an HTML5 application.

For more information, see Creating an HTML5 Application in the SAP Cloud Platform documentation.
2. Create a project using the SAPUI5 Application template.

For more information, see Creating a Project in the SAP Cloud Platform documentation.

SAP Cloud Platform Workflow in the Neo Environment

98 PUBLIC Developing Applications with Workflow Service
3.3.1.2.2 Define the Destination Route

You have to define the destination route for the workflow service in the application configuration file.

Procedure

In the neo-app.json file created in the webapp folder of your application, include the following destination
route element pointing to workflow service runtime into the routes array:

 Sample Code

{
"path": "bpmworkflowruntime",
"target": {
"type": "destination",
"name": "bpmworkflowruntime",
"entryPath": "/workflow-service"
},
"description": "Workflow Service Runtime"
}

3.3.1.2.3 Extend the View

Context

The view contains an input field, a button, and a text field. By pressing the button, a user starts a workflow
instance. The value of the input field will be used in the workflow context. The response of the workflow start
request will be printed out in the text field.

Procedure

In the view XML file created in webapp/view folder of your application, substitute the existing page element
with the following code:

 Sample Code

<Page title="Workflow Start UI">

<content>
<VBox width="100%" direction="Column" id="__vbox0">
<items>
<Input width="100%" id="textInput" value="{/text}"/>

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 99
 <Button text="Start Workflow" width="100px" id="__button0"
press="startWorkflow"/>
<Text text="{/result}" maxLines="0" id="__text0"/>
</items>
</VBox>
</content>
</Page>

3.3.1.2.4 Extend the Controller

Procedure

In the controller JS file created in webapp/controller folder of your application, include the following
functions as the fields of the second parameter of the Controller.extend function call:

○ Implement Data Model Instantiation [page 101]

○ Implement XSRF Token Fetch [page 101]
○ Implement Workflow Instance Start [page 102]
○ Bind an Action to the Button Push Event [page 103]

Results

As a result, the extension parameter of the controller looks as follows:

 Sample Code

{
onInit: function() {
this.getView().setModel(new sap.ui.model.json.JSONModel({
text: "",
result: ""
}));
},

startWorkflow: function() {
var token = this._fetchToken();
this._startInstance(token);
},

_startInstance: function(token) {
var model = this.getView().getModel();
var text = model.getProperty("/text");
var contextJson = JSON.parse(text);
$.ajax({
url: "/bpmworkflowruntime/rest/v1/workflow-instances",
method: "POST",
async: false,
contentType: "application/json",
headers: {
"X-CSRF-Token": token
},
data: JSON.stringify({
definitionId: "<your workflow ID>",

SAP Cloud Platform Workflow in the Neo Environment

100 PUBLIC Developing Applications with Workflow Service
 context: contextJson
}),
success: function(result, xhr, data) {
model.setProperty("/result", JSON.stringify(result, null, 4));
}
});
},

_fetchToken: function() {
var token;
$.ajax({
url: "/bpmworkflowruntime/rest/v1/xsrf-token",
method: "GET",
async: false,
headers: {
"X-CSRF-Token": "Fetch"
},
success: function(result, xhr, data) {
token = data.getResponseHeader("X-CSRF-Token");
}
});
return token;
}
}

3.3.1.2.4.1 Implement Data Model Instantiation

During initialization a data model should be assigned to the view. In this example, the model is represented by
an object with two fields: text and result. The text field refers to the input of the user, which will be used in the
workflow instance context while starting. The result field refers to the string representation of the response to
the workflow start request:

 Sample Code

onInit: function() {
this.getView().setModel(new sap.ui.model.json.JSONModel({
text: "",
result: ""
}));
}

3.3.1.2.4.2 Implement XSRF Token Fetch

To call the workflow start REST API, the request needs an XSRF token. The following function can supply the
token:

 Sample Code

_fetchToken: function() {
var token;
$.ajax({

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 101
 url: "/bpmworkflowruntime/rest/v1/xsrf-token",
method: "GET",
async: false,
headers: {
"X-CSRF-Token": "Fetch"
},
success: function(result, xhr, data) {
token = data.getResponseHeader("X-CSRF-Token");
}
});
return token;
}

3.3.1.2.4.3 Implement Workflow Instance Start

The workflow is started using the corresponding HTTP call to the workflow service REST API.

For more information, see Using Workflow APIs [page 125]. In this example, the input of the user is used in the
context of the workflow instance: Namely, in its text field. In addition, the response of the call is assigned to the
corresponding property in the data model:

 Sample Code

_startInstance: function(token) {
var model = this.getView().getModel();
var inputValue = model.getProperty("/text");
$.ajax({
url: "/bpmworkflowruntime/rest/v1/workflow-instances",
method: "POST",
async: false,
contentType: "application/json",
headers: {
"X-CSRF-Token": token
},
data: JSON.stringify({
definitionId: "<your workflow ID>",
context: {
text: inputValue
}
}),
success: function(result, xhr, data) {
model.setProperty("/result", JSON.stringify(result, null, 4));
}
});
}

 Note

Substitute the <your workflow ID> part of the URL with the ID of the deployed workflow definition of
interest.

Feel free to change the name of the text field of the workflow context to fit to the corresponding workflow
definition.

SAP Cloud Platform Workflow in the Neo Environment

102 PUBLIC Developing Applications with Workflow Service
3.3.1.2.4.4 Bind an Action to the Button Push Event

The logic described above is triggered when a user presses the button:

 Sample Code

startWorkflow: function() {
var token = this._fetchToken();
this._startInstance(token);
}

3.3.1.3 Data Propagation from My Inbox to Task

Application

You can associate a custom task UI to a workflow user task, which is then rendered in the detail view of My
Inbox for the task.

When you select a task, My Inbox instantiates the custom task UI application component and transfers a set of
data for the selected task.

 Sample Code

startupParameters{
taskModel: JsonModel > ({InstanceID:<value>,
TaskDefinitionID:<value>,.....}),
applicationPath: <string>,
queryParameters: {<key>:<value>,<key>:<value>,...... },
inboxAPI:{<APIs>}
}

Property Type Description

taskModel sap.ui.model.json.JSONModel Contains task properties.

For more information, see Accessing

Task Data from Task Application [page
104].

queryParameters Json Contains key value pairs of query pa­

rameter and value configured in the
Task UI component integration configu-
ration.

applicationPath single-value string data Contains the path to the Task UI com­
ponent using which the component is
loaded.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 103
Property Type Description

inboxAPI Contains the API published by My Inbox

for integration purposes.

For more information, see My Inbox UI

Integration API Reference [page 105].

From the Task UI component, this data can be accessed as shown below:

 Sample Code

var
startupParameters=this.getOwnerComponent().getComponentData().startupParameter
s;

3.3.1.3.1 Accessing Task Data from Task Application

Task data is transferred from My Inbox to the task application on startup using the property taskModel.

taskModel is of type sap.ui.model.json.JSONModel and contains the following task properties:

● SAP__Origin
● InstanceID
● TaskDefinitionID
● TaskDefinitionName
● TaskTitle
● Priority
● PriorityText
● Status
● StatusText
● CreatedBy
● CreatedOn
● Processor

PriorityText and StatusText contain translated texts that are specific to the My Inbox user's locale.

SAP Cloud Platform Workflow in the Neo Environment

104 PUBLIC Developing Applications with Workflow Service
3.3.1.3.2 My Inbox UI Integration API Reference

You can use a set of APIs to integrate your task application with My Inbox.

addAction

Adds an action button to the My Inbox footer.

Parameters

Name Type Description

action object A JSON object specifying action details.

Properties:

● action : string
● label : string
● type : string (either Accept or Reject)

actionEventHandler function The function to be called when the event occurs.

listener? object Context object to call the event handler.

Return Value

success : A boolean representing successful addition of the button to the footer.

getDescription

Retrieves the task description and returns a promise that is resolved when the task description is retrieved.

Parameters

Name Type Description

SAPOrigin string Value for the parameter SAP__Origin for the specific task

taskInstanceId string Value for the parameter InstanceId for the specific task

Return Value

Promise: A promise that is resolved when the task description is retrieved. It is rejected with an error if the
parameters SAPOrigin or taskInstanceId are passed with empty value or if the task description could not be
retrieved (due to network issues).

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 105
removeAction

Removes an action added previously by the integrated application.

Parameters

Name Type Description

actionName string Name of the action to be removed

Return Value

success : A boolean representing successful removal of the button from the footer

updateTask

Updates the task in the master task list and returns a promise that is resolved when the task list is updated.

Parameters

Name Type Description

SAPOrigin string Value for the parameter SAP__Origin for the specific task

taskInstanceId string Value for the parameter InstanceId for the specific task

Return Value

Promise: A promise that is resolved when the task list is updated. It is rejected with an error if the parameters
SAPOrigin or taskInstanceId are passed with empty value or if the task list could not be updated (due to
network issues).

setShowFooter

Shows or hides footer of the page.

Parameters

Name Type Description

showFooter boolean Flag representing whether to show or hide footer in the page.
The default value is false.

setShowNavButton

Shows or hides navigation button in header of the page.

SAP Cloud Platform Workflow in the Neo Environment

106 PUBLIC Developing Applications with Workflow Service
Parameters

Name Type Description

showNavButton boolean Flag representing whether to show or hide navigation button

in header of the page. The default value is false.

navEventHandler? function Function to be called when navigation button is clicked.

3.3.2 Creating a Workflow Form

You can create UIs for your end users using the form editor. End users can interact with a workflow through
user interfaces.

● Start Forms
Initiate a workflow based on form input. To provide a start form to your end users, integrate it into your
portal and or SAP Fiori launchpad.
● Task Forms
Enable end users to participate in a workflow instance using tasks in their inboxes.

 Note

You can’t use a start form in a user task or a task form to initiate a workflow.

A form includes a header section and a details section.

The information that is displayed in the header depends on the form type:

● Start Forms
The header information comes from the attributes that are configured in the SAP Fiori launchpad tile. Task-
related attributes such as Created On and Created By aren’t supported.
● Task Forms
The header information comes from the runtime attributes of the user task's that are defined in the
workflow editor, for example, Created On and Created By. In addition, some information comes from the
workflow editor, for example, Name, Subject, and Description.

The Form Details section displays the UI definition that you set up in the form editor. You can model fields and
also define a layout by grouping the fields into sections and subsections.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 107
3.3.2.1 Create Your Form

You can create start and task forms using the form editor.

Context

Access the form editor either directly as described in the steps below, or access it from within the workflow
editor.

For more information about using the workflow editor, see Configure a User Task UI Using Workflow Forms
[page 44].

 Note

You can use the slider below each table to adapt the table height.

Procedure

1. Right-click the workflow project or any folder within your project, for example, a dedicated forms folder,
and choose New Form .

 Note

You can store your forms in any existing folder, or you might want to create a folder that's used only for
storing the forms.

2. Enter a name, ID, and a revision for your form, for example:

Field Sample Value

Name ApprovalForm

ID approval-form

Revision 2.0 or Draft

3. Choose Create.

SAP Cloud Platform Workflow in the Neo Environment

108 PUBLIC Developing Applications with Workflow Service
Results

A corresponding file with the name <yourformname>.form is created, and the form editor opens an empty
form. To reopen a form file, either double-click it or choose Form Editor from the context menu. You can rename
the file at any time.

 Note

● If you’ve already referenced a task form file within a user task in a workflow, make sure to adapt the
reference in the workflow editor accordingly.
● The form ID must be unique inside your account. Don't change the form ID unless you're sure that you
want to give the form a new identity.

3.3.2.1.1 Define Form

You can build your form by using fields or collections. You can arrange it with sections and subsections.

Related Information

Add Fields [page 109]

Add Collections [page 114]

3.3.2.1.1.1 Add Fields

Build forms using fields that you can arrange using sections and subsections.

Procedure

1. To open a file, double-click it.

2. To add a field to your form, choose Add Field at the top of the field table.

Where the field appears depends on whether you’ve selected an existing field, any sections, subsection, or
collection.

If you selected an existing field before choosing Add Field, then the new field is inserted right below the
selected field. If you don't select an existing field, the new one that's added depends on which element
you've selected. If a section is selected, the new field is added at the end of the section. If a subsection is
selected, the new field is added to the end of the subsection. If a collection is selected, the new field is
added to the end of the collection. For more information, see Adapt the Form Layout [page 117] and Add
Collections [page 114].

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 109
3. On the Properties view, name the field by entering text for the field label.
4. Enter the ID of the field or use the automatically generated one.

 Note

IDs must start with a letter and can contain only alphanumeric characters and underscores. IDs must
be unique within a section, subsection, or collection. If a form doesn’t contain sections, subsections or
collections, IDs must be unique within the entire form.

5. Bind your field to a property element of the context model.

When you bind a field to a property in the task context, the respective value is shown during form
rendering. Furthermore, if the field is set to editable (see Set the mode of your field [page 112]), changes to
that value by the user are written back to the task context during task completion. If a bound property
doesn't exist in the task context, it’s created during task completion. For more information and limitations,
see Automatic Model Initialization [page 120].

The syntax follows the JUEL style described in Expressions [page 79]. Fields on form level, within sections
or subsections are bound to an absolute context path within the context model (keyword: 'context'). For
fields that are part of collections, you usually specify a path relative to the collection's context path
(keyword: 'item'). For more information, see Add Collections [page 114].

Context Path Suggestions

The form editor helps you enter complex context path bindings. This requires a syntactically valid JSON,
for example, your workflow sample context. It must exist on the same level as your form definition and
must have the same name, for example, my.form and my.json.

As a result, the editor provides a list of suggestions based on the already entered characters and the
underlying JSON. In addition, sample values are shown.

 Note

You can access the context model only using dot notation. Conditions and literals aren’t supported.
Make sure that you use a valid path to a property in the context.

 Example

Let's take a sample task form and assume that your task context is the following:

 Sample Code

{
"report": {
"name": "Travel for TechEd Las Vegas",
"id": "A2E6D6A5ABD4C37",
"owner": "Steve Consultant",
"totalClaimedAmount": 870.30,
"currencyCode": "EUR",
"includesVAT": true,
"numItems": 5,
"invoices": [{
"date": "2017-10-09",
"time": "13:30:00",
"orderDateTime": "2017-10-01T09:15:43.000Z",
"amount": 420.0

SAP Cloud Platform Workflow in the Neo Environment

110 PUBLIC Developing Applications with Workflow Service
 },
{
"date": "2017-10-15",
"time": "09:15:00",
"orderDateTime": "2017-10-10T14:33:21.000Z"
"amount": 510.0
}]
}
}

 Sample Code

You want to define a field within a section that displays the timestamp of the purchase order in the
invoice. You can use the following data for this field:

Property Sample Value Comment

Label Date and Time of Purchase Or­ -

der

Type DateTime -

Context Path $ The context path points to the property orderDateTime

{context.report.invoices[ within the first item of the invoices array.
0].orderDateTime}

For an example for collection fields, see Add Collections [page 114].

6. Set the type for your field.

Field types determine how the field is represented in your task UI. The task UI validates the user input
against the value range of the specified type.

Currently the following field types are supported:

Type Value Range UI Representation

String Any printable character Labeled input field

Boolean false or true Checkbox

Integer -9007199254740991 to 9007199254740991 Labeled input field

Float -3.4028235e+38 to 3.4028235e+38 Labeled input field

Date Any date of Gregorian calendar from year 1 to Labeled input field with date picker
year 9999

DateTime Any point in time within a date Labeled input field with date and time selector

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 111
 Type Value Range UI Representation

Time Any time of a day, from 00:00:00 to 23:59:59 Labeled input field with time selector
(or 12:00:00AM-11:59:59PM depending on the
locale)

 Note

If the defined field type doesn't match the type of the actual value within the task context, the task form
isn’t rendered. A detailed error message is issued in the browser console.

7. Set the mode of your field.

Currently the following modes are supported for fields:

Mode UI Representation

Editable (Default) The end user can modify the value on the UI.

Display-Only The end user isn't allowed to modify the value on the UI.

8. Set the constraints of your field.

Currently, only the following constraint is supported for editable fields:

Constraint UI Representation

Required The end user must enter a value; otherwise, they can’t use decisions to complete
the task (see Add or Delete Decisions [page 118]).

 Note

Constraints affect only the rendered form and not the workflow runtime itself. Required attribute values
can still be set to an empty string using the REST API or script tasks.

9. (Optional) On the Properties under UI Configuration, change the standard UI control derived from the field
type.

Field Type Supported Controls (for editable fields)

String Input, text area, dropdown, radio buttons

Boolean Checkbox (can’t be changed)

Date Input, dropdown, radio buttons

Time Input, dropdown, radio buttons

DateTime Input, dropdown, radio buttons

SAP Cloud Platform Workflow in the Neo Environment

112 PUBLIC Developing Applications with Workflow Service
 Field Type Supported Controls (for editable fields)

Integer Input, dropdown, radio buttons

Float Input, dropdown, radio buttons

Depending on the selected control, additional configuration options apply.

a. Define a placeholder for your Input or Text Area.

That way, an empty control displays the placeholder to give users a hint when they enter data.
a. Set the height for your field. This is only available for fields that are of type "String" and aren’t part of a
collection.

Currently the following field heights are supported:

Height UI Representation

Single Line (Default) A single-line input field

Small A text area approximately twice the height of a single-line field with scrolling ca­
pabilities

Medium A text area approximately twice the height of a small field with scrolling capabil­
ities

Large A text area approximately twice the height of a medium field with scrolling ca­
pabilities

b. Use dropdown lists or radio buttons.

Selectable Values:

Define an enumeration of allowed values for this type.

Each entry consists of two parts:

○ The value that is being populated to the workflow context, if selected.
○ A human-readable display value that is used for presentation inside the control.

For both the type-specific validations apply (see Form Validation [page 123]).
○ To add an entry, choose Add from the toolbar menu. You can add at most 100 entries to the list.
○ To remove a selected entry, choose Delete from the toolbar menu. You need at least 1 entry in the
list.
○ To influence the order of a selected entry, choose Move Up or Move Down from the toolbar menu.

You can’t mark fields that use dropdowns or radio buttons as optional. These fields are automatically
set to "required" in the editor and you can’t change this setting. To set the constraint yourself, you need
to switch back to the default control setting.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 113
  Note

If you use the form inside a task, the value inside the specified context path must match with one
of the elements. Otherwise, the form isn't rendered.

3.3.2.1.1.2 Add Collections

Build task forms using collections that you can arrange using sections and subsections.

Context

Similar to sections and subsections, collections can contain fields. Collections are rendered in the form as
tables, and the fields within a collection represent the table columns. As opposed to sections or subsection,
collections themselves are bound to a context path, namely an array within the collection, which specifies the
rows of the table.

Procedure

1. To open a file, double-click it.

2. To add a collection to your form, choose Add Collection at the top of the field table.

Where the collection appears depends on whether you’ve selected an existing collection, any sections, or
subsections. If you selected an existing collection before choosing Add Collection, then the new collection
is inserted right below the selected collection. If you don't select an existing collection, the position of the
newly added collection depends on which element was selected. If a section is selected, the new collection
is added at the end of the section. If a subsection is selected, the new collection is added to the end of the
subsection. For more information, see Adapt the Form Layout [page 117].
3. (Optional) In the Properties view, name the collection by entering text for the collection title, which would
be rendered as the table title in the form.
4. Enter the ID of the collection or use the automatically generated one.

 Note

IDs must start with a letter and can contain only alphanumeric characters and underscores. IDs must
be unique within a section or subsection. If a form doesn't contain sections or subsections, IDs must be
unique within the entire form.

5. Bind your collection to a property element. Collections on form level within sections or subsections are
bound to an absolute context path within the task model (keyword: 'context'). The context path must point
to an array. This binding specifies the rows of your table. The syntax follows the JUEL style described in
Expressions [page 79].

SAP Cloud Platform Workflow in the Neo Environment

114 PUBLIC Developing Applications with Workflow Service
  Example

Let's assume that your process context is the following:

{
"report": {
"name": "Travel for TechEd Las Vegas",
"id": "A2E6D6A5ABD4C37",
"owner": "Steve Consultant",
"totalClaimedAmount": 870.30,
"currencyCode": "EUR",
"includesVAT": true,
"numItems": 5,
"invoices": [{
"date": "2017-10-09",
"time": "13:30:00",
"orderDateTime": "2017-10-01T09:15:43.000Z",
"amount": 420.0
},
{
"date": "2017-10-15",
"time": "09:15:00",
"orderDateTime": "2017-10-10T14:33:21.000Z"
"amount": 510.0
}]
}
}

You want to define a collection that displays a list of invoices. You can use the following data for this
collection:

Property Sample Value

Title List of Invoices

Context Path ${context.report.invoices}

 Note

You can access the context model only using dot notation. Conditions and literals aren’t supported.
Make sure that you use a valid path to a property in the context.

6. A collection is rendered as a table. While the bound context property of the collection specifies the rows of
the table, you have to add fields to specify the columns. To do so, select the collection and press Add Field.
For more information, see Add Fields [page 109]. For fields in collections, you can specify the context path
relative to the containing collection. To do so, use the relative syntax $
{item.path.to.relative.property} instead of the absolute syntax $
{context.path.to.property}. However, you can still bind to absolute context paths.

 Example

Using the same task context and collection as before, you want to specify that for each invoice, the
timestamp of its purchase order and its amount should be shown. Also, each row should display the
global currency code of the report.

You can use the following data for the collection fields:

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 115
 Label Context Path Type

Date and Time of Purchase Order ${item.orderDateTime} DateTime

Amount ${item.amount} Float

Currency $ String
{context.report.currencyCod
e}

3.3.2.1.2 Set the Form Mode

Once you've created a form, you can choose whether end users are allowed to change the values in the form's
fields.

Procedure

1. In the fields table, make sure that no field is selected.

 Note

To deselect a selected field, click it again.

2. Set the mode of your form.

Currently, the following modes are supported:

Mode UI Representation

Editable (Default) For each field, you can modify the value on the UI.

Display-Only For each field, you can no longer modify the value on the UI. The fields are in dis­
play mode.

A form-wide display-only mode overwrites individual field "display-only" modes. You can no longer change
the mode for individual fields. However, your previously modeled modes as well as constraints on the
individual fields are preserved in case you switch to form wide Edititable mode again.

 Note

The mode affects only the rendered form and not the workflow runtime itself. You can still modify read-
only attribute values at the API level or in script tasks.

SAP Cloud Platform Workflow in the Neo Environment

116 PUBLIC Developing Applications with Workflow Service
3.3.2.1.3 Adapt the Form Layout

Define the layout of your forms, for example, whether to group fields.

Group Fields or Collections into Sections and Subsections

To group your fields or collections, choose Add Section. If your form does not have any sections, this action
moves all fields or collections into a new section. Otherwise, a new section is added.

If you need a more granular grouping, you can choose Add Subsection while a section is selected. If the
selected section already contains fields or collections, they are moved into the new subsection.

 Note

Don't add more than 100 sections to your form, or more than 100 subsections to a single section. If you
need more than 100 subsections, divide them up across several sections.

If you need more than 100 sections, split your UI into multiple forms that are connected using multiple user
tasks.

Only 100 fields or collections per section or subsection are supported. It is not possible to have both
collections and fields next to each other in the same section or subsection.

To add new fields to a section or subsection, select it and choose Add Field. To add new collections to a section
or subsection, select it and choose Add Collection.

For each section or subsection, you can specify text for a section title.

Move Form Elements

Use the following options to change the location of fields, sections, and subsections:

● The context menu

● The actions in the table toolbar (copy, cut, paste)
● Drag and drop

If you paste a subsection before or after a section, the subsection is converted into a section. If you paste a
section before or after a subsection or into a section, then it’s converted into a subsection. The latter one
applies only to sections that contain fields but not to sections that contain subsections. By using copy and
paste, it is also possible to move elements from one form to another. Pasting collections or fields that are part
of a collection into a start form is not possible.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 117
3.3.2.1.4 Create Decisions of a Task Form

Users can complete tasks using decision buttons.

You can model the following types of decisions for your task form:

● A positive decision
Example: Approve
● A negative decision
Example: Reject
● A neutral decision

Each decision type has its own visual appearance that matches its semantics.

The workflow context stores the decision the user has selected. For more information about how to access the
decision, see Access the Decisions [page 119].

3.3.2.1.4.1 Add or Delete Decisions

You must define the decisions that users can choose from to complete a task.

Procedure

1. Switch to the DECISIONS tab.

2. Choose Add.
a. Specify the display text for the decision button.
b. (Optional) Edit the generated decision ID.

 Note

IDs must start with a letter and can contain only alphanumeric characters and underscores.
Decisions in your form must have a unique ID.

c. Specify the decision type.

Move Decisions

Procedure

You can duplicate or change the order of decisions using any of the following options:
○ The context menu
○ The actions in the table toolbar (copy, cut, paste)

SAP Cloud Platform Workflow in the Neo Environment

118 PUBLIC Developing Applications with Workflow Service
 ○ Drag and drop

 Note

My Inbox sorts the decisions first by type (Positive, Negative, Neutral), then by the order in which they're
listed in the DECISIONS table.

3.3.2.1.4.2 Access the Decisions

To complete a task, an end user selects a decision.

Context

For user tasks that use forms, the decision is stored within the user task's properties. See Expressions [page
79]. For each completed task in a flow, the decision_id of the most recently selected decision is stored in the
decision property.

 Example

An end user chooses Accept in a user task with the ID "usertask1". You can access the corresponding
decision ID, for example, accept, using a JUEL expression, as follows:

 Sample Code

${usertasks.usertask1.last.decision}

Procedure

Use the decision in the context of an exclusive gateway, see Configure a Sequence Flow [page 72]

 Example

“${usertasks.usertask1.last.decision=="accept"}”

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 119
3.3.2.1.5 Automatic Model Initialization

There are a few runtime behaviors that you must consider when creating forms, for example, make sure that
you avoid binding collisions.

Model Initialization

To ensure that a form renders correctly in the UI, you must build the corresponding data model so that it can be
rendered. The following items are verified automatically:

● Binding collisions
When a binding collision occurs, the UI doesn't render, and shows an error message. In addition, the
workflow forms runtime posts an aggregated issue report to the browser console.
● Referenced objects in binding path are missing.
You can bind fields to context properties that don't exist in the task context when the form is opened. The
workflow forms runtime creates the missing context properties.

 Note

The missing properties are created with a default value, depending on their type:

Property Type Default Value

Numerical values, time, date and null

datetime

String empty string ("")

Boolean false

 Note

For binding paths that include array elements, missing context properties are created only if each array
element in the path exists in the context.

For more information, see Bind your field to an attribute of the task context model [page 110]. This is what
it looks like:

SAP Cloud Platform Workflow in the Neo Environment

120 PUBLIC Developing Applications with Workflow Service
 Workflow (Task) Context Binding UI Model (Initial) UI Model with Data

{} ${context.myNode1.my­
{ {
Node2.myProperty} myNode1: { myNode1: {
myNode2:{} myNode2: {
}
} myProperty:
"anyValue"
}
}
}

Missing context properties are also created for an existing element in a array.

Workflow (Task) Context Binding Input UI Model with Data

{a : [{}]} ${context.a[0].b.c} anyValue

{
a: [{
b: {

c: "anyValue"
}
}]
}

For example, the following scenario is not supported, because the specified array element (0) doesn't
exist:

Workflow (Task) Context Binding

{a : []} ${context.a[0].b.c}

3.3.2.1.6 Versioning Forms

Versioning is a key activity that should be considered by all developers who build production-grade software.

This holds specifically true for forms used by potentially long-running workflows. Without versioning, changes
you develop for forms in future workflow instances unexpectedly also affect already running instances. These
unintended changes often have a negative impact.

Comparison to Versioning with Git or Similar Tools

Don't confuse versioning of forms with other versioning methods that use version control systems (VCS).
Versioning forms in a Git repository handles design-time versioning of artifacts and is orthogonal to the
runtime-related versioning discussed here. See below for recommendations on how to combine the two.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 121
Technical Versioning of Forms

By default, forms are already versioned in a technical way: Each time a form is deployed to the runtime, a new
(technical) version is created for it. Previous versions are preserved for historical and auditing reasons;
however, end users cannot access them at runtime. This way, developers and administrators have
transparency over who deployed which form and when.

Compatible Changes Compared to Incompatible Changes

In the technical versioning outlined above, any change to a form represents a new (unqualified) version. There's
no way for developers to distinguish between compatible and incompatible changes.

If a change or release fixes a usability or functional issue, it's typically considered compatible. Incompatible
changes fundamentally alter a form and are usually driven by a business requirement. An incompatible change
can, for example, apply to mandatory form fields that you add to a form. Consequently, a workflow needs to
store additional data in its context that is expected by the changed form. To address this, developers typically
need to change the workflow definition accordingly. Incompatible changes are assumed to take effect for new
workflow instances while already running workflow instances continue to operate on the previous version.
Already running workflow instances wouldn't have the necessary context data.

Forms Revision Concept

To allow the differentiation between compatible and incompatible changes, each form has a revision property
that is stored along with any other properties, for example, the form name and form ID.

You can set the revision property when you create a new form or edit its metadata. For more information, see
Create Your Form [page 108].

When you refer to a form in a workflow’s user task, you are asked to specify the revision of the form to use. For
more information, see Configure a User Task UI Using Workflow Forms [page 44].

As stated above, changing the revision of a form and deploying it to the form runtime implies a major release of
the form. By contrast, deploying a form without a change of its revision implies a minor release. This lets you
choose between changes that affect existing workflow instances and changes that affect only future workflow
instances, provided that you change the revision of the respective workflows’ user tasks accordingly.

Versioning Best Practices

The following is a list of recommendations of when to leave a form revision unchanged, and when to alter the
revision.

SAP Cloud Platform Workflow in the Neo Environment

122 PUBLIC Developing Applications with Workflow Service
 Compatible Changes (Revision Unchanged) Incompatible Changes (Revision Altered)

Change the label or placeholder for a form field Change a form field type

Change the layout settings for a form, for exam­ Change the ID or value for a form field (*)
ple, sections or subsections

Change the text of a form field Change the decision ID for a form field

Remove a read-only form field Add or remove a form field (*)

Add a read-only form field (*)

(*) Although there may be conditions where compatibility can be ensured, these types of changes are usually
incompatible. This is decided on a case-by-case basis.

 Tip

When you're changing a form revision, we recommend that you tag or otherwise flag the corresponding
commits in Git. This helps when you need to patch an older revision at a later time.

Related Information

Add Fields [page 109]

3.3.2.1.7 Form Validation

The form editor automatically validates your form while you model it.

If there are missing mandatory entries or invalid inputs for any of your form’s elements, for example, for fields,
sections, subsections, or decisions, the form editor notifies you about these inputs. This already happens when
you add an element to your form.

You receive information about errors in your modeled form as follows:

● Form elements with invalid inputs are highlighted with a red mark.
● If the element itself has valid inputs but contains at least one other element with invalid inputs, an orange
mark is displayed.
● The actual validation error for each input of the form element is shown in the respective properties view.
Invalid input fields are highlighted in red and have an error message attached.

 Note

If the form editor detects any error in a form, it also adds a reference to the Problems view of SAP Web IDE.
The Problems view is dynamically updated when you change files within the scope of the analysis.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 123
3.3.2.2 Deploy Your Form

You must deploy a form to the form runtime before you can use it.

Prerequisites

● You are assigned the WorkflowDeveloper role. For more information, see Authorization Configuration
[page 150].
● All property values you've set must be valid or the deployment fails.
● Maintain all mandatory properties for the form itself, fields, sections, and subsections. Otherwise, the
deployment fails.

Procedure

Right-click the forms file, and choose Deploy Deploy to SAP Cloud Platform Workflow .

 Note

Deploying a modified form without changing its revision number, may influence running workflow instances
(see Versioning Forms [page 121]).

3.4 Build and Deploy Workflows

Prerequisites

You’re assigned the WorkflowDeveloper role. For more information, see Authorization Configuration [page 150].

Procedure

1. Ensure that you have completed modeling the workflow.

A new workflow instance automatically uses the latest deployed version of a given workflow definition. This
change doesn’t affect workflow instances that were started with an earlier version of the workflow
definition.

2. In the project explorer, select the workflow file, and from its context menu, choose Deploy Deploy to
SAP Cloud Platform Workflow .

SAP Cloud Platform Workflow in the Neo Environment

124 PUBLIC Developing Applications with Workflow Service
  Note

○ Ensure that you save the workflow before deploying a workflow.

○ You can deploy only one workflow at a time.
○ When your project contains (modified) forms with unchanged revisions, this may influence running
workflow instances (see Versioning Forms [page 121]).

3.5 Using Workflow APIs

The REST-based API allows a tight integration of tasks on SAP Cloud Platform with SAP Cloud Platform
Workflow.

SAP Cloud Platform Workflow exposes two kinds of API to address different use cases. The OData-based APIs
expose user-task related data implementing a subset of the Task Consumption Model (TCM), see SAP Note
2304317 . Their primary use case is to build a personal inbox. The REST-based APIs allow you to list and
manage workflow instances, definitions, and user tasks across recipients. Depending on your role, you can do
the following:

● Send messages to workflows.

● List user task instances and inspect details of a user task instance and its context.
● List workflow definitions and inspect details of a workflow definition.
● List workflow instances and inspect details of a workflow instance, its context, and its execution log.
● Execute various lifecycle and administrative operations on the resources involved in the workflow service.

For information about who can execute these actions, see Authorization Configuration [page 150].

Access the API Documentation

See the SAP Cloud Platform Workflow API hub documentation.

The API documents are also uploaded individually:

● Workflow API for Neo

● Inbox API for Neo

Authentication and Authorization

Clients must authenticate to use the workflow service APIs. The following authentication types are supported:

● Basic authentication.
● SAML2
● OAuth2 (client credentials, authorization code, and SAML 2.0 Bearer Assertion Flow for OAuth 2.0)

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 125
Rate Limits

To ensure optimal operation of the service, REST API execution is subject to resource limits, for example,
regarding the number of requests per second. If the limits are exceeded, API calls return HTTP status 429
(“Too many requests”). The client should then reduce the number of calls.

Related Information

Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161]
Access Workflow APIs Using OAuth 2.0 Authentication (Client Credentials) [page 126]
API Hub: Workflow APIs
Workflow API for Neo
Inbox API for Neo

3.5.1 Access Workflow APIs Using OAuth 2.0 Authentication

(Client Credentials)

Call workflow service APIs using OAuth 2.0 authentication (client credentials flow).

Context

 Note

The workflow service does not define any OAuth 2.0 scopes. Instead, assign the existing roles to the user
who executes the service calls.

Procedure

1. Register an OAuth client.

a. Navigate to your subaccount in the SAP Cloud Platform cockpit.

For more information, see Navigate to Global Accounts and Subaccounts in the Cockpit.
b. In the navigation area, choose Security OAuth .
c. Under OAuth Settings, choose Clients.
d. To create a client, choose Register New Client and use the following data, then choose Save.

SAP Cloud Platform Workflow in the Neo Environment

126 PUBLIC Developing Applications with Workflow Service
 Field Value Description

Name Free text

Subscription <SAP provider account>/bpmwork­ Creates the OAuth 2.0 client in the
flowruntime context of your workflow service
subscription.

ID This is your client ID used for author­

ization.

Authorization Grant Client Credentials Specifies the OAuth 2.0 flow that is
used to request the access token
and authenticate the API call.

Secret Free text This is your client secret used to ac­

cess APIs.

Token Lifetime Default: 60 minutes You can adapt the value.

For more information, see Register an OAuth Client.

2. To call the user oauth_client_<clientID>, assign the necessary role of the workflow service API.
a. Navigate to your subaccount in the SAP Cloud Platform cockpit.

For more information, see Navigate to Global Accounts and Subaccounts in the Cockpit.
b. In the navigation area, choose Services.
c. Search for the Workflow service.
d. On the Workflow tile, choose Configure Service.
e. In the navigation area, choose Roles.
f. In the Roles table, select the role that you want to assign to the oauth_client_<clientID> user,
where clientID is the ID of the OAuth client that you have just created.

For more information about roles, see Authorization Configuration [page 150].
3. Request an access token from the OAuth 2.0 authorization server.
a. Send a POST request to the token endpoint and specify the grant type as client credentials. To
determine the endpoint URL in the cockpit, see Security OAuth Branding OAuth URLs .

Example: https://oauthasservices-<your_account>.<landscape_host>/oauth2/api/v1/
token?grant_type=client_credentials
b. Authenticate the call using basic authentication, where the user name corresponds to your OAuth
client ID and the password to the client secret.
c. Copy the access token from the HTTP response.
4. Perform the call to the workflow service API by sending the access token as the header:
○ Header name: Authorization
○ Header value: Bearer <access token>

The only difference from basic authorization is the header where you use the authorization header as:
Bearer <access-token>. The rest all remains the same.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 127
  Note

Consume the API using the OAuth 2.0 authorization protocol.

There is no need for an XSRF token if you are using the OAuth 2.0 authentication protocol. All you need
is to get the access token first:
○ URL: Token endpoint URL
○ Method: POST
○ User name: OAuth client ID
○ Password: OAuth client secret

The access token that you receive is used to call the APIs.

3.5.2 Access Workflow APIs Using OAuth 2.0 Authentication

(Authorization Code Grant)

This procedure illustrates how to call workflow service APIs using OAuth 2.0 authentication using an example
walk-through of the authorization code flow. It shows how several OAuth2 concepts are applied to workflow
service and which configuration parameters are used.

Prerequisites

● Create a client in SAP Cloud Platform cockpit for your subaccount using the following data:

Field Value Description

Subscription <SAP provider account>/ Creates the OAuth 2.0 client in the
bpmworkflowruntime context of your workflow service sub­
scription.

Authorization Grant Authorization Code Specifies the OAuth 2.0 flow that is
used to request the access token and
authenticate the API call.

For more information, see Register an OAuth Client in OAuth 2.0 Configuration.

● Assign the necessary role of the workflow service API that you want to call to the user on whose behalf the
call to the workflow service API is executed. Typically, this is the user who authenticates the call to the
OAuth 2.0 authorization endpoint below. For more information about roles, see Authorization
Configuration [page 150].

SAP Cloud Platform Workflow in the Neo Environment

128 PUBLIC Developing Applications with Workflow Service
Context

Developers typically use this flow in web applications. However, other flows might be supported or more
appropriate in your use case. See, for example, a blog about another flow.

Procedure

1. Request an authorization code from the OAuth 2.0 authorization server.

a. Send a GET request to the authorization endpoint and specify both the client ID and the response type
as "code". To determine the endpoint URL in the cockpit, see Security OAuth Branding OAuth
URLs .

Example: https://oauthasservices-<your_account>.<landscape_host>/oauth2/api/v1/
authorize?client_id=<clientId>&response_type=code
b. Authenticate the call using the real user that should be propagated to the workflow service API (on
behalf user).

The response redirects to the URL that you specified as a callback URL in the client details. The value
of the parameter code represents the access token.
c. Copy the code from the HTTP URL.
2. Request an access token from the OAuth 2.0 authorization server.
a. Send a POST request to the token endpoint and specify the grant type as authorization code. To
determine the endpoint URL in the cockpit, see Security OAuth Branding OAuth URLs .Use
the url service configuration parameter and the code from step 1c.

Example: https://oauthasservices-<your_account>.<landscape_host>/oauth2/api/v1/
token?grant_type=authorization_code&code=<code_step1c>
b. Authenticate the call using basic authentication, where the user name corresponds to your OAuth
client ID and the password to the client secret.
c. Copy the access token from the HTTP response body (access_token attribute of the JSON
structure).

 Note

If the access token expires before you get to execute step 3, use a refresh token.

The HTTP response in step 2 includes a refresh token (refresh_token attribute). It’s typically
used when the lifetime of the returned access token has expired but the application still wants to
execute an HTTP request (as in step 3) on behalf of the given user. You can use the refresh token to
request a new access token for the user without again asking the user for consent. The new access
token then replaces the old one with a new lifetime.

To request a new access token for a given refresh token, send a POST request to the same token
endpoint as in step 2 passing the refresh token. The call must be authenticated again with basic
authentication, where the user name corresponds to your OAuth client ID and the password to the
client secret.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 129
  Example

https://oauthasservices-<your_account>.int.sap.hana.ondemand.com/
oauth2/api/v1/token?
grant_type=refresh_token&refresh_token=<refresh_token>

However, it’s important to understand that the refresh token has a lifetime as well. Lifetimes of
access and refresh tokens can be configured separately. If the lifetime of the refresh token has
expired, there’s no means to request a new refresh token.

3. Perform the call to the workflow service API by sending the access token as the header. Use the end-points
below the base URL from the service configuration parameter workflow_api_url.
○ Header name: Authorization
○ Header value: Bearer <access token>

3.5.3 Determine the Service Host

In the Neo environment, the URL of the host has the following format: https://<host>/workflow-
service/rest. To work with the API actions, you must determine the specific URL.

 Note

If you access the workflow APIs from a user interface of an application, you typically need to use a URL that
enables Cross-Origin Resource Sharing (CORS) through reverse proxies.

● In the Neo environment:

If you develop a custom task UI using an HTML5 application, you can leverage the existing destination
route in My Inbox. For an example of how to access the workflow API from a custom task UI, see
Creating an HTML5 Application for the Custom Task UI [page 85].
If you develop an HTML5 app from scratch, you have to define a new destination route on your own. For
more information, see Define the Destination Route [page 99].

Related Information

Determine the Service Host in Neo Environment [page 131]

SAP Cloud Platform Workflow in the Neo Environment

130 PUBLIC Developing Applications with Workflow Service
3.5.3.1 Determine the Service Host in Neo Environment

Procedure

1. In the cockpit, choose your subaccount.

2. Choose Connectivity Destinations in the navigation area.

3. From the list of destinations, select bpmworkflowruntime.
4. Under Destination Configuration, find the URL link.
5. Copy the URL, and use it in your API URL. Make sure that the complete URL ends with /rest.

3.5.4 Modifying the Context of a Workflow Instance

You can modify a context of a workflow instance in RUNNING, ERRONEOUS, or SUSPENDED status.

 Note

● If the context of a workflow instance is in COMPLETED or CANCELED status, the system does not allow
you to modify it.
● We recommend suspending the workflow instance first and ensure that further entries are not written
into the corresponding execution log. Then the context modification is considered safe from collisions
with any ongoing workflow instance activities. After the necessary changes to the context are
performed, you can resume the workflow instance execution. See the section about suspending or
resuming workflow instance. For more information, see /v1/workflow-instances/{workflowInstanceId}.

Override Context

Overriding a context of the workflow instance removes the contents of the context before performing the
override operation. It is substituted with the payload of the operation.

 Example

Context contents before overriding:

 Sample Code

{
variableOnlyInOldContext: 1,
variableOverriden: "good bye!",
variableNestedObject: {
variableNested: true,
variableNestedInOldContext: 1000
}
}

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 131
 Override operation payload:
{
variableOverriden: "hello!",
variableNestedObject: {
variableNested: false,
variableNestedNew: "new value"
},
variableNew: "I'm new"
}

Context contents after the override operation (equals the payload of the override operation):

 Sample Code

{
variableOverriden: "hello!",
variableNestedObject: {
variableNested: false,
variableNestedNew: "new value"
},
variableNew: "I'm new"
}

Patch Context

Patching a context of the workflow instance merges the contents of the context before performing the override
operation with the payload of the operation.

The following situations are possible in this case:

● A variable is present in the workflow instance context and in the operation payload. After the operation is
performed, the value of this variable in the workflow instance context is equal to the corresponding value in
operation payload.
● A variable is present in the workflow instance context, but not in the operation payload. After the operation
is performed, the variable remains unchanged.
● A variable is not present in the workflow instance context before performing the operation, but it is present
in the operation payload. After the operation is performed, the variable is added in the workflow instance
context with the corresponding value.

 Note

Merging happens at all levels of complex objects nesting.

 Example

Context contents before patching:

 Sample Code

{
variableOnlyInOldContext: 1,
variableOverriden: "good bye!",
variableNestedObject: {

SAP Cloud Platform Workflow in the Neo Environment

132 PUBLIC Developing Applications with Workflow Service
 variableNested: true,
variableNestedInOldContext: 1000
},
variableNew: "I'm new"
}

Patch operation payload:

 Sample Code

{
variableOverriden: "hello!",
variableNestedObject: {
variableNested: false,
variableNestedNew: "new value"
},
variableNew: "I'm new"
}

Context contents after the override operation:

 Sample Code

{
variableOnlyInOldContext: 1,
variableOverriden: "hello!",
variableNestedObject: {
variableNested: false,
variableNestedInOldContext: 1000,
variableNestedNew: "new value"
},
variableNew: "I'm new"
}

Consider the naming conventions for context variables. For more information, see Conventions,
Restrictions, and Limits [page 9].

3.5.5 Updating Task Properties

With the task patch API, you can modify the properties of the tasks in status READY or RESERVED.

To update a task, send an HTTP request with the PATCH method to the corresponding API endpoint with the
following payload:

 Example

Task Update Payload

 Sample Code

{
"subject": "<New subject>",
"description": "<New description>",

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 133
 "dueDate": "<New due date>",
"priority": "<New priority>",
"processor": "<New processor>",
"recipientUsers": "<New recipient users>",
"recipientGroups": "<New recipient groups>"
}

Where <New subject>, <New description>, <New due date>, <New priority>, <New
processor>, <New recipient users>, and <New recipient groups> refer to the values of the task
subject, description, due date, priority, processor, recipient users, and recipient groups after the operation
is performed.

Although this sample includes all fields, you only need to specify those fields that you really want to change.

For the "priority" field, the following values are supported:

● "LOW"
● "MEDIUM"
● "HIGH"
● "VERY_HIGH"

You can specify the due date using either of these formats: yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z' or
yyyyMMddHHmmss[.SSS]. The specified time stamp is UTC and is shown to the users in My Inbox in their local
time.

Supported date values are, for example:

● 2018-02-17T12:28:51Z
● 2018-02-17T12:28:51.854Z
● 20180217122851
● 20180217122851.854

 Note

The workflow service does not explicitly check whether processors, recipient users, or groups assigned to
user tasks actually exist in the system.

 Sample Code

{
"subject": "Approve purchase of the new monitor for John Doe",
"description": "John Doe has requested a new monitor, because
the old one has been broken",
"priority": "MEDIUM",
"dueDate": 20180217122851,
"processor": "JaneDoe",
"recipientUsers": "JaneDoe, AlexSmith",
"recipientGroups": "Managers, HRs"
}

To remove a due date, recipient users, recipient groups, or the processor from a task, use an empty string:

 Sample Code

{
"dueDate": "",
"processor": "",

SAP Cloud Platform Workflow in the Neo Environment

134 PUBLIC Developing Applications with Workflow Service
 "recipientUsers": "",
"recipientGroups": ""
}

Expressions

You can use Expressions [page 79] to refer to the context of the relevant workflow instance while updating the
task properties:

 Example

Task Update Payload with Expressions

 Sample Code

{
"subject": "Approve purchase order for $
{context.employee.name} ${context.employee.surname}",
"description": "Price: ${context.price*context.saleReduction}
EUR"
}

If the workflow instance context is as follows:

 Example

Workflow Instance Context

 Sample Code

{
"employee": {
"name": "John",
"surname": "Doe"
},
"price": 8000,
"saleReduction": 0.5
}

The task has the subject Approve purchase order for John Doe and the description Price: 4000
EUR.

Simultaneous Updating and Completing Tasks

With the same API endpoint that is used for updating the tasks you can also complete the tasks. The Workflow
Participant role must be assigned to your user. To this end, "status" ("COMPLETED") and optionally
"context" need to be present in the payload, for example:

 Sample Code

{
"context": {
"price": 6000,

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 135
 "reductionReason": "Outdated"
},
"status": "COMPLETED"
}

To update and complete the task with the same request, the Workflow Administrator role must be assigned to
your user. The payload then looks as follows:

 Sample Code

{
"context": {
"price": 6000,
"reductionReason": "Outdated"
},
"status": "COMPLETED",
"subject": "Approve purchase order for $
{context.employee.name} ${context.employee.surname}",
"description": "Price: ${context.price*context.saleReduction}
EUR"
}

This has the following implications. First, the context of the relevant workflow instance is updated accordingly.
Second, the task properties are updated taking into account the new values of the context. And, finally, task
status changes to "COMPLETED".

In the above example, after the operation is performed, the subject of the task still is "Approve purchase order
for John Doe", but the description is set taking into account the new values: "Price: 3000 EUR".

Related Information

Authorization Configuration [page 150]

3.5.6 Workflow Execution Log

The workflow execution log contains details about the execution history of a workflow instance.

The workflow execution log collects information that might be of use or interest to either a business user or an
administrator. However, it is not a technical log.

Logged Entries/Events

Log Entry/Event Description

WORKFLOW_STARTED Workflow instance started.

WORKFLOW_COMPLETED Workflow instance completed.

WORKFLOW_CANCELED Workflow instance canceled.

SAP Cloud Platform Workflow in the Neo Environment

136 PUBLIC Developing Applications with Workflow Service
 Log Entry/Event Description

WORKFLOW_SUSPENDED Workflow instance suspended.

WORKFLOW_CONTINUED Workflow instance continued after processing was stopped

due to an error.

WORKFLOW_RESUMED Workflow instance resumed.

WORKFLOW_CONTEXT_OVERWRITTEN_BY_ADMIN Context administrator completely overrode the workflow

context.

WORKFLOW_ROLES_PATCHED_BY_ADMIN Administrator changed the instance-specific role assign­

ment of the given workflow instance.

WORKFLOW_CONTEXT_PATCHED_BY_ADMIN Context administrator partially modified the workflow con­

text.

USERTASK_CREATED User task created.

USERTASK_CLAIMED User task claimed.

USERTASK_COMPLETED User task completed.

USERTASK_RELEASED User task released.

USERTASK_PATCHED_BY_ADMIN User task status, its properties, or its context was changed
by administrator.

USERTASK_CANCELED_BY_BOUNDARY_EVENT User task canceled by a boundary timer event.

USERTASK_FAILED User task failed

SERVICETASK_CREATED Service task created.

SERVICETASK_COMPLETED Service task completed.

SERVICETASK_FAILED Service task failed.

SCRIPTTASK_CREATED Script task created.

SCRIPTTASK_COMPLETED Script task completed.

SCRIPTTASK_FAILED Script task failed.

MAILTASK_CREATED Mail task created.

MAILTASK_COMPLETED Mail task completed.

MAILTASK_FAILED Mail task failed.

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 137
Log Entry/Event Description

INTERMEDIATE_MESSAGE_EVENT_REACHED Intermediate message event reached from a workflow in­

stance.

INTERMEDIATE_MESSAGE_EVENT_TRIGGERED Intermediate message event triggered for a workflow in­

stance.

INTERMEDIATE_TIMER_EVENT_REACHED Intermediate timer event reached in a workflow instance.

INTERMEDIATE_TIMER_EVENT_TRIGGERED Intermediate timer event triggered for a workflow instance.

CANCELING_BOUNDARY_TIMER_EVENT_TRIGGERED Boundary timer event triggered the cancellation of the at­

tached user task and continued the alternative flow.

NONCANCELING_BOUNDARY_TIMER_EVENT_TRIGGE Boundary timer event triggered the alternative flow attached

RED to it without canceling the attached user task.

3.5.7 Error Codes

If an error occurs while working with the SAP Cloud Platform Workflow API, the returned error object has an
"errorCode" attribute.

This attribute identifies the area or workflow element where the problem occurred.

The table below describes the error code groups and points to the documentation that helps you fix the error.

Error Code / Error Code Prefix Description Related Links

bpm.workflowruntime.generic This is a generic error. Contact SAP support cit­

.error ing the given log ID.

bpm.workflowruntime.express There was a problem resolving an expression.

ion This might be caused by the expression in the
workflow definition or the data accessed
through an expression, for example, the work­
flow context.

bpm.workflowruntime.destina There was a problem resolving or accessing a Destinations [page 152]

tion destination.
Configure the Workflow Service
Mail Destination with SAP Web IDE
[page 25]

bpm.workflowruntime.service There was a problem executing a service task.

task

SAP Cloud Platform Workflow in the Neo Environment

138 PUBLIC Developing Applications with Workflow Service
 Error Code / Error Code Prefix Description Related Links

bpm.workflowruntime.mailtas There was a problem executing a mail task.

k

bpm.workflowruntime.mailtas There was a problem connecting to the mail

k.connection server, either on network level or relating to the
secure communication setup.

bpm.workflowruntime.mailtas There was a problem while communicating with

k.server a mail server. The server refused the login or
didn’t accept a mail.

bpm.workflowruntime.scriptt There was a problem executing a script task.

ask

bpm.workflowruntime.usertas There was a problem executing a user task.

k

bpm.workflowruntime.rest There was a problem calling the REST API. Using Workflow APIs [page 125]

Related Information

API Hub: SAP Cloud Platform Workflow

SAP Cloud Platform Workflow in the Neo Environment

Developing Applications with Workflow Service PUBLIC 139
4 User Guide

The user guide for the workflow service is for end-users and key-users.

End-users find information on Working with Tasks in My Inbox [page 140]:

● Access the My Inbox Application [page 142]

● My Inbox Layout [page 142]
● Expert View [page 143]

Related Information

Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161]

4.1 Working with Tasks in My Inbox

You can process workflow service tasks within the My Inbox application, which runs on the SAP Fiori launchpad.
You can use My Inbox on your desktop or mobile device.

A user task is a type of flow object that appears in My Inbox. You can work on a task, complete a task instance,
and view its description.

My Inbox displays the following information about the workflow and tasks:

● Task title
● Tasks with status Ready and Reserved
● Tasks with priority

Key Features

● View the tasks that are assigned to you.

● Claim tasks.

 Note

When you claim a task, you become its processor and its other recipients no longer see it in My Inbox.
The status of a claimed task changes from Ready to Reserved.

● View your current and available tasks.

● Display the task count on the My Inbox tile in the SAP Fiori launchpad.

SAP Cloud Platform Workflow in the Neo Environment

140 PUBLIC User Guide
 ● Sort tasks by priority, due date, task title, and the user who created the task.
● Filter your tasks by priority, due date, status Ready, and creation date. The task list is limited to the first
1000 entries that match the filter. In the Filtered by header, you can view information about all the applied
filters on the task list in a tooltip, which appears when you hover over the Filter with your mouse.
● Group tasks by task title, priority, status, and by task type. The task type is the name of the user task as it
was assigned in the workflow model defined in the editor.
● View task-specific details.
● Release tasks for which you are the processor.

 Note

When you release a task, you are no longer assigned as a processor of this task and it becomes visible
in My Inbox for its other recipients. The status of the task changes from Reserved to Ready.

● View Workflow Log.

● Execute and complete tasks.

 Note

When you select a task from the List view, the task details are displayed in the Details view. The custom
action buttons, added by following the procedure described in Add Custom Action Buttons [page 91],
appear at the bottom of the screen. When you select one of the buttons, a Custom Action Dialog
appears on your screen. You have the option to add a Decision Note. The field with label Decision Note
is optional except for the case when it is marked with an asterisk (*) before it. In case the field should
be filled in, the Decision Option button is active only if this requirement is fulfilled. Otherwise you are
able to submit your decision without adding a Decision Note.

Rate Limits

To ensure optimal operation of the service, SAP Cloud Platform Workflow execution is subject to resource
limits, for example, regarding the number of requests per second. If the limit is exceeded, My Inbox displays the
following error message: " Your action could not be performed because the usage limits are
reached. Please retry later or contact your help desk for assistance.”. The client should
then reduce the number of calls. For more information, see Conventions, Restrictions, and Limits [page 9].

Related Information

Destinations [page 152]

SAP Cloud Platform Workflow in the Neo Environment

User Guide PUBLIC 141
4.1.1 Access the My Inbox Application

Prerequisites

● An SAP ID user and access to an SAP Cloud Platform trial or global account. For more information, see Get
a Paid Global Account.
● Assign the relevant runtime roles of the workflow service to the SAP ID user. For more information, see
Authorization Configuration [page 150]
● Subscribe to the SAP Cloud Platform Portal service.
● Enable My Inbox app in the SAP Fiori launchpad for users to access the application. For more information,
see Configuring SAP Fiori Launchpad Objects [page 15].

4.1.2 My Inbox Layout

Depending on your use-case scenario, you can use the Master-Detail view or the Expert View of My Inbox for
displaying and processing your tasks.

Master-Detail View

The Master-Detail view offers options for scanning, selecting, and navigating the tasks that are shown in the
Details area.

In the Master-Detail view of My Inbox, you can perform search, filtering, sorting and grouping operations. It is
optimized for mobile devices.

It allows you to perform all standard actions as follows:

● View details about the workflow for a selected task and events, relevant to it chronologically.

 Note

SAP Cloud Platform Workflow shows only the user ID; it does not show additional user details.

● Claim a task to reserve it for processing.

● Release a task for which you are the processor.
● Share a task via e-mail.
● You can sort, group, and filter tasks.
● You can view workflow related information.
● Process tasks using custom actions.
For more information, see Adding Task Completion Buttons [page 89].

SAP Cloud Platform Workflow in the Neo Environment

142 PUBLIC User Guide
Expert View

The Expert view is a tabular representation of the standard attributes of your tasks in My Inbox.

It allows you to:

● View large number of tasks.

● See the standard attributes for a task, such as Task Title, Status, and Priority.
● Use an advanced custom search filter to find the tasks you want to process.
● Sort, group, and filter tasks.
● Personalize the view per user, and share with other users.

4.1.3 Expert View

The Expert View is a tabular representation of the standard attributes of your tasks in My Inbox.

Expert View

The Expert View is a standard predefined tile, which is part of the Workflow catalog. To add it to your Fiori
Launchpad navigate to Me area App Finder Pin it to the desired Group.

Use the Expert View to perform any of the following tasks:

● View a large number of tasks.

● See the standard attributes for a task, such as Task Title, Status, and Priority.
● Quickly narrow the list down to tasks that you want to process by using the advanced custom search filter.
● Sort and group tasks.
● Personalize the view per user, and share it with other users.

 Info

The changes that you make to the Expert View of My Inbox are persistent. You can use the personalized My
Inbox in another browser or device without having to make the changes again.

Open Tasks

In the Expert View, you can open a task by clicking the line item of the task.

With the default UI of My Inbox, the Detail View screen provides an information tab. If general custom attributes
have been defined, they are shown here.

 Note

Your predefined custom attributes are shown in the header area of the Task Details screen. For more
information, see Display Custom Attributes in My Inbox [page 47].

SAP Cloud Platform Workflow in the Neo Environment

User Guide PUBLIC 143
  Note

The Created By column of the Expert View contains empty values. To hide it, choose Personalize and
deselect it from the Columns dialog. This action does not persist.

Show Log

To view details about a task workflow and its events chronologically, choose Show Log.

● Workflow Log
The Workflow Log tab contains details about the workflow of a selected task and events relevant to it
chronologically.

Claim

To reserve a task for processing, choose Claim.

 Note

When you claim a task, you become the processor of the task and all other recipients no longer see it in My
Inbox. In this case, the status of the task changes from Ready to Reserved.

Release

You can release any task for which you are the processor.

 Note

Once you release a task, you are no longer assigned as one of its processors, and it becomes visible in My
Inbox for its other recipients. The status of the task changes from Reserved to Ready.

SAP Cloud Platform Workflow in the Neo Environment

144 PUBLIC User Guide
4.1.3.1 Expert View Standard Operations

In the Expert view, you can search, filter, refresh, sort, and group tasks that require action. You can also
personalize the table columns.

Search Tasks

Search all tasks by entering one or more keywords in the Search field.

 Note

The search operation is performed on the client side, that is, only among the tasks that are loaded into the
UI.

Filter Tasks

Use the Show Filter Bar button to filter tasks by the following criteria: Task Title, Status, Priority, Due By, and
Created Within.

Refresh Tasks

Use the Refresh function to update your table with tasks.

Sort Tasks

Use the Sort function to sort tasks on the following criteria: Ascending, Descending, Task Title, Status, Priority,
Due On, and Created On.

Group Tasks

Use the Group function of the Expert view to group tasks by Ascending, Descending, Task Type, Status, Priority,
Due On, Created On, None.

SAP Cloud Platform Workflow in the Neo Environment

User Guide PUBLIC 145
Personalize Table

To choose which columns (All, Task Title, Status, Priority, Created By, Created On, Due Date) appear in your
table with tasks, use the Personalize function of the Expert view.

 Note

When you select a Task, the footer of the screen shows only the available standard task actions, for
example, Show Log, Claim, or Release. Custom task actions are shown when you open the Task Details view.

4.1.3.1.1 Variant Management

Variant management in the Expert View of My Inbox allows you to load, save, and change different personalized
variants of the filter bar.

Procedure

1. Choose Filters.
2. Select the types of filters you want to apply.
3. Choose Save View.
4. Insert the name of the view.
5. Choose one of the options: Set as Default, Public, or Apply Automatically.
6. Choose Save.
7. (Optional) Delete a variant.
a. Go to the Select View menu.
b. Choose Manage.
c. Select the view, and choose Delete View.

4.1.4 Scenario-Specific Тiles

Scenario-specific tiles display a filtered set of tasks for domain-specific approvals in My Inbox. The feature is
supported by both the Master-Detail view and the Expert view layouts of My Inbox.

This feature is explicitly configured by an Administrator in your organization. For more information, see: Define
Scenario-Specific Tiles in My Inbox [page 18]

Scenario-Specific Tiles in Master-Detail View

The usage of scenario-specific tiles allows you to:

SAP Cloud Platform Workflow in the Neo Environment

146 PUBLIC User Guide
 ● Use the full set of functionalities offered by the Master-Detail view.
● Work on a homogeneous task list, based on task types grouped into a scenario.

Scenario-Specific Tiles in Expert View

The Expert view-specific feature allows you to:

● Use the full set of functionalities offered by the Expert view.

● View the additional business data (custom attributes) rendered automatically as columns, as part of the of
the Expert View table, without having to filter by task type.
● Sort or filter the tasks based on additional business data (custom attributes). For more information, see:
Display Custom Attributes in My Inbox [page 47].

 Info

After the initial loading of My Inbox in Expert View, the usage of scenario-specific tile is marked by the
Filters (1) value in the header of the Table view. This indicates, that the task list is prefiltered according
to the scenario configuration.

 Note

You can personalize the display of columns using the table Personalize button . For more
information, see Expert View Standard Operations [page 145].

SAP Cloud Platform Workflow in the Neo Environment

User Guide PUBLIC 147
5 Security

This guide provides an overview of the security-relevant information that applies to the SAP Cloud Platform
Workflow.

It does not replace the administration guide that is available for productive operation.

Related Information

Security Guide for SAP Cloud Platform

5.1 Architecture with SAP Web IDE

The architecture of the workflow service comprises several components and subservices.

Overview of Components and Subservices

The workflow service includes the following subservices that are provisioned into the customer subaccount
using the SAP Cloud Platform cross-subaccount subscription concept:

● Workflow and form editors in SAP Web IDE Full-Stack

SAP Cloud Platform Workflow in the Neo Environment

148 PUBLIC Security
 ● Workflow service runtime
● Monitor workflows
● My Inbox

For more information, see Multitenant Applications in the SAP Cloud Platform documentation.

Prerequisites for using the workflow service:

● A subscription to the SAP Cloud Platform Portal, respectively the SAP Fiori launchpad is required to use My
Inbox and the Monitor Workflows app.
● While the workflow service runtime exposes a set of REST-based application programming interfaces
(APIs) for managing workflow instances and task instances, the workflow editor, the Monitor Workflows
app, and My Inbox provide only user interfaces (UIs).
● Access to all subservices of the workflow service requires a valid user identity in the corresponding identity
provider that is configured in the customer subaccount.
For more information, see Identity Provider and Identity Management [page 149].
● All UIs offer single sign-on authentication based on SAML assertions. The APIs of the workflow service
runtime can be accessed with SSO authentication using SAML or OAuth 2.0 as well as basic
authentication. In addition, all APIs that can lead to data manipulation in the workflow service runtime are
protected against cross-site request forgery (XSRF).
For more information, see the API documentation of the REST-based API.

5.2 Identity Provider and Identity Management

For identity management and authentication, the workflow service relies on the identity provider (IdP) that is
configured in the customer subaccount that owns the respective subscriptions.

All requests handled by the workflow service subscriptions are authenticated against the identity provider of
the customer subaccount and authorized against the role assignments specified on the subscriptions in the
customer subaccount. All users who need to interact with the various subservices of the workflow service must
be available in the respective identity provider. You can replace the default SAP Cloud Platform Identity
Authentication service with your own corporate identity provider.

 Note

For authentication using SAML or OAuth 2.0, you can use an additional corporate identity provider.
Requests that use basic authentication are still handled by the SAP Cloud Platform Identity Authentication
service.

For more information about the concepts and the necessary configuration steps, see Authorization and Trust
Management in the Neo Environment in the SAP Cloud Platform documentation.

 Note

Changes to the identity provider can cause running, erroneous, and suspended workflow instances with
principal propagation to fail on service tasks as soon as these are reached. It is extremely costly to recover
such instances.

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 149
Related Information

Groups in SAP Cloud Platform Workflow – Part 1

Authentication and Authorization Issues with SAP Web IDE [page 174]

5.3 Authorization Configuration

Assign roles to specific users using the workflow service instance.

The workflow service runtime is one of many SAP Cloud Platform services that you can subscribe to. A service
instance of the workflow service is created when you subscribe to the workflow service.

Authorization for the workflow service is provided at the following levels:

● Workflow service global roles: Users who are assigned to these global roles are then granted the associated
permissions for all workflow definitions, instances, and tasks.
● Instance-specific authorizations: Users who are assigned to these roles are granted permission only for the
respective workflow instance. The workflow service provides APIs that use these authorizations. Users who
are explicitly named by user ID, or as members of explicitly named groups, gain the associated permission
only for the respective workflow instance. You can assign instance-specific permissions using the REST
API. For more information, see Workflow Definition versus Workflow Instance [page 6].
To deploy workflow definitions, users must be assigned to the WorkflowDeveloper role.

Authorizations are cumulative: If any one authorization allows access, access is granted.

SAP Cloud Platform includes predefined platform roles that support the typical tasks performed by users when
interacting with the platform. In addition, subaccount administrators can combine various scopes into a
custom platform role that addresses their individual requirements. Certain activities, such as deployment of
applications and assignment of roles to users or groups, require platform roles. These roles are assigned in the
SAP Cloud Platform cockpit.

For more information about assigning global roles and permissions, see Getting Started with Workflow Service
in the Neo Environment [page 14].

Roles for Accessing Workflow Service Runtime

Role Description

WorkflowDeveloper (global role) ● Permission to use the workflow editor and deploy workflow definitions
● Permission to query workflow definitions
● Permission to retrieve the current error messages of a workflow instance
● Permission to retrieve the model of the latest version of a specified workflow defi-
nition

SAP Cloud Platform Workflow in the Neo Environment

150 PUBLIC Security
 Role Description

WorkflowContextAdmin (global ● Permission to partially modify or completely override the workflow context of a
role) workflow instance
● Permission to retrieve the context of a task instance
contextAdminUsers

contextAdminGroups

WorkflowContextViewer (global ● Permission to retrieve the context of a workflow instance

role) ● Permission to retrieve the context of a task instance

contextViewerUsers

contextViewerGroups

WorkflowInitiator (global role) ● Permission to view the sample context of a workflow definition
● Permission to start workflow instances (using the API or the Monitor Workflows
app)

WorkflowParticipant (global ● Permission to view tasks in My Inbox, where the user assigned to this role is a re­
role) cipient
● Permission to perform task operations including the following:
○ Claim
○ Release
○ Call the task completion API
● This role is a prerequisite to work with instance-specific permissions.

WorkflowAdmin (global role) ● Permission to use the Monitor Workflows app*

● Permission to query workflow definitions as well as query and cancel workflow in­
adminUsers
stances*
adminGroups ● Permission to retrieve and modify the tasks of a workflow instance
● Permission to retrieve the current error messages of a workflow instance
● Permission to retry the failed steps of an erroneous workflow instance
● Permission to suspend and resume a workflow instance for temporary suspen­
sion of processing
● Permission to retrieve the workflow logs for a given workflow instance
● Permission to download the workflow model in the Monitor Workflow app*

WorkflowMessageSender (global ● Permission to send a message to a set of workflow instances for consumption in
role) intermediate message events

WorkflowTenantOperator ● Permission to export data

(global role) ● Permission to undeploy workflow definitions
● Permission to delete multiple workflow instances
● Permission to purge all workflow definitions, workflow instances, and form defini-
tions

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 151
Role Description

WorkflowViewer (global role) ● Permission to query workflow definitions* as well as query workflow instances
● Permission to view context of workflow instances and task instances
viewerUsers
● Permission to retrieve the tasks of a workflow instance
viewerGroups
● Permission to retrieve the workflow logs for a given workflow instance
● Permission to download the workflow model

* Only for global roles

Related Information

Access the My Inbox Application [page 142]

5.4 Destinations

Subservices communicate using predefined destinations in a customer subaccount, for example, when the My
Inbox or the Manage Workflows application communicates with the workflow runtime.

Predefined destinations are generated and configured when you enable the workflow service in a customer
subaccount. For more information, see Principal Propagation for User Interfaces [page 152] below.

The workflow runtime communicates, according to the workflow definitions, with other services.

● The workflow runtime uses destinations of type Mail to communicate with mail servers.
For more information, see Configure the Workflow Service Mail Destination with SAP Web IDE [page 25]
and Configure Mail Tasks [page 64].
● To communicate with other services, the workflow runtime uses destinations of type HTTP.
For more information, see Destination Configuration for Service Task [page 153] below and Configure
Service Tasks [page 50]. For authentication and authorization purposes, also other, referenced
destinations might be used, for example, OAuth2 authorization endpoints.

Principal Propagation for User Interfaces

Communication between different subservices uses principal propagation, which forwards the user who is
logged on to the user interface to the workflow service runtime. This lets all requests that are sent to the
workflow service runtime on behalf of the user (who initiated the request from the user interface) be posted.

Principal propagation is automatically enabled when you enable the workflow service in a customer
subaccount.

For more information about the concepts and the necessary configuration steps, see Application-to-
Application SSO Authentication in the SAP Cloud Platform documentation.

SAP Cloud Platform Workflow in the Neo Environment

152 PUBLIC Security
Destination Configuration for Service Tasks

The workflow service supports outbound connectivity for orchestrating external services and systems.
Destinations decouple modeling service tasks in your workflow model from the configuration of the physical
back-end systems that are called in the service task at runtime.

 Tip

Configure destinations to use secure communication protocols, such as HTTPS, wherever possible.

While the standard destination concept in SAP Cloud Platform can be used for this purpose, there are several
limitations that apply to their usage in the context of the workflow service.

You can call services using the following authentication types:

● Basic Authentication: Select Basic Authentication as the authentication type in the destination.
● OAuth2 Client Credentials flow: For more information, see Configure a Service Task Destination with
OAuth2 Client Credentials Flow [page 154].
● OAuth2SAMLBearerAssertion: For calls to services outside of SAP Cloud Foundry. Use this authentication
type to propagate the user from certain actions on the workflow to other services. For more information,
see Configure a Service Task Destination with OAuth2SAMLBearerAssertion for Principal Propagation
[page 155] and Configuring Principal Propagation for Service Tasks [page 27].
● OAuth2UserTokenExchange: For calls to services in SAP Cloud Foundry. Use this authentication type to
propagate the user from certain actions on the workflow to other services. For more information, see
OAuth User Token Exchange Authentication and Configuring Principal Propagation for Service Tasks [page
27].
● No Authentication: If the service you want to call doesn't require any authentication, select No
Authentication as the authentication type in the destination.

Besides the authentication type, the following destination features are supported in the workflow service:

● Server authentication (verification): JDK default and custom truststores

● Supported proxy type: Internet, OnPremise
● Destination type:
○ Supports HTTP and HTTPS connectivity based on HTTP destinations in SAP Cloud Platform.
○ For an OnPremise destination, you can optionally specify the LocationId property.

To connect to on-premise back-end systems, you can use the SAP Cloud Platform Connectivity. For more
information about how to install and configure the SAP Cloud Platform Connectivity, see SAP Cloud Platform
Connectivity in the SAP Cloud Platform documentation.

To configure destinations, use the standard SAP Cloud Platform mechanisms in the SAP Cloud Platform
cockpit. For more information, see Configuring Destinations from the Cockpit.

 Note

For server verification, additional properties that were configured at the destinations as described in Server
Certificate Authentication are ignored. Consequently, you can't turn off trust verification, and host names
are always verified in strict mode.

If you use the OnPremise proxy type to connect to an on-premise back-end system, make sure that you
specify the URL of the virtual host that is maintained in the SAP Cloud Platform Connectivity as the

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 153
 destination URL, rather than the actual URL of the back-end system. The scheme of the specified URL
must be http://, not https://.

While destination configuration data is stored completely within the customer subaccount, the workflow
service runtime must temporarily access this data when executing a workflow instance. This data isn't
persisted within the workflow service itself.

5.4.1 Configure a Service Task Destination with OAuth2

Client Credentials Flow

You can set up destinations that use OAuth2 client credentials.

Prerequisites

● Model a service task in a workflow model.

● Create a destination in your account where the name matches the destination property in the service task.
In addition, make sure the URL points to the service you want to call.
● Verify that the service, which the service task should call, is protected with OAuth2 and supports the client
credentials flow.
● Know the corresponding OAuth2 token endpoint from which a valid request token can be requested.
● Know the client ID and the secret for requesting access tokens.

Procedure

1. In the cockpit, choose your subaccount.

2. In the navigation area, choose Connectivity Destinations .

3. Choose New Destination, and set the authentication type to No Authentication.
4. To create an additional property, choose New Property, and enter the name
bpm.oauth.token.destination.

The property must be able to use arbitrary values, for example, ServiceTaskOAuthEndpoint, and must
point to a second destination.
5. Create a new destination with the name that you have specified for the property value in the previous step.
6. Configure the destination using the following data:

Property Value

URL An OAuth2 token endpoint from which a valid access token can be requested

SAP Cloud Platform Workflow in the Neo Environment

154 PUBLIC Security
 Property Value

Authentication type Basic Authentication

User <client ID>

Password Set to client secret

5.4.2 Configure a Service Task Destination with

OAuth2SAMLBearerAssertion for Principal
Propagation

You can set up destinations that use OAuth2SAMLBearerAssertion for Principal Propagation.

Prerequisites

● Model a service task in a workflow model.

● Create a destination in your account where the name matches the destination property in the service task.
In addition, make sure the URL points to the service you want to call.
For more information, see Configuring Destinations from the Cockpit.
● Verify that the service, which the service task should call, is protected with OAuth2 and supports the
OAuth2 SAML bearer assertion flow.
● Know the corresponding OAuth2 token endpoint URL, client ID, and client secret.

Procedure

1. Edit or create a destination as described in Configuring Destinations from the Cockpit.

2. Set OAuth2SAMLBearerAssertion as the authentication type.
3. Configure the destination using the following data. Also maintain the additional properties necessary for
your particular service provider. For more information, see SAML Bearer Assertion Authentication.

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 155
 Property Value

audience entityID property of the SAML 2.0 metadata.

For SAP Cloud Platform Neo, see Principal Propagation to OAuth-Protected Ap­
plications

For SAP Cloud Platform Cloud Foundry, see Principal Propagation from the Neo
to the Cloud Foundry Environment.

To access a Neo service from the Cloud Foundry environment, you need to con­
figure trust between the Cloud Foundry and Neo environments. See, for exam­
ple, Principal Propagation from the Cloud Foundry to the Neo Environment.

For more information, see the documentation of your service provider.

URL Endpoint of the service you want to call

clientKey Client ID of the OAuth client

tokenServiceURL Token endpoint URL of the OAuth server

Example of what the URL could look like:

In the Neo environment: https://oauthasservices-

<subaccount>.<region>/oauth2/api/v1/token

tokenServiceUser Client ID of the OAuth client

tokenServicePassword Client secret of the OAuth client

If you want to call a service in the Cloud Foundry environment, see the account ID in the cockpit in your
space under Instance Service Key .

If you want to call a service in the Neo environment, see the account ID in the cockpit under Security
OAuth Clients .

4. Add a new property:

Property Value

authnContextClassRef urn:oasis:names:tc:SAML:2.0:ac:classes:X509

5. (Optional) If your destination points to a service in a different subaccount in the Neo or Cloud Foundry
environment, you must configure trust between these accounts.

 Note

For more information, see:

○ Authorization and Trust Management in the Neo Environment

○ Principal Propagation Between Neo Subaccounts
○ Principal Propagation from the Neo to the Cloud Foundry Environment

SAP Cloud Platform Workflow in the Neo Environment

156 PUBLIC Security
5.5 Data Protection and Data Privacy

Governments place legal requirements on industry to protect data and privacy. We provide features and
functions to help you meet these requirements.

SAP does not provide legal advice in any form. SAP software supports data protection compliance by providing
security features and data protection-relevant functions, such as blocking and deletion of personal data. In
many cases, compliance with applicable data protection and privacy laws is not covered by a product feature.
Furthermore, this information should not be taken as advice or a recommendation regarding additional
features that would be required in specific IT environments. Decisions related to data protection must be made
on a case-by-case basis, taking into consideration the given system landscape and the applicable legal
requirements. Definitions and other terms used in this documentation are not taken from a specific legal
source.

 Caution

SAP Cloud Platform Workflow shall not be used for storing and processing sensitive personal data.

 Recommendation

Working copies of data from systems of record that are stored in a workflow context should be limited to
the very minimum required for the processing.

5.5.1 Information Report

An information report is a collection of data relating to a data subject. A data privacy specialist may be required
to provide such a report or an application may offer a self-service.

REST API endpoints help the data privacy specialist when building a report. The data export endpoint, for
example, enables the data privacy specialist to retrieve all relevant information for further processing.

For more information, see Using Workflow APIs [page 125] and Export Workflow Service Data [page 30].

5.5.2 Erasure

When handling personal data, consider the legislation in the different countries where your organization
operates. After the data has passed the end of purpose, regulations may require you to delete the data.
However, additional regulations may require you to keep the data longer. During this period, you must block
access to the data by unauthorized persons until the end of the retention period, when the data is finally
deleted.

Personal data can also include referenced data. The challenge for deletion and blocking is first to handle
referenced data and then other data, such as business partner data.

As part of the SAP Cloud Platform offboarding process, all data stored within the workflow service is deleted.

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 157
For audit needs, the workflow service offers an export feature. For more information, see Export Workflow
Service Data [page 30].

To delete workflow data, the following APIs offer a broad scope of data deletion options:

● POST "/v1/purge" completely deletes all workflow data.

● DELETE "/v1/workflow-definitions/{definitionId}" deletes a single workflow definition and all
its workflow instances and the related data.
● PATCH "/v1/workflow-instances" deletes a single workflow instance and all related data.
● PATCH "/v1/workflow-instances/{workflowInstanceId}/context" allows updating the workflow
context to remove sensitive data, leaving the workflow instance in place.
● DELETE "/v1/forms/{formId}" deletes a single workflow form.

For more information, see the SAP Cloud Platform Workflow API.

 Caution

Workflow definitions and form definitions are persisted separately. Deleting a workflow definition does not
delete dependent form definitions and the other way round.

Deleting dependent artifacts of a workflow, such as form definitions, may break existing workflow
definitions and running workflow instances.

5.5.3 Change Log

For auditing purposes or for legal requirements, changes made to personal data should be logged, enabling the
monitoring of who made changes and when.

Therefore, SAP Cloud Platform Workflow may write logs into the audit log handled by the platform itself.

 Note

SAP Cloud Platform Workflow does not provide inherent support for logging changes in the workflow
context.

The workflow developer must take care of logging changes to attributes in the workflow context that hold
personal data. Such changes may occur, for example, when calling external services, through intermediate
message events, or when updating context data through the REST API.

Workflow definitions may include personal data, for example, the user IDs of task recipients. For this kind of
data, the API provides versioning access at /v1/workflow-definitions/{definitionId}/versions.

The workflow service contains information about which users completed which tasks. You can retrieve this
information using the REST API endpoint /v1/workflow-instances/{workflowInstanceId}/
execution-logs.

Furthermore, it contains information about which user has deployed a form definition. You can retrieve this
information by using the data export endpoint, see Information Report [page 157].

SAP Cloud Platform Workflow in the Neo Environment

158 PUBLIC Security
5.5.4 Glossary

Term Definition

Blocking A method of restricting access to data for which the primary

business purpose has ended.

Business purpose A legal, contractual, or in other form justified reason for the
processing of personal data. The assumption is that any pur­
pose has an end that is usually already defined when the
purpose starts.

Consent The action of the data subject confirming that the usage of
his or her personal data shall be allowed for a given purpose.
A consent functionality allows the storage of a consent re­
cord in relation to a specific purpose and shows if a data
subject has granted, withdrawn, or denied consent.

Deletion Deletion of personal data so that the data is no longer avail­

able.

End of business Date where the business with a data subject ends, for exam­
ple the order is completed, the subscription is canceled, or
the last bill is settled.

End of purpose (EoP) End of purpose and start of blocking period. The point in
time, when the primary processing purpose ends (for exam­
ple contract is fulfilled).

End of purpose (EoP) check A method of identifying the point in time for a data set when
the processing of personal data is no longer required for the
primary business purpose. After the EoP has been reached,
the data is blocked and can only be accessed by users with
special authorization (for example, tax auditors).

Personal data Any information relating to an identified or identifiable natu­

ral person ("data subject"). An identifiable natural person is
one who can be identified, directly or indirectly, in particular
by reference to an identifier such as a name, an identification
number, location data, an online identifier or to one or more
factors specific to the physical, physiological, genetic, men­
tal, economic, cultural, or social identity of that natural per­
son

Purpose The information that specifies the reason and the goal for
the processing of a specific set of personal data. As a rule,
the purpose references the relevant legal basis for the proc­
essing of personal data.

SAP Cloud Platform Workflow in the Neo Environment

Security PUBLIC 159
Term Definition

Residence period The period of time between the end of business and the end
of purpose (EoP) for a data set during which the data re­
mains in the database and can be used in case of subse­
quent processes related to the original purpose. At the end
of the longest configured residence period, the data is
blocked or deleted. The residence period is part of the over­
all retention period.

Retention period The period of time between the end of the last business ac­
tivity involving a specific object (for example, a business
partner) and the deletion of the corresponding data, subject
to applicable laws. The retention period is a combination of
the residence period and the blocking period.

Sensitive personal data A category of personal data that usually includes the follow­
ing type of information:

● Special categories of personal data, such as data reveal­

ing racial or ethnic origin, political opinions, religious or
philosophical beliefs, trade union membership, genetic
data, biometric data, data concerning health or sex life
or sexual orientation.
● Personal data subject to professional secrecy
● Personal data relating to criminal or administrative of­
fenses
● Personal data concerning insurances and bank or credit
card accounts

Where-used check (WUC) A process designed to ensure data integrity in the case of
potential blocking of business partner data. An application's
where-used check (WUC) determines if there is any depend­
ent data for a certain business partner in the database. If de­
pendent data exists, this means the data is still required for
business activities. Therefore, the blocking of business part­
ners referenced in the data is prevented.

SAP Cloud Platform Workflow in the Neo Environment

160 PUBLIC Security
6 Monitoring and Troubleshooting

When working with the workflow service, you may encounter issues that prevent access or affect performance.

 Note

We recommend that you also check the Questions & Answers for SAP Cloud Platform Workflow.

If none of these resources helps solve your problem, please open a ticket. See SAP Note 1888290 .

Related Information

End Users Can't Open SAP Fiori Launchpad Tiles [page 169]
Error When Clicking "Go to Service" on Portal Tile [page 178]
HTTP Status 403: User Doesn't Have Sufficient Privileges [page 175]
Tasks Not Appearing in My Inbox [page 179]
Error During Workflow Deployment in SAP Web IDE [page 179]
No Permissions Granted [page 176]

6.1 Managing Workflows Using the Monitor Workflows App

with SAP Web IDE
With the web-based administration Monitor Workflows app you can manage workflow instances and workflow
definitions.

The app offers two interlinked views, one for workflow instances and one for workflow definitions. Both can be
accessed using dedicated tiles in the SAP Fiori launchpad.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 161
  Note

You must have the latest maintenance version or latest version of SAP UI5 configured on SAP Fiori
launchpad to use the Monitor Workflows app.

Related Information

Managing Workflow Instances [page 162]

Managing Task Instances [page 164]
Managing Workflow Definitions [page 166]
Deep Linking in Monitor Workflows App [page 168]

6.1.1 Managing Workflow Instances

The workflow instances view shows a list of all workflow instances.

Prerequisites

The SAP Fiori launchpad objects are configured. For more information, see Configuring SAP Fiori Launchpad
Objects [page 15].

SAP Cloud Platform Workflow in the Neo Environment

162 PUBLIC Monitoring and Troubleshooting
The following actions are available:

● To search the workflow instances, use the following criteria: workflow ID, workflow definition ID, subject,
business key, or the initiator of the workflow instance.
● To search the workflow instances, type the keyword you want to use in the Search field, and choose 
(Search), or choose Enter .
● To filter for workflow instances based on status and definition, choose  (Filter) in the workflow instance
list.

 Note

By default, the filter is applied to show workflow instances in running, erroneous and suspended status.
However, you can also filter workflow instances that are in completed and canceled status.

● To display details about a workflow instance and to navigate to it, select a workflow instance.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 163
● To view the current context of a workflow instance, choose the Workflow Context tab.
● To view tasks of a workflow instance, choose Show Tasks on the details screen of the workflow instance.
● To retry the execution of failed steps of an erroneous workflow instance, choose Retry on the details screen
of the workflow instances.
● To cancel a running workflow instance, choose Terminate on the details screen of the workflow instances.
● To load more entries, scroll down to the end of the list and choose More.
You can also view the count of instances displayed in the view versus the total instance count.
● To suspend a running or erroneous workflow instance, choose Suspend on the details screen of the
workflow instance.
● To resume a suspended workflow instance, choose Resume on the details screen of the workflow instance.
This also retries failed steps.
● To navigate to the workflow definition of an instance, click the workflow definition ID on the details screen
of the workflow instance.

Related Information

Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161]
Deep Linking in Monitor Workflows App [page 168]
Blog: Controlling User Access to Monitor Workflows in SAP Cloud Platform

6.1.2 Managing Task Instances

The task instances view shows tasks for a given workflow instance.

Prerequisites

The SAP Fiori launchpad objects are configured. For more information, see Configuring SAP Fiori Launchpad
Objects [page 15].

SAP Cloud Platform Workflow in the Neo Environment

164 PUBLIC Monitoring and Troubleshooting
The following actions are available:

● To display details about a task instance, select the task.

● To navigate to the workflow instance of the task, click the workflow instance ID on the details screen.
● To navigate to the workflow definition, click the workflow definition ID on the details screen.
● To assign a processor for a task, choose Assign Processor.
This action is only available for tasks with status Ready or Reserved.
When you assign a task to a user, the user becomes its processor. All other task recipients can no longer
see the task in My Inbox. The status of the task changes from Ready to Reserved.
● To unassign the processor of a task, choose Unassign Processor.
This action is only available for tasks with status Reserved.
When you unassign a task from a processor, it is available again to all recipients and they can see the task
in My Inbox. The status of the task changes from Reserved to Ready.

Related Information

Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161]
Deep Linking in Monitor Workflows App [page 168]

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 165
6.1.3 Managing Workflow Definitions

The workflow definitions view shows a list of deployed workflow definitions.

Prerequisites

The SAP Fiori launchpad objects are configured. For more information, see Configuring SAP Fiori Launchpad
Objects [page 15].

The following actions are available:

● To filter the workflow definitions, use the following criteria: workflow definition ID, workflow definition
name, or the workflow definition version.
● To search the workflow definitions, type the keyword you want to use in the Search field, and choose 
(Search), or press Enter.
● To start a new workflow instance, select a workflow definition and choose Start New Instance.
If you’ve configured a sample context while modeling a start event, it’s shown as the context data while
starting a new workflow instance in the Start New Instance window. However, you can also modify this
JSON context data as required. For more information, see Configure Start Events [page 67].

SAP Cloud Platform Workflow in the Neo Environment

166 PUBLIC Monitoring and Troubleshooting
  Example

The JSON structure contains the content to be passed to the workflow context. In contrast to the workflow
service API, a context node as a wrapper isn’t required.

 Note

In the workflow context, use numbers where computations or comparisons on them are required. We
recommend that you don’t use numbers as IDs, especially not for business keys. Use a string instead.

For more information about using these actions, see the Workflow Service API documentation in Using
Workflow APIs [page 125].
● To navigate to the list of all instances of a definition, select the definition from the list and choose Show
Instances.
● To load more workflow definitions, scroll down to the end of the list and choose More.
● To download the workflow model, select the definition from the list, then choose Download Workflow
Model. With this, you retrieve the workflow model for the latest deployed version of a workflow definition.

 Note

We recommend that you don’t import this downloaded workflow model to SAP Web IDE Full-Stack.

Related Information

Managing Workflows Using the Monitor Workflows App with SAP Web IDE [page 161]
Deep Linking in Monitor Workflows App [page 168]

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 167
6.1.4 Deep Linking in Monitor Workflows App

You can access the workflow definitions, instances, and task instances using direct URLs. You can use the
below URL formats to access the required information.

Workflow Instance

● To access the list of workflow instances, use the following URL format:
https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayInstances&/workflowInstances

● To access a particular workflow instance, use the following URL format:

https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayInstances&/workflowInstances/
<workflow_instance_id>

Workflow Definition

● To access the list of workflow definitions, use the following URL format:
https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayDefinitions&/workflowDefinitions

● To access a particular workflow definition, use the following URL format:

https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayDefinitions&/workflowDefinitions/
<workflow_definition_id>

Task Instance

● To access the list of task instances for a particular workflow instance, use the following URL format:
https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayInstances&/workflowInstances/
<workflow_instance_id>/taskInstances

● To access a particular task instance, use the following URL format:

https://flpsandbox-<consumer_account>.<landscape_host>/sites?
siteId=<site_id>#bpmworkflowmonitor-DisplayInstances&/workflowInstances/
<workflow_instance_id>/taskInstances/<task_instance_id>

 Note

If you are using the default site, then site_id in the URL is not mandatory.

SAP Cloud Platform Workflow in the Neo Environment

168 PUBLIC Monitoring and Troubleshooting
Related Information

Managing Workflow Instances [page 162]

Managing Task Instances [page 164]
Managing Workflow Definitions [page 166]

6.2 End Users Can't Open SAP Fiori Launchpad Tiles

When SAP provides a new version of an HTML5 UI component, for example, the Monitor Workflows app or My
Inbox, end users may be unable to open the tiles for these applications, depending on the HTML5 cache status
in the SAP Fiori launchpad. The open action fails with an error message.

Symptom

Solution

● The cache in the SAP Fiori launchpad service component references a previously used version of the
affected HTML5 application. After an update, the previous version is no longer available. To clear the cache,
see Clear the SAP Fiori Launchpad Cache [page 169].
● The SAPUI5 version on SAP Fiori launchpad isn't the latest version. To update the version, see Change the
SAPUI5 Version [page 171].

Result

End users can now reload their SAP Fiori launchpad and use the tiles again.

6.2.1 Clear the SAP Fiori Launchpad Cache

You use this procedure to resolve the cache issues in SAP Fiori launchpad.

Prerequisite

You are unable to open the SAP Fiori launchpad tiles. For more information, see End Users Can't Open SAP Fiori
Launchpad Tiles [page 169].

Solution

Clear the cache using a user account that has permission to run the cockpit application and to edit the SAP
Fiori launchpad configuration for the given tenant.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 169
1. In your browser, open the SAP Cloud Platform cockpit for the affected account.
2. In the navigation area, choose Services , then choose the Portal Service tile.

3. On the Portal Service page, choose the Go to Service link.

4. In the navigation area, choose Site Directory. Select the affected site, and choose Edit.

5. In the navigation area, choose Settings. Choose Actions, then choose Clear HTML5 Application Cache.

SAP Cloud Platform Workflow in the Neo Environment

170 PUBLIC Monitoring and Troubleshooting
 6. Confirm the warning dialog by selecting Yes.
You see the following confirmation message:
“HTML5 applications updated to their latest versions successfully.”

6.2.2 Change the SAPUI5 Version

You use this procedure to change the SAP Fiori launchpad to the latest version.

Prerequisite

You are unable to open the SAP Fiori launchpad tiles. For more information, see End Users Can't Open SAP Fiori
Launchpad Tiles [page 169].

Solution
You have the user account that has permission to run the cockpit application and to edit the SAP Fiori
launchpad configuration for the given tenant.

1. In your browser, open the SAP Cloud Platform cockpit for the affected account.
2. In the navigation area, choose Services , then choose the Portal Service tile.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 171
3. On the Portal Service page, choose the Go to Service link.
4. In the navigation area, choose Site Directory. Select the affected site, and choose Edit.

5. 6. In the navigation area, choose Settings.

6. In the System Settings section, ensure that the SAPUI5 Version is set to Latest supported version.

7. If the version is not set to the latest, then choose Edit.

SAP Cloud Platform Workflow in the Neo Environment

172 PUBLIC Monitoring and Troubleshooting
 8. From the SAPUI5 Version list, choose Latest Supported Version.

9. Choose Save.
10. In the navigation area, choose Settings. Choose Actions, then choose Clear HTML5 Application Cache.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 173
11. Confirm the warning dialog by selecting Yes.
You see the following confirmation message:
“HTML5 applications updated to their latest versions successfully.”

6.3 Authentication and Authorization Issues with SAP Web

IDE

Related Information

Failing Service Tasks and Principal Propagation After Name Change of Local Service Provider [page 174]
Authentication Issues when Using a Custom IDP and Basic Authentication [page 175]
HTTP Status 403: User Doesn't Have Sufficient Privileges [page 175]
No Permissions Granted [page 176]
Communication Issues Between SAP Cloud Platform Workflow and an On-Premise Application Server ABAP
[page 176]
Intermittently Receiving 403 Status Response [page 177]

6.3.1 Failing Service Tasks and Principal Propagation After

Name Change of Local Service Provider

Symptom

SAP Cloud Platform Workflow in the Neo Environment

174 PUBLIC Monitoring and Troubleshooting
If you change the name of the Local Service Provider in Trust Management, then principal propagation in
service tasks no longer works and the affected workflow instances are erroneous.

Error code 403: User does not have sufficient privileges.

Solution

After you’ve changed the name, take the following steps to enable principal propagation again.

1. In the SAP Cloud Platform cockpit, choose Security Trust .

2. Switch to the Application Identity Provider tab, and click Add Trusted Identity Provider.
3. On the General tab, import the metadata file of the previously configured Local Service Provider.
4. Select the Only for IDP-Initiated SSO checkbox.
5. Choose Save.
6. Using the Monitor Workflows app, retry all erroneous workflow instances. See Managing Task Instances
[page 164].

6.3.2 Authentication Issues when Using a Custom IDP and

Basic Authentication

Symptom

You use a custom IDP and experience authentication issues when accessing the workflow service using basic
authentication (HTML response instead of a successful authentication).

Solution

Your custom IDP is not enabled for basic authentication by default. To change this configuration, create a
support ticket on component BC-NEO-SEC-IAM.

6.3.3 HTTP Status 403: User Doesn't Have Sufficient

Privileges

Symptom

You're missing appropriate permissions in the workflow service runtime.

Solution

● See the Authorization Configuration [page 150].

● Assign the Workflow Participant role to your user and all other users that are supposed to access My Inbox.

Check whether the workflow roles are assigned to you:

1. Log on to the SAP Cloud Platform cockpit.

2. Access your subaccount and choose Services from the navigation area.
3. Search for the workflow service.
4. On the Workflow tile, choose Configure Service.
5. In the navigation area, choose Roles, and assign the necessary roles to your user.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 175
 For more information on roles and permissions, see Authorization Configuration [page 150] and HTML:
Workflow Service API Reference.
6. Log off and log on again for the changes to take effect.

Related Information

Tutorial Step 5: Assign roles

6.3.4 No Permissions Granted

Symptom

You have assigned the appropriate roles in the SAP Cloud Platform cockpit; however, you still receive the
following message: No permission (forbidden).

Solution

Either log off using an action usually available in the top right corner and log on again, or clear your browser
cache to delete existing cookies.

New roles that are assigned to you are not applied to existing browser sessions; they do not take effect until
after you log in again to the SAP Cloud Platform Identity Authentication service.

6.3.5 Communication Issues Between SAP Cloud Platform

Workflow and an On-Premise Application Server
ABAP

Symptom

You need information on the technical configurations for a scenario where an on-premise application server
ABAP communicates with SAP Cloud Platform Workflow. You want to propagate the user context of an end
user from the workflow service to an on-premise system to the cloud.

 Note

The principal propagation from the workflow service to an on-premise system via cloud connector is not
supported yet.

Solution

The following systems and applications are involved. Ensure that you use the correct versions.

● Workflow API endpoint or subscription URL for the workflow service

● Application software on an AS ABAP on-premise system
● SAP Cloud Platform Connectivity
Version 2.11 or higher so that additional Principal Type settings are available.

SAP Cloud Platform Workflow in the Neo Environment

176 PUBLIC Monitoring and Troubleshooting
 ● Authorization servers
○ Cloud
○ On-premise

Set up appropriate trust:

● Ensure that all the systems involved have configured certificate trust relationships on the SSL or TLS
certificate level.
For example, to have SAP Cloud Platform server certificates that are signed by the Digicert Certificate
Authority, add the DigiCert Global Root CA using transaction STRUST. For more information, see
Establish the SSL Connection to SAP Cloud Platform.
● Ensure that the Principal Type setting of SAP Cloud Platform Connectivity of the respective Cloud To
On-Premise connection is X.509 certificate (strict usage).
● Ensure that all the systems involved have configured trust relationships on the level of the involved SAML
identity providers. For information about trust relationships on the SAP Cloud Platform, see Configure
Trust to the SAML Identity Provider. For information about trust relationships on the on-premise side, see
the documentation for your AS ABAP, and search for transaction SAML2.

Implement and configure the application software. The application software must initiate and execute a
suitable OAuth2 SAML2 authorization flow.

● For information about how to implement an OAuth 2.0 client on AS ABAP using the CL_OAUTH2_CLIENT
class, see the SAP Community Wiki .
● When you communicate with SAP Cloud Platform and want to propagate the principal, you use the
following:
○ The OAuth2 client profile HANA_CLOUD_PLATFORM
○ A client configuration for “SAML 2.0 Bearer Assertion”
○ A client using the authorization server of SAP Cloud Platform

Accessing Workflow Service APIs without Principal Propagation

When making a request from an ABAP system to the Workflow Service APIs without Principal Propagation (e.g.
basic authentication) where an XSRF token is required, the propertytype_accept_cookie property of the
HTTP client object needs to be set before the request for the XSRF token is made. After that, the same HTTP
client must be used to make the request to the actual resource. No additional cookie handling is required in this
case. Also, refer to Intermittently Receiving 403 Status Response [page 177].

General Troubleshooting

To analyze errors returned by the ABAP OAuth2 service, see 1688545 .

6.3.6 Intermittently Receiving 403 Status Response

Symptom

When calling API end-points that require CSRF tokens, you intermittently receive a 403 status response.

The issue only occurs in call sequences that involve:

● A GET or HEAD request to an end point requesting a CSRF token through an X-CSRF-Token: Fetch
header.
This request might use the “xsrf-token” end point of the workflow service API.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 177
● A request of a modifying HTTP method. That is a PUT, POST, PATCH, or DELETE method that provides the
CSRF token retrieved in the first call in the X-CSRF-Token” header.

The second request intermittently returns a 403 status response.

Solution

Usually, the issue occurs when the APIs are called using stateless HTTP clients or when HTTP clients are used
in a stateless manner. That is often the case when you do the following:

● Use command-line tools, such as curl, or tools from operating system scripting languages, for example,
Microsoft Windows Powershell.
● Use programming APIs in a way that they execute sequential requests in different clients or connection
contexts.

The intermittent nature of the issue is caused by the session affinity of the user sessions on the servers that
execute requests to the workflow service, but are located behind load balancers.

Session affinity means that a user session is bound to the actual node. To run follow-up requests in the same
user session, load balancers have to forward requests to the previously used node. This is achieved by
mechanisms of the load balancer.

If a subsequent call isn’t forwarded to the same node as the first call, then a new or another user session
located on that node is used for the authenticated user. This however means that the CSRF token value
provided by the client (from the first call) doesn’t match the value expected by the server (derived from the
user session for the subsequent call).

Therefore, it’s essential that both requests are forwarded to the same node. To achieve this, adapt your code
respectively the invocation of your command-line tool according to the session affinity mechanisms of the load
balancer.

Try the following:

● Use the HTTP 1.1 protocol. It uses persistent TCP connections by default.
● Enable TCP Keep-Alive in your client for the two subsequent requests, if this isn’t the default setting.
● Ensure that you reuse clients that can act in a stateful manner. Don’t refresh or discard a client after the
first call.
● Ensure that the first request returns or uses appropriate cookies and that these are also used for the
second request:
○ Login or session cookies that contain, for example, SESSION in their name.
○ load-balancer cookies that contain, for example, BigIP in their name.

See the documentation of the command-line HTTP clients or the library functions you use, respectively. For
example, for curl this usually involves the cookie and cookie-jar command-line parameters. For the ABAP
CL_HTTP_CLIENT class, make sure that you use the same instance for both calls and enable the property
propertytype_accept_cookie before the XSRF-token fetch request. Do not apply additional cookie
handling in this case.

6.4 Error When Clicking "Go to Service" on Portal Tile

Symptom

SAP Cloud Platform Workflow in the Neo Environment

178 PUBLIC Monitoring and Troubleshooting
When you chose Go to Service on the Portal tile in the services overview of the SAP Cloud Platform cockpit, you
see the following error: The site cannot be displayed due to insufficient privileges as
shown below.

Solution

1. Navigate to your subaccount. For more information, see Navigate to a Subaccount.

2. In the navigation area for your subaccount, choose Services.
3. Search for Portal.
4. On the Portal tile, choose Configure Portal.
5. In the navigation area, choose Roles.
6. Select the TENANT_ADMIN role and verify that your user is assigned to this role.
7. If your user is not assigned, choose Assign, enter your user ID, and choose Assign.
8. To see the change, log off and log on again.

Result

When you now choose Go to Service on the Portal tile, the landing page of the Portal service opens.

6.5 Tasks Not Appearing in My Inbox

Symptom

You can't see the tasks you've created, even though you directly assigned your user as a recipient user.

Solution

User IDs are case sensitive in the workflow service. When you authenticate against the SAP Cloud Platform
Identity Authentication service, your user ID is provided in all uppercase letters. Your user ID must match the
one in the recipient user field. Therefore, use only uppercase letters to enter your user ID, for example,
P123456789 instead of p123456789.

Related Information

Groups in SAP Cloud Platform Workflow – Part 1

Groups in SAP Cloud Platform Workflow – Part 2

6.6 Error During Workflow Deployment in SAP Web IDE

Symptom

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 179
You see the following error message while you are deploying the workflow editor on SAP Web IDE:

Solution

See the list of possible causes for the failure and the respective solutions:

● SAP Cloud Platform Workflow isn't enabled. To enable the workflow service, see Getting Started with
Workflow Service in the Neo Environment [page 14].
● The destination isn't configured correctly. To configure the destination, perform the following steps:
1. Log in to your subaccount in the SAP Cloud Platform cockpit.
2. In the navigation area, choose Connectivity Destinations .
3. Choose the bpmworkflowruntime destination.
4. In the Destination Configuration section, choose Edit.
5. In Additional Properties, select New Property, then choose WebIDEEnabled as the new property.
6. Set this property to true.
7. Choose Save.

Result

After performing these steps, you should be able to deploy the workflow again.

6.7 Workflow Service Cannot be Enabled in the Account

Symptom

In the cockpit, enabling the workflow service fails.

Solution

1. Check whether the Portal service is enabled.

2. Retry enabling the workflow service.
3. Check the Questions & Answers .
4. Open a ticket as described in https://launchpad.support.sap.com/#/notes/1888290

6.8 Unable to Open the Workflow Editor

Symptom

SAP Cloud Platform Workflow in the Neo Environment

180 PUBLIC Monitoring and Troubleshooting
When you try to open the workflow editor, the editor doesn’t load.

Solution

This is caused by a conflict with another SAP Web IDE extension, for example, SAP EIM Smart Data Integration
Editors. To resolve the issue, create a new workspace in the SAP Web IDE Full-Stack using the following steps:

1. Log on to the SAP Web IDE Full-Stack.

2. In the top-right corner of the SAP Web IDE Full-Stack, choose your workspace (<youruser>@Workspace).
3. Select Workspace Manager.
4. Choose Create Workspace.
5. Provide a workspace name for your new workspace and choose Create. The workspace is created under
Workspace Manager.
6. Select Open in new tab associated with the new workspace.
7. Enable the Workflow Editor feature by navigating to Preferences Extensions once the SAP Web IDE is
launched.

Result

You can now open the workflow editor under the new workspace folder created in SAP Web IDE Full-Stack.

Related Information

Enablе the Workflow Editor in SAP Web IDE [page 34]

6.9 Unable to Find the Deploy Option

Symptom

You created a workflow in the workflow editor in SAP Web IDE Full-Stack. When you try to deploy the workflow,
you cannot find the Deploy Deploy to SAP Cloud Platform Workflow option in the context menu of your
workflow.

Solution

Check whether SAP Cloud Platform Workflow is enabled in the project settings in your project using the
following steps:

1. Log on to the SAP Web IDE Full-Stack.

2. Select your workflow project from the workspace.
3. Right-click on your project and choose Project Project Settings .
4. Enable the project type SAP Cloud Platform Workflow under Project.
5. Choose Save.

Result

You can now find the Deploy Deploy to SAP Cloud Platform Workflow option in the context menu of your
workflow.

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 181
6.10 Cannot Deploy Workflow

Symptom

You created a workflow in the workflow editor in SAP Web IDE Full-Stack. When you try to deploy the workflow,
you are not allowed to do so.

Solution

Check whether the workflow roles are assigned to you:

1. Log on to the SAP Cloud Platform cockpit.

2. Access your subaccount and choose Services from the navigation area.
3. Search for the Workflow service.
4. On the Workflow tile, choose Configure Service.
5. In the navigation area, choose Roles, and assign the WorkflowDeveloper role to your user.
6. Log off and log on again for the change to take effect.

6.11 Service Calls Fail

Solution

1. In the Monitor Workflow - Workflow Instances app, look for errors under ERROR MESSAGES.
2. Check whether the destination exists and the path is valid.
3. If basic authentication is used, check whether the user and password are valid.
4. On-premise destination and cloud connector: Make sure that the domain mapping is correct. For more
information, see this answer and Communication Issues Between SAP Cloud Platform Workflow and an
On-Premise Application Server ABAP [page 176].
5. If principal propagation is configured for the service task, verify the following:
○ Verify that you’ve executed all steps for enabling principal propagation as described in Configuring
Principal Propagation for Service Tasks [page 27].
○ Check whether you’ve configured the service task destination as described in Configure a Service Task
Destination with OAuth2SAMLBearerAssertion for Principal Propagation [page 155].
○ If you’ve modified the role or group assignments for the user who is propagated to the service task, but
if those changes aren’t reflected in the service task call:
○ Make sure that the affected user has logged out and logged in again.
○ Wait until the token for the OAuth client, which is configured in the service task destination, has
expired. The expiration depends on the token lifetime, which is configured in the OAuth client.
○ Make sure that the affected user has either completed a user task or started a workflow, where the
user task or start event is configured as principal propagation source.
○ If you’ve renamed the name of the local service provider, follow the steps described in Failing Service
Tasks and Principal Propagation After Name Change of Local Service Provider [page 174].

SAP Cloud Platform Workflow in the Neo Environment

182 PUBLIC Monitoring and Troubleshooting
Related Information

Managing Task Instances [page 164]

6.12 My Inbox Features Not Active

Symptom

You are used to work with My Inbox and are missing features usually available there.

Solution

Some features are generally available for My Inbox, but not all of them are already available for My Inbox used
by the workflow service.

Related Information

Working with Tasks in My Inbox [page 140]

SAP Cloud Platform Workflow in the Neo Environment

Monitoring and Troubleshooting PUBLIC 183
Important Disclaimers and Legal Information

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 a 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.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

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.

Gender-Related Language
We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.

SAP Cloud Platform Workflow in the Neo Environment

184 PUBLIC Important Disclaimers and Legal Information
SAP Cloud Platform Workflow in the Neo Environment
Important Disclaimers and Legal Information PUBLIC 185
www.sap.com/contactsap

© 2020 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.

SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN