Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 29 ยท Administration and Automation

Workflows, Permissions and Customization

Learn how Jira administrators customize workflows with conditions, validators and post functions, control access with permission schemes and roles, and add custom fields.

Out of the box, Jira works for a generic team. Sooner or later your team will need something specific: a "Ready for QA" status that only testers can set, a bug that cannot be closed without a resolution, a field for "customer ticket number", or a project that only some people may see. This is the work of a Jira administrator (or a project administrator for team-level settings).

This lesson explains the four building blocks of customization: workflows, permission schemes with roles, custom fields and screens. The settings pages of a hosted Jira cannot run on this site, so they are described in words and read-only blocks, and menu names can differ between plans and versions. The runnable examples are stand-ins: small JavaScript models of the rules, so you can see how a transition check or a permission lookup is decided. They are not Jira's code.

What an admin can shape

Workflows Statuses and allowed moves.
Permissions Who may do what.
Custom fields Extra data on an issue.
Screens Which fields appear where.
1 / 2

Custom workflows

A workflow is a set of statuses and transitions, as introduced in Issues, Issue Types and Workflows. To customize one, an administrator opens the workflow editor, which shows a diagram, and adds statuses (each assigned to one of the three status categories), then draws transitions between them. A workflow is attached to issue types through a workflow scheme (company-managed projects), so bugs can follow a different path from stories.

Each transition can have three kinds of rules:

  • Conditions decide whether a user may see and use the transition at all. Example: only members of the role "Testers" can move an issue from "In Review" to "Done". If the condition fails, the button is simply not offered.
  • Validators check the input when the user tries the transition. Example: moving a bug to "Done" requires the Resolution field. If the check fails, the user sees an error and the issue stays where it was.
  • Post functions run after the transition succeeds. Example: set the Resolution to "Done", clear the Assignee, or update a field. Jira runs several of them in a defined order.

Keep two ideas in mind when designing. First, a status describes a state of the work, not a person or a hand-off ("In Review", not "Waiting for Ana"). Second, fewer statuses are better: every extra stop is a place for work to wait, which hurts flow.

Before adding a status, ask what decision or action changes between the old and new status. If nothing changes, you probably need a label or a field, not a status.

A transition check, step by step

The stand-in below applies the three rule kinds in the same order a user experiences them: first the condition (is the button visible), then the validator (is the data complete), then the post function (what happens afterwards). The rules themselves are examples.

JS Condition, validator and post function (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Permission schemes and roles

Jira separates who a person is from what they may do. Three pieces make that work:

  1. Permissions are single abilities, such as Browse Projects, Create Issues, Edit Issues, Transition Issues, Assign Issues, Administer Projects and Delete Issues.
  2. A permission scheme is a table that grants each permission to one or more holders. A holder can be a project role, a group, a single user, or special values like "Assignee", "Reporter" or "Anyone".
  3. Project roles (for example Administrators, Developers, Testers, Viewers) are named buckets that you fill with people separately in each project.

The benefit of roles is reuse: one permission scheme can serve fifty projects, and each project decides who is a Developer. Add someone to the Developers role of one project and the scheme gives them the right abilities there, with no change to the scheme itself.

TEXT
Permission scheme "Standard software" (excerpt, as a table)
Permission           Granted to
Browse Projects      Project role: Viewers, Developers, Testers
Create Issues        Project role: Developers, Testers
Transition Issues    Project role: Developers, Testers
Delete Issues        Project role: Administrators
Administer Projects  Project role: Administrators

Design permissions with the principle of least privilege: grant what people need to do their jobs and no more. Deleting issues is a good example, because a deletion cannot be undone and loses history. Most teams let only administrators delete and ask everyone else to close or resolve issues instead.

JS A permission-scheme lookup (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that Ana can create issues in SHOP but not in OPS: the permission scheme is shared, the roles are not. A user who has no role in a project (Max) gets nothing, not even read access.

Permissions in Jira are layered. Besides the permission scheme there are issue security levels (hide individual issues from some people), workflow conditions, and global permissions. When someone says "I can't do X", check all of them before changing the scheme.

Custom fields and screens

Standard fields cover most needs, but a team might also need "Customer ticket number" (text), "Browser" (select list), "Affected users" (number) or "Go-live date" (date). An administrator creates a custom field by choosing a field type, giving it a name and a description, and adding it to the right screens (the Create, Edit and View layouts that decide which fields appear and when).

Practical advice that saves pain later:

  • Reuse before you create. Duplicate fields with similar names ("Browser", "Browsers", "Web browser") break searches and reports.
  • Use a select list instead of free text for any value you filter by. In JQL and Filters you saw why: browser = Safari works only if everyone types the same word.
  • Limit the contexts. A field can be restricted to certain projects and issue types, so people are not asked about things that do not apply.
  • Prefer fewer fields. Every required field is a reason for someone to give a hasty answer or abandon the issue.

Team-managed projects have a lighter model: the team's own administrators change issue types, fields and workflows for that single project, without a global scheme. That is quick and flexible, but changes do not carry over to other projects, so shared reporting across many teams is easier with company-managed projects.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A validator on the transition to Done requires the Resolution field. When is it checked?

    Validators run when the transition is attempted and block it, with an error message, if the data is missing.
  2. 2. What is the main benefit of project roles in permission schemes?

    Schemes grant permissions to roles, and each project fills the roles with its own people.
  3. 3. A transition button is missing for a developer, though others see it. Which kind of rule most likely hid it?

    Conditions control whether a user is offered the transition. Validators and post functions run after the user has chosen it.
  4. 4. Why is a select-list custom field better than free text for "Browser"?

    Consistent values make filtering and charting reliable.

Summary

  • Administrators shape Jira with workflows, permission schemes, roles, custom fields and screens.
  • Transitions can have conditions (who can use them), validators (is the data complete) and post functions (what happens afterwards).
  • A permission scheme grants abilities to roles, groups or users; roles are filled per project; follow least privilege.
  • Create custom fields sparingly, choose list types for values you filter by, and limit their contexts.
  • Team-managed projects trade global consistency for fast local control.
  • The JavaScript examples are stand-ins for the rules, not Jira's implementation, and menus differ between versions.

Next, let Jira work for you: Jira Automation and the REST API.