--- title: "BigPicture Field Mapping Visibility and Synchronization Behavior" canonical: "https://support.appfire.com/space/SUPPORT/3407216820/BigPicture%20Field%20Mapping%20Visibility%20and%20Synchronization%20Behavior" format: markdown --- This document is based on a resolved support case and is intended to help administrators understand the functional behavior behind box-level field mapping, scope configuration, permissions, and synchronization rules in BigPicture Cloud. # Overview In BigPicture, field mapping connects BigPicture fields with Jira fields so data can stay synchronized between the app and Jira. The availability of field mapping depends on how the box scope is defined and whether the user has the required permissions. A key finding from this case is that a box scoped through a **Jira Board** may be treated differently from a box scoped directly through a **single Jira project or Space source**, even when the board filter returns issues from only one project. In that situation, the box-level **Field mapping** option may not appear. > 📝 A board can technically use a filter that spans multiple Jira projects. Because of that, BigPicture may treat board-based scope as a potentially multi-source setup, which can prevent box-level field mapping from being shown. # What was observed in this case - The customer was a BigPicture app administrator and a space administrator. - The box pulled **real Jira work items**, not only basic BigPicture tasks. - The box scope was configured using a **Board**. - The board filter returned issues from only **one Jira project**. - Despite that, the **Field mapping** option was missing at the box level. - When the customer changed the source from **Board** to **Spaces**, the **Field mapping** option became available. > ✅ Confirmed behavior from the case: switching from a board-based source to a project/space-based source made the box-level **Field mapping** option visible. # When box-level Field mapping is available Box-level field mapping is intended for simpler scope definitions, especially where BigPicture can clearly identify a single Jira project behind the box. In practice, the option is usually available when the following conditions are met: - The box contains actual Jira work items. - The scope is clearly tied to a **single Jira project** rather than a broader or indirect definition. - The user has sufficient permissions in both BigPicture and Jira. If these conditions are not met, field mapping may still be possible, but only from the global application configuration rather than from the individual box. # Why Field mapping can be missing The support discussion identified four main reasons why the box-level **Field mapping** action may not appear. | Possible cause | Explanation | | --- | --- | | Box contains only basic BigPicture tasks or sample data | Field mapping applies to Jira-synchronized work items. If the box does not contain real Jira issues, mapping is not relevant and the option may be hidden. | | Scope is based on multiple Jira projects | Box-level field mapping is not intended for multi-project scope definitions. In those cases, use the global field configuration. | | Scope is based on a Jira Board | Even if the board filter returns issues from one project, the board is still treated as a potentially broader source, so BigPicture may not show box-level mapping. | | Missing permissions | The user needs the right permissions in both BigPicture and Jira for field mapping to be available and usable. | # Required permissions Field mapping depends on access in two layers: BigPicture and Jira. | System | Required role or access | | --- | --- | | BigPicture | **Box Admin**, **App Admin**, or **App Resource Admin** | | Jira | **Jira Project Admin** or **Jira Admin** for the project behind the box scope | > ⚠ī¸ Being only a space administrator in BigPicture may not be enough. The Jira-side administrative permission is also important for field mapping scenarios. # Recommended troubleshooting path 1. Confirm the box contains real Jira work items. 2. Check whether the scope is defined directly by **Project/Space** or indirectly by **Board**. 3. Verify that the source effectively represents a single Jira project. 4. Review both BigPicture and Jira permissions for the user performing the configuration. 5. If the scope is board-based, test the same setup with a direct project-based or space-based source. 6. If box-level mapping is still unavailable, use **App configuration → General → Fields** to configure mapping globally. > ℹī¸ If a box must stay board-based, the safest fallback is to configure field mapping globally in the app settings rather than relying on the box-level option. # How synchronization behaves when mapping is changed The case also clarified the meaning of the option **Overwrite Jira work item data with data from the app**. This option becomes relevant when an administrator changes an existing field mapping and both sides already contain values. The setting is used as a **one-time migration decision** at the moment the mapping changes. It determines which existing values should win during the transition from the old mapping to the new one. > The overwrite option does not define the long-term sync direction. It decides how already existing data should be reconciled when the mapping is changed. After that one-time reconciliation, synchronization continues normally in both directions. If a user later changes the value in Jira, it updates in BigPicture. If a user changes the value in BigPicture, it updates in Jira. # Example: changing a mapped target field Assume the BigPicture **End Date** field was previously mapped to one Jira field, and now the administrator wants to remap it to **Jira Due Date**. The problem is that the Due Date field may already contain values. | Task Key | BigPicture End Date | Jira Due Date | | --- | --- | --- | | MAC-1 | 6/16/2026 | 6/23/2026 | | MAC-2 | 6/17/2026 | 6/24/2026 | | MAC-3 | 6/16/2026 | Empty | At the point of remapping, BigPicture needs to know which values should be preserved: - If the administrator chooses to overwrite Jira with app data, the existing Jira Due Date values are replaced with the current BigPicture End Date values. - If the administrator chooses the opposite behavior, BigPicture values are updated from the existing Jira Due Date values. This is why the option becomes active only when a mapping is changed and a data migration choice is required. # Access model reminder: App User role vs box role The same support case also clarified a related access question. A user needs both: - The **App User** role in **App Administration → Security** - An appropriate **box-level role** such as Viewer, Editor, Admin, or Sub-box Creator The App User role allows the person to access and open BigPicture from Jira. The box-level role then controls which boxes they can open and what they can do inside them. > 📝 A box role alone is not enough. If the user does not have the **App User** role, they will not be able to access BigPicture even if they were assigned to a box. # Practical guidance - Use a direct project- or space-based source when you want box-level field mapping to be available. - Do not assume that a board limited to one project will always be treated as a single-project scope. - Use global field configuration when the box scope is indirect, broad, or board-based. - Before changing mappings, review which system currently contains the correct field values. - Remember that the overwrite option is a one-time migration choice, not a permanent sync-direction setting.
Expand **Why is Field mapping missing even though my board contains only one project?** Because BigPicture may treat board-based scope as a potentially multi-source definition. The board itself is not always recognized as a simple single-project scope. **Can I still configure field mapping if the box-level option is hidden?** Yes. Use **App configuration → General → Fields** to manage mapping globally. **Does the overwrite option make Jira or BigPicture the permanent source of truth?** No. It is only used when changing a mapping to decide how existing values should be reconciled at that moment. **Is being a space admin enough to manage field mapping?** Not always. You may also need the required Jira administrative permission for the underlying project. **Can I grant someone a box role without making them an App User?** No. The App User role is required for access to the BigPicture app itself.