Micro Focus Content Manager SDK 10.1
Microsoft Teams Integration

Two modes of operation

The Teams integration has two modes of operation, client and server side. It is possible to use the integration in either one or both of these modes. The ServiceAPI and Teams application manifest must be installed irrespective of which mode the integration is to be used in. If only the server side mode is required then follow the directions below to modify the manifest. If only the client side integration is required then EmailLink does not need to be configured.

Edit manifest to remove client side mode

Once the manifest has been either manually created or generated using the script the client side integration with Channels and Chats can be remove by removing the contents of the configurableTabs property and leaving it as an empty array.

"configurableTabs": [ ],

Components

The Teams integration is made up of three components, not all of which need to be configured depending on the level of functionality required. The components are:

  • ServiceAPI,
  • Teams Application manifest, and
  • Email Link (only required for server side filing)

Requirements

The components listed above work together to provide the complete Teams integration. If the only part of the integration required are the client side components then only the ServiceAPI and Teams manifest are required, Email Link is required to support scheduled server side filing of chats, posts and files.

Server side architecture

Check in styles and places

The server side component of the Teams integration is managed using check in styles and check in places. Check in Styles and places have a one to many parent-child relationship, meaning one check in style may have zero or more check in places associated with it. The purpose of the check in style is to encapsulate a collection of properties required to create a record, the purpose of the check in place is to track the connection details and synchronization state for a particular application and user.

For example, there might be one check in style that specifies a record type and default settings required for a particular project or customer. This check in style may have linked to it many check in places for different users, some linked to email folders, some linked to Teams channels and others linked to teams users for filing Teams chats.

Creating the check in style and place for Teams

The usual way to create check in styles and places for the teams server side integration is via the teams client side app. This will allow you to create a check in style, navigate to a channel or user and create a check in place for that channel or user. Check in places may be created via the SDK if there is a need to automate this process, for example if it is undesirable to install the client app in Teams. To create the Check in place:

  1. find the appropriate check in style
  2. use the Microsoft Graph API to get the details of the desired channel or user
  3. create the check in place using CheckinStyle.FindOrCreatePlace

NOTE: The place Id must be structured correctly:

Place type Description Place Id Place id example
ChannelPostsForServerProcessing All posts for a channel. {team-id}/channels/{channel-id} dd8b1122-13f0-41df-923d-a407637b4047/channels/19:3te1ccfc9b6c4390be34f7b69439f57a@thread.tacv2
ChannelDocsForServerProcessing All files for a channel. {team-id}/channels/{channel-id} dd8b1122-13f0-41df-923d-a407637b4047/channels/19:3te1ccfc9b6c4390be34f7b69439f57a@thread.tacv2
TeamsChatForServerProcessing All chats involving this user. users/{id}/chats/getAllMessages users/98e82caf-9073-449d-9284-1bfad890e3d5/chats/getAllMessages
DocsForServerProcessing All files owned by this user. users/{id}/drive/root users/98e82caf-9073-449d-9284-1bfad890e3d5/drive/root

ServiceAPI

The ServiceAPI must be installed and must have a valid HTTPS certificate, any HTTP errors will cause the Teams Integration to fail.

The ServiceAPI performs four functions within the integration:

  • hosts the web application that is used to administer the Teams integration (at /CMServiceAPI/office/index.html?teamsadmin=1),
  • hosts the web application that is embedded in Teams as the posts, chat and files add-ins (at /CMServiceAPI/office/index.html),
  • provides the backend services to which the add-on communicates when reading from or writing to Content Manager, and
  • provides services that act as a proxy between the Add-in and the Microsoft Graph API for reading from and writing to Microsoft Graph API.

Setup Script

The simplest way to configure the Microsoft Teams Integration is to use the setup script, which will create:

  • an Azure App,
  • a manifest for Teams, Office and Outlook integrations, and
  • sample authentication settings for the ServiceAPI hptrim.config.

To use the script:

  1. install the Azure CLI,
  2. download and run the script,
  3. if you wish to use Azure CLI 2.36 then download the old version of the setup script.

More help running this script can be found in the video in this post.

Microsoft protected APIs

The Microsoft Graph API services used to file either all messages in a channel or all chats for a user are protected, this means that they may only used with approval from Microsoft. Prior to submitting this form the Azure App for the Teams integration must be created as the approval is given for a particular App. In the request form an answer to the 'why does your application need to access all messages in the tenant' question might be as simple as 'Our organisation is required for compliance reasons to archive all Teams posts in a corporate Record management system'.

