Query Using Relationships as Search Criteria

You want to search for an Item using the relationship and related Items as search criteria. In this recipe, we get the User Item that matches the Identity name as an Alias relationship to the User Item.

Technique
The following are some key points to understand when constructing an AML query:

1. Use the get action on the relationship Items to include it as search criteria.
   
   1. Without the get action the relationship Item is ignored as search criteria.
   2. The relationship Items are also returned. Currently there is no way to use relationships as search criteria and not return them in the results, as you can with the related Item described below.

2. Include the related_id property name in the select attribute for the relationship Item if you want to return the related Item nested inside the related_id property in the results.

   <Item type="Part BOM” select="quantity,related_id"/>

   Use () to include the select attribute value for the related Item inside the select attribute for the relationship Item.

   <Item type="Part BOM” select="quantity,related_id(item_number,description)"/>

3. The select attribute for the nested Item tag for the related_id property has higher precedence over the select value inside the () for the relationship’s select attribute.

4. The get action is not required for the nested Item tag for the related_id property to include it as search criteria.

   These two AML scripts are equivalent queries for selecting the name property for the related Item:

   <Item type="User” action="get” select="first_name,last_name,email">
<Relationships>
<Item type="alias” action="get” select="related_id(name)"/>
</Relationships>
</Item>
<Item type="User” action="get” select="first_name,last_name,email">
<Relationships>
<Item type="alias” action="get” select="related_id">
<related_id>
<Item type="Identity” action="get” select="name"/>
</related_id>
</Item>
</Relationships>
</Item>

   Clearly the first example is simpler and requires less coding (referring to the IOM logic that would construct the AML) and is the recommended style when all you require is specifying a select for the related Item for the query.

   But the second style opens the opportunity to now include additional search criteria for the related Item.
   

AML

<Item type="User” action="get” select="first_name,last_name,email">
<Relationships>
<Item type="Alias” action="get” select="related_id">
<!--
This get will limit root Items to only those that match the relationship criteria.
The get action is required otherwise the criteria are ignored.
To include the nested Item tag for the related_id include the property name in the select attribute for the relationship Item.
Can include the select attribute value for the related Item inside ()
i.e. related_id(name)
-->
<related_id>
<Item type="Identity” action="get” select="keyed_name">
<!--
This get has no effect and the search will work with or without it.
It is recommended that you include it because the AML parser may be stricter in the future.
The select attribute over rules the parent relationships select.
-->
<name>Larry Bird</name>
</Item>
</related_id>
</Item>
</Relationships>
</Item>

JavaScript
var innovator = new Innovator();
var qry = innovator.newItem(“User”,"get”);
qry.setAttribute(“select”,"first_name,last_name,email”);
var alias = new Item(“Alias”,"get”);
alias.setAttribute(“select”,"related_id”);
var identity = new Item(“Identity”,"get”);
identity.setAttribute(“select”,"name”);
identity.setProperty(“name”, “Larry Bird”);
alias.setRelatedItem(identity);
qry.addRelationship(alias) ;
var results = qry.apply();
if (results.isError()) {
top.aras.AlertError(results.getErrorDetail());
return;
}