Customer portal app
Embed the Jira Service Management customer portal in Microsoft Teams and let your customers quickly raise new requests without leaving Microsoft Teams.
Configuration
Jira Cloud
To get started, you’ll need to configure the customer portal app first.
You can add several customer portals!
In Jira go to “Settings” → “Apps” → “Microsoft Teams for Jira”/”Teams settings” → “Customer portal” → “Create new portal app”
In this area, you’ll be able to do a few settings like:
setting the name of the app
setting the icon of the app
Then you only need to choose which service desks you want to access in Microsoft Teams.
When you are done, click “Save & Download” to generate the app (.zip-file) and retrieve it by clicking “Download app” in the next step.
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 the browser.
To learn more about the app compatibility mode, please see the limitation section: App compatibility mode
Create customer users on demand
In case you do not 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 do not 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
Native portal look and feel
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. As this uses preview/private Atlassian functionality, it’s turned off by default.
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.
Jira Server & Data Center
To get started, you’ll need to configure the customer portal app first.
In Jira go to “Settings” → “Apps” → “Microsoft Teams for Jira” → “Customer portal”.
In this area, you’ll be able to do a few settings like:
setting the name of the app
setting the icon of the app
When you are done, click “Download app” to generate the app (.zip-file).
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.
💻 Local installation
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.
To upload the app, go to the apps section in Microsoft Teams and select “Upload a custom app”. Then choose “Upload for me or my teams”.
You will be prompted to select a file, please 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.
📢 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)
You can make the app available for all your users, so they can install it manually from the apps section of Microsoft Teams. It will show prominently and even have an own section.
To add the app to be available like this, you have two options:
A. Add the app from Microsoft Teams
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.
B. Add the app from the Microsoft Teams admin portal
You have also the possibility to achieve the same outcome, by visiting the Microsoft Teams admin portal, using the following URL:
https://admin.teams.microsoft.com/policies/manage-appsOn this page, you also have the option to upload a custom app.
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.
For this purpose, please upload the app first, using the steps in the previous section. Then, visit the Teams admin portal policy section.
https://admin.teams.microsoft.com/policies/app-setupOn this page, you can either create a new policy (e.g. for a subset of users), or you can use the existing “Global (Org-wide default)”-policy. On the edit-page for the policy, you have the option to add the app. Make sure to search for the title you choose during the configuration in Jira.
For even greater visibility, you can also immediately 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!