Welcome back to the blog post series about how to create your own Microsoft Teams extension for SAP solutions. In today’s seventh blog post, you will learn how to deploy your extension application to SAP Business Technology Platform and upload it to your Microsoft Teams client.
As explained in the first part (click here), this sample Microsoft Teams extension for SAP SuccessFactors will allow you to create leave requests right from within Microsoft Teams. It also provides features for managers to approve or reject leave requests. Again, this blog series has a special focus on those customers already using the SAP Business Technology platform in their landscape.
A quick reminder for your convenience – Feel free to check out the GitHub repository provided in the SAP-samples organization. Please be aware, that the repository is still being updated, so make sure you’re pulling on a regular basis.
https://github.com/SAP-samples/btp-extend-workflow-cai-msteams/tree/full-scope
The provisioning of your Microsoft Teams extension application consists of two different processes. On the one hand, you need to deploy the actual application to your SAP BTP subaccount. There it will be running as a Cloud Foundry application and provide the runtime features of your extension.
On the other hand, you need to inform Microsoft Teams about the capabilities of your new app and where Microsoft Teams can find the current implementation. Furthermore, you can upload icons and define the visual appearance of your extension app in Microsoft Teams.
So, let’s get started with the last technical instructions of this series and see if you’ve closely followed the steps of the previous blog posts!
2) For the deployment to the SAP Business Technology Platform, make sure that you've created an SAP XSUAA instance in your SAP BTP subaccount as described in the fourth part of this blog post series (click here). Otherwise, the deployment will fail due to the required binding.
Important - Remove the .sample file extension from the provided vars.yml file before updating your values. Otherwise, you might end up committing your environment variables to Git.
3) Please make sure to set the <cf-app-name-placeholder> to your application name in the /deploy/manifest.yml file before deployment. The same applies to the XSUAA service binding. Replace <cf-xsuaa-instance-placeholder> by the name of your XSUAA instance.
Hint – You’ve noted down the app name in the fourth part of this blog post series (click here). Please be reminded that you also need to update various Azure settings in case you change the name of your application. The XSUAA instance was created in the same blog post.
Important – Do not change the env section of the manifest.yml file! By using the ((VAR_NAME)) syntax, the variables are filled dynamically from your vars.yml file during deployment! Remove the .sample file extension before deployment.
4) Once you’re done, you can start the deployment process. First, open a new command line or terminal and navigate to the root of your cloned project.
5) Once there, you must first login to your dedicated SAP BTP target subaccount (if not already done).
6) Select your target subaccount and the correct space by typing the respective numbers.
7) You can now either use the combined build-push command to start the deployment or run the build command and respective cf push command separately.
! Important - Only tested with Node v14 !
8) After the deployment has finished, you can view the status of your application in your SAP BTP cockpit. Your application should be started, and the existing instance should be in RUNNING state.
1) Before you upload the manifest definition of your extension app to Microsoft Teams, please make sure, that you’ve updated all parameters in the respective /deploy/msteamsfiles/manifest.json file. Further details and parameter descriptions can be found below
Important - Please remove the .sample file extension before changing the manifest.json file.
2) Once you've updated the manifest.json file, you must zip all files in the /deploy/msteamsfiles folder. This resulting zip file will be uploaded to Microsoft Teams in the next step.
3) Start the Microsoft Teams Web (click here) or Desktop Client and login with a user having administrative permissions for Microsoft Teams in your organization.
Important - To upload new Microsoft Teams apps to your organization, the uploading user must have at least the following Azure Active Directory role.
4) You should be able to upload a new app to your organization, by clicking on Upload a custom app on the lower left of your Microsoft Teams App store. Select the zip file you just created, and start the upload.
5) If you don't see the link to Upload a custom app in your Microsoft Teams client, you can use the Microsoft Teams admin center (click here) to do so. Just login with an Active Directory user that has the Microsoft Teams administrator role assigned and use the respective menu to upload your app (see screenshot below).
6) Once the upload is successful (either using the client or the admin center), you should see your extension application in the Build for your org section within the Microsoft Teams app store.
7) Add the new app to your Microsoft Teams profile, by clicking on the tile and hitting the Add button.
8) Whenever you want to upload a new version of your extension app, you can delete the existing app from your organization and then re-upload the app. To do so, click on the small dots at the top right of your app tile within the Microsoft Teams app store.
Alternatively, you can also update your app with a new zip file. Therefore, just click Update instead of the Delete button. In this case, make sure to increase the version property (e.g., from 1.0.0 to 1.0.1) within your manifest.json file before creating a new zip file.
9) If you don't have the respective options in your Microsoft Teams client, you can again use the Microsoft Teams admin center (click here) for the same actions. Just search and select your SAP SuccessFactors app from the Manage apps sub-menu.
Wow, that has been quite a ride, but finally you’ve managed to deploy your Microsoft Teams extension application to SAP BTP and upload the app definition to Microsoft Teams. Congratulations! Now it’s time to test your app and to see if things work out properly!
1) Login with your employee test user and add the SAP SuccessFactors app from the Microsoft Teams app store (if not done yet). This will assign the app to your user profile and generate a conversation reference in the Azure Storage account container.
2) The bot will greet you with a welcome message. Now you can start the leave request flow by typing Leave Request into the message pane of your extension app and see if your bot comes to life.
3) Please be aware, that for the first usage, you are asked to login with your Active Directory user once, to grant the application the required permissions.
4) You can also check out the Leave Request tab of your extension application. Please be aware that also here you will be required to “Sign In” on first usage.
Hint - I haven’t tested this yet but as the tab implementation (based on adaptive cards) does not support silentAuth, you might be required to login again if your Azure session expires.
To start receiving notifications with your manager user, he or she has to add the extension application to his profile first. This will create the required conversation reference in the Azure Storage account container. Without this reference, the bot does not know to which chat the notification needs to be sent to.
So, make sure you login with your manager at least once, to test the notification feature. Start the leave request conversation with the bot, to trigger the initial login which is required when using the extension application for the first time.
Auto-approved leave requests
In case your leave requests are auto-approved, please make sure you are using a suitable test user for your scenario. Leave requests created by user with the Admin access to MDF OData API permission are always auto-approved. Either remove the permission from the respective Permission Role(s) temporarily or take another test user. The sfadmin user for example has this permission assigned in multiple permission roles. More information about this standard behavior can be found in SAP Help (click here) or in the following SAP Note (click here).
You might face error messages when creating a new leave request, although there is sufficient balance shown. This might have various reasons. The most common reasons are explained below, and I will give you some guidance on where to find further error details. The current error handling does not forward the SAP SuccessFactors error details to the end user yet.
- If you create a leave request for a date that already has an existing leave request, your call to SAP SuccessFactors will result in an error! You cannot create two leave requests for the same date. Make sure to either reject the leave request using the manager user or login to SAP SuccessFactors and cancel the existing leave request before creating a new one.
- The balance displayed in the current Microsoft Teams extension is based on approved leave requests only. If there are approvals in pending state, they will not be subtracted from the available balance. SAP SuccessFactors will throw an error, if the value of “Remaining balance - Pending approvals” is less than what's required for the new leave request.
- Creating a leave request for a public holiday or weekend might lead to error messages triggered by SAP SuccessFactors. Make sure your leave request covers a regular working day.
If none of the these issues applies to your test scenario, please find further error details within the Monitoring area of your SAP Cloud Integration instance.
Select the corresponding integration flow with status Failed and click on Open Text View.
Check the Log and Response Body tabs to find more details on the error.
Please be aware, that the SAP SuccessFactors calls in our development landscape have longer response times when using the app for the first time. As a side effect, Microsoft Teams triggers the chat bot messages once again after a few seconds. This results in duplicated bot or error messages when SAP SuccessFactors is e.g., asked to create the same leave request twice.
Important - Please be aware that the leave request scenario has been chosen for demonstration purposes only. The available SAP SuccessFactors APIs don’t match the requirements of this scenario to a 100%. This is why some of the OData calls are quite complex (e.g., to determine the available time types or balances).
Please ensure that the API calls of your own scenarios have satisfying response times by testing things in Postman first. Also keep in mind that your integration flows will add further processing time to your requests.
If no result or message is returned after 10-20 seconds, you can also cancel the communication by just typing Cancel. Then restart the communication by typing Leave Request again.
In addition to the error messages explained above, there’s a list of known issues within the Readme of the GitHub repository. In case you tackle any problem, please check the GitHub for these issues first.
The current version of the extension app only provides features for creating leave requests. It is not yet possible to view existing leave requests. The respective button has been added as an inspiration for you, to enhance the solution with further functionalities.
The same applies to further dialogues provided by the bot. If you check the MainDialog coding, you can see that there’s another entry point for a potential feedback feature by sending Feedback to the chat bot. You could e.g., implement a bot which allows you to give feedback to other colleagues within a team or a group-chat.
Reaching this point of the blog post series, you've successfully implemented the sample scenario in your own landscape. Congratulations! I hope you’ve learned a lot of new things when it comes to integration scenarios between your existing SAP solutions and Microsoft services like Teams.
Whereas this blog post series uses the leave request process as an example, a major part of the content, settings and coding can be reused for scenarios of your choice. As said, the architecture itself is not limited to SAP SuccessFactors, but allows you to integrate also other SAP solutions like SAP S/4HANA.
This will also be part of the last and final blog post, in which I give you a brief introduction, how to modify the current setup for the integration of an SAP S/4HANA On-Premise system. Furthermore, I will provide you more details on limitations of the current solution and a few things to consider, in case you want to enhance the current sample scenario.
Stay curious!
As explained in the first part (click here), this sample Microsoft Teams extension for SAP SuccessFactors will allow you to create leave requests right from within Microsoft Teams. It also provides features for managers to approve or reject leave requests. Again, this blog series has a special focus on those customers already using the SAP Business Technology platform in their landscape.
- Preface and scenario introduction (click here)
- Target application features (click here)
- Requirements and application architecture (click here)
- SAP BTP subaccount configuration and test users (click here)
- SAP SuccessFactors instance setup (click here)
- Set up your SAP Cloud Integration instance (click here)
- Get your Microsoft Azure settings ready (click here)
- Deploy your Microsoft Teams extension (this blog post)
- Maintain the extension application details in the manifest file
- Provide the environment variables of your landscape
- Deploy the extension application to SAP BTP
- Upload the application manifest file to Microsoft Teams
- Improvement ideas and further topics (click here)
A quick reminder for your convenience – Feel free to check out the GitHub repository provided in the SAP-samples organization. Please be aware, that the repository is still being updated, so make sure you’re pulling on a regular basis.
https://github.com/SAP-samples/btp-extend-workflow-cai-msteams/tree/full-scope
The provisioning of your Microsoft Teams extension application consists of two different processes. On the one hand, you need to deploy the actual application to your SAP BTP subaccount. There it will be running as a Cloud Foundry application and provide the runtime features of your extension.
On the other hand, you need to inform Microsoft Teams about the capabilities of your new app and where Microsoft Teams can find the current implementation. Furthermore, you can upload icons and define the visual appearance of your extension app in Microsoft Teams.
So, let’s get started with the last technical instructions of this series and see if you’ve closely followed the steps of the previous blog posts!
SAP BTP deployment
1) Before you start the deployment process, please clone the existing GitHub repository to your device (if not done yet). You will need to modify some of the files provided before the deployment can be done.
git clone https://github.com/SAP-samples/btp-msteams-leaverequest
cd btp-extend-workflow-cai-msteams
git checkout full-scope2) For the deployment to the SAP Business Technology Platform, make sure that you've created an SAP XSUAA instance in your SAP BTP subaccount as described in the fourth part of this blog post series (click here). Otherwise, the deployment will fail due to the required binding.
3) Please update all environment variables in the /deploy/vars.yml file before you start the deployment. You can find a list of the environment variables and the relevant descriptions below.
Important - Remove the .sample file extension from the provided vars.yml file before updating your values. Otherwise, you might end up committing your environment variables to Git.
Environment variables sample file (vars.yml)
Environment variables
| DOMAIN / REACT_APP_APP_DOMAIN The Cloud Foundry domain of your Microsoft Teams extension which can be derived from your application name and the target SAP BTP region (e.g. eu20, us20, …).Hint - You've noted down this value in the previous blog post (click here), when you configured the domain-placeholder. In case you use a custom domain, this logic does not apply! MICROSOFT_APP_ID / REACT_APP_MICROSOFT_APP_ID The Client ID of your extension application app registration. Hint - You’ve noted down this Client ID in the beginning of the previous blog post (click here). MICROSOFT_APP_PASSWORD The Client Secret which you created for your app registration Hint - You’ve noted down this Client Secret in the beginning of the previous blog post (click here). MICROSOFT_AD_TENANT_ID The ID of your Azure Active Directory Hint - You’ve noted down this ID in the beginning of the previous blog post (click here). BTP_LANDSCAPE The SAP BTP region in which your extension app is supposed to be deployed e.g., eu20 or us20. BTP_ACCOUNT_NAME The subdomain of the SAP BTP subaccount in which your extension application is supposed to be deployed e.g., teams-sfsf. XSUAA_CS_URL_SUFFIX The audience value (e.g., azure-live-eu20 or aws-live-eu10 or aws-live) which can be extracted from the SAML metadata of your SAP BTP subaccount. Make sure you don’t include the subdomain of your SAP BTP subaccount but only use the value after the last period (as shown in the screenshots below). Download SAP BTP SAML Metadata Audience value in your Metadata file Hint - You can also get the audience value from the SAML configuration of your existing Enterprise Application created during the trust setup between SAP BTP and Azure Active Directory. Get the audience value from your Enterprise Application XSUAA_CLIENT_ID The Client ID of your Process Integration Runtime service key. Hint - You’ve noted down this Client ID in the following blog post (click here) when creating the Process Integration Runtime instance. XSUAA_SECRET The Client Secret of your Process Integration Runtime service key. Hint - You’ve noted down this Client Secret in the following blog post (click here) when creating the Process Integration Runtime instance. CPI_BASE_URI The runtime URL of your SAP Cloud Integration tenant incl. the https:// prefix. Hint - You can also find this value in your Process Integration Runtime (click here). It is the url parameter of your service key instance. CPI_PATH The path of your integration flows which is added to the SAP Cloud Integration runtime URL. Hint - Most likely /http is the correct value, but you can double check in the Monitoring area of your SAP Cloud Integration tenant by checking the runtime URLs of your integration flows. Integration flow prefix in SAP Cloud Integration BTP_SCOPES/REACT_APP_APP_SCOPES The custom scope created in the previous blog post (click here). Hint - Make sure you include the full scope name incl. the api:// prefix. Custom scope of your application registration MICROSOFT_BLOB_CONTAINER_NAME The name of the Azure Storage account container created in the previous blog post (click here). MICROSOFT_BLOB_CONNECTION_STRING The connection string of the Azure Storage account created in the previous blog post (click here). |
3) Please make sure to set the <cf-app-name-placeholder> to your application name in the /deploy/manifest.yml file before deployment. The same applies to the XSUAA service binding. Replace <cf-xsuaa-instance-placeholder> by the name of your XSUAA instance.
Hint – You’ve noted down the app name in the fourth part of this blog post series (click here). Please be reminded that you also need to update various Azure settings in case you change the name of your application. The XSUAA instance was created in the same blog post.
Important – Do not change the env section of the manifest.yml file! By using the ((VAR_NAME)) syntax, the variables are filled dynamically from your vars.yml file during deployment! Remove the .sample file extension before deployment.
manifest.yml configuration sample - Do not change or set the ((Variables))
4) Once you’re done, you can start the deployment process. First, open a new command line or terminal and navigate to the root of your cloned project.
5) Once there, you must first login to your dedicated SAP BTP target subaccount (if not already done).
cf login -a "<Cloud Foundry API endpoint of your target Region"
Sample: cf login -a "https://api.cf.eu20.hana.ondemand.com"6) Select your target subaccount and the correct space by typing the respective numbers.
7) You can now either use the combined build-push command to start the deployment or run the build command and respective cf push command separately.
! Important - Only tested with Node v14 !
The automated way:
npm run build-push
The manual build and push:
npm run build-client
cf push -f ./deploy/manifest.yml --vars-file ./deploy/vars.yml8) After the deployment has finished, you can view the status of your application in your SAP BTP cockpit. Your application should be started, and the existing instance should be in RUNNING state.
Your extension application running in SAP BTP
Microsoft Teams manifest upload
1) Before you upload the manifest definition of your extension app to Microsoft Teams, please make sure, that you’ve updated all parameters in the respective /deploy/msteamsfiles/manifest.json file. Further details and parameter descriptions can be found below
Important - Please remove the .sample file extension before changing the manifest.json file.
Sample manifest.json (Some parts removed for screenshot)
Configuration parameters
| msteamsappguid-placeholder Create a new GUID for your Microsoft Teams app.Hint - It can be generated using the Windows PowerShell by invoking the [guid]::NewGUID() command. On a Mac, you can give it a try with the uuidgen command.Important - This GUID is used by Microsoft Teams only and does not equal the Client ID your application registration. Create a new GUID in Windows PowerShell msappid-placeholder The Client ID of the application registration created for your Microsoft Teams extension app. Hint - You’ve noted this Client ID in the beginning of the previous blog post (click here). domain-placeholder The domain of your Microsoft Teams extension which can be derived from your application name and the region of your target SAP BTP subaccount (e.g., eu10 or us20). Hint - You've noted down this domain in the previous blog post (click here) when you set the domain-placeholder. |
2) Once you've updated the manifest.json file, you must zip all files in the /deploy/msteamsfiles folder. This resulting zip file will be uploaded to Microsoft Teams in the next step.
Zip all files in the /deploy/msteamsfiles folder
3) Start the Microsoft Teams Web (click here) or Desktop Client and login with a user having administrative permissions for Microsoft Teams in your organization.
Important - To upload new Microsoft Teams apps to your organization, the uploading user must have at least the following Azure Active Directory role.
Microsoft Teams administrator role
4) You should be able to upload a new app to your organization, by clicking on Upload a custom app on the lower left of your Microsoft Teams App store. Select the zip file you just created, and start the upload.
Upload a custom app for your organization
5) If you don't see the link to Upload a custom app in your Microsoft Teams client, you can use the Microsoft Teams admin center (click here) to do so. Just login with an Active Directory user that has the Microsoft Teams administrator role assigned and use the respective menu to upload your app (see screenshot below).
Upload a custom app via the Microsoft Teams admin center
6) Once the upload is successful (either using the client or the admin center), you should see your extension application in the Build for your org section within the Microsoft Teams app store.
There it is - Your new Microsoft Teams app
7) Add the new app to your Microsoft Teams profile, by clicking on the tile and hitting the Add button.
Add the app to your Microsoft Teams profile
8) Whenever you want to upload a new version of your extension app, you can delete the existing app from your organization and then re-upload the app. To do so, click on the small dots at the top right of your app tile within the Microsoft Teams app store.
Delete or update your app using the Microsoft Teams client
Alternatively, you can also update your app with a new zip file. Therefore, just click Update instead of the Delete button. In this case, make sure to increase the version property (e.g., from 1.0.0 to 1.0.1) within your manifest.json file before creating a new zip file.
9) If you don't have the respective options in your Microsoft Teams client, you can again use the Microsoft Teams admin center (click here) for the same actions. Just search and select your SAP SuccessFactors app from the Manage apps sub-menu.
Update or delete your extension app using the admin center
Test your application
Wow, that has been quite a ride, but finally you’ve managed to deploy your Microsoft Teams extension application to SAP BTP and upload the app definition to Microsoft Teams. Congratulations! Now it’s time to test your app and to see if things work out properly!
1) Login with your employee test user and add the SAP SuccessFactors app from the Microsoft Teams app store (if not done yet). This will assign the app to your user profile and generate a conversation reference in the Azure Storage account container.
2) The bot will greet you with a welcome message. Now you can start the leave request flow by typing Leave Request into the message pane of your extension app and see if your bot comes to life.
Test your extension application
3) Please be aware, that for the first usage, you are asked to login with your Active Directory user once, to grant the application the required permissions.
Initial login is required to grant permissions
4) You can also check out the Leave Request tab of your extension application. Please be aware that also here you will be required to “Sign In” on first usage.
Hint - I haven’t tested this yet but as the tab implementation (based on adaptive cards) does not support silentAuth, you might be required to login again if your Azure session expires.
Initial "Sign In" is also required for the tab component
Hints and important information for testing
Notifications
To start receiving notifications with your manager user, he or she has to add the extension application to his profile first. This will create the required conversation reference in the Azure Storage account container. Without this reference, the bot does not know to which chat the notification needs to be sent to.
So, make sure you login with your manager at least once, to test the notification feature. Start the leave request conversation with the bot, to trigger the initial login which is required when using the extension application for the first time.
Auto-approved leave requests
In case your leave requests are auto-approved, please make sure you are using a suitable test user for your scenario. Leave requests created by user with the Admin access to MDF OData API permission are always auto-approved. Either remove the permission from the respective Permission Role(s) temporarily or take another test user. The sfadmin user for example has this permission assigned in multiple permission roles. More information about this standard behavior can be found in SAP Help (click here) or in the following SAP Note (click here).
Admin access to MDF OData API
Error messages
You might face error messages when creating a new leave request, although there is sufficient balance shown. This might have various reasons. The most common reasons are explained below, and I will give you some guidance on where to find further error details. The current error handling does not forward the SAP SuccessFactors error details to the end user yet.
- If you create a leave request for a date that already has an existing leave request, your call to SAP SuccessFactors will result in an error! You cannot create two leave requests for the same date. Make sure to either reject the leave request using the manager user or login to SAP SuccessFactors and cancel the existing leave request before creating a new one.
- The balance displayed in the current Microsoft Teams extension is based on approved leave requests only. If there are approvals in pending state, they will not be subtracted from the available balance. SAP SuccessFactors will throw an error, if the value of “Remaining balance - Pending approvals” is less than what's required for the new leave request.
- Creating a leave request for a public holiday or weekend might lead to error messages triggered by SAP SuccessFactors. Make sure your leave request covers a regular working day.
If none of the these issues applies to your test scenario, please find further error details within the Monitoring area of your SAP Cloud Integration instance.
SAP Cloud Integration Monitoring features
Select the corresponding integration flow with status Failed and click on Open Text View.
Identify the request which caused the error in Microsoft Teams
Check the Log and Response Body tabs to find more details on the error.
Analyze the logs of the failed request to find more error details
Initial response times
Please be aware, that the SAP SuccessFactors calls in our development landscape have longer response times when using the app for the first time. As a side effect, Microsoft Teams triggers the chat bot messages once again after a few seconds. This results in duplicated bot or error messages when SAP SuccessFactors is e.g., asked to create the same leave request twice.
Important - Please be aware that the leave request scenario has been chosen for demonstration purposes only. The available SAP SuccessFactors APIs don’t match the requirements of this scenario to a 100%. This is why some of the OData calls are quite complex (e.g., to determine the available time types or balances).
Please ensure that the API calls of your own scenarios have satisfying response times by testing things in Postman first. Also keep in mind that your integration flows will add further processing time to your requests.
Error message due to a leave request being send to SAP SuccessFactors twice
Duplicated chat bot messages due to long response times
If no result or message is returned after 10-20 seconds, you can also cancel the communication by just typing Cancel. Then restart the communication by typing Leave Request again.
Known Issues
In addition to the error messages explained above, there’s a list of known issues within the Readme of the GitHub repository. In case you tackle any problem, please check the GitHub for these issues first.
Further Features
The current version of the extension app only provides features for creating leave requests. It is not yet possible to view existing leave requests. The respective button has been added as an inspiration for you, to enhance the solution with further functionalities.
The same applies to further dialogues provided by the bot. If you check the MainDialog coding, you can see that there’s another entry point for a potential feedback feature by sending Feedback to the chat bot. You could e.g., implement a bot which allows you to give feedback to other colleagues within a team or a group-chat.
What’s next?
Reaching this point of the blog post series, you've successfully implemented the sample scenario in your own landscape. Congratulations! I hope you’ve learned a lot of new things when it comes to integration scenarios between your existing SAP solutions and Microsoft services like Teams.
Whereas this blog post series uses the leave request process as an example, a major part of the content, settings and coding can be reused for scenarios of your choice. As said, the architecture itself is not limited to SAP SuccessFactors, but allows you to integrate also other SAP solutions like SAP S/4HANA.
This will also be part of the last and final blog post, in which I give you a brief introduction, how to modify the current setup for the integration of an SAP S/4HANA On-Premise system. Furthermore, I will provide you more details on limitations of the current solution and a few things to consider, in case you want to enhance the current sample scenario.
Stay curious!
- SAP Managed Tags:
