Microsoft Teams

Before you begin the installation, you might want to check with your Microsoft Teams administrator — they may have set up policies that require the app to be installed by an administrator or that only make it viewable in the Teams app catalog by administrators. If you can't find the xMatters app in the Teams app catalog, the Microsoft Teams documentation has further instructions on how to grant users access to the app.

1. Click the Apps icon in the sidebar to open the Teams app catalog.
2. Type "xMatters" in the search field.
3. Click the xMatters app tile.
4. In the setup dialog, click the Add button to use the xMatters app features.
   • Select Add to a team from the Add button drop-down if you want to use the xMatters bot in a Teams channel. On the next screen, search for the channel where you want to use the app, and click Set up a bot. You can also add the bot to a Teams channel after app installation.

   

When you add the xMatters app in Teams, the configuration is automatically added to xMatters with default settings. To change the name used when sending alerts or the priority of the alert in xMatters, access the configuration by going to the Workflows page in xMatters.

1. Before you can use the xMatters bot in a private chat or a Teams channel, you need to sign in to xMatters with a global connection. To bring up the sign in message, start a private chat with the bot and type signin in the To field.
2. Click Sign in to launch the authorization flow.

   

3. Enter the hostname of your xMatters instance. After you click Continue, you're taken to the regular xMatters login screen.
   • If you're using Single Sign-On with xMatters, log into xMatters in a different tab on your browser before you click Continue. Enter the instance URL in this format: example.xmatters.com to avoid errors.

   

4. If you're already logged into xMatters, it authenticates using the logged-in account's credentials. Otherwise, enter the credentials of the user you want to use to authenticate between Teams and xMatters.
   • The bot will have the same permissions as this user to interact with information in xMatters when you use bot commands in a chat or channel.
   • We recommend using an xMatters account that is unlikely to be deleted (e.g., an admin or support account) to authenticate the connection. The global connection will break if the authenticating account has been deleted.
5. Select the check box to agree to the permissions and click Allow to give the app permission to access information in xMatters and act on behalf of the user you entered above.

   

6. Copy the authorization code that Microsoft Teams displays — you'll need it to confirm the connection with xMatters — then close the dialog.

   

7. Paste the code into the chat and send it.

   

You can now use the xMatters bot in your Teams chats and channels!

If you're not already signed in to xMatters with a personal connection, you will be prompted to sign in when you add or view an incident in Teams.

You can also sign in with a personal connection from the Home tab of the xMatters app.

1. Click Sign in from the Home tab of the xMatters app.
2. After you click Sign in, enter the hostname of your xMatters instance. After you click Continue, you're taken to the regular xMatters login screen.
   • If you're using Single Sign-On with xMatters, log into xMatters in a different tab on your browser before you click Continue. Enter the instance URL in this format: example.xmatters.com to avoid errors.

   

3. If you're already logged into xMatters, it authenticates using the logged-in account's credentials. Otherwise, enter the credentials of the user you want to use to authenticate between Teams and xMatters.
   • The xMatters app will have the same permissions as this user to interact with information in xMatters when you use Teams as a device or initiate and manage incidents from Teams.
4. Select the check box to agree to the permissions and click Allow to give the app permission to access information in xMatters and act on behalf of the user you entered above.

   

You can now use the xMatters bot to register Teams as an xMatters device and initiate incidents from Teams!

Add one of the following commands in a private chat with the xMatters bot (note that you can't invite someone to the chat because it's just between you and the bot). You can also prompt the bot in your Teams channel using @xMatters followed by one of the commands.

• find <group> or lookup <group> Type the name of a group in xMatters (or partial keyword — typing 'adm' finds 'System Admins' and 'Database Admins'). The xMatters bot gives you a list of matching groups. If there are lots of matching groups, use See next and See previous to flip through the results.
  • When you find your group, click it to see who's on call in that group and post that information to the chat or channel.



• on-call <group> or oncall <group>: Type the full name of a group to see who's on call in that group and post that information to the chat or channel (if someone is absent, their replacement is shown or, if there's no replacement, it shows the next person in the escalation). If you use the command in a Teams channel, you can click Invite to invite the on-call members of the group to join the conversation.

In your team channel, prompt the bot using @xMatters and then use the invite command:

1. Enter the invite command.
   • invite <group>, engage <group>, or page <group>: Type the full name of a group to invite the on-call members of the group to join the conversation. You can also click Invite when you look up who's on-call.
   • You can also invite individuals and dynamic teams; however, we recommend inviting groups — unless there's a reason to invite a specific person or dynamic team — so you gain the advantages of automatic escalations, rotations, and temporary absences and replacements.
2. In the modal that opens, enter a message to the invitee so you can let them know why you're inviting them to the conversation.
3. Click Invite.

xMatters alerts the on-call members on their preferred device, where they have two response options (whichever response they choose, xMatters updates the channel with their response and any comments they added):

• Join channel: displays a link that takes them right to the channel (assuming they respond via email, text, or the xMatters mobile app).
• Escalate: For groups, this escalates the notification immediately to the next on-call member in the group.

