External Notifications - tsgrp/HPI GitHub Wiki

This page is being moved to the alfresco documentation

External notifications are available starting with the ACA 3.4 release. Basic workflow task notification support on both Slack and MS Teams is supported.

OC Setup

By default External Notifications are off by default. To turn this on, set the following OC properties within your override properties file.

send.external.notifications=true

Slack Setup

Step 1: Navigate to https://api.slack.com and sign in

Click on the tab Your Apps in the top right corner. If you have not created an app yet, then hit the Create New App button. Give it a name and select the workspace where you want the application to live. If you already have an app created, then click on it.

Step 2: Customize app Display Information (optional)

When the app was clicked on, the basic information should have been loaded. At the bottom of this page there is the Display Information section. This gives the ability to customize what the particular app will look like to the user. Go ahead and customize this section now or skip to Step 3.

Step 3: Add a Bot User

Find the submenu under Features called Bot Users and click on it. This will bring up an option to turn on and add a bot user. You can customize the display name and default username if you choose. Also, it gives the option to show that the bot user is always online.

Step 4: Reinstall/Install the app

If you have not installed the application, now would be a good time to do that to the particular workspace. You can do that by clicking on the Install App submenu under the Settings menu. It will also have you choose a channel for the bot to have permissions to post. This is a default channel the bot will post to if a channel is not specified within the post message API call.

Step 5: Set up the app's scopes

OAuth scopes let you specify exactly how your app needs to access a Slack user's account. Different Slack API calls require different scope permissions. The scope permissions that you need to add are the following: channels:read, chat:write:bot, users:read, users:read:email. Once adding these, it will need you to reinstall your app.

Step 6: Grab the Bot User OAuth Access Token

Click on the submenu OAuth & Permissions under the Features menu. You should be able to see a Bot User OAuth Access Token. This will be needed to override the slack.auth.token property value.

Step 7: Override the Slack Properties

Now that we have the bot user set up, you can now successfully override the properties to get Slack external notifications connected.

MS Teams Setup

Step 1: Navigate to https://portal.azure.com/ and sign in

In the search bar, search for App Registrations. Click on the New registration plus button in the top left corner of the view.

Step 2: Register the application (API)

  • Fill out the name field with whatever name you want to give this application.
  • Then, fill out who can use this application or access this API. This will depend on use-cases, but typically should be restricted to Single tenant (the company org account EX: tsgrplab).
  • Leave the Redirect URI empty, this will not be used for our external notification API.

Step 3: App Overview

The Overview tab should showing right now. Some important variables to note here are the Application (client) ID and the Directory (tenant) ID. Take note of these two variables, they will be used below.

Step 4: API Permissions

Navigate to the API permissions tab on the left menu bar. Click the plus button to Add a permission. These permissions are the access/scopes you are giving to this API. Good practice is to not give your API more permissions than it needs, these can be added/subtracted at anytime. Go ahead and add the following permissions:

  • Chat.Read
  • Chat.ReadWrite
  • Group.Read.All
  • Group.ReadWrite.All
  • User.Read
  • User.Read.All
  • User.ReadBasic.All
  • User.ReadWrite
  • User.ReadWrite.All

Step 5: Grant/Request Admin Consent

You may notice there are some permissions that need Admin Consent. These are the permissions of Group.Read.All, Group.ReadWrite.All, User.Read.All, User.ReadWrite.All. If you are not the admin, you will have to get them to grant these permissions. To grant the permissions, follow this documentation link: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent#grant-admin-consent-in-app-registrations

Step 6: Authentication

Click on the Authentication tab on the left side menu. There are 2 different ways the following configurations can be filled out on this screen depending on if your azure account loads their new or old view for this section.

  1. The "new" experience, which should be loaded by default (this is Azure's update to some of these views).

    • Click on the Add a platform. It will ask you to add a redirect URI. We don't necessarily need one for this API, but it's a required field. So give it your application url root/homepage EX: http://localhost:8080.
    • Leave the Logout Url section blank
    • Select the check-boxes for the Access token and ID tokens (this is very important because it lets the application generate a access token to be used within the API calls)
    • Once that is created, scroll to the bottom of the page to the Advanced Settings header. Turn this on. We are not using re-direct URI's. That means we are grabbing tokens without user involvement/sign-in window.
    • Click Save at the top to save all these changes.

  2. The "old" experience. You can tell if you are on the old, if the button to the right of the Discard says Switch to the new experience.

    • Skip the Redirect URIs section and do not input a logout url.
    • Under the Implicit grant section, select the check-boxes for the Access token and ID tokens (this is very important because it lets the application generate a access token to be used within the API calls)
    • Click Yes for the Default client type to treat application as a public client.
    • Click save at the top to save all these changes.

Step 7: Creation of a Service Account User

A service account user is needed to send a direct 1:1 message to the user that is receiving the task notification.

Step 8: Encrypt the Service Account User's Password

This is a valid user within your organization/team's azure directory. So, we need to encrypt the password before adding to our override property file.

Step 9: Override the Microsoft Teams Properties

Now that we have the App set up, you can now successfully override the properties to get Teams external notifications connected.

Microsoft Graph API Limitations (https://docs.microsoft.com/en-us/graph/overview?view=graph-rest-beta)