Advanced AML Topics

Advanced AML Topics

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. 

Name Usage Example
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">
doGetItem

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.

Get Actions

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.

Name Usage Example
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">

Edit/Update Actions

Name Usage Example
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">

Custom Actions

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.

<AML>
  <Item type="Part" action="Add Part and Attach to Parent" parent="MP0101">
    <item_number>P-0001</item_number>
    <name>New Child Part</name>
    <description>A part created as an example to show off custom actions</description>
  </Item>
</AML>
The parent attribute in this example is entirely unique to this custom action.

Conclusion

AML is an incredibly powerful tool that every administrator of Aras Innovator should have in their belt. The standard actions and attributes are enough for most use cases, but it's flexible enough to allow for customization to suit your particular business needs. 


Mike Lindner
Parents
  • Hi Chris,

    is "getItemRepeatConfig" the better version for the  "levels" action? Or do both version the job the same way?

  • Hi Angela,

    The GetItemRepeatConfig action is likely preferable in most use cases, but it does function differently to the levels attribute.

    For example, the AML below uses GetItemRepeatConfig. If you run this query with a proper ID from your database, you'll see that only the Part BOM relationships are included in the results.

    <AML>
    <Item type="Part" action="GetItemRepeatConfig" id="9B8B42162852429197D0A2536C3D816F">
    <Relationships>
    <Item type="Part BOM" repeatTimes="0" repeatProp="related_id"></Item>
    </Relationships>
    </Item>
    </AML>

    If you instead use the levels attribute as in the example below, you'll see that every relationship is included in the result without having to manually specify them. By default, this would be Part BOM, Part Document, Part CAD, Part AML, Part Alternate, Part PSW, Part Changes, and Part Goal.

    <AML>
    <Item type="Part" action="get" id="9B8B42162852429197D0A2536C3D816F" levels="2">
    </Item>
    </AML>

    For debugging purposes, the levels attribute can be handy as it allows for a quick, shorthand way of seeing a lot of data. But for any production purposes, you are likely better off using GetItemRepeatConfig. 

    Chris

    Christopher Gillis

    Aras Labs Software Engineer

  • Hi Chris,

    thanks for the explanation! I never used 'levels' in the past, so I didn´t know that it will return all available relationships. From my POV it´s especially useful for developing! It helps to test certain ideas without having to think about the AML query details. It later can be easily replaced with an performance optimized query. That will save some time, that´s cool. 

  • Also bear in mind that the levels attribute will get federated relationships as well. Not only could this cause additional performance issues, but if your federation code returns an error (even a "No items found error"), it can prevent any data from being returned.

  • Hey Eric, you should have wrote this one half a year ago where I exactly had this situation. And it made me crazy cause it was really hard to find the reason why no data was returned anymore. Aras support in the end provided me a simple solution for a more flexible error handing for the federated items onGet method.

  • Hi Chris,

    Please can you explain using action 'GetItemRepeatConfig' will this help me in achieving below structure?

    Part
        - BOM

              -Part
                  -BOM

                      -Part
                         -BOM

    I have tried using this and failed to achieve the expected result.

Comment
  • Hi Chris,

    Please can you explain using action 'GetItemRepeatConfig' will this help me in achieving below structure?

    Part
        - BOM

              -Part
                  -BOM

                      -Part
                         -BOM

    I have tried using this and failed to achieve the expected result.

Children