Skip to main content
Skip table of contents

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

  1. Enter a name for your app shown in Microsoft Teams

  2. Decide on an icon

  3. Select your service desks accessible in Teams

  4. 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.

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

Features in Jira_Start a chat in Jira_JSM chat notifications.jpg

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:

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

  1. Enter a name for your app shown in Microsoft Teams

  2. Decide on an icon

  3. Select your service desks accessible in Teams

  4. When you’re done click “Download app” to generate the app (.zip file).

  5. 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

  1. Go to the apps section in Microsoft Teams

  2. Open “Manage your apps

  3. Select “Upload an app”.

  4. 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:

CODE
https://admin.teams.microsoft.com/policies/manage-apps

More 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!

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.