Map fields between Aha! Roadmaps and your development system

The Aha! Roadmaps development tool integrations allow Aha! Roadmaps users to fully customize how they map Aha! Roadmaps record fields and records themselves to your development system.

Note: A field in Aha! is not able to create a record in an integrated tool (or vice-versa).

Click any of the following links to skip ahead:

• How it works

• Choose a mapping direction

• Configure field mappings

• List of mappable fields

• Notes on particular fields

• One-way directional fields

• Constant field

• Assignee field

• Custom fields

How it works

Once you create an integration and define which Aha! Roadmaps records you wish to map to your development system, you will be able to see the available field mappings in your integration configuration.

Integrations support mapping the following Aha! Roadmaps records:

• Initiatives

• Releases / Schedules

• Epics

• Features / Activities

• Requirements

After specifying how you wish Aha! Roadmaps records to be mapped, select the field mapping option to customize how the fields for that record are mapped between Aha! Roadmaps and your development system. For each record, we provide a default set of mappings based on what is most commonly used among Aha! Roadmaps customers. You can revise these mappings to fit the needs of your organization.

Top

Choose a mapping direction

For each field mapping, you can specify the mapped Aha! Roadmaps and development system fields. You can also specify the direction of the mapping by clicking the blue arrow icon. The directional options include:

• One way: Syncs the field in only one direction — either from Aha! Roadmaps or from the development system.

• One way (set once): Syncs the field in only one direction as a one-time event.

• Two way: Allows full two-way communication between Aha! Roadmaps and the development system for the field.

One way mapping direction is not the only way to ensure a one-way field sync, however. When you edit a custom layout, you can also mark any field as read-only. Read-only fields block anyone from updating the field through a record's drawer or details view, so that users in your Aha! Roadmaps account have the proper context but cannot accidentally adjust fields that need to stay static.

