Mapping Custom Fields

As mentioned in Additional Data Syncing, you are also able to sync other meta data associated with stories in Avion — such as size, step name, journey name and release name — depending on your epic choice setup.

In Jira, each issue type, such as epics, stories, tasks etc, have their own "screen" defined. A screen contains a list of fields that can be set when creating or updating the issue. If we try to update a field value that is not present on the issue's screen, Jira will throw an error.

At some point, we would like to abstract this behind the scenes, using Jira's APIs, however unfortunately at the moment, Jira does not provide us the flexibility within the APIs to do this, so there is some manual setup involved.

Here are some guidelines on how to add custom fields to an issue type's screen. Note that it's different, depending on your type of project.

Classic Projects

1) Navigate to the screens page — Avion will link you to this:

Truly a work of art 👨‍🎨

2) Locate the default issue screen. Generally this will use the following format:

  • AA: ProjectType Default Issue Screen

  • Where AA is your project key

  • And ProjectType is your chosen template type

For example, if your project was called My Cool App (MCA) and was setup with a Kanban template, your default screen name would be:

  • MCA: Kanban Default Issue Type

If you have lots of projects in your organisation, check the format of the name carefully to ensure you are selecting the correct screen for the project that is synced up to Avion.

It's worth noting that screen names — frustratingly — can actually be renamed 🤦‍♀️. If you need help working out what your default issue screen is, please don't hesitate to get in touch!

3) Click Configure to add and remove fields

4) At the bottom of a field tab, use the dropdown to add a new field. If you are using the Avion configuration whilst reading this, Avion will have created a field for you to select here. It will either be Avion Journey, Avion Step or Avion Release.

5) Take note of the field that you added, as you will need to select the same field name from the dropdown list in Avion.

Next-Gen Projects

1) Navigate to the issue type screen setup page in question — Avion will link you to this:

2) Add a new custom field.

  • If you are attempting to sync up Journey, Step or Release meta, use Text

  • If you are attempting to sync up Size meta, use Number

3) Name the field as you would like and hit Save Changes

4) Take note of the field name that you created, as you will need to select the same field name from a dropdown list back in Avion

Renaming Fields

It's absolutely fine to rename a custom field, both in classic or next-gen projects. As long as the field type is correct, Avion will be able to sync with it.