TL;DR: This blog post explains how to integrate SAP Cloud Platform Workflow with Microsoft Outlook (Office 365 edition). We introduce the basic building blocks needed to make this scenario work and present a sample application to help you get started quickly. At the end of this blog post and with a bit of effort on your side, you will be able to process simple form-based tasks running in SAP Cloud Platform Workflow directly within Microsoft Outlook.
Today’s business world demands a lot from us: we are always working on a tight schedule and constantly forced to switch contexts, juggling an ever-growing number of topics at the same time. Mastering this complexity by creating a work environment that allows you to be as efficient as possible is – more than ever – a key priority for today’s IT departments.
When participating in a process automated through a workflow, users usually have to work on a series of tasks. This might include filling a form, approving a request, or reviewing a document, for example. To this end, users access their tasks in an inbox of some sort. Traditionally, this inbox is provided as a Web application embedded in a portal. For SAP Cloud Platform Workflow, the inbox of choice is My Inbox and can be plugged into a Fiori Launchpad. Recently, mobile inboxes have emerged to complement this desktop scenario so users can process simple tasks that don’t require in-depth information or data capture on the go. Imagine a simple leave request approval or a purchase requisition, for example. For SAP Cloud Platform Workflow, customers can make use of Mobile Cards offered as part of SAP Cloud Platform Mobile Services to configure their own mobile inbox and customize it to their needs [1]. This certainly serves the purpose and power users will appreciate the advanced capabilities an inbox can provide such as sorting, filtering, grouping, tabular representations, mass actions, and more.
For a casual user, regularly checking an inbox is usually not a common habit, though. To be totally honest, even as somebody developing business process management software, I don’t work that way. What I do each day, though, is writing and answering e-mails. One of my primary tools I use daily (and unfortunately for a considerable amount of time) is my e-mail client. Like many of you, I use Microsoft Outlook. Even after close to 50 years, e-mail is still going strong and no matter what others may tell, there is no sign this is changing anytime soon. So, why not working on your tasks right within your e-mail client? Now, you might say: “I already do get e-mails that tell me there is work for me to do, so what’s the difference?”. Think further. Sure, you get an e-mail that presents you with a hyperlink that takes you to your task inbox and there is nothing fundamentally wrong with that. It just disrupts your flow. But imagine you could directly complete your tasks within Microsoft Outlook without having to leave the e-mail client? And all that without having to install any additional software or plug-ins? Still interested? Read on and we will show you how you can accomplish exactly that for form-based tasks in SAP Cloud Platform Workflow!
SAP and Microsoft have been partners for close to 30 years now. What started with an agreement to certify Microsoft Windows NT for running SAP R/3 workloads has become a long-standing partnership. In recent years, Microsoft Azure has become a certified cloud infrastructure for running SAP workloads such as SAP NetWeaver and SAP HANA. Finally, in October 2019, SAP and Microsoft announced an “extensive go-to-market partnership […] to accelerate customer adoption of SAP S/4HANA and SAP Cloud Platform on Microsoft Azure” [2]. This announcement was made as an evolution of the original announcement of project Embrace back at SAPPHIRE 2019 [6], a project to ease the transition of SAP customers to the cloud. It takes the SAP/Microsoft partnership to a whole new level and effectively makes Microsoft Azure SAP’s preferred cloud infrastructure provider.
Now, in the context of SAP Cloud Platform Workflow and SAP Intelligent Business Process Management [8] at large, there are many different use cases that make an integration with Microsoft products shine. Think of the integration of SAP One Inbox [7] – a service released in beta and planned to be released later this year to provide a central inbox for all your tasks and work items – with Microsoft To Do or Microsoft Teams. Think of the integration between SAP Cloud Platform Workflow and Microsoft Power Automate and Microsoft OneDrive to better your workflow productivity and manage documents along with your workflows, respectively. And finally, think of processing your SAP Cloud Platform Workflow tasks in Microsoft Outlook.
With all that said, let’s build on the spirit of this renewed partnership and get to work!
The basic idea of integrating SAP Cloud Platform Workflow with Microsoft Outlook is to send e-mail notifications about new tasks to all entitled recipients and to allow task processing directly via mail. The key element in achieving this goal is a custom Java app you will be deploying to SAP Cloud Platform later on that uses SAP Cloud Platform Workflow public REST APIs to retrieve relevant information and then sends out e-mails formatted in a specific way via your mail server of choice.
The overall flow of the integration is outlined in the picture below:
SAP Cloud Platform Workflow supports intelligent automation of structured business processes by formalizing them into an executable workflow model, off of which workflow instances can then be started. Business processes are typically long running and highly asynchronous in nature, making conventional programmatic automation tedious and error prone. Using workflows greatly simplifies such tasks by allowing to declaratively sequence a mixture of different tasks, such as (a) user tasks for processing user input, (b) service tasks for calling remote systems, (c) script tasks for procedural logic executed in the context of a workflow instance, and more.
When automating business processes, a significant portion of the effort is spent in the development of user interfaces used to start workflows or process tasks, for example. In many cases, however, these user interfaces are conventional screens for presenting and entering data in a structured way, also known as forms. Developing these form screens with SAPUI5 over and over again is inefficient. This is why Workflow Forms were introduced. Workflow Forms allow you to capture forms for data display and data input in a declarative way, leaving development of user interfaces with SAPUI5 for those cases where it really matters and where it adds value.
SAP Cloud Platform Workflow follows an API-first approach of offering its functionality through REST and OData APIs that you can use to integrate with the service via remote calls. SAP Cloud Platform Workflow APIs are documented on [17].
The custom Java app is specifically making use of the REST APIs to retrieve task instance details and complete tasks:
Outlook Actionable Messages [14] is a feature in Microsoft Outlook that allows you to take quick actions right within the e-mail client. While this feature has been around for some time, the added support for Adaptive Cards [15], [16] has greatly improved the reach of what you can achieve.
Below is a sample Adaptive Card that could be embedded into an e-mail and acted upon:
When examining Workflow Forms and Adaptive Cards at closer distance, you will see both are very similar in nature: they are serialized in a JSON format and exhibit a comparable language:
This makes it relatively easy to convert between the two formats. In this sample project, we have used an open source JSON transformation library called JSLT [18] that works similarly to XSLT but with JSON. You can find the transformation (transform.jslt) in the project’s resources folder (see below later in this blog post). It’s not complete – you will have to extend it if you want to transform more advanced Workflow Forms. If that’s not to your liking, you can of course also transform the JSON files with plain code and write your own little transformer for that purpose.
Before we can get your hands on the actual integration, you will need to fulfill a few prerequisites:
With the basic set up in place, we want to deploy a sample project that will serve as the scenario for this little integration project. Head over to [9] and clone the repository to your local file system. Then, import cf-outlook-integration-sample/order-spare-parts-process.zip into WebIDE similarly to how it is described in step (4) in [4]. You should have a project as shown below (remember to show hidden files through the ‘eye’ toolbar button):
The project is ready to run with one exception: you need to configure yourself as the approver of the workflow we are about to test-drive. Open file <your-project-name>/order-spare-parts-workflow/workflows/OrderSpareParts.workflow, select the step ‘Approve Spare Parts Order’, and on the second tab of the property sheet on the right, find the Users input field and enter your user ID you log on with to SAP Cloud Platform Cloud Foundry Trial (this will be an e-mail). Pay special attention to the fact that these user IDs are case sensitive!
After this, build and deploy the project as described in step (5) in [4]. Will all that is going on under the hood (services being provisioned, applications and content being deployed) his will take a while, so grab a cup of coffee and relax. Once deployment finished successfully, head over to your SAP Cloud Platform Cockpit. You should see applications and services created as follows, respectively:
Now, head over to the Applications tab and click on the app ‘order-spare-parts-approuter’. You should see a route bound to the app:
The route is your main entry point into your final application. Follow the route to see your Fiori Launchpad in action:
You will find that you don’t have permissions to access any of the apps so let’s fix that next. Follow the instructions of step (6) in [4]. For this integration project, you will only need to create roles for the workflow application identifier (WorkflowAdmin, WorkflowContextViewer, WorkflowDeveloper, WorkflowInitiator, WorkflowParticipant). Make sure to assign the newly created role collection to your user.
Finally, log off from your launchpad and log back in and you should be able to access the apps.
Click on the ‘Spare Parts’ tile and trigger a Spare Parts Ordering workflow by entering some data like shown below:
You should now find a task in your inbox. Head back by pressing ‘<’ or clicking the SAP icon, then click on ‘My Inbox’. You will find a task as presented below:
Approve the request. This completes the workflow.
As you can see, this is a simplistic one-step workflow which just includes the approval step you have gone through yourself a minute ago. Nothing you would consider realistic by any means but just what we need to test our Outlook integration end-to-end.
Now that we have a running workflow, we want to transition the approval step from My Inbox to Outlook so that you can approve the spare parts order in an e-mail!
The first step towards enabling Outlook integration is registering an Actionable E-Mail Provider with Microsoft. You will need to do this by accessing [10] and logging in with your Azure Active Directory user. Create a new provider and (a) give it a friendly name, (b) state the e-mail address(es) from which the e-mails will be sent, (c) enter the target URL where your Java app talking to Microsoft will be reachable (more on that in a bit), and (d) make sure to set the scope of submission to ‘Test Users’, also specifying your e-mail address used in Outlook. You can leave the Public Key field empty (not considered for now).
Regarding (c): you will later deploy your Java application to SAP Cloud Platform Cloud Foundry which will then be reachable via a publicly reachable URL that Microsoft can call back. Note that on SAP Cloud Platform Cloud Foundry Trial, you cannot reserve a custom domain, so your application effectively resides in the same global namespace as any other developers’ applications on a given trial landscape so you need to choose a name that won’t clash (‘hello-world’ won’t do!). Now, since you haven’t deployed the app yet and the app itself needs to be configured with the details of the Actionable E-Mail Provider, we have a little chicken-and-egg problem. We will go with a naming convention that should mostly work and be unique for all people following this blog:
https://<your-trial-account>-<your-cf-space-name>-wfs-forms-adaptive-cards.cfapps.<eu10|us10>.hana.o...
<your-trial-account> should match your subdomain as shown below and can be found in SAP Cloud Platform Cockpit:
<your-cf-space-name> name will be ‘dev’ by default on SAP Cloud Platform Cloud Foundry Trial. And depending on whether you choose the EU or the US trial landscape, you should choose ‘eu10’ and ‘us10’, respectively.
Coming back to registering the Actionable E-Mail Provider at Microsoft [10], you should finally see something like this:
Once you are done with your configuration, make sure to note (1) the target URL of your Java app you defined in (c) above, (2) the Provider Id (a GUID, aka ‘originator’) that was generated for you as well as (3) your Organization Id (this is the GUID provided as part of the Organization Info, so literally in the string "YOUR COMPANY (<some GUID>)" you need "<some GUID>" only). You will need this in the next step.
Next, we want to configure, build, and deploy our Java application that will pull tasks from SAP Cloud Platform Workflow and push them as Adaptive Cards via e-mail to Outlook.
Open the repository you cloned from [9] in your favorite code editor. We will have to make some configuration changes here.
First, we need to adapt the cf-outlook-integration-sample/manifest.yml file and update the application’s technical name (line 3) to match the subdomain of the target URL you registered in the previous step, that is:
name: <your-trial-account>-<your-cf-space-name>-wfs-forms-adaptive-cards
You should have something like this:
Next, we need to update the cf-outlook-integration-sample/src/main/resources/application.properties file.
Open the file and (a) update the card.submission.url property to match the full target URL of your Java app, (b) update all mail.smtp.* properties to match your e-mail server like host, port etc. (user and password are later stored in a destination for security purposes), and (c) specify the organization.id and originator.id you noted down when creating the Actionable E-Mail Provider. You should have something similar to this:
Open a terminal and from the cf-outlook-integration-sample folder, issue the following commands:
# Build the Java app
$ mvn clean install
# Log in to CF Trial
$ cf login https://api.cf.eu10.hana.ondemand.com
or
$ cf login https://api.cf.us10.hana.ondemand.com
# Push your application
$ cf push
Now that the application is deployed, it is a good time to check the URL you registered with Microsoft as the target URL for the Actionable E-Mail Provider matches the public URL of your application. To do so, again go to the applications tab in your SAP Cloud Platform Cockpit, go to your Java app and look at the route assigned:
If the route does not match the URL you configured with Microsoft, no problem. Take the route that you have now. Head back to [10], register another Actionable E-Mail provider with the updated URL (you can delete the old provider), update your application.properties file accordingly (card.submission.url, organization.id, and originator.id), compile, and deploy it again, and you should be set.
The last step for us to take is to configure the e-mail destination that the Java app will use to retrieve user and password to call the e-mail server with.
Head over to your SAP Cloud Platform Cockpit and import the mailserver destination file you will find in the cf-outlook-integration-sample into your trial sub-account as shown below, setting your email-address as the user and password along the way:
Don’t change the name of the destination unless you also update the mail.destination property in the application.properties file of your Java application.
With all pieces in place, it is time to test-drive our work and see if everything works out as expected.
As a preparatory step, you might want to install the Actionable Messages Debugger for Outlook [11].
Now, follow the exact same steps you went through earlier to order spare parts but at the point where you would approve the request in My Inbox, don’t approve just yet but instead head over to your Outlook client. If you are on Mac, you are out of luck and can’t use the native macOS client. Instead, log in to the Outlook Web client [12]. You should also see an e-mail such as this:
You can now press the Approve or Reject button and should get a confirmation in Outlook ‘The task was completed’. Just to make sure this really worked, go back to My Inbox and refresh your task list. The task should have been completed successfully – brilliant!
The code provided will serve as a starting point for you. It’s not production ready and you should consider revising certain aspects to use it productively, including but not limited to the following:
In this blog post, we have seen how you can nicely integrate Microsoft Outlook with SAP Cloud Platform Workflow by transforming your Workflow Forms into Adaptive Cards embedded into e-mails. These e-mails, when opened in Outlook, allow the recipient to process tasks right within the e-mail client and hence to streamline the day-to-day work experience.
When this work was presented earlier this year at the DSAG Technologietage 2020 (German SAP User Group Technology Days) in Mannheim, Germany, feedback was extremely positive. Customers had many proposals on how to extend this idea, include other Microsoft products such as Microsoft Teams, etc. Let us know what you think down in the comments below. We are interested in what you think!
There is now an SAP Clout Platform Discovery Center mission for you to explore if you want a more guided approach to implementing this best practice. Check it out on [19].
[1] https://blogs.sap.com/2019/09/16/use-sap-cloud-platform-mobile-cards-with-sap-cloud-platform-workflo...
[2] https://news.sap.com/2019/10/sap-microsoft-partnership-cloud-migration-offerings/
[3] https://developers.sap.com/tutorials/hcp-create-trial-account.html
[4] https://developers.sap.com/tutorials/cp-starter-ibpm-employeeonboarding-1-setup.html
[5] https://developer.microsoft.com/en-us/office/dev-program
[6] https://news.sap.com/2019/05/sapphire-now-embrace-sap-partners-ecosystem-customers-cloud/
[7] https://www.sap.com/documents/2018/12/1ce4576f-2e7d-0010-87a3-c30de2ffd8ff.html
[8] https://www.sap.com/germany/products/cloud-platform/capabilities/ibpm.html
[9] https://github.com/SAP-samples/cloud-workflow-samples
[10] https://outlook.office.com/connectors/oam/publish
[11] https://store.office.com/app.aspx?assetid=WA104381686&productgroup=Outlook
[12] https://outlook.office.com/mail/
[13] http://portal.azure.com
[14] https://docs.microsoft.com/en-us/outlook/actionable-messages/
[15] https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card
[16] https://adaptivecards.io/
[17] https://api.sap.com/api/SAP_CP_Workflow_CF/resource
[18] https://github.com/schibsted/jslt/
[19] https://discovery-center.cloud.sap/#/missiondetail/3255/3285
Motivation
How Users Work on Tasks Today
Today’s business world demands a lot from us: we are always working on a tight schedule and constantly forced to switch contexts, juggling an ever-growing number of topics at the same time. Mastering this complexity by creating a work environment that allows you to be as efficient as possible is – more than ever – a key priority for today’s IT departments.
When participating in a process automated through a workflow, users usually have to work on a series of tasks. This might include filling a form, approving a request, or reviewing a document, for example. To this end, users access their tasks in an inbox of some sort. Traditionally, this inbox is provided as a Web application embedded in a portal. For SAP Cloud Platform Workflow, the inbox of choice is My Inbox and can be plugged into a Fiori Launchpad. Recently, mobile inboxes have emerged to complement this desktop scenario so users can process simple tasks that don’t require in-depth information or data capture on the go. Imagine a simple leave request approval or a purchase requisition, for example. For SAP Cloud Platform Workflow, customers can make use of Mobile Cards offered as part of SAP Cloud Platform Mobile Services to configure their own mobile inbox and customize it to their needs [1]. This certainly serves the purpose and power users will appreciate the advanced capabilities an inbox can provide such as sorting, filtering, grouping, tabular representations, mass actions, and more.
For a casual user, regularly checking an inbox is usually not a common habit, though. To be totally honest, even as somebody developing business process management software, I don’t work that way. What I do each day, though, is writing and answering e-mails. One of my primary tools I use daily (and unfortunately for a considerable amount of time) is my e-mail client. Like many of you, I use Microsoft Outlook. Even after close to 50 years, e-mail is still going strong and no matter what others may tell, there is no sign this is changing anytime soon. So, why not working on your tasks right within your e-mail client? Now, you might say: “I already do get e-mails that tell me there is work for me to do, so what’s the difference?”. Think further. Sure, you get an e-mail that presents you with a hyperlink that takes you to your task inbox and there is nothing fundamentally wrong with that. It just disrupts your flow. But imagine you could directly complete your tasks within Microsoft Outlook without having to leave the e-mail client? And all that without having to install any additional software or plug-ins? Still interested? Read on and we will show you how you can accomplish exactly that for form-based tasks in SAP Cloud Platform Workflow!
SAP and Microsoft – Driving Innovation Together
SAP and Microsoft have been partners for close to 30 years now. What started with an agreement to certify Microsoft Windows NT for running SAP R/3 workloads has become a long-standing partnership. In recent years, Microsoft Azure has become a certified cloud infrastructure for running SAP workloads such as SAP NetWeaver and SAP HANA. Finally, in October 2019, SAP and Microsoft announced an “extensive go-to-market partnership […] to accelerate customer adoption of SAP S/4HANA and SAP Cloud Platform on Microsoft Azure” [2]. This announcement was made as an evolution of the original announcement of project Embrace back at SAPPHIRE 2019 [6], a project to ease the transition of SAP customers to the cloud. It takes the SAP/Microsoft partnership to a whole new level and effectively makes Microsoft Azure SAP’s preferred cloud infrastructure provider.
Now, in the context of SAP Cloud Platform Workflow and SAP Intelligent Business Process Management [8] at large, there are many different use cases that make an integration with Microsoft products shine. Think of the integration of SAP One Inbox [7] – a service released in beta and planned to be released later this year to provide a central inbox for all your tasks and work items – with Microsoft To Do or Microsoft Teams. Think of the integration between SAP Cloud Platform Workflow and Microsoft Power Automate and Microsoft OneDrive to better your workflow productivity and manage documents along with your workflows, respectively. And finally, think of processing your SAP Cloud Platform Workflow tasks in Microsoft Outlook.
With all that said, let’s build on the spirit of this renewed partnership and get to work!
Solution at a Glance
Overall Architecture
The basic idea of integrating SAP Cloud Platform Workflow with Microsoft Outlook is to send e-mail notifications about new tasks to all entitled recipients and to allow task processing directly via mail. The key element in achieving this goal is a custom Java app you will be deploying to SAP Cloud Platform later on that uses SAP Cloud Platform Workflow public REST APIs to retrieve relevant information and then sends out e-mails formatted in a specific way via your mail server of choice.
The overall flow of the integration is outlined in the picture below:
- First, the custom Java app needs to periodically check for new tasks in SAP Cloud Platform Workflow; this is done every 30 seconds by default
- For each new task, additional details such as the associated task form and context data are retrieved from SAP Cloud Platform Workflow
- For each new task, general task information, the associated form, and the context data are transformed into a Microsoft Outlook Actionable Message [14] in the Adaptive Card format [15], [16]
- Each Microsoft Actionable Message is sent via e-mail to the recipients via the mail server that was configured along with the custom Java app in an e-mail destination
- All recipients receive one e-mail per assigned task and process them (e.g. approve/reject) in a first-come-first-served manner right within Outlook (as it is the case today, each task can be processed only once by any of the recipients)
- By processing a task, Microsoft Office 365 will issue a callback to the custom Java app
- The custom Java app will receive the callback, verify the authenticity and validity of the request and complete the task in SAP Cloud Platform Workflow
Technical Building Blocks
Workflow and Forms
SAP Cloud Platform Workflow supports intelligent automation of structured business processes by formalizing them into an executable workflow model, off of which workflow instances can then be started. Business processes are typically long running and highly asynchronous in nature, making conventional programmatic automation tedious and error prone. Using workflows greatly simplifies such tasks by allowing to declaratively sequence a mixture of different tasks, such as (a) user tasks for processing user input, (b) service tasks for calling remote systems, (c) script tasks for procedural logic executed in the context of a workflow instance, and more.
When automating business processes, a significant portion of the effort is spent in the development of user interfaces used to start workflows or process tasks, for example. In many cases, however, these user interfaces are conventional screens for presenting and entering data in a structured way, also known as forms. Developing these form screens with SAPUI5 over and over again is inefficient. This is why Workflow Forms were introduced. Workflow Forms allow you to capture forms for data display and data input in a declarative way, leaving development of user interfaces with SAPUI5 for those cases where it really matters and where it adds value.
Workflow Public APIs
SAP Cloud Platform Workflow follows an API-first approach of offering its functionality through REST and OData APIs that you can use to integrate with the service via remote calls. SAP Cloud Platform Workflow APIs are documented on [17].
The custom Java app is specifically making use of the REST APIs to retrieve task instance details and complete tasks:
- GET /v1/task-instances
- GET /v1/task-instances/{taskInstanceId}
- GET /v1/task-instances/{taskInstanceId}/context
- GET /v1/task-instances/{taskInstanceId}/form/model
- PATCH /v1/task-instances/{taskInstanceId}
Outlook Actionable Messages with Adaptive Cards
Outlook Actionable Messages [14] is a feature in Microsoft Outlook that allows you to take quick actions right within the e-mail client. While this feature has been around for some time, the added support for Adaptive Cards [15], [16] has greatly improved the reach of what you can achieve.
Below is a sample Adaptive Card that could be embedded into an e-mail and acted upon:
Transforming Forms into Cards
When examining Workflow Forms and Adaptive Cards at closer distance, you will see both are very similar in nature: they are serialized in a JSON format and exhibit a comparable language:
This makes it relatively easy to convert between the two formats. In this sample project, we have used an open source JSON transformation library called JSLT [18] that works similarly to XSLT but with JSON. You can find the transformation (transform.jslt) in the project’s resources folder (see below later in this blog post). It’s not complete – you will have to extend it if you want to transform more advanced Workflow Forms. If that’s not to your liking, you can of course also transform the JSON files with plain code and write your own little transformer for that purpose.
Putting it All Together
Prerequisites
Before we can get your hands on the actual integration, you will need to fulfill a few prerequisites:
- You will need Java 8 and Maven 3 installed
- You will need an SAP Cloud Platform Trial account. Head over to [3] and get your own trial account if you have not done so already.
- You will need SAP Cloud Platform Workflow set up in your trial account. If you are not familiar with SAP Cloud Platform Workflow or don’t have a running environment already, I recommend setting it up as part of the tutorial for SAP Intelligent Business Process Management [4] which includes a setup of SAP Cloud Platform Workflow as well. Follow step (1) and (3) of the tutorial.
- You will need a Microsoft Office 365 Business subscription with Microsoft Exchange included. Get in touch with your IT help desk when in doubt. There is also an Office 365 developer edition you can try instead [5].
- You will need Microsoft Outlook installed to display Adaptive Cards (Microsoft Outlook for Mac does not support it yet so you will need to use Outlook Web Access in this case).
- The user ID on the SAP Cloud Platform (SCP) needs to be the same as the user in Microsoft Azure Active Directory (AAD) / Office 365. In case you have a different user in SCP than the one you have in AAD, you need to add the SCP user in the AAD as a guest user. For this navigate to [13] and open Azure Active Directory. From there select “+ New guest user” and add the SCP user ID (which is an e-mail) as the invited user’s identity / e-mail address.
Deploying and Testing the Sample Workflow Project
With the basic set up in place, we want to deploy a sample project that will serve as the scenario for this little integration project. Head over to [9] and clone the repository to your local file system. Then, import cf-outlook-integration-sample/order-spare-parts-process.zip into WebIDE similarly to how it is described in step (4) in [4]. You should have a project as shown below (remember to show hidden files through the ‘eye’ toolbar button):
The project is ready to run with one exception: you need to configure yourself as the approver of the workflow we are about to test-drive. Open file <your-project-name>/order-spare-parts-workflow/workflows/OrderSpareParts.workflow, select the step ‘Approve Spare Parts Order’, and on the second tab of the property sheet on the right, find the Users input field and enter your user ID you log on with to SAP Cloud Platform Cloud Foundry Trial (this will be an e-mail). Pay special attention to the fact that these user IDs are case sensitive!
After this, build and deploy the project as described in step (5) in [4]. Will all that is going on under the hood (services being provisioned, applications and content being deployed) his will take a while, so grab a cup of coffee and relax. Once deployment finished successfully, head over to your SAP Cloud Platform Cockpit. You should see applications and services created as follows, respectively:
Now, head over to the Applications tab and click on the app ‘order-spare-parts-approuter’. You should see a route bound to the app:
The route is your main entry point into your final application. Follow the route to see your Fiori Launchpad in action:
You will find that you don’t have permissions to access any of the apps so let’s fix that next. Follow the instructions of step (6) in [4]. For this integration project, you will only need to create roles for the workflow application identifier (WorkflowAdmin, WorkflowContextViewer, WorkflowDeveloper, WorkflowInitiator, WorkflowParticipant). Make sure to assign the newly created role collection to your user.
Finally, log off from your launchpad and log back in and you should be able to access the apps.
Click on the ‘Spare Parts’ tile and trigger a Spare Parts Ordering workflow by entering some data like shown below:
You should now find a task in your inbox. Head back by pressing ‘<’ or clicking the SAP icon, then click on ‘My Inbox’. You will find a task as presented below:
Approve the request. This completes the workflow.
As you can see, this is a simplistic one-step workflow which just includes the approval step you have gone through yourself a minute ago. Nothing you would consider realistic by any means but just what we need to test our Outlook integration end-to-end.
Now that we have a running workflow, we want to transition the approval step from My Inbox to Outlook so that you can approve the spare parts order in an e-mail!
Register an Actionable E-Mail Provider
The first step towards enabling Outlook integration is registering an Actionable E-Mail Provider with Microsoft. You will need to do this by accessing [10] and logging in with your Azure Active Directory user. Create a new provider and (a) give it a friendly name, (b) state the e-mail address(es) from which the e-mails will be sent, (c) enter the target URL where your Java app talking to Microsoft will be reachable (more on that in a bit), and (d) make sure to set the scope of submission to ‘Test Users’, also specifying your e-mail address used in Outlook. You can leave the Public Key field empty (not considered for now).
Regarding (c): you will later deploy your Java application to SAP Cloud Platform Cloud Foundry which will then be reachable via a publicly reachable URL that Microsoft can call back. Note that on SAP Cloud Platform Cloud Foundry Trial, you cannot reserve a custom domain, so your application effectively resides in the same global namespace as any other developers’ applications on a given trial landscape so you need to choose a name that won’t clash (‘hello-world’ won’t do!). Now, since you haven’t deployed the app yet and the app itself needs to be configured with the details of the Actionable E-Mail Provider, we have a little chicken-and-egg problem. We will go with a naming convention that should mostly work and be unique for all people following this blog:
https://<your-trial-account>-<your-cf-space-name>-wfs-forms-adaptive-cards.cfapps.<eu10|us10>.hana.o...
<your-trial-account> should match your subdomain as shown below and can be found in SAP Cloud Platform Cockpit:
<your-cf-space-name> name will be ‘dev’ by default on SAP Cloud Platform Cloud Foundry Trial. And depending on whether you choose the EU or the US trial landscape, you should choose ‘eu10’ and ‘us10’, respectively.
Coming back to registering the Actionable E-Mail Provider at Microsoft [10], you should finally see something like this:
Once you are done with your configuration, make sure to note (1) the target URL of your Java app you defined in (c) above, (2) the Provider Id (a GUID, aka ‘originator’) that was generated for you as well as (3) your Organization Id (this is the GUID provided as part of the Organization Info, so literally in the string "YOUR COMPANY (<some GUID>)" you need "<some GUID>" only). You will need this in the next step.
Configuring and Deploying the Java Application
Next, we want to configure, build, and deploy our Java application that will pull tasks from SAP Cloud Platform Workflow and push them as Adaptive Cards via e-mail to Outlook.
Open the repository you cloned from [9] in your favorite code editor. We will have to make some configuration changes here.
First, we need to adapt the cf-outlook-integration-sample/manifest.yml file and update the application’s technical name (line 3) to match the subdomain of the target URL you registered in the previous step, that is:
name: <your-trial-account>-<your-cf-space-name>-wfs-forms-adaptive-cards
You should have something like this:
Next, we need to update the cf-outlook-integration-sample/src/main/resources/application.properties file.
Open the file and (a) update the card.submission.url property to match the full target URL of your Java app, (b) update all mail.smtp.* properties to match your e-mail server like host, port etc. (user and password are later stored in a destination for security purposes), and (c) specify the organization.id and originator.id you noted down when creating the Actionable E-Mail Provider. You should have something similar to this:
Open a terminal and from the cf-outlook-integration-sample folder, issue the following commands:
# Build the Java app
$ mvn clean install
# Log in to CF Trial
$ cf login https://api.cf.eu10.hana.ondemand.com
or
$ cf login https://api.cf.us10.hana.ondemand.com
# Push your application
$ cf push
Now that the application is deployed, it is a good time to check the URL you registered with Microsoft as the target URL for the Actionable E-Mail Provider matches the public URL of your application. To do so, again go to the applications tab in your SAP Cloud Platform Cockpit, go to your Java app and look at the route assigned:
If the route does not match the URL you configured with Microsoft, no problem. Take the route that you have now. Head back to [10], register another Actionable E-Mail provider with the updated URL (you can delete the old provider), update your application.properties file accordingly (card.submission.url, organization.id, and originator.id), compile, and deploy it again, and you should be set.
Configure an E-Mail Destination
The last step for us to take is to configure the e-mail destination that the Java app will use to retrieve user and password to call the e-mail server with.
Head over to your SAP Cloud Platform Cockpit and import the mailserver destination file you will find in the cf-outlook-integration-sample into your trial sub-account as shown below, setting your email-address as the user and password along the way:
Don’t change the name of the destination unless you also update the mail.destination property in the application.properties file of your Java application.
Let’s Run it Already!
With all pieces in place, it is time to test-drive our work and see if everything works out as expected.
As a preparatory step, you might want to install the Actionable Messages Debugger for Outlook [11].
Now, follow the exact same steps you went through earlier to order spare parts but at the point where you would approve the request in My Inbox, don’t approve just yet but instead head over to your Outlook client. If you are on Mac, you are out of luck and can’t use the native macOS client. Instead, log in to the Outlook Web client [12]. You should also see an e-mail such as this:
You can now press the Approve or Reject button and should get a confirmation in Outlook ‘The task was completed’. Just to make sure this really worked, go back to My Inbox and refresh your task list. The task should have been completed successfully – brilliant!
What’s Next
The code provided will serve as a starting point for you. It’s not production ready and you should consider revising certain aspects to use it productively, including but not limited to the following:
- Make retrieval of task changes more robust (see TODOs in Task Change Listener Job)
- Enhance the transformation of Workflow Forms to Adaptive Cards to cover more use cases
- Establish proper trust between Azure AD and Sub-Account by importing SAML metadata from Azure
- Once trust is set up, make use of standard XSUAA security libraries to support principal propagation from Outlook to the Java application
- Perform additional checks when submitting cards (see TODO in Card Submission Controller)
- …
Summary and Outlook
In this blog post, we have seen how you can nicely integrate Microsoft Outlook with SAP Cloud Platform Workflow by transforming your Workflow Forms into Adaptive Cards embedded into e-mails. These e-mails, when opened in Outlook, allow the recipient to process tasks right within the e-mail client and hence to streamline the day-to-day work experience.
When this work was presented earlier this year at the DSAG Technologietage 2020 (German SAP User Group Technology Days) in Mannheim, Germany, feedback was extremely positive. Customers had many proposals on how to extend this idea, include other Microsoft products such as Microsoft Teams, etc. Let us know what you think down in the comments below. We are interested in what you think!
Updates
May 26, 2020
There is now an SAP Clout Platform Discovery Center mission for you to explore if you want a more guided approach to implementing this best practice. Check it out on [19].
References
[1] https://blogs.sap.com/2019/09/16/use-sap-cloud-platform-mobile-cards-with-sap-cloud-platform-workflo...
[2] https://news.sap.com/2019/10/sap-microsoft-partnership-cloud-migration-offerings/
[3] https://developers.sap.com/tutorials/hcp-create-trial-account.html
[4] https://developers.sap.com/tutorials/cp-starter-ibpm-employeeonboarding-1-setup.html
[5] https://developer.microsoft.com/en-us/office/dev-program
[6] https://news.sap.com/2019/05/sapphire-now-embrace-sap-partners-ecosystem-customers-cloud/
[7] https://www.sap.com/documents/2018/12/1ce4576f-2e7d-0010-87a3-c30de2ffd8ff.html
[8] https://www.sap.com/germany/products/cloud-platform/capabilities/ibpm.html
[9] https://github.com/SAP-samples/cloud-workflow-samples
[10] https://outlook.office.com/connectors/oam/publish
[11] https://store.office.com/app.aspx?assetid=WA104381686&productgroup=Outlook
[12] https://outlook.office.com/mail/
[13] http://portal.azure.com
[14] https://docs.microsoft.com/en-us/outlook/actionable-messages/
[15] https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card
[16] https://adaptivecards.io/
[17] https://api.sap.com/api/SAP_CP_Workflow_CF/resource
[18] https://github.com/schibsted/jslt/
[19] https://discovery-center.cloud.sap/#/missiondetail/3255/3285
- SAP Managed Tags:
21 Comments
