Microsoft Teams Integration
Overview
Section titled “Overview”Orvanta enables bidirectional interaction with Microsoft Teams through two primary approaches: triggering Orvanta scripts from Teams commands and executing Teams actions from Orvanta workflows.
Action on Orvanta from Microsoft Teams
Section titled “Action on Orvanta from Microsoft Teams”Setup requirements
Section titled “Setup requirements”Workspace administrators must navigate to the Workspace Settings page and select the “Slack / Teams” tab, then click “Connect to Microsoft Teams.” For self-hosted instances, OAuth configuration is required as documented in the setup OAuth guide.
Command handler implementation
Section titled “Command handler implementation”Once connected, users can either designate an existing script or create a new one to handle the /orvanta command. The system provides a template script that receives these parameters:
activity_id: The Teams conversation activity identifiercommand: The triggered command textfrom_name: Username of the command initiatorteam_id: Microsoft Teams Team identifierteams_message: Original payload from Teams backend
Permission management
Section titled “Permission management”Resources and variables must be shared with the automatically-created teams group to be accessible to Teams commands. This can be accomplished by:
- Directly sharing individual resources/variables to the group
- Hosting them in folders associated with the
teamsgroup
Advanced command handling
Section titled “Advanced command handling”Multiple commands can be managed using flows with branches, text parsers, and approval steps to implement complex command logic with human-in-the-loop workflows.
Monitoring and auditing
Section titled “Monitoring and auditing”Command executions appear on the Runs page, with permissions managed through the g/teams global group. The from_name parameter identifies which user triggered the command; the teams_message parameter provides additional Teams-specific metadata.
Approval steps integration
Section titled “Approval steps integration”Two approval types are supported:
Interactive approval: Teams members approve/reject directly within Teams without accessing the Orvanta UI. Forms defined on approval steps display as modals in Teams messages.
Basic approval: Simple links that open Orvanta’s approval interface in a browser.
The TypeScript client exposes helper functions for requesting interactive or basic approvals, with support for dynamic enums and default arguments.
Action on Teams from Orvanta
Section titled “Action on Teams from Orvanta”Resource configuration
Section titled “Resource configuration”Create a ms_teams_webhook resource type with a webhook URL (per Microsoft’s documentation on incoming webhooks). Scripts can then utilize this resource to post messages to Teams channels using the IncomingWebhook library.
Error handlers and alerts
Section titled “Error handlers and alerts”Orvanta integrates with Teams for error notifications and critical alerts. Critical alerts are triggered by:
- Job re-runs after crashes
- License key renewal failures
- Workspace error handler failures
- Worker group falling below specified thresholds
- Jobs queued beyond defined timeout thresholds
Critical alerts require SMTP configuration and Teams connection in instance settings (Enterprise Edition feature).
Troubleshooting
Section titled “Troubleshooting””Bot not in conversation roster” error
Section titled “”Bot not in conversation roster” error”Common causes include channel moderation restrictions, missing bot installation, or bot ID mismatches. Resolution involves checking Teams channel moderation settings, verifying bot installation in the team, and validating Azure AD configuration.
Message delivery issues
Section titled “Message delivery issues”If messages fail to deliver, verify the service URL region matches your Teams tenant location:
- Americas:
https://smba.trafficmanager.net/amer/(default) - EMEA:
https://smba.trafficmanager.net/emea/ - APAC:
https://smba.trafficmanager.net/apac/ - US Government:
https://smba.infra.gcc.teams.microsoft.com/
Set the TEAMS_SERVICE_URL environment variable if needed.