The Jira integration connects Xyte's incident management with Jira Service Management (JSM), keeping both systems in sync automatically.

What it does:

• Incident opened in Xyte (unless excluded by Filtering) → a new Jira Service Management request is created automatically, with full incident, device, and location details
• Incident resolved in Xyte → the Jira request is transitioned to the configured close status
• Incident updated in Xyte → when the incident changes, the Jira request's summary (built from your Update summary template, if set) and priority are updated
• Jira request updated → changes to the title, description, or priority in Jira are reflected back in Xyte (requires webhook setup). While an Update summary template is set, summary edits in Jira don't change the incident title.

Authorization requires a site with both Jira and Jira Service Management. Xyte requests the write:jira-work scope at authorization time so it can push incident updates back to Jira. Your Atlassian account must have access to a site that has both Jira and Jira Service Management enabled. If your account only has JSM, Atlassian will respond with Access denied on the consent screen; in that case, ask a workspace admin to enable a Jira product on the site or grant your user access to one.

📘

Share the questionnaire first

Send the Jira questionnaire to your Jira admin before you start. It lists every answer you need to complete this setup yourself.

In the Xyte Organization portal, open Settings → Integrations → Ticketing System and choose Jira. The setup wizard has these steps:

• Authorization — connect your Atlassian account. See Authorizing Access.
• Service Desk — the Jira Service Management project Xyte opens requests in.
• Request types — the Request Type used for new requests.
• Field mapping (optional) — which Jira fields the summary and description land in, and their text when the request is created and updated. See Field Mapping and Ticket text templates.
• Close status — the transition applied when the Xyte incident is resolved.
• Webhook (optional) — sync changes made in Jira back to Xyte. See Webhook Setup.
• Filtering (optional) — report only incidents at or above a chosen priority. See Filtering.
• Enable — turn the integration on.

🚧

Save each step before moving on

Each step has its own save button — Update, Save fields, Save filtering, Activate. The Prev / Next buttons only move between steps and save nothing, so leaving a step without clicking its own button discards what you entered there.

Authorizing Access

1. Click the Authorize access button.

2. You will be redirected to Atlassian's authorization page — log in with a user that has administrative privileges on your Jira instance.

3. Review and approve the requested permissions. Xyte requests the scopes needed to create and manage Service Desk requests and to push incident updates (summary, priority) back to Jira.

   

4. You will be redirected back to Xyte to complete the setup.

   

5. Click Next.

Select Service Desk

1. Select the Service Desk from the list fetched from your Jira account.

   

2. Click Update, then Next.

If your required Service Desk is not listed, verify that there are no limiting permissions on the Jira side, then click the refresh icon button next to Update to have Xyte re-fetch all available options.

Request Types

1. Select the Request Type to use when new incidents are detected.

   

2. Click Update, then Next.

If your required Request Type is not listed, verify that there are no limiting permissions on the Jira side, then click the refresh icon button next to Update to re-fetch all available options.

Field Mapping

Xyte sends two fields when it creates a Jira request:

• Summary — the incident title, or your Summary template if you set one (see Ticket text templates).
• Description — the full incident details, including: incident ID and link, status, priority, organization, device (model, serial, MAC, IP, firmware, last seen, link) and the space path, and more (incident description, assignee, created/closed times, customer, vendor, connection) — or your Description template if you set one.

By default each one goes to the same-named field on the selected Request Type. Use this step to map them to a different field, or choose — Do not send —. A field set to — Do not send — is not sent, whatever its template says.

1. For each Xyte field, pick the Jira field it should land in.
2. Click Save fields, then Next.

The dropdown only lists fields that are on the Request Type's form. Jira rejects any field that isn't on the request form, so Xyte only offers (and only sends) fields the form exposes. If Description is missing from the list, your Jira requests will arrive with the title only.

To fix it:

1. In Jira Service Management, go to Project settings → Request types → (the Request Type Xyte uses) → Request form, and add the Description field to the form. It can be optional, or hidden from the customer portal.
2. In Xyte, go back to the Request Types step and select the Request Type again, so Xyte re-reads the form's fields. If the same type won't save, switch to another one and back. Each pick creates a test request in Jira ("Xyte Integration - Workflow Discovery") that you can delete.
3. In Field Mapping, map Description → Description and click Save fields.

Note: choosing the Request Type again (step 2) resets the Field mapping and the Close status and disables the integration — so select the close status again and re-activate it in the Enable step.

Ticket text templates (optional)

The summary and the description are set on the Field mapping step, below the field map, with one tab per event: Create and Update. Both are optional — leave a field blank and Xyte keeps its built-in behavior (the incident title for the summary; the full structured device/space details for the description).

• Summary — on Create and on Update. The Update template is applied whenever the incident changes, so it can differ from the one used at creation.
• Description — on Create only.

Click Edit next to a field, type any text and insert {key} placeholders from Supported fields, then click Apply and Save fields. Each placeholder is replaced with that incident's value — for example:

{title} - {priority} - {space_name}

How placeholders behave