To see what the bot can do, use @xMatters help in a team or a private chat with the bot.

In a private chat with the bot, you can also use @xMatters with the following commands to check the bot's status and sign in and out:

• status: Displays basic information about the bot: what teams it's added to, what xMatters deployment its connected to, and what workflow (plan) it belongs to.
• signout: Signs the bot out and clears the associated configuration in xMatters. You must be the original sign-in user to sign the bot out. If that's you and you still have trouble with the signout command, you can try the uninstall instructions.
• signin: Signs the bot into xMatters again. See the installation instructions above for details on the sign-in process. You can also use install and connect to accomplish the same thing.

Although you can add the app to a team during installation, you can also add it after the fact.

1. Click the ••• beside the team name and select Manage Team.
2. On the Apps tab, click More Apps.
3. Search for "xMatters" and click the tile for the app.
4. From the Open drop-down, select Add to a team.
   • The team and channel is already selected; you can change this if needed.
5. Click Set up a bot.

You're ready to use the bot in this conversation.

Sign out of global connection

Because we've made installing this integration so simple, the process to remove it is a little different.

There are a couple of ways to disconnect the bot from xMatters. In either case, you need to be the original user who signed the bot into xMatters.

The easiest way is to use the signout command in a private chat with the bot.

If that doesn't work for some reason, you can easily remove the bot from a team by going to Manage Team > Apps, then clicking the trash can beside the bot. To find the teams where the bot is installed, use the status command in a private chat with the bot.

Once you remove the bot from the last team it's in, we delete the configuration in xMatters. If you've converted the built-in integration to a custom workflow, we don't delete it but we add "Deleted YYYY-MM-DD" to the description so you know it's not tied to a team in Microsoft Teams.

Sign out of personal connection

You can also log out of your personal xMatters account using the signout command. The bot will automatically detect if you are signed in with a global or personal connection (or both!) and will let you disconnect depending on your permissions. You also have the option of signing out of your personal connection from the Home tab of the xMatters bot.

The process to initiate an incident in a chat or Teams channel is the same:

1. In your chat or Teams channel, select the xMatters app icon underneath the chat box. You may need to expand the list of messaging extensions to see the app.
2. If you are not yet logged in to your personal xMatters account, you will be prompted to enter your xMatters credentials to sign in.
3. An Initiate Incident dialog box will open up where you will see the different incident submission forms you can use. Select one and click Next.

For a custom incident resolution workflow form to appear as an option in the list, it must be enabled for the mobile app.

4. Type a summary and description for the incident, and select a severity. You also have the option to add xMatters users or groups as notification recipients before you initiate the incident.
   • These populate the incident details. The status defaults to "Open", and the xMatters user you log in as is set as the owner, initiator, and resolver.



5. Provide values for any additional fields in the incident submission form.
6. Click Initiate.
7. Once the incident is created, it will appear in your chat box as a message draft.



8.  You can add additional details before sending it to your chat or Teams channel.



• Once you send the message, you can share the incident card by clicking the ••• at the top right corner of the incident card and selecting Copy. You can then paste the incident card in other chats or Teams channels.

If incident creation is taking longer than usual, you can navigate to the xMatters Incidents page in a different tab.

If you're adding the tab to a meeting, you need to join the meeting first. After that, the instructions for adding the tab to a meeting or chat are the same.

1. Click the + beside the tabs at the top of the meeting.
2. Search for "xMatters", and then click the icon for the bot.
3. Click Add to add it to the meeting, and then click Connect to connect to xMatters.
4. Enter your xMatters hostname (for example, example.xmatters.com) and click Continue (if you're not already logged into xMatters, you'll be asked to do it here).
5. Finally you're asked to let Teams access xMatters — select the check box and click Allow.
   • The bot searches for incidents you have permission to view and displays the results. If there are a lot of results, use the search field to narrow the list.
6. Select an incident and click Save to add a tab to the meeting with incident information (including a link to the incident in xMatters).

Other group members or meeting attendees who click the incident tab will see the Connect button to connect to their xMatters account, so only users with permission to see the incident details in xMatters will see the details in Teams. To see all the incident details, click the Open in xMatters link to open the Incident Console in xMatters.

If someone else on your team added an incident tab to a chat or meeting, you can also view the details as long as you have access to the incident in xMatters.

1. Click the xMatters incident tab at the top of the chat or meeting.
2. Click Connect to connect to xMatters.
3. Enter your xMatters hostname (for example, example.xmatters.com) and click Continue (if you're not already logged into xMatters, you'll be asked to do it here).
4. Finally you're asked to let Teams access xMatters — select the check box and click Allow.

You can update basic incident details from Teams.

1. Click the xMatters incident tab at the top of the group chat or meeting.
2. Click the edit icon beside the value you want to update.
3. Select or type the new value and then click Update Incident.
   • The incident details are also updated in xMatters.

To update additional incident information, click Open in xMatters to open the Incident Console in xMatters.