Read-only fields are not locked fields, however. They can still be updated through integrations, and this is often key to their true value. For example, you can use read-only fields to ensure that users in your Aha! Roadmaps account cannot adjust feature effort estimations set by developers over a Jira integration. Read-only fields can also be updated through the Aha! API (https://www.aha.io/api), through bulk edits in list reports, and through clicking and dragging records in Gantt charts and roadmaps.

Top

Configure field mappings

When mapping certain fields, such as a record's Status, or custom fields such as the Predefined choice list or Predefined tags fields, a Configure option will appear at the right side of the row to allow value mapping for the field between Aha! Roadmaps and your development system.

Choose a mapping direction

For each field mapping, you can specify the mapped Aha! Roadmaps and development system fields. You can also specify the direction of the mapping by clicking the blue arrow icon. The directional options include:

• One way: Syncs the field in only one direction — either from Aha! Roadmaps or from the development system.

• One way (set once): Syncs the field in only one direction as a one-time event.

• Two way: Allows full two-way communication between Aha! Roadmaps and the development system for the field.

One way mapping direction is not the only way to ensure a one-way field sync, however. When you edit a custom layout, you can also mark any field as read-only. Read-only fields block anyone from updating the field through a record's drawer or details view, so that users in your Aha! Roadmaps account have the proper context but cannot accidentally adjust fields that need to stay static.

Read-only fields are not locked fields, however. They can still be updated through integrations, and this is often key to their true value. For example, you can use read-only fields to ensure that users in your Aha! Roadmaps account cannot adjust feature effort estimations set by developers over a Jira integration. Read-only fields can also be updated through the Aha! API (https://www.aha.io/api), through bulk edits in list reports, and through clicking and dragging records in Gantt charts and roadmaps.

Top

Configure field mappings

When mapping certain fields, such as a record's Status, or custom fields such as the Predefined choice list or Predefined tags fields, a Configure option will appear at the right side of the row to allow value mapping for the field between Aha! Roadmaps and your development system.

[Existing image]

After clicking Configure, a modal will open. You can automatically map matching values by clicking the Match like values button. You can then manually drag values into place to finalize preferred mappings and map them as one-to-one or one-to-many.

Top

List of mappable fields

The following table provides a comprehensive list of standard Aha! Roadmaps fields that you can map within each record type.

Notes on particular fields

Assigned to user

There is some nuance to this field that we discuss in the Assignee field section below.

Comments

When you first send an Aha! Roadmaps record to an integrated tool, Aha! Roadmaps does not send any existing comments. This is so that you can complete your strategic plans in Aha! Roadmaps before sending records to engineering.

Though you can edit comments in Aha! Roadmaps, Aha! Roadmaps will not send edits to comments to integrated tools.

Record relationships

For Jira 2.0 and Azure DevOps 2.0 integrations only.

Start date

Release start dates are computed from the start of the earliest release phase or milestone in Aha! Roadmaps. For this reason, a release's start date can only be mapped one way, from Aha! Roadmaps to your integrated tool.

Team (Jira)

The Jira Team field supports bidirectional mapping in Jira 2.0 integrations, so team assignments stay in sync in both systems. You need to complete two additional steps before the Team field becomes available to map:

• In the Configure account step of your Jira integration settings, enable the Organization checkbox, then paste your Atlassian organization ID into the Organization ID field that appears.

• Click Reload configuration on the Mappings step if the Team field does not appear in your list of Jira fields after you save the organization ID.

To find your Atlassian organization ID:

• Sign in to the Atlassian admin console (https://admin.atlassian.com) with an administrator account.

• Click the app switcher (grid icon) in the upper left of the navigation.

• Select your account icon, then click Teams.

• Copy the organization ID from the Teams page URL. In https://home.atlassian.com/o/6a231649-90dd-4e42-b6ce-45ab5aae4ca8/, for example, the organization ID is 6a231649-90dd-4e42-b6ce-45ab5aae4ca8.

Jira's API treats Team as a custom field, so look for it in your list of Jira custom fields rather than among the standard Jira fields.

Note: The Aha! Roadmaps editable choice list custom field does not support bidirectional sync with the Jira Team field. Map the Jira Team field to a predefined choice list custom field instead.

Top

One-way directional fields

Nearly all standard Aha! Roadmaps fields support all of the directional options when setting up an integration. However, the following Aha! Roadmaps fields only support a one-way connection due to the nature of the data being communicated:

• Constant

• Created timestamp

• Custom table fields (Jira integrations)

• Last updated timestamp

• In parking lot?

• Record relationship fields (e.g. the initiative or epic record relationships on a feature card)

• Release URL

• Release start date

• Remaining estimate

• URL

Technically, the <record> % complete field supports a two-way connection, but we strongly advise against it. If you find yourself setting up a mapping with limited directionality and it is not on this list of limited fields, the problem is generally due to an API limitation with the field you are trying to sync to in the development system.

Top

Assignee field

You can map the assignee field, also called Assigned to user, in all 2.0 integrations, and by default the mapping is bidirectional. Mapping this field gives everyone insight into the person responsible for a particular record, regardless of the tool they use.

However, there are a few nuances to assignee field mapping that are worth noting:

• A user's email address must match in each tool if you want to assign a record to the same person.

• The Aha! Roadmaps integration (or the user the integration is running as) must have appropriate user permissions in the integrated tool to see users' email addresses.

If neither of these situations exist, then Aha! Roadmaps will not be able to assign a record to a user in both tools. And then in that case:

• If Aha! Roadmaps has a Default user configured, then the record will show an assignee in Aha! Roadmaps but not in the integrated tool.

• If you choose to Resend all fields in Aha! Roadmaps, the assignee will be removed from the record in the integrated tool.

Top

Constant field

The Constant field is an Aha! Roadmaps field mapping option. Use this field to specify a constant value that will be passed to your development system. You cannot map a Constant field to a multi-select field in Aha! Roadmaps (like a predefined choice list).

Top

Custom fields

In addition to mapping default Aha! Roadmaps fields, you can also map Aha! Roadmaps custom fields to your integrated system. You can customize their mapping just like you would a default Aha! Roadmaps field.

Aha! Roadmaps supports the following custom field types for mapping to your development system:

When mapping the Predefined choice list or Predefined tags fields, a Configure option will appear at the right side of the row to allow value mapping for the field between Aha! Roadmaps and your development system.

After clicking Configure, a modal will open. You can automatically map matching values by clicking the Match like values button. You can then manually drag values into place to finalize preferred mappings and map them as one-to-one or one-to-many.

Custom table fields

If you link epics or features to custom table records, you can send a value from the linked custom table record to Jira. For example, if your team tracks program increments in a custom table, map each program increment's code to a Jira field. Developers see the value on the Jira issue, and you avoid copying the same data into a separate custom field.

To map a custom table field:

• Open the field mappings for an Aha! Roadmaps record type in your Jira integration.

• In the Aha! Roadmaps field column, select the custom table relationship field, then select the custom table field whose value you want to send.

  • The mapping displays the relationship and the field together, such as "Program increment → Code."

• Select the Jira field to map it to.

• Set the mapping direction to Aha! to Jira.

Custom table field mappings have a few limits:

• Relationship type: Only many-to-one relationship fields are available. Many-to-many and one-to-many relationships link several custom table records to one Aha! Roadmaps record, so they do not provide a single value to send.

• Direction: Custom table fields sync one way, from Aha! Roadmaps to Jira.

• Field compatibility: Map single-value custom table fields to a compatible Jira field. If the two field types do not match, choose a different Jira field.

• Record mappings: Custom table records do not appear as a record type in your integration mappings. You cannot send a custom table record to Jira as its own Jira issue.

Top