Integrate PDQ with Jira

Install the free PDQ app for Jira Cloud to view linked devices, deploy packages, and start remote desktop sessions — all without leaving a Jira issue. The integration automatically surfaces devices that belong to the issue reporter, giving your support team instant context about the end user's machine.

How it works

When you open a Jira issue, the PDQ app reads the reporter's email address and looks it up across all of your configured PDQ tenants. Any device whose email custom field matches is displayed directly on the issue, so your team can act on it immediately.

The matching flow works like this:

1. A user opens a Jira issue.
2. The app reads the reporter's email address from the issue. (If no reporter is set, it falls back to the issue creator's email.)
3. The app queries every configured PDQ tenant for devices where the designated email custom field matches that address (the comparison is case-insensitive).
4. All matching devices are displayed in the PDQ panels on the issue.

Once devices are matched, you can take action directly from the issue:

• View device details — hostname, OS version, online/offline status, and custom fields are shown at a glance.
• Deploy a package — select any package from your PDQ library and deploy it to the device.
• Open the device in PDQ — jump to the full device details page with one click.
• Launch a remote desktop session — start a Remote Desktop connection to the device through PDQ.

The app adds two panels to each Jira issue: an Issue Panel (above the Activity section) and a Sidebar Panel (in the right-hand context area, always visible as you scroll). Both panels display the same linked device information. Jira admins can enable or disable the sidebar panel from the configuration page — see Admin settings below.

The integration supports multiple PDQ tenants, so organizations managing several environments can surface devices from all of them in a single Jira instance.

Before you begin

Make sure you have the following before starting:

You will also need a PDQ API key and a custom field on your devices populated with user email addresses — we will walk you through creating both in Steps 1 and 2 below.

Step 1 — Create a custom field in PDQ

Where you are: PDQ

The integration uses a custom field on each device to determine which user a device belongs to. If you have already created and populated a custom field with user email addresses, you can skip ahead to Step 2.

1. In PDQ, navigate to More → Custom Fields in the left navigation.
2. Click Add Custom Field.
3. Name the field something recognizable, such as emailAddress or Email.
4. For each device, populate this field with the email address of the device's primary user.
   • You can do this manually per device, or use the Import Values feature to bulk-update many devices at once from a CSV file.

Tip: The field name matching is case-insensitive (e.g., emailAddress and EmailAddress will both work), but we recommend noting the exact name you chose for consistency when configuring the integration in Step 4.

For more details, see Working with Custom Fields.

Step 2 — Generate a PDQ API key

Where you are: PDQ

1. In PDQ, click the gear icon in the lower-left corner to open Settings.
2. Navigate to the API Keys section.
3. Click Create API Key and give it a descriptive name (e.g., "Jira Integration").
   

4. Copy the API key and store it securely. You will not be able to view it again after leaving this page.

   

Don't see the API Keys section? Your PDQ role may not have API key management permissions. Contact your PDQ admin to enable this in your role's RBAC settings.

Important: If you ever suspect an API key has been compromised, revoke it immediately from the same Settings page and generate a new one.

For more information, see PDQ API.

Step 3 — Install the app in Jira

Where you are: Jira Cloud

1. In your Jira Cloud instance, navigate to Apps → Explore more apps (or visit the Atlassian Marketplace).
2. Search for PDQ.

3. Click Install and follow the prompts to add the app to your Jira site.

   

Once the app is installed, a new PDQ Configuration page becomes available in your Jira admin settings.

Step 4 — Configure the integration

Where you are: Jira Cloud — Admin

1. In Jira, navigate to Jira Admin → Apps → Manage apps → PDQ Configuration.
   
2. You will see a tenant configuration form. Fill in the following fields:

3. Click Test Connection to verify that Jira can communicate with your PDQ tenant.

   

   Successful connection displays this information:

   

   Failed connection displays this information:

   

4. Click Save Configuration.

   

    

Adding multiple tenants

If your organization manages multiple PDQ tenants, click Add Tenant and repeat the configuration for each one. The integration will query all configured tenants and display matching devices from each.

Admin settings

The configuration page also includes the following settings:

• Restrict to specific spaces — controls which Jira spaces display the PDQ panels. When enabled, a searchable list of all spaces in your Jira instance appears. Toggle on only the spaces where you want PDQ to be visible (e.g., your IT Service Desk space). When disabled, PDQ appears on all spaces — this is the default behavior.
  
• Sidebar Panel — controls whether the PDQ panel appears in the right-hand sidebar of issues (in addition to the main panel above Activity). This is enabled by default.
• Debug Mode — enables detailed console logging for troubleshooting. When turned on, diagnostic information will appear in the browser console and Forge tunnel output. Keep this disabled during normal use.
  

Step 5 — Verify the integration

Where you are: Jira Cloud

1. Open any Jira issue where the reporter has an email address that matches a device's custom field in PDQ.
2. Look for the PDQ panel in the issue sidebar (right side) and above the Activity section.

3. You should see the matching device(s) listed with their hostname, OS, and status.

   

If no devices appear, see the Troubleshooting section below.

Using the integration

Viewing device information

When you open a Jira issue, the PDQ panel automatically looks up the reporter's email address across all configured tenants and displays any matching devices. Device cards show key information at a glance, including hostname, operating system, and online/offline status.

If the issue has no reporter, the app falls back to the issue creator's email address. If neither is available, no devices will be matched.

Deploying a package

1. In the PDQ panel, click Deploy package on the device you want to target.
2. The deployment view shows a “Deploy to” section with the target device. If you have multiple devices, you can switch devices using the dropdown.

3. Use the Search packages field to find and select a package from your PDQ library.

   

4. Click Deploy to initiate the deployment.
   

5. A confirmation message will appear. You can track the deployment's progress in PDQ.

   