Conversation silent interval

The Teams integration groups user chats into conversations so that each conversation can be stored in a separate Record. To achieve this the integration assumes that a period of silence in a group chat indicates that particular conversation has finished. For example if users A, B and C are chatting in Teams and a period of time elapses with nothing being said the integration will assume that the next thing said is a new conversation and file it in a new Record. When filing chats manually it is possible to choose to file one or more of these contiguous conversations as a single record. To configure how long this silent time should be got to System Options > Email and chat > Wait until the conversation has been silent for the specified time.

Setup instructions

ServiceAPI Authentication Permissions

The ServiceAPI must be configured to use OpenId Connect authentication as described in the authentication section. New permissions must be assigned to the Azure AD Application to support Teams, these are:

  • Delegated:
    • ChannelMessage.Read.All
    • ChannelSettings.Read.All
    • Chat.Read
    • ChatMember.Read
    • email
    • Files.Read
    • Files.Read.All
    • Files.ReadWrite.All
    • GroupMember.Read.All
    • Sites.ReadWrite.All
    • User.Read.All
  • Application:
    • ChannelMessage.Read.All
    • ChannelMember.Read.All
    • ChannelSettings.Read.All
    • Chat.Read.All
    • ChatMember.Read.All
    • Files.Read.All
    • Files.ReadWrite.All
    • TeamSettings.Read.All

To assign these permissions:

  • open the Azure AD Application used for authenticating Teams
  • go to API permissions
  • select 'Add a permission'
  • select Microsoft Graph
  • choose either 'Delegated' or 'Application' permissions
  • find the permission and add it
  • once you have added all the permissions select 'Grant admin consent' to consent to all permissions.

ServiceAPI Authentication Application ID

The Teams integration requires that the Application ID Uri in the Azure AD App include the domain name of your ServiceAPI server, this must be adjusted before installing the office integration manifests. To adjust the Application ID URI:

  1. open the Azure App referenced from your ServiceAPI hptrim.config file,
  2. go the 'Expose an API' page,
  3. edit the Application ID URI field,
  4. by default the Application ID URI will look something like this api://2d89cb2b-3cb7-4c21-807e-029fdbfe74a7,
  5. edit the Application ID URI to include the name of your ServiceAPI server, for example api://myserver.com/2d89cb2b-3cb7-4c21-807e-029fdbfe74a7, then
  6. Once you have modified this you will need to update the appIdURI property (case sensitive) in the ServiceAPI hptrim.config file.

ServiceAPI Authorized Client Applications

The Teams integration relies on single sign on from the Microsoft add-in framework. To allow this to work we need to register our add-in, this is done in the 'Expose an API section of the Azure App created previously. To register your add-in:

  1. Add a Scope
  2. name it access_as_teams_user
  3. fill in the fields with values you think are appropriate, for example:
    • Admin consent display name: CM Teams Tab.
    • Admin consent description: Enable Teams to call the add-in's web APIs with the same rights as the current user.
    • User consent display name: Teams can act as you.
    • User consent description: Enable Teams to call the add-in's web APIs with the same rights that you have.
  4. save the scope
  5. Add two client applications, each time selecting the scope you just added, the Client Id for each of the three are:
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

Teams App Manifest

The manifest's purpose is to notify Microsoft Teams of the presence of your add-in. Manifest files must be customised before upload to your Office 365 Admin. To prepare your manifest:

  • download the sample manifest,
  • generate a new Guid and replace [MANIFESTGUID] with this new Guid,
  • replace [SERVICEAPIURL] with your ServiceAPI Url
  • if you want to include a link to the Content Manager Web Client replace [WEBSITEURLATTR] with "websiteUrl": "{YOUR WEB CLIENT URL]",
  • if you do not wish to include a link to the Content Manger Web client remove [WEBSITEURLATTR],
  • replace [APPCLIENTID] with the client id from the Azure Ad App
  • replace [APPIDURI] with the Application ID URI from the Azure Ad App
  • create a zip file called content-manager-teams.zip which contains:
  • upload the manifest from the Microsoft Teams Admin center

Browser Cookies

It may be that the Teams integration addin does not display after it has been uploaded, if this is the case ensure that all cookie blocking is disabled in your web browser.

Email Link

Email Link serves two purposes in the Teams integration, to:

  1. file all posts and/or files in selected Channels, and
  2. file all chats for selected users.

Email Link should be installed as usual, there must be a Microsoft authentication configuration for your Office 365 domain that is of type OAuth and has Teams selected.