Assets filter configuration migration — the complete guide

[#1]

Assets Filter Configuration Migration: 📄 The Complete Guide

If you've migrated a JSM Assets schema to Cloud and your filters came back broken, empty, or quietly wrong — you're not alone, and it's not a misconfiguration on your end. It's a known gap in how migration tooling handles filters referencing Assets fields.

This guide covers why it happens and how to migrate Assets filter configurations correctly.

⛓️‍💥 Why Assets filters break during migration

A Jira filter referencing an Assets custom field isn't just querying a value — it's querying a relationship between an issue and an object in your Assets schema. Assets custom fields support AQL-based filtering through their Filter Scope and Filter Issue Scope configuration, which constrains which objects appear based on object attributes and relationships. When the underlying object reference doesn't survive migration cleanly, the filter has nothing valid to point to. The clause itself often migrates as a definition; the part doing the actual filtering doesn't.

This is two query languages stacked together: JQL filters the relevant work items first, then AQL applies to the objects connected to that set. If either layer loses its reference during migration — the field configuration, the schema link, or the AQL scope itself — the chain breaks downstream, often silently.

Common symptoms:

• Filters return zero results post-migration, even though the issues exist
• Filters return the wrong result set, because the Assets clause is being ignored rather than evaluated
• Dashboards and boards built on those filters appear empty or stale — usually how teams first notice the problem
• Assets custom fields linked to other Assets custom fields silently return zero objects, because the AQL placeholder referencing a sibling field (e.g., ${customfield_XXXXX${0}}) lost its link

That last pattern is the one teams misdiagnose most often.

👀 The hidden cause: AQL placeholders and field-to-field links

When an Assets custom field is linked to another Assets custom field whose Filter Issue Scope uses AQL referencing the first field, the AQL fails silently if that link didn't carry across migration. In practice: a "Services" field meant to filter by what's connected to a selected "Host" field returns zero objects — not an error, just an empty list — if the Host field's link didn't preserve correctly.

This is the exact pattern enterprise teams report: nothing looks broken in the UI, the field exists, the filter exists, but the relationship between them is gone. The fix requires confirming every Assets custom field on the issue screen or request form is aware of all the fields it references — even ones not directly present on the form.

If your migration approach doesn't explicitly test these field-to-field dependencies, this is exactly the kind of issue that surfaces weeks later as "the filter just stopped working."

🧩 What JCMA does and doesn't preserve

JCMA moves filter definitions — the saved query structure — reliably for standard Jira fields. It falls short on clauses built on Assets custom fields and AQL-based object references, which don't survive in a way that keeps them functional. The filter exists in Cloud; the Assets-aware filtering inside it doesn't.

This extends to ordering logic too. AQL queries can be ordered with a suffix clause, and if the order-by attribute is a reference type, dot notation sorts by an attribute of the referenced object — for example, ORDER BY Department.Name. Multi-level reference chains like this break first, since they depend on more than one relationship resolving in sequence.

✅ A correct filter migration approach

1. Inventory before you migrate. Export every saved filter and flag Assets field references explicitly — don't assume automatic carry-over.
2. Map each Assets-referencing clause to its Cloud equivalent. Filter validation is downstream of field validation. If the field is a reference type, confirm the relationship itself migrated, not just the field's presence.
3. Check field-to-field AQL links, not just individual fields. For any field whose Filter Scope references another field via the ${customfield_XXXXX${0}} placeholder, confirm both fields are linked on the issue screen post-migration. This is the most commonly missed step and the likeliest cause of silent zero-result failures.
4. Test migrate filters against a non-production Cloud instance. Compare result counts against the source. For AQL-heavy filters, also test the standalone AQL search inside Assets to isolate whether the failure is in the AQL logic or the Jira-side call.
5. Rebuild rather than assume for legacy and reference field types — they fail for different reasons. Legacy field types have no direct Cloud mapping. Reference field types fail because the object-to-object relationship didn't survive, even if the field did. Multi-level reference chains need each link verified independently.
6. Validate dashboards and boards separately. A filter can work in isolation but still feed a misconfigured gadget if the field mapping shifted.
7. Re-test after any schema fix. A filter fixed once can break again if a dependent field changes later, especially in chains where one field's AQL scope depends on another's configuration.

The root cause, and why it's worth fixing upstream

Filter breakage is a symptom, not the problem. The problem is that the Assets field, object reference, or field-to-field AQL link underneath didn't migrate with full fidelity. Treating filter validation as part of your core Assets schema migration — not a cleanup task afterward — fixes the cause once instead of chasing every downstream filter, dashboard, and board individually.

With a pre-migration backup and object-level validation that includes field-to-field AQL dependencies, filter issues become rare rather than routine, because you catch the broken reference before it ever reaches a filter.

Assets filter migration isn't really about filters. It's about whether the schema underneath them — including the relationships between fields — migrated with its structure intact. Validate at the schema and field-link level first, and the filters take care of themselves.