Customer portal app
Embed your Jira Service Management customer portal in Microsoft Teams and let your customers quickly raise new requests without leaving Microsoft Teams.
Configuration Jira Cloud
Good to know: You can add several customer portals! We recommend to use multiple portals in one app in case you want customers to see all service project portals at a glance.
Tip: If you have dedicated service desks for a specific user group, we recommend using individual customer portal apps per service desk.
Jira admin settings
Go to “Apps” → “Microsoft Teams for Jira” → ”Teams settings” → “Customer portal” tab.
Click on “Create new portal app”.
Create customer portal
Enter a name for your app shown in Microsoft Teams
Decide on an icon
Select your service desks accessible in Teams
Choose a banner which is shown in the background for a more attractive look.
Set and done
Decide on specific options* for your customer portal app.
When you’re done click “Save & download” to generate the app (.zip file).
Retrieve the file by clicking on “Download app” in the next step.
Options & explanations
1. Custom app compatibility mode
In case you are using apps that rely on a custom UI in the portal, e.g. Forms, turn on this option to open the final step (creating the request) in a browser pop-up window in Teams.
To learn more about the app compatibility mode, please see the limitation section: App compatibility mode.
2. Create customer users on demand
In case you don’t sync all your customer users automatically from Microsoft Azure AD, there might be cases where a Teams user does not have a customer user yet.
By default, we will create a new customer user on demand, the first time a user accesses the portal from Microsoft Teams. In case you don’t want this, turn this option off.
Please note: In this case, the user will see an error message in Teams.
Related: Customer single sign on
3. Collect CSAT
(=Customer Satisfaction Score)
This option can only be used when chat notifications are available and set for the respective service desk in your Teams settings (mandatory).
By toggling this option on, you will be able to collect feedback after a request has been (successfully) solved.
4. Disable ‘shared with’ field
Toggling this option on, it will hide the ‘shared with’ field from your create request screen. However, it will be displayed when opening up existing requests under ‘my requests’.
5. Disable knowledge base article suggestions
Whenever a new request is raised, our app automatically refers to your knowledge base articles to provide a possible solution to their current problem. Probably the ticket won’t be raised in the first place as the user maybe has found an adequate solution in an article.
However, if you prefer to not see any knowledge base article suggestions in your customer portal, you can activate this option.
6. Native portal look and feel
As this uses preview/private Atlassian functionality, it’s turned off by default.
In case your users expect the portal to look more similar to the original web-based portal (e.g. portal icons, description texts & announcement banners), you can use this option to configure it.
After enabling it, you’ll need to create a new API key, so we can sync the customizations from the web portal. We recommend creating a service user with access to the portal (e.g. portal-customization@yourcompany.com) and create the API token using this user.
Teams chat notifications
Jira Service Management chat notifications via bot: When creating a new Microsoft Teams chat in a JSM ticket, you can choose to post updates via the JSM bot about the request as an adaptive card into the chat (including CSAT collection).
Prerequisites
The customer portal app needs to be installed first in Microsoft Teams. Just then you can enable notifications (see below “set up”).
Our notifications bot can only be used for JSM projects. We’re currently working on making it available for all Jira projects.
Check out these links before moving on:
Please refer to the “Distributed / company-wide installation” section on this page
Local installations (“sideloading”) will not work for testing the chat notifications feature. The app must be available via your organizations app catalog.
Set-up
The bot can currently only be installed into one customer portal in Teams.
When installing the bot into one of your customer portals, it sends requests updates into the respective MS Teams chat keeping the reporter in the loop about their ticket. The bot sends information any time there are changes made to the ticket (e.g. chats started, meetings scheduled etc.).
The bot only works for customer facing chats where the reporter is part of the chat.
See below and check out the steps to take for enabling notifications for your Teams app.
Enable notifications
Choose a service desk in your customer portal section. Click on “enable notifications”.
📌 The bot can currently only be installed for one of your customer portals.
Link approval
If you’re a Microsoft 365 admin you can now approve the following link.
If not, send the link to your admin for approval.
Enable/disable
If there is “disable notifications” banner showing up in your service desk overview, your Microsoft 365 admin has given consent to the link (above).
🚀 The bot is now active.
Jira issue view / chat
Now when creating a Teams chat in a JSM project, you can now select to post request updates into the chat.
📌 We’re working on allowing the function for all Jira projects!
Bot notifications in Teams
Request updates include: customer facing status changes, comments, approvals and resolution of the request (+ CSAT collection).
Approvals and resolutions will be posted as an adaptive card, which enables user interactions.
Customer Portal tabs in Teams
Open “My requests” → choose your current one.
The card you’re seeing provides all necessary contextual information - even “related chats” (bot) are included and available for both agents and customer.
Jira Server & Data Center
Jira admin settings
Go to “Apps” → “Microsoft Teams for Jira” → “Customer portal”.
Create customer portal
Enter a name for your app shown in Microsoft Teams
Decide on an icon
Select your service desks accessible in Teams
When you’re done click “Download app” to generate the app (.zip file).
Retrieve the file by clicking on “Download app” in the next step.
Deployment / Rollout
To deploy the app (.zip-file) you just downloaded from the configuration page (see above), you have different options.
It’s recommended to test the app for yourself first by using a local installation.
Option 1: Local installation
The app needs to be configured in Jira first. Follow steps for Jira Cloud or Jira Server!
To test the app locally, you can upload it directly from Microsoft Teams. It may be possible that your company has disabled installing apps, so you may need the help of a Microsoft 365 administrator in your company.
Upload app in Teams
Go to the apps section in Microsoft Teams
Open “Manage your apps”
Select “Upload an app”.
Then choose “Upload a custom app” (see below)
Upload custom app
You will be prompted to select a file.
Choose the zip-file you downloaded during the configuration in Jira.
🚀 That’s it! You can now log in with your Jira account and raise new service requests.
Option 2: Distributed / company-wide installation
If you finished testing and want to provide the app to your end-users, you have different options to do this. Usually, you’ll need the help of a Microsoft Teams administrator to use the following distribution options.
In case you want to learn more about general concepts of apps in Microsoft Teams, we recommend reading the official documentation.
If you are a Microsoft Teams administrator, but not an active Teams user, the app icon might not display correctly.
1. Via Microsoft Teams company-wide app (manual)
All user access
You can make the app available for all your users.
They can install it manually from the apps section of Microsoft Teams.
It will show prominently and even have an own section.
You have 2 options to make the app available (see below).
Option 1: Add the app from MS Teams
MICROSOFT TEAMS ADMIN
If you are a Microsoft Teams administrator, you should have the option to upload a zip-file directly from Teams, so it is available to your users.
Option 2: Add the app from MS Teams admin portal
Visit the Microsoft Teams admin portal, using the following URL: https://admin.teams.microsoft.com/policies/manage-apps
And upload a custom app (.zip file) you’ve downloaded before.
2. Via Microsoft Teams admin policy (automated)
In case you want to make sure that a certain set or all users actually have installed the app by default - e.g. to increase visibility - you can also do this.
Option 1: Add the app from MS Teams
MICROSOFT TEAMS ADMIN
If you are a Microsoft Teams administrator, you should have the option to upload a zip-file directly from Teams, so it is available to your users.
Option 2: Add the app from MS Teams admin portal
Visit the Microsoft Teams admin portal, using the following URL: https://admin.teams.microsoft.com/policies/manage-apps
And upload a custom app (.zip file) you’ve downloaded before.
Visit MS Teams admin center
https://admin.teams.microsoft.com/policies/app-setup
Either create a new policy (e.g. subset of users) or use existing “Global (Org-wide default)-policy.
See background (red mark): Add the app here. Make sure to search for the title you choose during the configuration in Jira.
MS teams admin center
For even greater visibility, you can pin the app to the sidebar of your users, using the “Pinned apps” settings.
Troubleshooting
App not appearing for all or certain users
It may take up to 24 hours for the app to be visible for users in Teams.
As the app is considered a “custom app”, certain restrictions in your Microsoft Teams admin center might apply. Make sure you have allowed custom apps and the app permission policy actually allows custom apps - you are also able to only allow this app in particular, in case you don’t want other custom apps to run.
A good point to start is the Manage apps section in Teams:
https://admin.teams.microsoft.com/policies/manage-appsMore information can be found in the Microsoft docs:
https://docs.microsoft.com/en-us/microsoftteams/app-policies
https://docs.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings
User sees error “customer with email address not found”
See here: Customer user authentication error
Cloud Limitations
There are a few limitations to be aware of, due to the nature of the app. As we cannot just embed the official Jira Service portal in Teams, it’s a custom app that tries to mimic the normal customer portal as closely as possible.
Custom fields
We currently support many custom fields that you can configure to your Jira Service Management portal view. As it’s a manual effort for certain kinds of fields, we do not support all possible fields out of the box. In case the screen to create a new request is missing any crucial fields, please don’t hesitate to get in touch, we’ll try to add the field in an upcoming version.
Third party app compatibility
Another limitation of re-building the functionality is the missing app support. In case you do have custom apps from the Atlassian Marketplace to extend your customer portal (like ProForma forms), unfortunately we can’t show the app in Teams. We are in early evaluation of supporting certain apps, but in the meantime, please use the “Compatibility mode” toggle in the Jira configuration page for a workaround. Instead of opening the form in Teams itself, a click on the request type in the app will then open in the users browser, where they will be able to complete the request.
Customer single-sign-on using email address
As of today, Atlassian does not provide a good way of authenticating / identifying customers externally. To avoid having customer users go trough a weird workaround of a login flow, we decided to start with a simple single-sign-on, based on the users email address. In most cases, this should just work out of the box, e.g. when the users email address in Outlook / Microsoft 365 is the same as in Jira.
However, there might be certain cases (e.g. email aliases, hybrid setups), where the email address does not match. Please see our dedicated troubleshooting article (Customer user authentication error) or reach out to our support!