SP12 Extended AML Enhancements

This section contains examples of AML Enhancements released as part of SP12. You can use AML to set xProperty values and attributes such as their permission_id and explicit flag. For example:

<AML> <Item type="Part” id="816AEDE3506042C38211796A3581F4B9" action="edit"> <xp-shape set="value">Cylindrical</xp-shape> </Item> </AML>

Available options for the “set” attribute are “value”, “permission_id”, and “explicit”. It does not matter if the xProperty is defined or not. If you want to explicitly define the xProperty, you must use “explicit.” Use the “|” separator to set several operations at the same time:

<AML> <Item type="Part” id="816AEDE3506042C38211796A3581F4B9" action="edit">

 <xp-color set="value|permission_id|explicit” permission_id="A518B142B9CB4013A85392AA60AB7899" explicit="1">blue</xp-color> </Item> </AML>

The xClasses set on an Item are configured as relationships in AML using the pattern %itemtype_name%_xClass. The type name is automatically defined based on the name of the ItemType specified on the xClassification Tree. This means that the xClass name for the item type “Part” would be “Part_xClass.” For the “CAD” item type the xClass name would be “CAD_xClass”.

For example:

<Item type="Part” id="816AEDE3506042C38211796A3581F4B9" action="update">

<Relationships>

 <Item type="Part_xClass” id="CF3E37DFE57E451CB910FDFF6B429579" action="add">

 <related_id>51CF3CA830AD49BB97CE9C3553863A76</related_id>

 </Item>

 </Relationships>

</Item> 

Use the Is Define/Is Not Defined flags to filter items by their defined xProperties. The @defined_as attribute enables you to precisely specify how an xProperty is defined. The attribute uses the following allowed values:

• Class enables you to define an xProperty according to its classification. It does not matter if the xProperty is defined or not defined explicitly.
• Explicit enables you to define an xProperty explicitly. It does not matter if the xProperty is defined or defined using classification.
• Class|explicit enables you to define an xProperty both explicitly and using classification.

The following example retrieves all parts from the database where the xProperty is defined:

<AML>

<Item type="Part” action="get">

<xp-cost condition="is defined"/>

</Item>

</AML>

This example retrieves all parts from the database where the xProperty is explicitly defined:

<AML>

<Item type="Part” action="get">

<xp-cost condition="is defined” defined_as="explicit"/>

</Item>

</AML>

This example gets all the parts from the database where the xProperty is NOT defined using classification:

<AML>

<Item type="Part” action="get">

<xp-cost condition="is not defined” defined_as="class"/>

</Item>

</AML>

You can use the selected attribute’s extended syntax to get more information about defined xProperties. Use ‘xp-*’ to get all the xProperties defined for an item. You can also request additional information about xProperties by including the following special values in your request.

• Select=”xp-cost” returns a value
• Select=”xp-cost($value)” returns the monetary value associated with an item.
• Select=”xp-cost(permission_id)” returns the permission ID attribute but does not return a value.
• Select=”xp-*(@defined_as)” returns all defined xProperties but does not return a value.

The following example retrieves all Parts from the database. The response also includes the item_number and all defined xProperties:

Query:

<AML>

<Item type="Part” action="get” select="item_number, xp-*(@defined_as)"></Item>

</AML>

Return:

 <Item type="Part” typeId="3B135425…" id="0FA8ED…">

999-888

 <xp-length defined_as="class” is_null="0"/> 

 </Item>

 <item_number>999-777</item_number>

 <xp-width defined_as="class|explicit” is_null="0"/>

 <xp-height defined_as="explicit” is_null="0"/>

 </Item>

</Result>

The following example shows the information request for an item’s defined xProperties:

Query:

<Item type="Part” action="get” select="item_number, xp-cost($value, @permission_id, @explicit), xp-length($value, @permission_id, @explicit)">

</Item>

Return:

<Result>

 <item_number>999-888</item_number>

 <xp-cost explicit=“1">10</xp-cost>

 <xp-length permission_id="123...” explicit="0" />10<xp-length>

The following example shows the request for information about an item’s defined xProperty:

Query:

<Item type="Part” action="get” select="item_number, xp-*($value, @defined_as)"/>

The following example retrieves all the items in the database that are not Part where the xProperty cost is equal to 100:

 <Item type="xPropertyContainerItem” action="get">

100

 <Item type="ItemType” select="id">

 <name condition="ne">Part</name>

 </Item>

 </itemtype>

 </Item>

</AML>

You can use the condition="in” by="…" attributes to return any property for any item type. The following example finds all Type A items that reference type B items that have a cost greater than 10 associated with them:

In the following example, the user wants to retrieve all CADs with the same name as the PART items where the cost of the PART items is equal 100.

<AML> <Item type="CAD” action="get"> <name condition="in” by="name"> <Item type="Part” action="get” select="name"> <cost>100</cost> </Item> </name> </Item> </AML>

You do not have to specify condition="in” by="…" attributes for properties that have Item as the data type. The following code examples are equivalent:

<Item type="Part” action="get">

 <created_by_id>

 <Item type="User">…

<Item type="Part” action="get">

 <created_by_id condition="in” by="id">

 <Item type="User">…

Aras Innovator does not check to see if a polyitem has an xProperty associated with it. If an xProperty exists on a polymorphic item but does not exist on the poly source, a get query returns a Null value if you request an xProperty as part of an AML query as shown in the following example:

<AML>

<Item type="%AnyPolyItemType%" action="get” >

<xp-weight condition="le">1</xp-weight>

</Item>

</AML>

The following example is a query that returns the xClass Bolt and all of its descendants:

<AML>

<Item type="Part” action="get">

<Relationships>

<name>Bolt</name>

</Item>

</related_id>

</Item>

</Relationships>

</Item>

</AML>

[<filter_expression>] has been added to extend the @select attribute syntax. It returns a Boolean value that determines whether or not property should be added to the result. Use square brackets to define <filter_expression> after an explicit property name or “*”.

is_not_null() is the only valid filter expression used in AML. select=”*[is_not_null()]” means: add all properties into the response if property value is NOT NULL.

<Item type="A1" action="get” /> 

is equivalent to

 <Item type="A1" action="get” select="*[is_not_null()]"/>