How to send notifications: Integration with MS Teams

Center of Excellence

1. Abstract

A typical request during project implementations is to support the process workflow by adding notifications to users when certain actions have been executed and the next workflow steps can start.

In this article, we want to show how to handle the notification to Microsoft Teams through the engagement of an external layer, Power Automate, which is triggered on demand from our toolkit platform Board through a rest API call (procedure step).

This article is focused on MS Teams through Microsoft Power Automate; however the REST API protocols are widely adopted and allow to implement the same process also with other tools exposing API endpoints like Slack, etc.

NOTE: MS Power Automate is a module of the Microsoft 365 ecosystem. The module might be/or might not be part of the customer’s Microsoft 365 subscription.

Here is the link to the Power Automate website: https://powerautomate.microsoft.com/en-us/pricing/

2. Context

Let’s imagine we want to send a notification via Teams to the region’s controller once the user of the specific legal entity has submitted the financial closing data. It is assumed that the local users send to the region controller and then to the group manager, thus a three levels workflow Local >> Region >> Group.

The notification should contain details of the submitted perimeter, audit track of who did it and when, a link to go back to Board to review the submitted results.

The desired outcome is the following notification sent via Power Automate to the region’s controller Microsoft Teams account.

Let’s see how to configure the process together.

3. Content

3.1 Power Automate- Configuration

3.1.1 Cloud Flow Creation

First, an HTTP request must be created and configured within Power Automate (this application must be installed by the IT department and made accessible to anyone within the company network).

1) Open the power automate suite and choose first the instant cloud flow and then the HTTP request option.

2) Click on the green header to expand the advanced configuration window.

In the “request body” area you must type the JSON Schema.

JSON Schema is a grammar language for defining the structure, content, and (to some extent) semantics of JSON objects.

It lets you specify the metadata of an object’s properties and what values are valid for those properties.

To facilitate the interpretation of our JSON Schema, some JSON keywords are explained below:

• type: Defines the type of data.
• properties: Defines various keys and their value types within a JSON document.
• items: Enumerates the definition for the items that can appear in an array.
• required: Lists the keys that are required and mandatory.

Below is our compressed JSON schema:

This is the basic structure you will need to add to the schema to be able to receive variables/parameters from Board.

Then, as you can see in the example, inside the basic schema structure you must define each specific variable you will need to receive from Board according to your specific business case.

In our example, we will receive from Board 3 variables: “audit”, “closingmonth” and “email” (see image above).

So, in the JSON schema, we need to define their value types and their properties.

For example, let’s take the “audit” variable, the syntax in our business case would be as follows:

The “Type” of the “audit” variable is defined as an “array”: this because in our example it will contain multiple item values. Then, since it is an array, we need to also define the type of each single item contained.

In our specific example, the “audit” variable array will contain 3 items: “Legal Entity” (code), “AuditText” (value),”LegalEntity” (desc).

For each item, you can see that the JSON Schema specifies the type and whether it is required/mandatory (or not).

Below the “Type” of the “closingmonth” variable is defined as an “array” and in our specific example will contain 2 items: “Text” (entity by row), “ClosingMonth” (month display).

Here after the “Type” of the “email” variable is defined as an “array” and our specific example will contain 2 items: “Lines” (entity by row), “email” (email addresses) to whom post the notification message on Teams.

Of course, if your variable is not an array but a single item the JSON schema will simply define its type and nothing else.

Once all the variables are correctly defined in the JSON Schema, the cloud flow (Power Automate) will allow mapping each variable or a specific item to an “operation step”.

In the following paragraph, we show how to add and set up a step.

3.1.2 How to add a new step

Once the JSON schema is defined correctly, you can collapse the “HTTP request” step in the cloud flow and (as shown below) start adding additional operational steps (i.e., concrete actions executed by the flow)

In our example, we want to populate some variables to be then added to the message that the user will receive in teams. To do so, we need to add “Data Operation” steps which will connect the Board/JSON schema variables to our Teams message. In other words, we need to click the New Step button and choose Data Operation in the Built-in tab (see images below).

Power Automate provides a list of standard actions by default:

In our example, we will be using two “Select” data operation steps for the “LegalEntity” and “AuditText items” from the “audit” variable.

We will, of course, add as many “select” data operation steps as required to populate properly all the dynamic text required by our desired Teams message.

Once we have all the “select” steps necessary we need to add a “Compose” step which will finally create the Teams message we want to send. See below image where we have typed the desired fixed text plus the dynamic text derived from the previous “select” data operation steps:

Inside the message text, you can either add an expression (fX ) or use directly a “select” variable.

If we take our example, we needed to apply a function to the “SelectLE” variable to have a list of all the Legal Entities submitted separated by a comma. In this way the message will display one or more values depending on how many legal entities were submitted, avoiding the need to create separate flows depending on the workflow step.