• A key with no value for that incident renders as nothing, and the rest of the text is kept.
• An unrecognized plain key (a typo, or a Jira macro such as {quote} or {code}) is sent through as written. A placeholder with a filter that can't be applied — e.g. {title|shout} — is rejected when you save. Filters and the full key list: Incident field templates.
• Only letters, digits and underscores are recognized inside the braces: {space_name} works, {space name} is left as plain text.
• The summary is always sent as one line — Jira doesn't accept a multi-line summary, so line breaks (from the template or from a value) are collapsed into single spaces. A summary longer than 255 characters (Jira's limit) is cut at 255 and ends with ....
• To get the default for a field (the incident title, or the structured details), leave its template blank.
• The Create summary is applied when the request is created; the Update summary whenever the incident itself changes (title, description, status, priority, assignee, or closing). Renaming a device or space doesn't refresh it on its own. Updates need the write:jira-work permission, which Xyte requests at authorization.
• The description template is applied only at creation — Xyte never rewrites the description afterwards.
• Templated text still goes through Field Mapping: the description only lands in Jira if the Request Type's form has a Description field and it's mapped.
• While an Update summary template is set, edits to the summary in Jira don't change the incident title in Xyte, and the next incident update overwrites them with the rendered template. Without one, the webhook syncs summary edits back to the incident title.

Available keys and filters

The full key list (with examples), the date / default / truncate filters and the validation rules are on Incident field templates.

Close Status

1. Select the status transition to apply to a Jira request when the incident is resolved in Xyte.
2. Click Update, then Next.

If your required Close Status is not listed, verify permissions on the Jira side and click the refresh icon button next to Update.

Make sure at least one status transition in your Jira workflow can move a request from any open state to closed, otherwise Xyte will not be able to close the request.

To disable automatic closing (and manage request status entirely from Jira), select the Do not automatically close option.

To list the available transitions, Xyte opens a test request titled Xyte Integration - Workflow Discovery in the chosen service desk each time the request type is selected or the list is reloaded. Xyte doesn't close it — close or delete it in Jira.

Webhook

Optional — see Webhook Setup below.

Filtering (optional)

Choose the Minimum incident priority to report — No filter — send everything (the default), or Critical and above down to Planning and above — and click Save filtering.

Incidents below the selected priority are skipped, and stay skipped for their whole lifecycle even if their priority is raised later. An incident that was already reported keeps updating normally even if its priority is later lowered.

Enable

1. Click the Activate button to enable the integration (the same button reads Disable while it's active).

   

Once active, every new Xyte incident (unless excluded by Filtering) will automatically open a Jira Service Management request.

Webhook Setup (Sync from Jira to Xyte)

By default, sync goes one way: Xyte → Jira. To enable updates from Jira back to Xyte (title, description, priority changes, and closing the Xyte incident when the Jira request is resolved), register a webhook in Jira and share a secret with Xyte.

The setup is a one-time flow:

1. Create the webhook in Jira
2. Generate the shared secret
3. Paste the secret into Xyte's Webhook step
4. Verify it's working

You need site-admin permissions in Jira to access the WebHooks page below. If you don't have access, ask your Jira admin to do Steps 1–2 and hand off the secret.

What syncs back to Xyte

Xyte will not reopen a closed incident, even if the Jira request is reopened.

Step 1 — Create the webhook in Jira

1. In Jira, navigate to Settings (cog icon) → System → WebHooks (under the Advanced section).
   • Direct URL: https://<your-jira-instance>.atlassian.net/plugins/servlet/webhooks
2. Click + Create a WebHook.
3. Fill in the form:

Do not save the form yet. Continue to Step 2 to generate the secret first.

Step 2 — Generate the shared secret

Still on the WebHooks create form:

1. In the Secret section, click Generate secret. Jira will populate the field with a fresh random string.
2. Copy the secret value now — Jira hides it permanently after you save and you'll need to regenerate (which invalidates any existing pairing) if you lose it.
3. Click Save to create the webhook. Jira will now sign every delivery with HMAC-SHA256 over the raw request body using this secret, and include the signature in the X-Hub-Signature header.

If you'd rather supply your own value, paste any strong random string (e.g. openssl rand -hex 32) into the Secret field instead of clicking Generate. Treat it like a password.

Step 3 — Paste the secret into Xyte

1. In Xyte, open the Jira Integration settings and click the Webhook step in the setup wizard (between Close status and Filtering).
2. Paste the secret from Step 2 into Webhook Secret and click Update.

The Webhook step is optional and can be completed at any time, even after the integration is already active. If you skip it, Xyte → Jira continues to work; only the Jira → Xyte direction is disabled.

Without a matching secret in Xyte, inbound webhook deliveries from Jira are rejected with 403 Forbidden. The integration's outbound sync (Xyte → Jira) is unaffected.

Step 4 — Verify it's working

1. Open any Jira request that is linked to a Xyte incident.
2. Change the summary, priority, or description, or transition the request to a status in the Done category.
3. Open the matching incident in Xyte and confirm the change is reflected (typically within a few seconds).

If nothing happens, see Troubleshooting below.

How Xyte authenticates the request

For every inbound delivery Xyte recomputes HMAC-SHA256(body, webhook_secret) and compares it (constant-time) to the value Jira sent in the X-Hub-Signature header (in the form sha256=<hex>). The first active Jira integration whose stored secret produces a matching signature wins; if none match, the request is rejected with 403 Forbidden.

Once authenticated, Xyte matches the Jira request ID to an existing incident in that integration's organization. If no incident is found, the event is silently ignored — Xyte does not create incidents from Jira-originated events.

Updating

You can update the integration settings (service desk, request type, field mapping, templates, close status, filtering) or disable the integration at any time from the Jira Integration settings in Xyte.

• Field mapping and description template are used only when a request is created, so a change affects new requests only. Changing the service desk or request type resets settings — see the last bullet below.
• Update summary template — existing requests pick up the new summary on their next update.
• Close status applies to every incident resolved after the change, including ones opened before it.
• Choosing a different Service Desk or Request Type disables the integration — re-activate it in the Enable step. After changing the Service Desk, pick the Request Type again too. Choosing a Request Type clears the field mapping and close status, so set those again before re-activating.

Troubleshooting