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.
Note: Working with Forms in JSM?
With the latest version of Microsoft 365 for Jira, Forms are fully supported in your customer portal app in Microsoft Teams. đ Learn more.
Configuration Jira Cloud
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, 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.
Chat notifications
When creating a new MS Teams chat in a JSM ticket, you can choose to post updates about the request into the issue-related chat incl. CSAT collection (see screenshot above).
Technically, it is our customer portal app which acts like a bot here (e.g. IT Support portal) and thus, âpostsâ updates on the issue in the respective MS Teams chat.
This is how it looks on the Microsoft Teams side (e.g. when an issue is successfully resolved incl. CSAT):
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 also be used to Jira Software/business projects. đ Learn more here.
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 request 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.).
Good to know: Bot notifications are available for both chats with internal and external customers/users.
Enable notifications
(Jira admin settings > Teams settings)
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, 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!