This guide offers detailed instructions for creating and configuring a custom MS Teams application. It is for IT and HR administrators to integrate the custom Teams application with their organization's workspace.
Prerequisites
- Microsoft 365 Account: You must have an active Microsoft 365 account and be a member of a Microsoft Teams workspace.
- Open Microsoft Teams: Log in to your Microsoft Teams account.
- User Role: You need permission to install apps in your Teams workspace. Certain apps might require Teams or IT admin approval if you're not an admin.
- App Approval: Some organizations require apps to be approved by an administrator before you can install them.
- Azure Subscription: You need access to the Azure portal to create and configure the bot for the Teams application.
- AI Assistant Setup: The AI assistant feature should be enabled in your HR platform to allow interaction with Teams bots.
Procedures
Step 1: Create a Bot in the Azure Portal
- Go to the Azure Portal and sign in with your Microsoft credentials.
- Search for "Azure Bot Services" and select Create.
- Select your subscription, create a new resource group, and provide a unique name for your bot.
- Choose the Bot Channels Registration option and select Create.
- After creating the bot, navigate to the bot's Configuration settings.
- Set the Messaging Endpoint to the URL provided by the application, for example, https://company-com.applaudcloud.com/teams/events.
- In your bot's Settings tab, retrieve the Microsoft App ID and App Secret. You will use these credentials later in the Teams Developer Portal to connect the bot with Teams.
Step 2: Resource Configuration
- After completing the deployment, navigate to the Deployment details screen.
- Select Go to resource to open the resource associated with the deployment.
- In the resource screen, from the left-hand navigation panel, select Configuration.
- Under the Configuration tab, locate the Webhook URL and copy it.
- Open the Azure Portal, go to the Configurations module, and paste the copied Webhook URL under the Messaging endpoint field.
- Select Apply to save the changes.
Step 3: Configure App ID and Password
If you have selected App Type as MultiTenant for your app, follow these steps:
Create a New Client Secret
- Select the Configurations tab and select the Manage Password option next to the Microsoft App ID field. You will be directed to the Certificates and Secrets section.
- On the Certificates & Secrets page, select + New client secret, provide the required details, and select Add to create a new client secret.
- Copy the Value of the newly created client secret.
Configure App ID and Password
- Return to the Configurations tab in the resource.
- Paste the copied client secret Value into the App Password field.
- Close the Certificates and Secrets section using the breadcrumbs to return to the Configuration section.
- Note the Microsoft App ID and provide it in the Configuration tab.
Step 4: Create a Microsoft Teams App
- Go to the Teams Developer Portal and sign in using your Microsoft credentials.
- Select Create a new app and provide the app name and other details.
- Select the Teams workspace where you want to install the app.
- Select the Channels section from the menu and select the "MS Teams" channel listed under the Available Channels.
- You will be redirected to the Channel information page. Review the information and select Save to complete the channel setup.
- Define the app's permissions by selecting the APIs the app needs to access, such as chat, user profiles, or channels.
Step 5: Provide App Credentials to Application
- In the Teams Developer Portal, go to Settings > App Credentials and retrieve your Client ID, Client Secret, App ID, and Bot credentials(from Azure).
- Connect to the application by inputting these credentials into your HR platform so the Teams app can communicate with the platform.
Step 6: Configure branding
- Under Basic Information, navigate to Branding and choose branding elements.
- Add your app's name, short description, app icon, background color, and a longer description that will appear on your app's detail page in Teams.
Step 7: Publish Bot in Teams
- Log in to your Microsoft Teams account using admin credentials.
- In the left navigation bar, select the Ellipsis [...] and select the Developer Portal icon to open the App builder.
- In the Developer Portal, select the Apps tab and New App to create a new Teams app.
- Once your app is created, associate your Azure bot with the Teams app by entering the Request URL, for example, https://company-com.applaudcloud.com/teams/events, which Teams will use to communicate with the application. The Application platform generates this URL.
- Select Publish and choose the Publish to your org option in the dialog box.
- Assign the necessary permissions to your MS Teams app to control user access and functionality.
- Your bot is now ready to be discovered and used by users in your organization.
- Select Publish your App and complete the publishing process.
Step 8: Configure OAuth & Permissions
- Navigate to OAuth & Permissions under the app dashboard, and select OAuth 2.0 settings.
- Define OAuth Scopes by adding the necessary OAuth Scopes for your application, for example, User. Read, TeamsActivity.Send, Channel.ReadBasic.All.
- Input the redirect URL provided by the application, for example, https://company-com.applaudcloud.com/oauth/callback.
Step 9: Configure Teams App Capabilities
- Configure your app's capabilities, such as tabs, messaging extensions, or task modules, based on your custom requirements.
- Turn on Event Subscriptions and provide a Request URL for event notifications, for example, https://company-com.applaudcloud.com/teams/events.
Step 10: Connect the App to the Application
- After installing the app, go to the app's Settings in Teams and enter the Application instance URL to link the application.
- Once connected, verify the integration by performing basic queries or actions.
Step 11: Connect Individual User Accounts
- Each team member must authenticate their user account with credentials to connect to the application.
- Ensure the app responds correctly to all users by performing critical HR-related tasks.
Step 12: Distribute the Application
- In the Developer Portal, navigate to Manage Distribution to make the app available to other Teams workspaces.
- Optionally, share the app as a public installation link.
Additional instructions (If Needed)
Disconnect user account
- In the Teams sidebar, select Apps or locate the Custom AskHR app you have installed. Navigate to the Home tab within the app's interface. Look for a Disconnect your Account option on the app's Home tab. This option allows individual users to unlink their accounts from the Application platform.
- Select Disconnect Account and confirm the disconnection when prompted, which will log you out and sever the link between your user account and the Application platform.
Connect to a different application
- After disconnection, you'll be prompted to connect to a new application.
- Enter the URL of the new application or platform you want to connect to, for example, https://new-company-com.applaudcloud.com.
- After entering the new application URL, you'll be redirected to log in with your user credentials to connect to the application on the new platform.
Uninstallation
- Depending on your Teams version, select About or Settings for the app to open its configuration details.
- Scroll down and look for the Uninstall option.
- Select Uninstall and confirm the action when prompted. This will remove the app from your Teams workspace.
- Notify other team members. If your team members have been using the app, you should notify them that the custom AskHR app has been uninstalled.
If you manage multiple Teams environments, install the app at the organizational level to make it available across different teams.
- Only the admin who installed the custom app can modify the connection URL or platform instance.
- If the Disconnect Application option is used, all users will be logged out and need to reconnect individually once a new connection is established.
- Publishing the app for public Distribution does not automatically add it to the Microsoft Teams App Store. You'll need to submit it separately for approval.