Integrating MS Teams with MS Graph

Applies to version: 2020.1.x and above; author: Tomasz Słuszniak

Introduction

When implementing projects in WEBCON BPS you can facilitate communication between project members via the Team feature in Microsoft Teams. Instead of adding a new Team manually, let WEBCON digital process automation help you!  Adding a new Team can be automated by using the WEBCON BPS when registering a new project workflow – you can also use the Microsoft Graph platform.

Creating a team is divided into two stages:

1. Creating the Office 365 group
2. Creating the team based on the group

To connect WEBCON BPS with Microsoft Graph, create a data source connection for a REST Web Service. Such a configuration was described in this article -> Integration with AAD using REST invoke method and Microsoft Graph (webcon.com)

An example process for managing projects contains several form fields:

1. Project name
2. Project description
3. Project manager
4. Team – Employee and Role

Creating the team

To create the new team, start by creating the Office 365 group. To create this group, use the https://graph.microsoft.com/beta/groups (advanced description of this method can be found at https://docs.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-beta&tabs=http).

At first, configure the action of invoking the REST WebService:

In the action select the connection to the Microsoft Graph.

In the “Request data” tab enter the method address (/beta/groups) and http (POST) method:

Then go to the JSON tab and fill in the data set that will be passed to the Web service.

The group name (“displayName” attribute) should be consistent with the organization policy. Depending on the settings, the group naming may require specific prefix or suffix. For more information see -> https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/groups-naming-policy.

When creating the group without the required prefix, Microsoft Graph will return an error message and propose a name consistent with the policy.

{“error”: {

    “code”: “Request_BadRequest”,

    “message”: “The property is missing a required prefix/suffix per your organization’s Group naming requirements.”,

    “details”: [

      {

        “target”: “displayName”,

        “suggestedPropertyValue”: “Grp_BPS MSGraph Integration“,

        “code”: “MissingPrefixSuffix”

      }

    ]

  }

}

When creating a group, you can also define its members. We will use an item list form field for this, with which we select the employees and their roles. A list of group members sent to Microsoft Graph should look like this:

“members@odata.bind”: [

   “https://graph.microsoft.com/beta/users/t.sluszniak@webcon.pl”,

   “https://graph.microsoft.com/beta/users/t.green@webcon.pl”

To create such a list, we will first pass our data through a technical form field – multiple lines of text.

The action uses the SQL query to merge all records into a list, with entries separated by commas. The final result is in a format that can be used for calling the Microsoft Graph method. Our technical form field prepared in such a way can be passed when creating a group like so:

The last step in the configuration of the action creating the Office 365 group is the configuration of response processing after calling the Web service method. In the “Response” tab, the ID of the created group was mapped to a technical form field. The “Response” tab contains all form fields which will be returned by the Web service after correctly calling it. We are only interested in the ‘id’ field, and the target form field on the side of WEBCON BPS will be our aforementioned technical field called ‘_Group ID’. The group ID will be then used in the next step – creating the team.

Creating the team based on the group

To create the team in Microsoft Teams, another method available in Microsoft Graph has been used – https://graph.microsoft.com/beta/groups/{id}/team (advanced description of this method can be found at -> https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta#example-4-create-a-team-from-group).

Microsoft recommends that when creating the team based on a newly created group, wait about 15 minutes after creating them because there may be delays due to data replication. Otherwise, you may receive a 404 error.

We can easily account for the required delay in WEBCON BPS by using the “On timeout” trigger for our action.

The timeout will execute the action creating the team three times. Each execution will be preceded by a 5-minute interval. The recommended time of 15 minutes stated by Microsoft is the maximum possible delay. Oftentimes, the team can be formed after only 5 minutes have elapsed.

For team creation, we can use the same type of actions as when creating a new group – Calling the REST Web Service. The same connection was used in the action, but the data in the other tabs will change. The first change is the address of the called method:

Set the address “/beta/teams” and the http method to “POST”.

In the “JSON” tab indicate the group for which the team will be created, optionally you can create an additional channel in the team e.g. with a tab displaying the WEBCON BPS project form.

1. A template, based on which the new team will be created. A list of available templates can be found at -> https://docs.microsoft.com/en-us/MicrosoftTeams/get-started-with-teams-templates#what-are-base-template-types.
2. A group, for which the team will be created – in this place the ID saved when creating the Office 365 group was used.
3. The channels – https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta#example-5-create-a-team-from-a-group-with-multiple-channels-installed-apps-and-pinned-tabs.

The final tab is the “Response” tab, but if you want to create a new team there is no need to save their ID because according to the documentation – each team has the same ID as the group for which the team was created (https://docs.microsoft.com/en-us/graph/api/resources/team?view=graph-rest-beta).

We can use the response to limit any unnecessary action executions, e.g. in situations where the team was created during the first execution of the timeout. To avoid repetition, we can save the value from “Location” and map it to some technical form field in the “Destination field” column:

Now that we have passed a value to a technical form field on the first successful execution, we can build a simple execution condition for our action, which will allow it execute only if the aforementioned technical field is empty:

Action In action! 

A simple project was created to demonstrate the integration with Microsoft Graph. All required form fields should be filled in on the project workflow form. Completing the “Team” list allows you to assign all people listed here as members of the group and team.

Once we proceed to the next step, the ‘Timeout’ trigger will begin counting and will execute the action of creating the Office 365 group after 5 minutes (and will try 2 more times after that if necessary).

After creating the team, all members will receive information about adding them to the team in the Microsoft Teams application and by e-mail.

As a result of the action of calling the Microsoft Graph Web service, the team was created in the Microsoft Teams application along with a channel containing the project form to which the team is related.

The integration of the project management process with Microsoft Teams can be additionally extended upon e.g. by informing the team members about data updates in the workflow by sending them an e-mail -> https://docs.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-beta&tabs=http.