I hope these tips & tricks might save you some time when you build your first workflows using the SAP Cloud Platform Workflow Service. This post is part of a series on the Workflow Service.
For very simple User Tasks you can configure a Workflow Form, which doesn't require any coding. The next step up (more effort/more flexibility) is to build a UI5 component which can be displayed inside the My Inbox app. It's easy for this component to read the context and complete the User Task using the My Inbox API.
In my case this approach had a couple of drawbacks. Firstly, my form is quite complex and I wanted to be able to use the full screen to display it (not just the detail pane of My Inbox). Second, I didn't want to put everything into the workflow context. Instead, I wanted to save the key fields in the context and call my OData service (built with the S/4HANA Cloud SDK) to get all the field values. A benefit of this approach is that I could use the same UI5 component to implement both the display view of my form (as launched from the Fiori Launchpad) and the approval view (as launched from My Inbox).
It turns out that calling your own OData service from your My Inbox component has some limitations. It's possible - see Call an External Service from a Custom Task UI - but I chose to launch the full version of my app instead.
If you want to use a custom UI5 component within My Inbox for your workflow you should plan on putting all the data in the context, and you probably won't use the same component outside of My Inbox.
Don't forget to add the workflow service to the manifest.js and neo-app.json files of your app, otherwise you'll get a 404 when you try to confirm the user task.
When you Configure the Workflow Service Mail Destination you need to enter a username and password for an SMTP server (to send the emails). If your customer doesn't want to have their credentials used in this way there are cloud services (such as SendGrid) which can be used instead. You'll need to ensure however that this source doesn't trigger the corporate spam filter when the emails arrive.
Your workflow doesn't have to be arranged Left-to-right or Top-to-bottom (in the Workflow Editor). A 'loop' pattern (i.e. four sides of a rectangle) can be useful because it makes it easier to build a flow between different components. For example, you might have an approval flow that sometimes needs to be repeated or you might need a 'short cut'. Also, if you arrange your workflow in a similar shape to the pane in Web IDE (i.e. rather than being very long) you can see more of the workflow at any time.
Web IDE will allow you to rename the workflow in the Explorer pane (see below, right) but that will cause problems with artifacts like script files and email files, which are stored under sub-folders using the same id. If you want to see a meaningful name for your workflow in the Admin app, set the subject property instead (see below, left) by clicking on the workflow when the Workflow Editor is open. This value can contain context expressions so you can use the name or ID of the business object (like a customer or project) that the instance references. NB This determines the workflow instance subject not the task instance subject.
Sometimes you might need your workflow (in the Neo environment) to call a service in the Cloud Foundry environment. An example would be if you are using the S/4HANA Cloud SDK as your 'back end' in conjunction with the Cloud Application Programming Model (CAPM).
The workflow Service Task allows you to specify that the user details should be propagated in the call (usually the user who completed the last User Task). This is called Principle Propagation and it means that you can make authorisation checks in the (called) service based on the logged-on user (not a system user).
It's quite possible to do this, but you need to setup a destination in Neo called bpmworkflowruntimeoauth. See Principal Propagation from the Neo to the Cloud Foundry Environment & Configuring Principal Propagation for Service Tasks.
This will be necessary until the portal and workflow services are both mature in the Cloud Foundry environment. When that happens we should be able to work just within the one environment.
Customers sometimes want email notifications to be sent when users have an inbox item (like an approval). This presents challenges because emails are insecure (they can easily be forwarded) and we don't want to clog up everyone's email inbox with hundreds of emails. A justification for going with emails would be if there is an approval required urgently and the approver isn't often logged-in to the Fiori Launchpad (FLP).
My current customer wanted emails but I wanted to encourage them to use My Inbox. So, I decided to create User Tasks as well as an email notification. A benefit of this approach is that users can still action the item if they have lost the email. How to achieve this?
The challenge for me was passing the task instance id to my UI5 app, so that the app could complete the User Task when the approver made a decision (approve or reject). You could send the email before creating the User Task, but the problem is that you won't know the task instance id until after the User Task has been created.
If you put the User Task before the Email Task it wouldn't send the email until the User Task had been completed (by the approver making a decision).
My first approach was to use a boundary timer. One minute after the User Task had been created a Script Task would be triggered (in a parallel track) to read the User Task instance id and an Email Task would send the email. The problem was that if the User Task was completed (in My Inbox) before the 1 minute had elapsed the parallel track would never be triggered (and the workflow would refuse to progress). That's because all parallel tracks must be completed before the workflow moves on.
The best solution I found was to put the Email Task and the User Task in parallel tracks without any timer. That is, the email is sent at (logically) the same time as the user task is created. I added the unique 'request ID' (e.g. '10003476') to the user task as a Custom Attribute. In the email link I pass the task definition ID (e.g. 'usertask1@testworkflow') and the same 'request ID'.
When the user clicks on the email link and the UI5 app opens, the app uses the Task Consumption Model (TCM) service to find the task instance ID for that combination of task definition and request ID (as Custom Attribute). When the user makes a decision the app is able to complete the user task (using the task instance ID) and the workflow progresses.
If there is no matching user task in the inbox my app displays an error message. This approach ensures that you can't approve the request just by guessing the url or by being forwarded the email. You have to have the workitem in your inbox before you can approve it.
As I mentioned above, taking care how you lay out your workflow (in the Workflow Editor) can make it easier for a colleague to understand the flow. If you need move a number of tasks and gateways at once you can select them with the Marquee tool. To move them you click and drag, but you must click inside one of the objects (like a task). If you click inside the selection but in free space, nothing will happen.
User Task UI Components
For very simple User Tasks you can configure a Workflow Form, which doesn't require any coding. The next step up (more effort/more flexibility) is to build a UI5 component which can be displayed inside the My Inbox app. It's easy for this component to read the context and complete the User Task using the My Inbox API.
In my case this approach had a couple of drawbacks. Firstly, my form is quite complex and I wanted to be able to use the full screen to display it (not just the detail pane of My Inbox). Second, I didn't want to put everything into the workflow context. Instead, I wanted to save the key fields in the context and call my OData service (built with the S/4HANA Cloud SDK) to get all the field values. A benefit of this approach is that I could use the same UI5 component to implement both the display view of my form (as launched from the Fiori Launchpad) and the approval view (as launched from My Inbox).
It turns out that calling your own OData service from your My Inbox component has some limitations. It's possible - see Call an External Service from a Custom Task UI - but I chose to launch the full version of my app instead.
If you want to use a custom UI5 component within My Inbox for your workflow you should plan on putting all the data in the context, and you probably won't use the same component outside of My Inbox.
Don't forget to add the workflow service to the manifest.js and neo-app.json files of your app, otherwise you'll get a 404 when you try to confirm the user task.
Cloud email providers
When you Configure the Workflow Service Mail Destination you need to enter a username and password for an SMTP server (to send the emails). If your customer doesn't want to have their credentials used in this way there are cloud services (such as SendGrid) which can be used instead. You'll need to ensure however that this source doesn't trigger the corporate spam filter when the emails arrive.
Loopy layouts are good
Your workflow doesn't have to be arranged Left-to-right or Top-to-bottom (in the Workflow Editor). A 'loop' pattern (i.e. four sides of a rectangle) can be useful because it makes it easier to build a flow between different components. For example, you might have an approval flow that sometimes needs to be repeated or you might need a 'short cut'. Also, if you arrange your workflow in a similar shape to the pane in Web IDE (i.e. rather than being very long) you can see more of the workflow at any time.
Careful with renaming
Web IDE will allow you to rename the workflow in the Explorer pane (see below, right) but that will cause problems with artifacts like script files and email files, which are stored under sub-folders using the same id. If you want to see a meaningful name for your workflow in the Admin app, set the subject property instead (see below, left) by clicking on the workflow when the Workflow Editor is open. This value can contain context expressions so you can use the name or ID of the business object (like a customer or project) that the instance references. NB This determines the workflow instance subject not the task instance subject.
 |  |
