How to use Assets Query Language (AQL)
Assets Query Language (AQL) allows for powerful, dynamic searches in Assets.
Advanced AQL search offers more flexibility than Basic Search, allowing you to conduct specific searches using logical operators (AND, OR), keywords, and dot operations.
Search for objects with Advanced AQL search
To search a single object schema for objects that match a specific AQL statement, use the Advanced AQL search.
Go to Assets and select an object schema.
Select the relevant object type.
Select the Objects tab.
Select the Filter icon, then the Advanced AQL tab.
Enter your AQL query.
Select Update filter.
The query results will be filtered based on the selected object type.
Filter objects that appear in a reference attribute
You can use AQL to filter which objects appear in a reference attribute.
To create a reference, you must be logged in as a Jira admin or have Object Schema Manager permissions.
From your service project:
Go to Assets and select an object schema.
Select the relevant object type.
Select Attributes.
In the attribute listing, enter a Name and Description.
Under Type, select Object, and under Type value, select the object type you want to reference.
Under Additional Value, select the Reference type for this reference. Learn more about managing references
Select Add.
The objects will be filtered based on the selected reference’s object type.
Filter objects that appear in an object custom field
You can use AQL to filter which objects appear in an object custom field by using the AQL. The Filter scope field filters based on attributes in Assets, while the Filter issue scope field filters based on other Jira fields in the issue.
To modify an object field configuration, you must be logged in as a Jira admin.
Go to Custom fields in the navigation sidebar.
Find your Assets objects field.
Look for Assets objects under the Type column or search by name.
Select More options, then Contexts and default value.
Select Edit Assets objects field configuration.
Select the object schema you want the field to access from the dropdown.
(Optional) Enter an advanced query in Filter scope (AQL) to filter objects based on their attributes in Assets. Learn more about AQL
(Optional) Enter an advanced query in Filter issue scope (AQL) to filter objects based on other Jira Service Management fields.
(Optional) Select Display a default object when this field appears in a customer portal if you want the Filter issue scope (AQL) field to be pre-filled with a default object in the portal.
Under User interaction, select the attributes users can search for and those that will show on the Jira work view.
Select Save.
Lookup objects using Atlassian automation
You can use AQL to look up objects when using Atlassian automation. The Lookup objects action can be triggered by a specific condition.
Based on the AQL value provided, the Lookup objects action will return a list of objects, which can then be used in other actions with the {{lookupObjects}} smart value. Learn more about Lookup objects
Manage how Assets creates attributes when importing data
You can use AQL to manage how Assets creates attributes during data import. When creating an attribute-type mapping as part of the import, you can use the AQL field to generate references or statuses from raw data by incorporating a placeholder in your AQL statement.
For example, if the Category attribute is a reference, and you want the Data source field to contain the name and link to the referred object (instead of just the name as a string), you could use an AQL statement like Name = ${Category} to create the reference link.
To manage an import, you must be logged in as a Jira admin or have Object Schema Manager permissions.
From your service project:
Go to Assets and select an object schema.
Select Configure, then the Import tab.
Select Edit mapping on your import structure to view the object type mapping.
Select Edit attributes mapping to view the attribute type mapping.
Select a Data source field.
This field specifies where the objects are located in the data file. Attribute mapping will be disabled until a data source field is provided for each mapped attribute. Every object imported into Assets will require at least one data source field to let Assets know where to find the objects. Learn more about the data source field
Select a Destination attribute to map to the data source field.
Optionally, modify default settings for the attribute mapping:
AQL: Enter an AQL statement to create references from data.
Concatenator: Specify an alternative concatenator for this attribute mapping.
Regular expression: Enter a regex that applies only to this mapping.
Base 64: Provide an alternate Base 64 value here.
Select an attribute as the identifier.
This uniquely identifies each object and becomes its new label when created. The identifier is also key for updating data—objects with the same identifier in the destination schema will be updated, while those without it will be created.
Select Add.
Manage how child objects are created when importing data
You can use AQL to manage how child objects are created during a data import. When importing into a parent object type with child types, the Filter data source by AQL field helps assign objects to the correct child type based on source data values.
For example, if you have a parent object type ('Hardware assets') with three child object types ('Phones', ‘Laptops’, or ‘Servers’), you can filter and assign objects to the correct child type based on the data.
To manage an import, you must be logged in as a Jira admin or have Object Schema Manager permissions.
From your service project:
Go to Assets and select an object schema.
Select Schema configuration, then the Import tab.
Select Edit mapping on your import structure to view the object type mapping.
Select Edit attributes mapping to view the attribute type mapping.
Select Create child mapping and enter the following:
Object type: This will be disabled, as the child object type matches the parent.
Filter data source by IQL: Optional. Use this to filter objects from the data.
Identifier case matching: Disabled.
Missing objects: Choose from:
Remove: Only imported entries remain.
Update: Non-imported objects will be edited.
Ignore: Non-imported objects remain unchanged.
Missing objects outbound references: Choose from:
Remove: Only imported references persist.
Ignore: Unmatched outbound references remain unchanged.
Empty values: Choose how empty values from the external source should be handled:
Use default: Use the value from the import structure.
Remove: Remove current values.
Ignore: Keep current values.
Select Create.
Was this helpful?