In a previous blog post, we gave an introduction to AML and covered the basic structure of an AML request. While the simple concepts covered in that post are powerful enough for many use cases, you can make your AML requests even more useful with just a few simple tweaks by adding attributes to your requests.
Basic Item Attributes
There are a handful of attributes that are available for every type of AML request.
|type||The name of the ItemType to query on. Almost every query will need a type to run properly.||<Item type="Part">|
|where||An optional condition to filter the results of your query||<Item type="Part" where="[Part].item_number like 'MP%'">|
|id||The unique ID of the specific item to query on. Using this attribute is equivalent to using a where clause like where="[Part].id = 'YOUR_ID'"||<Item type="Part" id="1FEB0204D83147CCA9DA1CB658F9642D">|
|action||The type of query you want to perform. (e.g. "get", "update", "add", etc.)||<Item type="Part" action="get">|
A boolean value indicating whether any items should be returned from the query. Useful to speed up execution of actions like "update" and "add". Is true by default.
|<Item type="Part" action="update" doGetItem="0">|
Specific Item Actions
The attributes above are available regardless of what kind of AML query you are performing. However, most of the standard queries you can perform through AML also have more specific attributes available.
The get action has a number of different attributes to control what items get returned and how. For a full list of what attributes are available for each different standard action, you can check out section 2.4 of the Aras Innovator Programmer's Guide.
|select||Specify which properties will be returned by this query.||<Item type="Part" action="get" select="item_number,name">|
|levels||Returns all relationships to the level defined. Using levels="2" will return all relationships as well as all relationships of those child items. Should be used sparingly due to performance issues.||<Item type="Part" action="get" levels="2">|
|serverEvents||Determines whether the server events on the ItemType will be run as part of this query. Can be useful when debugging new onBeforeGet/onAfterGet server events. By default the server events will always run.||<Item type="Part" action="get" serverEvents="0">|
|version||Only applicable to Versionable items. Determines whether the item will be versioned as part of this update. Can be useful when performing a one-time mass edit as a result of a data model change.||<Item type="Part" action="edit" version="0">|
|serverEvents||Determines whether the server events on the ItemType will be run as part of this query. Can be useful when performing an initial data load to both improve performance and avoid potential conflicts as a result of the server events. By default the server events will always run.||<Item type="Part" action="update" serverEvents="0">|
In addition to all of the standard actions, you can also use the action attribute to pass in the name of any Method in your database. Running a query like this will use the Item you've built in the AML query as the context item when you run your Method.
As an example, we'll create a new action with the Method code below. The purpose of this new action is to allow us to add a new Part with an optional property that will let us attach it to an existing part in the database.
With this new action in place, the AML we run will end up looking like the example below.
<Item type="Part" action="Add Part and Attach to Parent" parent="MP0101">
<name>New Child Part</name>
<description>A part created as an example to show off custom actions</description>