Matrix custom field Documentation

Adding a new field

  1. Head to the custom field configuration page ( → Issues → Custom fields) and create a new field

    image-20250310-143129.png

  2. Select “Advanced” and pick either the single or multi-select Matrix custom field

    image-20250310-143117.png

  3. Give your custom field a name and put it on the appropriate screens

  4. Search for the custom field you just created and configure it (… → Contexts and default values → Edit custom field config)

    image-20250310-143721.png
    image-20250310-143758.png

  5. You can now give your X and Y axis a name and add options for both dimensions. Click “Preview” to show how the field will look like:

    image-20250310-143909.png

  6. Click “Submit” to save the configuration

Reporting

You can use all Matrix custom fields in JQL statements (and consequently in filters, Automation rules or any other JQL based control):

# perform a simple Text based match against either of the selected values (will match e.g. "Team" or "My Team") Rating ~ Team # search for a specific value in the X dimension or Y dimension # single select: matches exact value # multi select: matches if any value matches "Rating.xValues" = High "Rating.yValues" = Everyone # search based on the grid index (0-indexed), e.g. "Give me all issues where the Impact is higher than "Medium") # single select: matches based on the selected value # multi select: matches based on _any_ selected value (e.g. if _any_ of the options is higher than "Medium") "Rating.xCoordinates" > 2

Caveats

No support for the JSM customer portal

As of Mar 10, 2025 it is not possible to add custom fields to the JSM customer portal (this is a limitation of the APIs provided by Atlassian). Please raise a ticket at our support system to let us know if you would like to see this feature, so we can decide whether building a workaround is justified.