Set up Attio for Jira on a project
Whoever opens an issue wants to know something that is not in Jira: who this customer is, what they pay for, who owns the account. Attio for Jira puts those details on the issue itself, read from your own Attio workspace. Nothing is copied into Jira and nothing runs on a schedule: the values are fetched when somebody opens the issue. It works on service management, software and business projects.
Setup is done project by project, by a project administrator, and it is six questions long. This page is the shape of the whole job so you can see what you will be asked before you start. The thing worth knowing up front is that nothing appears on a single issue until all six are answered, including the last one.
#Before you start
Some of these are outside the settings page, and they are the ones that hold people up. The rest are decisions you can make while you are in there.
What you need | Why it matters |
|---|---|
A Jira project of any type | The Attio page is offered on service management, software and business projects. On a software or business project the reporter is usually a colleague, so match on a Jira field that names the customer. Only the customer portal panel needs a service management project. |
Project administrator rights on it | Only administrators of that project can open or change the Attio settings. The app asks Jira again on every action rather than relying on the page being hidden, so the check cannot be walked around. |
An Attio workspace API key | One key, pasted into one Jira project. There is no Attio sign-in, no username and password, and no Attio app to install. There is also no site-wide key to set once for everybody. |
Two read permissions on that key | The key has to be able to read records and to read object configuration. Read-only is enough, and read-only is what the app asks for. |
An Attio object holding your customers | It needs an attribute carrying whatever you will match on: an email address when you match people, a domain when you match companies, or whatever a Jira field holds (a name, a domain or an address) when you match a field. A text attribute works in each case. |
Jira's approval to read reporter email addresses | Needed when you match on the reporter. Jira does not put the reporter's address in the issue, so without this the card can only ever say no address is available. Atlassian classes it as sensitive, which is why a site administrator may be asked about it. Matching on a Jira field does not need it. |
A new permission can reach your site before anybody approves it. An upgrade that needs a new Jira permission arrives on every installation straight away and waits for a site administrator in Admin Hub rather than blocking. Until it is approved, your settings will save and the card will still not appear. The page says so above the tabs, under "Saved, but the card is not switched on yet".
#Where the settings live
Inside the Jira project: Project settings, Apps, Attio. The entry is listed as "Attio" with the line "Connect this project to an Attio workspace". A project that has not finished setup opens into a six-step wizard. A project that has finished opens the same six sections as tabs, plus a seventh, Customer portal, with the same controls and no step numbers.
There is no site-level place to do any of this. Every project that wants the card connects its own workspace, and two projects on the same site can point at two different Attio workspaces. A Jira site administrator gets a read-only list of which projects are connected to which workspace, and nothing on that list can enter, reveal or clear a key.
#The six questions
Step | What it asks | What pressing Next does |
|---|---|---|
Connect | An Attio workspace API key. | Tests the key against Attio and stores it only if Attio accepts it and the two reads are there. |
Record type | Which Attio object holds your customers. | Stores the object. Changing it later clears everything chosen under it. |
Matching | How the customer is found: Match the person by the reporter's email address, Match their company by its domain, or Match a field on the issue. | Stores the method, the Jira field if there is one, and the attribute the value is compared against. |
Fields | Which of that object's attributes the card shows, and in what order. | Stores the chosen attributes and their order. |
Permissions | Who sees the card, on top of being able to open the issue. | Stores the audience. It ships with a default that suits the project type (agents on a service management project, anyone who can see the issue elsewhere), so this step can never block you. |
Placement | Where on the issue the card appears. | The last button reads "Finish setup", and pressing it is what switches the card on. |
There is no Save button anywhere in the wizard. Pressing Next is what does the work for that step, so an answer is never left sitting unsaved behind you, and the footer counts you through from "Step 1 of 6" to "Step 6 of 6".
#What finishing setup actually does
The card is switched on for a project that has all five of a stored key, a record type, an attribute to match on, at least one field and at least one placement. Tick the placements without the rest and the card still shows nowhere, which is why setup ends with placement rather than starting with it.
There is no separate on and off switch. Choosing at least one placement is what makes the card appear for everyone in the project, and removing every placement is what takes it away again. The step says as much: "Until one of these is on, the card renders nowhere, including for you."
#Who sees what while you are setting up
This app is deliberately quiet, and it is worth knowing that before you ask a colleague to look.
Viewer | What they see on an issue before setup is finished |
|---|---|
A project administrator | One sentence naming the piece that is missing, with an "Open project settings" link under it. |
Anyone else in the project | Nothing at all. No placeholder, no message, no empty box. |
Anyone outside the audience you choose | Nothing at all, for a deliberate reason: saying the card exists would itself say something about the customer. |
A portal customer or an unlicensed user | Never the card. None of the three placements is offered without a licence. Customers see only the separate portal panel, and only after an administrator publishes fields to it on the Customer portal tab. |
So an empty issue view is the normal appearance of an unfinished project rather than evidence of a fault. It is also why an administrator's view of a half-built setup looks informative while everybody else's looks broken.
#A few things worth knowing
Finishing the wizard is the only route to a visible card, and the Placement step is last on purpose. A project with a key, an object and a full set of fields still shows nothing anywhere until a placement is chosen.
The wizard only exists until setup is finished. After that the page opens as tabs for good, and the only way back into it is Reset to defaults, which erases the key and every other Attio setting the project has.
On a software or business project, the Agents in this project audience is unavailable, because nobody holds agent access there. The default for those projects is Anyone who can see the issue.
#Related
Six answers, and the last one is the switch.
