Jira ticketing
Link tasks to Jira issues, and let field work comment on and move those issues as it progresses.
The Jira integration connects Maintella to the ticketing system your own support engineers already work in. When an admin assigns a task, they pick the Jira issue it relates to. From then on, Maintella reports back to that issue as the work progresses — a comment when the task is assigned, started and completed, and optionally a status change at each point.
This is different from the other integrations described in the integrations overview. Those exist to import assets. Jira imports nothing: it links work you are already tracking upstream to the field visit that resolves it, and sends the work report back.
It works with both Jira Software (and Jira Work Management) and Jira Service Management. The setup is the same except for one step — granting project access — and one extra choice for service projects.
What ends up in the ticket
The completion comment carries the evidence of the visit:
- The work report — the answers your workflow collected
- Started and completed times, and time on site
- The engineer’s name and company
- A link back to the full report in Maintella
So the ticket your support engineer closes contains the proof of what was done, without anyone copying it across by hand.
Before you start
You need an Atlassian organization admin to create two things, and a Jira project admin to grant access. In small teams that is often the same person.
Maintella authenticates as a service account — a non-human Atlassian identity — rather than as any individual. That means comments are authored by the service account rather than by the admin who assigned the task, so the comment body names the responsible person explicitly.
Step 1 — Create the service account and its credential
In Atlassian Administration:
- Create a service account for Maintella. Give it a recognisable name, because that name is what appears as the author of every comment Maintella posts.
- Create an OAuth 2.0 credential on that service account. You will be shown a client ID and client secret once — copy both before closing the dialog, as the secret cannot be retrieved later.
- Select these scopes, and only these:
| Scope | Why |
|---|---|
read:jira-work | Find and read issues |
write:jira-work | Comment on and transition issues |
read:servicedesk-request | Read service management requests |
write:servicedesk-request | Comment on service management requests |
Two things to avoid. Do not add administrative scopes such as manage:jira-configuration or
manage:jira-project; Maintella never needs them, and a credential that can reconfigure your
Jira is a much larger risk if it leaks. And prefer these classic scopes over the granular
equivalents — the granular service management scopes are, in practice, more restrictive for the
calls Maintella makes.
The client secret does not expire. Access tokens are short-lived and renewed automatically, so there is nothing to rotate on a schedule.
Step 2 — Give the service account access to the project
This is the step that most often gets missed, because granting the service account a Jira licence is not the same as giving it access to a project. Without this, Maintella cannot see the project at all: ticket search returns nothing and the integration reports itself unhealthy.
Jira Software and Jira Work Management
Add the service account to the project in the project’s own access or people settings. An open team-managed project may already admit it by virtue of its product access, but do not rely on that — check.
Jira Service Management
Add the service account as a member of the service space, from the space’s own member settings. Product access alone is not enough, and neither is an organization-level agent licence.
Note that this consumes a Jira Service Management agent seat, which is a licensed cost. It is required: without agent capability, Maintella cannot post internal notes, cannot read queues, and cannot see the project in the first place.
Repeat for each project or space you want Maintella to work with.
Step 3 — Enable the integration in Maintella
In the admin app, under Organization → Integrations, enable Jira Cloud and provide:
- Jira site URL — for example
https://yourcompany.atlassian.net - OAuth client ID and client secret from step 1
Maintella resolves the rest from your site automatically.
Each organization can have one active ticketing integration at a time. One integration covers every project on your Jira site, including a mix of software and service projects.
Step 4 — Choose projects and what should happen
Open the integration and use the Settings tab.
Jira projects — tick the projects ticket search should cover. Only projects the service account can reach appear here, so an empty or short list is a sign that step 2 is incomplete. Service projects are labelled, because they behave differently for comments.
What happens at each stage — for assigned, started and completed independently, choose whether Maintella posts a comment, moves the ticket to a chosen status, both, or neither. The status choices are read live from your Jira, so they are your real workflow transitions rather than a generic list.
A reasonable starting point is a comment at every stage and a transition only on completion. You can add the earlier transitions once you trust it.
Service projects: who sees the comment
Service management comments are either internal notes, visible only to agents, or public replies, which appear in the customer portal and notify whoever raised the request.
Maintella posts internal notes by default, deliberately. A work report contains engineer names, timings and whatever your form collected, and that is usually not something to send to an end customer by accident.
Switch the integration to public replies when the person who raised the request should hear what was done — an asset owner or site host who reported the fault and wants to know it is fixed. It is a per-integration choice, so consider it carefully if you use one service project for internal triage and another for customer requests.
Assigning a task to a ticket
Once set up, the Ticket field in the task assignment wizard becomes a search box. Type to
search by title, or paste an issue key such as SUP-123 to go straight to it. The matching issues
appear with their current status so you can confirm you have the right one.
If your organization has no ticketing integration, this stays a plain free-text field and nothing is sent anywhere, exactly as before.
Service level agreements
Maintella does not manage SLA timing. Your ticketing system’s own timestamps are authoritative, which keeps a single source of truth.
In the normal case Maintella reports a transition within seconds of the field engineer acting, so there is nothing to reconcile. If Jira is unreachable, Maintella keeps retrying until it succeeds — nothing is dropped — but the status change then lands later than the work happened, and an SLA measured from transition times will reflect that delay.
If that matters to you, configure it in Jira rather than in Maintella. Jira Service Management can pause an SLA on nominated statuses — the same mechanism as “waiting for a third party”. If your field-work statuses pause the clock, delivery timing during a visit stops mattering and only the final resolution is time-critical.
Every comment also states when the work actually started and finished, so a disputed measurement can always be settled by reading the ticket.
Checking it works
The integration’s Health tab reports three things: whether the credential still authenticates, whether Maintella can see your projects, and whether every configured project is still reachable. It runs on a schedule as well as on demand, because these failures are quiet ones — a revoked secret or a withdrawn permission shows up as nothing happening rather than as an error.
The Activity tab lists every ticket update Maintella has sent, undelivered ones first, with the reason anything failed. If a work report has not reached a ticket, it is listed there.
Common problems
| Symptom | Cause |
|---|---|
| Ticket search finds nothing, project list is empty | The service account has no access to the project — step 2 |
| Health says “Not found, or the service account has no access” | A configured project was deleted, or its permission was withdrawn. Jira does not distinguish the two |
| Health says the credential failed | The client secret was revoked or replaced. Create a new credential and update the integration |
| Comments arrive but the status never moves | The configured transition is not available from the ticket’s current status. Maintella posts the comment anyway and records a warning on the Activity tab |
| A service project comment went to the customer | The integration is set to public replies — see above |
Related
- Integrations overview — asset sync and diagnostics
- Tasks and reporting — assigning work and reading reports
- Roles and permissions — who can configure integrations