The deployment view also provides quick access to Device details and Remote access buttons for the selected device.

Opening a device in PDQ

Click the device name or the View Device Details link to jump directly to the full device details page in PDQ.

Starting a remote desktop session

Click Remote Access to launch a remote desktop session to the device through PDQ's built-in Remote Desktop feature.

Troubleshooting

The PDQ panel does not appear on issues

• Confirm the app is installed by going to Jira Admin → Apps → Manage apps and checking that PDQ is listed and enabled.
• Make sure you have completed the configuration in Step 4 and saved at least one tenant.
• If only the sidebar panel is missing, check that the Sidebar Panel toggle is enabled in the admin configuration page.
• If a Jira admin has enabled Restrict to specific spaces on the PDQ Configuration page, ensure the current space is toggled on in the list. PDQ will not appear on spaces that are not enabled.
• Try refreshing the Jira issue page.
  

No devices found for an issue

• Verify that the issue has a reporter assigned and that the reporter's email address is visible in their Jira profile. If no reporter is set, the app falls back to the issue creator's email.
• Check that the custom field name in the integration configuration is spelled correctly and matches the custom field name in PDQ.
• Confirm that the device(s) in PDQ have the custom field populated with the reporter's email address.
• Ensure the API key is valid and has not been revoked.
• Try enabling Debug Mode in the admin configuration page and check the browser console for more detailed error information.

"No PDQ tenants configured" error

Navigate to Jira Admin → Apps → Manage apps → PDQ Configuration and verify at least one tenant is configured and saved.

Package deployment fails

• Verify the API key has sufficient permissions for deployments.
• Check that the target device is online in PDQ.
• Review the deployment logs in PDQ for detailed error information.

Test Connection fails during configuration

• Double-check the Organization URL format. It should look like app.pdq.com/your-org-name/devices.
• Confirm the API key is correct and has not expired or been revoked.
• Ensure your network allows outbound HTTPS connections to *.pdq.com.

Cannot access the PDQ Configuration admin page

If you are a Jira administrator but receive an “Admin access required” error when navigating to Jira Admin → Apps → Manage apps → PDQ Configuration, your account may not have been recognized as an admin.

This was a known issue in versions prior to v6.3.0 affecting users whose admin rights came through certain Jira Cloud groups (such as org-admins) rather than via a direct Jira administrator role. Starting in v6.3.0, the integration uses Jira’s native ADMINISTER permission check, which correctly identifies all Jira administrators regardless of which group grants them that role.

To resolve:

• Update the PDQ app to v6.3.0 or later. In older versions, the integration relied on a fixed list of admin group names (site-admins, org-admins, jira-administrators, system-administrators) which may not have matched your Jira configuration.
• If you are on an older version and cannot update immediately, ask a user who is a member of one of the groups listed above to perform the configuration on your behalf.
• If the issue persists after updating, ensure your Jira account has the Administer Jira global permission assigned (directly or via a group) in Jira Admin → System → Global permissions.

Security and privacy

The PDQ app requests only the minimum permissions necessary to function. Here is what the app can and cannot do:

What the app can read:

• Issue details (summary, reporter) to identify the end user.
• User profile information and email addresses for device matching.

What the app cannot do:

• It cannot create, edit, or delete any Jira issues, comments, or other data.
• It cannot access any Jira data outside of the issues you view.

How your data is stored:

• Your PDQ API key is stored using encrypted secret storage provided by the Atlassian platform. It is never exposed in logs or visible to non-admin users.
• The app stores tenant configuration (organization URL, match field name) in Atlassian's app storage. No Jira user data is stored outside the Atlassian platform.

Technical details — Jira permission scopes:

Known limitations

• Jira Cloud only. The integration is not compatible with Jira Data Center or Jira Server.
• API rate limits. The PDQ API allows 300 requests per 2 minutes per organization. For very large device inventories, the initial load on an issue may take a few extra seconds while the integration paginates through your full device list. There is no limit on the number of devices or packages supported.
• One user per device. The integration matches devices based on a single email custom field per device. If a device is shared by multiple users, only the email in the custom field will be matched.

FAQ

Is the Jira integration free? Yes. The PDQ Jira app is free to install and use from the Atlassian Marketplace. However, you need a PDQ Premium plan to generate the API keys required for the integration.

Can I use this with multiple PDQ organizations? Yes. The integration supports multi-tenant configuration. Click Add Tenant on the configuration page and add as many PDQ tenants as you need. Devices from all tenants will appear together on each issue.

How does device matching work? The app reads the Jira issue reporter's email address and compares it (case-insensitive) against the custom field you specified during configuration on every device across all configured tenants. All matching devices are displayed. If no reporter is set, it falls back to the issue creator's email.

What if a reporter has multiple devices? All devices that match the reporter's email will be displayed. You can select which device to deploy to or connect to from a dropdown in the panel.

Can I limit PDQ to specific Jira spaces? Yes. On the PDQ Configuration page, enable Restrict to specific spaces. A searchable list of all spaces in your instance will appear — toggle on the ones you want. PDQ will only be visible on enabled spaces. If you leave this setting disabled, PDQ appears everywhere (the default).

Can I change the custom field used for matching? Yes. Navigate to the admin configuration page in Jira (Jira Admin → Apps → Manage apps → PDQ Configuration) and update the Email Match Field ID for the relevant tenant.

I see "Admin access required" errors on the configuration page. Only Jira administrators can access the PDQ Configuration page. Your account must have the Administer Jira global permission, which you can check in Jira Admin → System → Global permissions. See the Cannot access the PDQ Configuration admin page troubleshooting section above for more details.

Related articles

• PDQ API
• Working with Custom Fields
• Integrate with Freshdesk (Freshworks)