# Field Mapping

Hiera uses field mapping to connect your Jira custom fields to the data points it needs for scheduling, capacity, risk assessment, and more. Proper field mapping ensures all views display accurate information.

## Mapped Fields

The following fields can be mapped in Hiera:

| Field            | Purpose                           | Used By                                       |
| ---------------- | --------------------------------- | --------------------------------------------- |
| **Start Date**   | Beginning of the scheduled period | Timeline, Capacity, OKR health                |
| **End Date**     | End of the scheduled period       | Timeline, Capacity, OKR health                |
| **Area**         | Component or functional area      | Filters, grouping, swimlanes                  |
| **Team**         | Team assignment                   | Filters, Capacity grouping, Workload Planning |
| **Risk**         | Risk level (Low/Medium/High)      | Risk Matrix, risk-only filter                 |
| **Impact**       | Business impact (Low/Medium/High) | Risk Matrix                                   |
| **Story Points** | Estimation value                  | Capacity calculations, SP-to-hours conversion |

## Auto-Detection

When you first open Hiera in a project, it attempts to auto-detect common field names. For example:

* A field named "Start date" or "Start Date" will be automatically mapped to Start Date.
* A field named "Story Points" or "Story points" will be mapped accordingly.

Auto-detection works for most standard Jira configurations. If your fields use non-standard names, you will need to map them manually.

## Manual Mapping

To configure field mappings:

1. Open Hiera in the target project.
2. Click the **Fields** button in the toolbar.
3. For each field, select the corresponding Jira custom field from the dropdown.
4. Click **Save** to apply.

If a field has no suitable match, leave it unmapped. Views that depend on unmapped fields will display a notice indicating what is missing.

## Fallback to Jira Defaults

When no custom mapping is provided for Start Date or End Date, Hiera falls back to Jira's built-in date fields. This ensures basic Timeline functionality works even without custom date fields.

## Per-Project Storage

Like hierarchy configuration, field mappings are stored in **Forge Storage** on a per-project basis. Each project maintains its own mappings independently.

## Troubleshooting

* **Fields not appearing in dropdown**: Ensure the custom field is available in the project's field configuration scheme.
* **Dates not showing on Timeline**: Verify that Start Date and End Date are mapped and that issues have values in those fields.
* **Risk Matrix empty**: Confirm both Risk and Impact fields are mapped and that issues have values set.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hiera.gitbook.io/hiera-docs/admin-and-configuration/field-mapping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.