The Adaptive Markup Language, sometimes referred to as Aras Markup Language, serves as the backbone of Aras Innovator. Almost every action that a user performs in the client sends an AML request to the Aras Innovator server to process the business logic. In this blog post, we'll cover the basic structure of an AML request so you can write your own queries.
Testing AML Queries
As part of this blog post, we'll be offering a few different sample AML queries which you may wish to test in your development environment. You can do this in a couple of different ways.
Nash
Nash is a lightweight application available in every instance of Aras Innovator which lets you run AML queries directly against your server. You can access Nash by appending `Clientscriptsnash.aspx` to the end of the URL you typically use to access your Aras Innovator instance (e.g. http://localhost/InnovatorServer/Client/scripts/nash.aspx). The Aras Homepage community project also features a handy link to access Nash on your instances.
InnovatorAdmin
As an alternative to Nash, you can also check out InnovatorAdmin, an extremely useful tool written by a member of the open Aras community. In addition to some other helpful features, InnovatorAdmin lets you run AML queries just like the built-in Nash application does. InnovatorAdmin also features IntelliSense to make writing your AML queries even easier.
The AML Structure
<AML>
If you are running your queries through Nash with the default settings, they should begin and end with this tag. You'll notice all of the sample queries you will find in this blog post are wrapped in AML tags so you can easily copy and paste them directly into Nash for testing.
<Item>
The most used tag in AML. As most administrators of Aras Innovator know, everything in Innovator is an Item. Even ItemTypes themselves are stored in Innovator as Items. This tag lets you query for Items in the database by defining a few different attributes.
- id – The unique ID of the item in the database
- type – The name of the ItemType you want to query on
- action – The type of query you want to perform
As a simple example, let's try querying for the Administrators Identity by passing in the ID.
<AML>
<Item type="Identity" action="get" id="2618D6F5A90949BAA7E920D1B04C7EE1"/>
</AML>
Note: If you're testing this AML through Nash, you must wrap your entire query inside of an <AML/> tag like the example above.
<property>
Property tags in AML exist as children to an <Item/> tag. The name of these tags correspond with the names of the ItemType's properties. For example, we could rewrite the query above to search for the name of the Identity rather than searching directly on the ID.
<AML>
<Item type="Identity" action="get">
<name>Administrators</name>
</Item>
</AML>
When using the get action, any property tags that you specify will be used as conditions to define which Items you want to get. However, when you use actions like add, edit, or update, the property tags define what changes to the item you want to make. In the example below, we'll add a new Identity with some property values.
<AML>
<Item type="Identity" action="add">
<name>My Group Identity</name>
<is_alias>0</is_alias>
<description>A group identity that we will add members to later</description>
</Item>
</AML>
Note that these property tags use the names of the properties on the ItemType which may not match the labels that you see in the Client. All property names will be lowercase and any spaces are typically replaced with underscores.
Item properties are stored at a database level as an ID. We can query on an Item property by passing in this ID, or we can use an <Item/> tag to expand our AML query and pass in additional parameters. Below you'll find a find a simple query to look up all Parts managed by my Identity.
<AML>
<Item type="Part" action="get">
<managed_by_id>
<Item type="Identity" action="get">
<name>Chris Gillis</name>
</Item>
</managed_by_id>
</Item>
</AML>
You can continue to nest <Item/> tags like this to easily build quite complex queries.
<Relationships>
We can use this tag to query on the relationships that exist between items in Aras Innovator. The Relationships tag is merely a container and will never have any attributes defined on it. You can see an example of how to use this tag below when we search for the Members of our Administrators Identity.
<AML>
<Item type="Identity" action="get">
<name>Administrators</name>
<Relationships>
<Item type="Member" action="get"/>
</Relationships>
</Item>
</AML>
Just like with properties, we can also add or edit Relationships through this tag. Note that nested item properties can perform different actions than their parents like in the example below.
Now that we've learned a few different core AML techniques, let's combine them all together into one query. Let's try to find all of the Group Identities in our system that a specific user is a member of.
<AML>
<Item type="Identity" action="get">
<is_alias>0</is_alias>
<Relationships>
<Item type="Member" action="get">
<related_id>
<Item type="Identity" action="get">
<name>Chris Gillis</name>
</Item>
</related_id>
</Item>
</Relationships>
</Item>
</AML>
We can also use these same concepts to add or edit Relationships as well. Note that nested <Item/> tags can perform different actions than their parents. In the example below you can see how to add Members to the Group Identity we created earlier.
<AML>
<Item type="Identity" action="get">
<name>My Group Identity</name>
<Relationships>
<Item type="Member" action="add">
<related_id>
<Item type="Identity" action="get">
<name>Chris Gillis</name>
</Item>
</related_id>
</Item>
<Item type="Member" action="add">
<related_id>
<Item type="Identity" action="get">
<name>Eli Donahue</name>
</Item>
</related_id>
</Item>
</Relationships>
</Item>
</AML>
With just a few key concepts under your belt, you're already on your way to being an AML wizard.
Conclusion
I hope this brief introduction to AML has been helpful. In future blog posts, we'll cover more advanced topics in AML like using different attributes to configure your query and using custom actions. If you have any questions about AML or suggestions for AML topics to cover in the future, please leave a comment!