Do this | Don't do this |
You can call services in Cloud Foundry (from Neo)
Sometimes you might need your workflow (in the Neo environment) to call a service in the Cloud Foundry environment. An example would be if you are using the S/4HANA Cloud SDK as your 'back end' in conjunction with the Cloud Application Programming Model (CAPM).
The workflow Service Task allows you to specify that the user details should be propagated in the call (usually the user who completed the last User Task). This is called Principle Propagation and it means that you can make authorisation checks in the (called) service based on the logged-on user (not a system user).
It's quite possible to do this, but you need to setup a destination in Neo called bpmworkflowruntimeoauth. See Principal Propagation from the Neo to the Cloud Foundry Environment & Configuring Principal Propagation for Service Tasks.
This will be necessary until the portal and workflow services are both mature in the Cloud Foundry environment. When that happens we should be able to work just within the one environment.
Email Notifications for Inbox Items
Customers sometimes want email notifications to be sent when users have an inbox item (like an approval). This presents challenges because emails are insecure (they can easily be forwarded) and we don't want to clog up everyone's email inbox with hundreds of emails. A justification for going with emails would be if there is an approval required urgently and the approver isn't often logged-in to the Fiori Launchpad (FLP).
My current customer wanted emails but I wanted to encourage them to use My Inbox. So, I decided to create User Tasks as well as an email notification. A benefit of this approach is that users can still action the item if they have lost the email. How to achieve this?
The challenge for me was passing the task instance id to my UI5 app, so that the app could complete the User Task when the approver made a decision (approve or reject). You could send the email before creating the User Task, but the problem is that you won't know the task instance id until after the User Task has been created.
If you put the User Task before the Email Task it wouldn't send the email until the User Task had been completed (by the approver making a decision).
My first approach was to use a boundary timer. One minute after the User Task had been created a Script Task would be triggered (in a parallel track) to read the User Task instance id and an Email Task would send the email. The problem was that if the User Task was completed (in My Inbox) before the 1 minute had elapsed the parallel track would never be triggered (and the workflow would refuse to progress). That's because all parallel tracks must be completed before the workflow moves on.
The best solution I found was to put the Email Task and the User Task in parallel tracks without any timer. That is, the email is sent at (logically) the same time as the user task is created. I added the unique 'request ID' (e.g. '10003476') to the user task as a Custom Attribute. In the email link I pass the task definition ID (e.g. 'usertask1@testworkflow') and the same 'request ID'.
When the user clicks on the email link and the UI5 app opens, the app uses the Task Consumption Model (TCM) service to find the task instance ID for that combination of task definition and request ID (as Custom Attribute). When the user makes a decision the app is able to complete the user task (using the task instance ID) and the workflow progresses.
If there is no matching user task in the inbox my app displays an error message. This approach ensures that you can't approve the request just by guessing the url or by being forwarded the email. You have to have the workitem in your inbox before you can approve it.
 |
In the Workflow Editor you'd see something like this. Between the two Parallel Gateways are the two tracks. The top track has a User Task. The bottom track has a Script Task followed by an Email Task. It's common to have a Script Task before a Service Task or an Email Task so that you can manipulate the workflow context |
Mass move of objects
As I mentioned above, taking care how you lay out your workflow (in the Workflow Editor) can make it easier for a colleague to understand the flow. If you need move a number of tasks and gateways at once you can select them with the Marquee tool. To move them you click and drag, but you must click inside one of the objects (like a task). If you click inside the selection but in free space, nothing will happen.
The Marquee tool allows you select multiple objects by clicking and dragging, but you must click and drag inside an object (like a Task) |
- SAP Managed Tags:
8 Comments
