Skip to main content

Connect Jira

MonoPbx connects to your Jira so that call features can use it: the customer's open requests on the call screen, issues created from calls, call notes and worklogs, and click-to-call from an issue. This page covers the connection, the field mapping and the health check. The call features have their own page, Jira and calls.

You need the Jira permission jira:write to connect and jira:read to see the connection. The built-in Owner role has both.

Choose how MonoPbx signs in​

Open Admin, Settings, Integrations, Jira. The page shows only the ways that work on your server.

ModeWorks withHow it signs in
API tokenJira CloudYou enter the Atlassian account e-mail and an API token. MonoPbx keeps both sealed and never shows them again. This always works, with no setup on the server.
Personal access tokenJira Data Center and Jira ServerYou enter the host name and a personal access token from your Jira profile.
Sign in with Atlassian (OAuth 2.0)Jira CloudAn administrator signs in to Atlassian once. MonoPbx keeps the access and refresh tokens sealed with your company's key. Offered only after a system administrator has set up an Atlassian app (see below).

Connect with an API token (Jira Cloud)​

  1. Sign in to Atlassian with the account MonoPbx should act as. Open id.atlassian.com/manage-profile/security/api-tokens.
  2. Select Create API token, give it a name such as "MonoPbx" and copy the token. Atlassian shows it only once.
  3. In MonoPbx, enter your Jira site (for example acme.atlassian.net), the account's e-mail address and the token, then select Connect.
  4. Select Test connection. The status header turns to Healthy when the credentials work, the account can see the project and nothing is missing.

The issues MonoPbx creates and the comments it writes show that account as their author, so a dedicated service account is a good choice.

Connect Jira Data Center or Server (personal access token)​

  1. In Jira, open your profile, then Personal Access Tokens, and create a token.
  2. In MonoPbx, enter the host name (a port is allowed, for example jira.example.com:8443) and the token, then select Connect.
  3. Select Test connection.

MonoPbx reaches Jira from the server, and only over public HTTPS addresses. A self-hosted Jira must therefore be reachable on a public name.

Set up Sign in with Atlassian (system administrators)​

If you see "Sign in with Atlassian is not set up on this server", no Atlassian app is registered yet. You can keep using an API token, or a system administrator can set it up once for the whole installation:

  1. Open developer.atlassian.com/console/myapps and create an OAuth 2.0 integration.
  2. Under Authorization, add the callback URL shown on the Jira page of MonoPbx (it looks like https://<your PBX>/admin/jira). Copy it with the Copy button so it matches exactly.
  3. Under Permissions, add the Jira platform REST API and enable the scopes read:jira-work, write:jira-work and read:jira-user. MonoPbx also asks for offline_access, which Atlassian grants with the sign-in.
  4. Under Settings, copy the Client ID and the Secret.
  5. In MonoPbx, open Admin, Settings, Integrations, Jira with a system-administrator sign-in, find Atlassian app (system administrators) and enter the client id and the secret, then Save. The secret is stored sealed and is never shown again.
  6. Under Distribution, set the app to Sharing if people outside the Atlassian organization that owns the app need to sign in.

After that, every company on the installation sees Sign in with Atlassian on its Jira page. Atlassian rotates the refresh token on every refresh. MonoPbx stores the new one before it uses it. If Atlassian refuses a refresh, the connection shows as revoked until you connect again. Removing the app in MonoPbx turns the sign-in off, and existing OAuth connections cannot refresh their tokens until an app is set again. An installation may also be set up with the environment variables MPBX_JIRA_CLIENT_ID and MPBX_JIRA_CLIENT_SECRET. The console setting wins when both exist.

Disconnecting removes every token and secret from MonoPbx. Atlassian does not offer a way to revoke a sign-in from our side, so also remove the app from your Atlassian account under Connected apps.

If the connection fails​

The page explains every failure in words. The common ones:

You seeWhat it meansWhat to do
Sign in with Atlassian is not set up on this serverNo Atlassian app is registered.Connect with an API token, or ask a system administrator to follow the steps above.
Jira refused the e-mail or tokenThe credentials are wrong or were revoked.Create a new API token and connect again.
The account may not do thisA scope or the project permission is missing.Give the account access to the project in Jira.
Jira cannot be reachedA wrong site name, a network problem or a non-public address.Check the site name. For Data Center, use a public host name.
The sign-in is unknown or expiredThe Atlassian sign-in took longer than ten minutes or was used twice.Start it again.

Map the fields​

Mappings tell MonoPbx which Jira project and issue type to use for new issues, and which Jira field holds each of our values.

Our fieldWhat it holds
customer_phone, customer_emailThe customer's number and e-mail. customer_phone is also the field the lookup by number searches.
caller_number, called_numberThe numbers on the call.
call_id, call_direction, call_duration, recording_urlFacts about the call.
agent, queueThe agent and the queue that took the call.

Each value is a Jira field id such as customfield_10050. Project keys and ids are checked strictly, because they end up in JQL and in Jira's web addresses. Use the field ids from your Jira site, not the field names.

Check the connection​

Select Check connection on the Jira settings page. MonoPbx checks that the credentials work, that the scopes you granted are enough (OAuth only), and that the mapped project exists.

When a check fails, the connection shows as failing or revoked, and your company's administrators get the alert JiraConnectionFailing until a check passes.

Webhook from Jira (optional)​

Turn on the webhook to see Jira changes in MonoPbx as they happen. MonoPbx creates a private address and a secret. Both are shown once, so copy them into Jira at System, WebHooks, for the events issue created and issue updated.

MonoPbx accepts a delivery only when its signature matches the secret, its timestamp is within five minutes, and it has not arrived before. Accepted changes appear as jira.issue_changed events that hold the ids and the names of the changed fields only.

Before you start​

  • Jira Cloud or Data Center. Sign in with Atlassian and the API token need Jira Cloud. Jira Data Center and Server connect with a personal access token.
  • Public HTTPS. Jira must reach the webhook address, and that address must be a public name.
  • A mapped customer field. Without a customer_phone mapping, no customer is found by phone number.