In practice the expression used was slice(join(body('SelectLE'),','), 2, -5):

• Slice: which returns a substring by specifying the starting and ending position or value.
• Join: whichreturns a string that has all the items from an array, separated by the specified character, in our case “,”.
• Body: which returns an action's body output at runtime.

Similar functions were applied to the other dynamic parts of the text like submitted Months or Audit track.

At this point, we have managed to creation of a fully dynamic Teams message.

The final step is to add an “Apply to each” step which will finally post the message in Teams to one or more users depending on the workflow configuration.

See the below image where we have used the variable “email” in the recipient space and provided the compose as the output:

After all the above steps our Power Automate flow is completed and should look as follows:

Once the flow’s configuration is over, by clicking "Save", Power Automate generates the HTTP URL that will then be used by Board to post data to Microsoft Teams via Power Automate.

Power automate will generate the API and related path so that our flow can be called from Board passing the required parameters.

The HTTP URL can be found at the top of the configured flow, and it is a combination of several components, which are:

Base URL+ Api-path+ Api-version+ sp + sv + sig

Where:

Base URL = https: //prod-123.xxxxxxxxxx.xxxxx.azure.com:443

Api path = /workflows/a1f3xxxxxxxxxxxxxxxxxxxxxxxxxxxx/triggers/manual/paths/invoke

Api-version = 2016-06-01

sp = /triggers/manual/run

sv = 1.0

sig = DYnvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each of these components is used later in Board during the configuration of the data source connection and the rest API call.

3.2 Board - Configuration

From Board’s perspective two actions must take place:

1. System Administration → Data Source configuration

2. Data Model → Procedure → Rest API call step configuration

3.2.1 System Administration

First, you need to define a new Data Source connection in the System Administration tile (which is visible only if the admin checkbox is tickled for the Instance below the Platform authorization area).

Add a new data source connection and from the dropdown menu select API, you get several pieces of information to be fulfilled:

Name, which is the proper name you want to give to the connection.

Authentication Type must be set to API key.

Key, defines the authentication method for the API call and has to be set equal to “sig”.

Value must be set equal to the "sig" value, which can be retrieved from the HTTP URL generated by Power Automate.

Add to is set by default to Header.

Api base URL identifies the instance where the cloud stream is located that is called in Board.

Once the Data source connection has been configured, you can proceed to the step configuration.

3.2.2 Board Procedure

To configure the new step, add it to the desired Board procedure and proceed as follows.

Fill in the main settings section:

1. From the "Connection" dropdown menu, select the appropriate Data source connection configured as explained above.
2. Enter the API endpoint URL in the "Api path" field. If the chosen Data source connection includes a base URL for the API endpoint, it will automatically appear next to the "Api path" field.
3. (Optional) From the "On error go to group" dropdown menu, select a group of steps which the Procedure should run in case the API request returns an error status code.
4. Select the appropriate API method request: POST.

In the Parameters section, you can add as many additional parameters as you want to pass to the endpoint to receive the expected response.
To add a parameter, click on add a parameter to add the following basic parameters in the Query String which will recreate the HTTP request URL:

Api-version, it comes from the URL generated before by Power Automate.

Sp, it comes from the URL generated by Power Automate.

Sv, it comes from the URL generated by Power Automate.

Sig, it comes from the URL generated by Power Automate.

Additionally, you can also configure other optional parameters to be sent to the cloud flow. These are the parameters which will allow us to create a customized message and mailing list. These parameters are generated by a layout definition that will be included in the request body.
To do so, proceed as follows:

1. Click the “ADD LAYOUT” button to open the Layout editor. The Layout editor works exactly like the one implemented for the "Export Dataset" step and has the same constraints.
2. Configure a Layout to define the data that will be sent.
3. Replace the placeholder in the "Parameter name" column with a custom name. The "parameter name" value is required and must be unique within the table. “Parameter names” must be in sync with what was defined in the JSON Schema in Power Automate, this is necessary to be able to pass the parameters from the Board procedure to the MS Teams Cloud flow.

Once the Layout query is defined, an edit layout button will appear in the table.

In our example, the parameters section looks like the following:

If we take the “audit” parameter (corresponding to the “audit” variable in Power Automate), we can see that it is generated through a layout with 1 entity by row and 2 blocks. See the example below:

Of course, the most important parameter in this list is 'email', which is what will allow us to send notifications to different users, depending on the configuration of the workflow. However, even this information is generated through a layout using a cube containing the email addresses to be used and structured by the entities relevant to the workflow.

The image below shows the configuration in our example, where we have a cube “Emails for notifications” which contains all the email addresses for each line: