What you need before you connect Attio
Most of the time spent setting this up is not spent in Jira. It goes on finding somebody who can make a key in Attio, and on getting a Jira site administrator to approve a permission that sounds alarming until you know why it is needed. Both are worth lining up before you open the settings page.
This page is the whole list. Nothing else is required, and there is no site-wide switch to throw first: the first project to connect is set up exactly like the fortieth.
#The list
What | Why |
|---|---|
A Jira Service Management project | The Attio settings page is offered on service desk projects only. On any other project type the app does not appear in project settings at all, for anybody. |
A project administrator | Only administrators of that project can open or change the Attio settings, and the app re-checks that with Jira on every action rather than relying on the page being hidden. |
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. |
Two read permissions on that key | The key must be able to read records and read object configuration, named in Attio as record_permission:read and object_configuration:read. The read-write versions also satisfy the requirement, but read-only is enough. |
An Attio object holding your customers | It needs an attribute carrying what you will match on: an email address or a text attribute when matching people, a domain or a text attribute when matching companies. |
Jira's permission to read reporter email addresses | Jira does not include 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. |
#About the key
The helper text under the field states the rule: "An Attio workspace key is exactly 64 characters." A key of any other length is refused in the browser and nothing is sent to Attio at all. The message reports how many characters were pasted, so a truncated paste can be told from a stray extra character.
The key is stored encrypted for the project that pasted it and is never sent back to the browser, so no screen in the app can display, copy or export it, including for the person who pasted it. The field always starts empty: a row of dots as its placeholder means a key is already stored, and the helper text reads "Leave this empty to keep the key this project already has."
The app does not know Attio's own menus, and the link under the field, "Create a key in Attio", opens the Attio web app rather than the key-creation screen. Where the app has advice of its own it is in the message for a rejected key: "The key is the right length but Attio will not accept it. It has usually been revoked, or it belongs to a different workspace. Create a new key in Attio under Workspace settings, Developers, and paste it here."
A key that is missing a permission does not need replacing. If Attio accepts the key but has not granted the reads the card needs, the screen names the missing ones under "The key works but is missing permissions" and tells you what to do: "Edit this key in Attio, grant those scopes, then try the same key again. You do not need a new key." Nothing is stored until the key has passed, so a bad paste cannot replace a working connection.
#What the app asks Jira for
Six permissions, and no more. Only one of them writes anything.
Read issues, so the card can confirm the viewer may see the request before anything else happens.
Read users, for the audience checks and for naming whoever connected a project.
Read service management requests.
Read a user's email address, which is the one that makes the product work at all.
Storage for the app's own data.
Permission to write one non-secret flag on the project, holding only whether the project is ready and which placements were chosen. That flag is what lets Jira hide the card in projects that have not finished setup.
There is no permission to create, edit or delete anything in Jira beyond that flag, and no write permission for Attio at all.
A new permission can reach your site before anybody approves it. An upgrade that needs a new permission arrives on every installation straight away and waits for approval rather than blocking. Anything depending on it stops quietly until then. If that is what is happening, the settings page says so under "Saved, but the card is not switched on yet": "Your settings are stored. Jira would not let this app update the project, which is what makes the card appear on issues. A Jira site administrator may need to approve this app's new permissions in Admin Hub. Choose a placement again once they have."
#What setup will ask you
A project that has not finished setup opens into six steps, in this order. Each one stores its own answer when Next is pressed, so there is no Save button to hunt for, and the last button reads "Finish setup".
Connect: the Attio workspace API key.
Record type: which Attio object your customers live in.
Matching: whether a reporter is matched as a person or as their company, and on which attribute.
Fields: which attributes the card shows, and in what order.
Permissions: who can see the card, on top of being able to see the issue.
Placement: where the card appears. Pressing Finish setup here is what switches it on.
Once the project is set up, the same page opens as a settings screen with those six as tabs. A project that is already configured stays on the tabbed page for the rest of the visit, even while an edit temporarily leaves it incomplete.
#A few things worth knowing
A key on its own shows nothing. A record type, an attribute to match on, at least one field and at least one placement are all required before the card renders anywhere, including for the administrator setting it up.
There is no key-only disconnect. Removing a key means "Reset to defaults", which also erases the record type, the matching attribute, every field, the audience and the placements, and takes the card off every issue in the project.
A truncated paste is caught before it costs anything, but only because of the length rule. A 64-character key from the wrong Attio workspace looks perfectly valid until the test names a workspace you did not expect, which is what the workspace name on the success panel is for.
#Related
Two permissions in Attio, six in Jira, and one 64-character string.
