Skip to main content

AQS parameters

Overview​

When building an AQS query, you can define one or more parameters.

A parameter is a placeholder value that will be provided when the query runs. This lets you build the query without having to provide an actual value.

When the query runs, the parameter will be substituted with a value provided by:

  • the user running the query

  • another process (e.g. a workflow that's triggered the query)

For example, you might want to fetch all jobs assigned to a particular team. Rather than creating multiple queries, each with a different team value, you could create a single query with a TeamName parameter. When the query runs, an actual team name can be inputted when prompted.

The fields of the Parameter window
An example query node comparing a Team Name attribute with a TeamName parameter

Parameters are accessible to all nodes in a query, so they're useful for supplying the same value to multiple nodes, e.g. in an AQS Join query, you could use the same TeamName parameter to fetch additional data about that team.

Note

To see this example built step-by-step, see Example 4 - Parameters and Join.

Default parameters​

In many scenarios, the AQS Builder provides one or more default parameters. A parameter is a placeholder that gets substituted with a value when the query runs. By including one of these in a query, it's possible for the query to fetch different data in different contexts:

  • Current item ID - available when editing the query of an item form control. It represents the ID of the item being viewed or edited via the item form. This can be used to fetch items related to that item, enabling fields on the form to display context-sensitive lookup results.

  • Current user ID - available in most scenarios where it makes sense. It represents the ID of the currently signed in user. This can be used to fetch items related to that user.

For example, the query below fetches all jobs assigned to teams the user belongs to. For each job, it navigates to the related team, then its team members, then their users, and compares each user's ID with the Current user ID parameter.

An example query that only fetches job items assigned to the current user
See JSON code
{
  "type": "Query",
  "properties": {
    "collectionCode": "Live",
    "dodiCode": "designInterfaces_jobs",
    "parameters": [
      {
        "name": "currentItemId",
        "type": "AlloyId",
        "title": "Current item ID"
      },
      {
        "name": "currentUserId",
        "type": "AlloyId",
        "title": "Current user ID"
      }
    ]
  },
  "children": [
    {
      "type": "And",
      "children": [
        {
          "type": "Exists",
          "children": [
            {
              "type": "Attribute",
              "properties": {
                "attributeCode": "attributes_tasksTeam"
              }
            }
          ]
        },
        {
          "type": "Equals",
          "children": [
            {
              "type": "ItemProperty",
              "properties": {
                "itemPropertyName": "itemId",
                "path": "root.attributes_tasksTeam.attributes_teamsMembers^attributes_usersTeamMembers"
              }
            },
            {
              "type": "AlloyId",
              "properties": {
                "parameterName": "currentUserId"
              }
            }
          ]
        }
      ]
    }
  ]
}