How to use Assets Query Language (AQL)

Assets Query Language (AQL) is a language used in Assets in Jira Service Management.

As one of the most powerful and dynamic features in Assets, you can use AQL in many different ways.

Search for objects using the Advanced AQL search

You can use AQL to return highly specific search results. Unlike Basic Search, Advanced AQL search enables you to use logical operators such as AND and OR, keywords, and dot operations.

To search a single object schema for objects that match a specific Assets Query Language (AQL) statement, you can use the Advanced AQL search:

1. Select Assets in the top navigation bar.

2. Select an object schema from the list.

3. Select an object type.

4. Select Objects mode.

5. Select the icon (in List view) or the Filter icon (in Detail view).

6. Select the Advanced AQL tab.

7. Enter your AQL query.

8. Select Update filter. The results of the query will be pre-filtered by the currently selected object type.

Filter the objects that appear in a reference attribute

You can use AQL to filter which objects will appear in a reference attribute. Any objects appearing in this field will already be filtered by the currently selected object type of the reference.

To create an reference, you must be logged in as a Jira admin or have Object Schema Manager permissions.

1. From your service project, go to Assets > Object schemas.

2. Select the relevant object schema.

3. Select the relevant object type.

4. Select Attributes.

5. In the listing of attributes, enter a Name and Description.

6. In the listing of attributes, under Type enter Object, and under Type Value select the object type you want to reference.

7. In the listing of attributes, under Additional Value, select the Reference Type of this reference. Learn more about how to add, edit, and delete different types of references.

8. Select Add.

Filter the objects that appear in an Assets objects custom field

You can use AQL to filter which objects will appear in an Assets objects custom field by using an AQL statement in the Filter scope and Filter issue scope field. The Filter scope field is used to filter the values based upon their attributes in Assets, while the Filter issue scope field is used to filter the values based upon other Jira fields that appear in the issue.

To modify an Assets object field configuration, you must be logged in as a Jira admin.

1. Go to Custom Fields in the navigation sidebar

2. Find your Assets objects field (look for Assets objects under Type column or search the name)

3. Select more options > Contexts and default value

4. Select Edit Assets objects field configuration

5. Select the object schema you want the field to access from the dropdown (under Object schema).

6. (Optional) Enter an Assets Query Language (AQL) query in Filter scope (AQL) to define which objects should be shown. You can use this field to filter Assets objects based on their attributes in Assets. Learn more about AQL.

7. (Optional) Enter an Assets Query Language (AQL) query in Filter Issue scope (AQL) to define which objects should be shown. You can use this field to filter Assets objects based upon the values from other fields in Jira Service Management. Learn more about AQL.

8. (Optional) Click Display a default object when this field appears in a customer portal if you want the Filter Issue Scope (AQL) field to be filled with a default object when the field appears in a portal.

9. Under User interaction, select the Assets attributes that users can search for and those that will show on the issue view

10. Select Save.

Lookup objects using Atlassian automation

You can use AQL to lookup objects when using Atlassian automation. The Lookup action can be triggered by a set condition.

Based on the AQL value provided to the action, the Lookup action will then provide a list of objects that can be used in other actions using 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 when you are importing data. When you are creating an attribute-type mapping as part of your import, you can use the AQL field to create references or statuses from your raw data by using a placeholder within your AQL statement.

For example, if the Category attribute was a reference, and you wanted the value in the Data source field to be contain the name and link to the referred object (instead of a string value of the name), you could use an AQL statement like Name = ${Category} to create that link.

To configure an import, you must be logged in as a Jira admin or have Object Schema Manager permissions.

1. From your service project, go to Assets > Object schemas.

2. Select an Object schema.

3. Select Configure, then choose the Import tab.

4. In the Import tab, select on Edit mapping on your import structure to view the object type mappings.

5. Select Edit attributes mapping to view the attribute type mappings.

6. Every object imported into Assets will require at least one piece of information - the data source field that lets Assets know where to find objects in the data source. Learn more about the data source field.

   1. Select a Data source field. The data source field specifies the location of the objects in the data file. Your attribute mapping will be disabled until you supply a data source field for each mapped attribute.

   2. Select a Destination attribute to map to the data source field.

   3. Optionally, you can modify the default settings for this attribute mapping:

      1. AQL - enter an IQL statement here to create references from data.

      2. Concatenator - enter an alternative concatenator here that applies only to this attribute mapping.

      3. Regular expression - enter a regular expression here (regex) that applies only to this attribute mapping.

      4. Base 64 - enter an alternate Base 64 value here.

7. Select one of the attributes as an identifier. An identifier uniquely identifies each object, and will become that object’s new label when it is created. You must have exactly one identifier to run your import. The identifier is also important when you are updating data - any object with the same identifier in the destination schema will be updated, while objects with identifiers not found in the destination schema will be created.

8. Click Add, at right.

Manage how Assets creates child objects when importing data

You can use AQL to manage how Assets creates child objects when importing data. If you have created a parent object type with one or more child object types and you are importing data into the parent object type, you have the option to use the Filter data source by AQL field to assign each incoming object to a child object type.

For example, if you have a parent object type called Hardware assets with three child object types (Phones, Laptops, and Servers), and you want to assign each incoming object to one of the child object types based on a value found in the source data, you can use the Filter data source by AQL field to sort the child objects.

To configure an import, you must be logged in as a Jira admin or have Object Schema Manager permissions.

1. From your service project, go to Assets > Object schemas.

2. Select an Object schema.

3. Select Schema configuration, then choose the Import tab.

4. In the Import tab, select on Edit mapping on your import structure to expand it.

5. Select the object type mapping where you wish to create a child mapping and select Edit attributes mapping.

6. A button to Create child mapping will appear under the attributes mapping. Select this and enter the following information:

   1. Object type - since the child object type will be the same as the parent object type, this option will be disabled.

   2. Filter data source by IQL - An optional IQL to query the objects fetched from source. If you wish to filter the objects from data, you can accomplish that here.

   3. Identifier case matching - this option will be disabled.

   4. Missing objects - select from:

      1. Remove - Only entries from the import will persist as Assets object/s. Any object manually created in Assets will be deleted.

      2. Update - All objects in Assets not present in the import will have an attribute edited.

      3. Ignore - Object in Assets that is not found in the import won't be removed or updated.

   5. Missing objects outbound references - select from:

      1. Remove - Only outbound references from the import will persist as Assets references. Any outbound references manually created in Assets will be deleted.

      2. Ignore - Outbound references in Assets that aren’t found in the import won't be removed or updated.

   6. Empty values - When an object is updated, choose if empty values from the external source should remove the existing value. Select from:

      1. Use default - use the value specified in the “Define import structure” screen for this object type.

      2. Remove - remove the current value. If the attribute is a status, select, or reference type attribute with more than one value, all of the values will be removed.

      3. Ignore - keep the current value for this object type. If the attribute is a status, select, or reference type attribute with more than one value, all of the values will be kept.

   7. Unknown values - this option will be disabled.

7. Select Create.

Use the Assets REST API

You can use AQL as part of a call to the Assets REST API to fetch objects based on an AQL statement.

Learn more about using AQL retrieve a list of objects.