...
This Universal Task requires that Universal Controller property Web Service Default Response Content (uc.web_service.response.content.default) is set to JSON.
...
Name | Location | Description |
|---|---|---|
Universal Templates | User documentation for creating Universal Templates in the Universal Controller user interface. | |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. | |
Credentials | User Documentation for Credentials Details Field Description. | |
Launch a Task | User Documentation for Launching a Task. | |
Force Finish/Cancel | User Documentation for Cancelling a Task. | |
Azure Active Directory | https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app | Register an application with the Microsoft identity platform. |
| Properties | User Documentation for all Universal Controller properties. |
| Panel | |
|---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Overview
Microsoft Teams is a collaboration app that helps teams stay organized and have conversations. This Universal Extension provides the capability to monitor a Microsoft Teams channel for uploaded files and run job(s) and/or workflows accordingly.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
Software Requirements for Universal Agent
Both Windows and Linux agents are supported:
Universal Agent for Windows x64 Version 7.0.0.0 and later with python options installed.
Universal Agent for Linux Version 7.0.0.0 and later with python options installed.
Software Requirements for Universal Controller
Universal Controller Version 7.0.0.0 and later.
This Universal Task requires that Universal Controller property Web Service Default Response Content (uc.web_service.response.content.default) is set to JSON.
Network and Connectivity Requirements
Universal Agent needs to have network connectivity towards the following Microsoft Domains to allow necessary APIs to be called
Azure Active Directory Requirements
An application must be registered in the Azure Active Directory. See official instructions on Quickstart: Register an application with the Microsoft identity platform
Use as "Supported account Types" option "Accounts in this organizational directory only".
When registration finishes an Application (client) ID is generated (required as part of Extension Task configuration).
Configure API permissions.
Assign the following Microsoft Graph API permissions.
...
API / Permissions name
...
Type
...
Description
...
ChannelMessage.Read.All
...
Delegated
...
Read user channel messages
...
User.Read
...
Delegated
...
Sign in and read user profile
...
4. Create a client secret -> Add client secret (client secret is required as part of Extension Task configuration)
Key Features
This Universal Extension provides the following main features:
Support authentication to Microsoft Teams with Oauth2 protocol for Grant Type Resource Owner Password Credentials (aka "Password Credentials").
For a specific Microsoft Teams Channel, periodically poll all the new messages since the last lookup.
For each fetched message having attachments, launch a task in Universal Controller with variables holding the list of attachments' SharePoint URLs, names and a message summary.
Support for up to 5 attached files (any additional files are skipped).
Ability to resume from the last read message on restart.
Different Log levels for the Universal task, with DEBUG level providing more information in case of issues.
Universal task instance must be stopped with Force Finish/Cancel command to avoid leaving a running monitor process.
The scope is to support exchange of files on a dedicated Microsoft Teams channel that will act as service channel.
To share a file, a conversation is created with the file being attached. It is not expected that anyone will react or reply to this message.
Known Issues
This extension is subject to the limitations of MS Graph API.
For more technical details, please refer to Microsoft Graph REST API v1.0 chatMessage: delta
Actions and replies on the channel conversations are not supported.
Only returns channel conversations within the last eight months.
Incremental read of new messages is relying on a delta token from the API. Its value, which is opaque, must be kept in a variable to allow for it to resume between runs. See how to configure the task in the example section below.
Import the Universal Template
To use this downloadable Universal Template, you first must perform the following steps:
- This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
- To import the Universal Template into your Controller, follow the instructions here.
- When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Configure Universal Task
For the new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Template.
Input Fields
The input fields for this Universal Extension are described below.
...
Field
...
Input type
...
Default value
...
Type
...
Description
...
Action
...
Required
...
Monitor Attachments
...
Choice
...
The action performed upon the task execution
...
Client Credentials
...
Required
...
-
...
Credentials
...
The credentials for the application registered in the Azure Active Directory.
They are comprised of:
Application (client) ID
Client secret : The client secret issued to the client during Application registration process
...
Resource Owner Credentials
...
Required
...
-
...
Credentials
...
The user's credentials for Microsoft 365.
They are comprised of:
username
password
...
Channel Identifier
...
Required
...
Channel Link
...
Choice
...
The Type of identifier for the channel.
For example: Channel Link to provide the URL
...
Channel Link
...
Optional
...
-
...
Text
...
The URL link of the required channel.
Required if Channel Identifier is "Channel Link".
...
Interval (seconds)
...
Optional
...
60
...
Integer
...
The Message Polling Interval in seconds.
...
Universal Controller URL
...
Required
...
-
...
Text
...
Universal Controller URL.
For example: http://192.168.88.10:8080/uc
...
Universal Controller Credentials
...
Required
...
-
...
Credentials
...
The Universal Controller Credentials.
The Credentials must have “Web Service Access” Permissions.
...
Launch Task
...
Required
...
-
...
Text
...
The name of the Task to be launched in the Universal Controller.
The task will always be launched with the Task variable {attachment_urls} which contains the SharePoint URLs list of the attachments in JSON format.
...
Offset Token
...
Optional
...
-
...
Large Text
...
Tracker for the last read message from the channel.
It can be set to the previous instance run execution with the output parameter offset_token. By setting it, it allows it to resume from the last read message.
...
Launch Task Variables
The Variables that are passed to the launched task are described below.
...
Parameter
...
Type
...
Description
...
attachment_urls
...
Large Text (JSON)
...
The list of the attachment URLs (as SharePoint URLs), in JSON format.
...
attachment_names
...
Text (JSON)
...
The list of the attachment names (as listed on the message), in JSON format.
...
message_summary
...
Text (JSON)
...
A summary of the message information in JSON format: modified date, sender, message id.
Example: attachment_urls
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"contentUrls": [ "https://uacextensions.sharepoint.com/sites/my_site/Shared%20Documents/General/my_file.txt" ]
} |
Example: attachment_names
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"names": [ "my_file.txt" ]
} |
Example: message_summary
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"lastModifiedDateTime": "2021-09-21T16:09:29.236Z",
"id": "1632240161921",
"from": {
"user": {
"displayName": "John Doe"
}
}
} |
Task Output
Output Fields
The output parameters are set after every message processing. If they are 'preserved on re-run', they prevent a re-run of the task instance from restarting from scratch.
The output fields for this Universal Extension are described below.
...
Field
...
Type
...
Preserved on re-run
...
Description
...
Last Modified Date Time
...
Text
...
True
...
The last modified date time on the last modified message (the maximum value in case of 'Run forever').
...
Offset Token
...
Large Text
...
True
...
Tracker for the last read message from the channel.
...
Outstanding Message
...
Boolean
...
True
...
Shows whether there are more messages to be read from the channel.
...
Launched Task
...
Text
...
True
...
The sysID (32 char) of the last launched task as returned by UAC REST API.
...
Message Count
...
Text
...
False
...
The number of fetched message since the start of the monitoring (task instance).
...
Task Count
...
Text
...
False
...
The number of launched tasks since the start of the monitoring (task instance).
Exit Codes
The exit codes for this Universal Extension are described below.
...
Exit Code
...
Status Classification Code
...
Status Classification Description
...
Status Description
...
2
...
AUTHENTICATION_ERROR
...
Bad Authentication data
...
AUTHENTICATION_ERROR: Incorrect username or password.
...
3
...
AUTHORIZATION_ERROR
...
Insufficient Permissions
...
AUTHORIZATION_ERROR: The authorization credentials provided for the request are invalid.
...
20
...
FOREIGN_API_REQUEST_ERROR
...
Bad request to third party API
...
FOREIGN_API_REQUEST_ERROR: Bad request to Microsoft API.
...
21
...
FOREIGN_API_RESPONSE_ERROR
...
Validation error response from third party API
...
FOREIGN_API_RESPONSE_ERROR: Microsoft API response validation error.
...
22
...
LAUNCH_TASK_EXEC_ERROR
...
Error while launching a Task in UAC REST API
...
LAUNCH_TASK_EXEC_ERROR: Error while launching a task.
Task Examples
Follow the steps below to create a Task.
...
Give the Task a name.
...
Select an active agent of version 7.0.0.0 or higher for the task to run on.
...
Select the action.
...
Set your Client Credentials.
...
Set your Resource Owner Credentials.
...
Set your Universal Controller Credentials.
...
Select the Channel Identifier.
...
Enter the Launch Task name.
...
Enter the Universal Controller URL.
...
Enter the Offset Token from the previous instance execution.
...
Example with the Usage of Offset Token in an Instance Re-run
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
${ops_msteams_monitor_offset_token} |
...
The offset is kept between the task executions and allow to resume from the last read message on that channel.
Document References
This document references the following documents:
...
Name
...
Location
...
Description
...
Universal Templates
...
https://docs.stonebranch.com/confluence/display/UC72x/Universal+Templates
...
User documentation for creating Universal Templates in the Universal Controller user interface.
...
Universal Tasks
...
https://docs.stonebranch.com/confluence/display/UC72x/Universal+Tasks
...
User documentation for creating Universal Tasks in the Universal Controller user interface.
...
Credentials
...
...
User Documentation for Credentials Details Field Description.
...
Launch a Task
...
...
User Documentation for Launching a Task.
...
Force Finish/Cancel
...
...
User Documentation for Cancelling a Task.
...
Azure Active Directory
...
https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
...
Register an application with the Microsoft identity platform.
...
https://docs.stonebranch.com/confluence/display/UC72x/Properties
...
User Documentation for all Universal Controller properties.