← All guides

Before you start: setting up Jira for Mermix

Mermix connects to your Jira Cloud site and makes changes there when you push your plan. A few things decide whether that goes smoothly. This checklist takes about ten minutes, and it is written so you can forward it to whoever administers Jira at your company.

1. Who connects Jira

The first connection between a Mermix workspace and a Jira site must be made by a Jira administrator of that site. This stops anyone else from claiming your company's Jira site for their own workspace. One site belongs to one Mermix workspace.

Whoever connects, Mermix then works as that account in Jira: every change it pushes is made with that account's permissions and shows in the Jira history under its name. Mermix needs Jira administrator rights only for that first connection. Reconnecting later to the same site does not need them. Mermix never changes your Jira configuration; What Mermix can see and change in Jira lists every permission it asks for.

You can connect with your own account, but we recommend creating a separate Jira user for Mermix, for example mermix@yourcompany.com:

  • Changes Mermix pushes show in Jira as made by "Mermix", not by a colleague.
  • The permissions Mermix needs sit on one account, not on a person.
  • The connection keeps working when the person who set it up changes role or leaves. If the connecting account is deactivated, Mermix loses its connection until an Admin reconnects; workspace Admins get an email when that happens.

It takes one Jira seat and a mailbox for the account. Sign in to Atlassian once as that user, then click Connect with Atlassian in Mermix while signed in as it.

3. Permissions in each project you plan

In every Jira project Mermix plans, the connected account needs:

Atlassian is renaming "issues" to "work items" one site at a time, so your permission scheme may show either name; both are given below.

To do this Jira permission
See the project and its work Browse projects
Change start dates and estimates Edit work items (Edit Issues)
Change due dates and sprints Schedule work items (Schedule Issues); sprints also need Edit work items
Change who a task is assigned to Assign work items (Assign Issues)
Add or remove dependencies Link work items (Link Issues), in both projects

The people Mermix assigns work to also need Assignable user in those projects.

The easiest way: create a group called mermix, add the Mermix user to it, and add the group to these lines of each permission scheme your projects use (company-managed projects). In a team-managed space, give the Mermix user the Member or Administrator role.

If something is missing, Mermix tells you: at the end of setup, once your first calendar is ready; when you add a project; and before each push (the Push drawer greys out the change and names the permission and the account). Adding a dependency it can't save says so too, before anything is sent to Jira.

4. Settings in Atlassian Administration that can block Mermix

Some organisations restrict apps. Check these in admin.atlassian.com:

  • User-installed apps. Under Apps → Atlassian apps, choose Looking for your Marketplace and third-party apps?, then Settings → User Installed Apps. There an admin can block apps that users add themselves. If it is blocked, Atlassian's own consent screen says your site admin must authorize the app. Either allow user-installed apps, or have a Jira administrator connect Mermix themselves.
  • Data security policies (Atlassian Guard, paid plans). A policy can stop apps from reading some projects. Mermix then simply does not see them. Exclude Mermix, or those projects, from the policy.
  • IP allowlists (paid plans) do not block Mermix: Atlassian does not apply them to OAuth 2.0 apps, which is how Mermix connects. Nothing to change.

5. Fields on your screens

  • Start date. Mermix uses the Start date field built into Jira, the one the Jira calendar and timeline use, so dates you push show there too. Jira Software sites have it, usually on every project's screens already. Mermix never creates a field. If your site has none, restore it from the trash (Jira settings → Fields), or show it on your projects: the field scheme of each company-managed project, or the work type in a team-managed space. Without one, Mermix reads no start dates from Jira: work whose only date is a start date waits in the backlog, and the rest is placed from its estimate and due date. Until a project has the field on its screens, Mermix pushes everything except the start date and tells you why.
  • Time tracking. Mermix always pushes estimates. Your team sees them in Jira only if the Time tracking field is on the work type (company-managed: the project's field scheme; team-managed: Space settings → Work types).

6. Team emails

When you import your team, Mermix receives a person's email address only if their Atlassian profile shows it to Anyone. For everyone else, you type the email in Mermix. You can import people without one, but a person needs an email to get a Mermix login, and Mermix asks for it when you edit their details.

Next