Action – Get

AML Query

<!-- SOAP_ACTION = GetItem, ApplyAML, or ApplyItem -->
<Item type='{ItemType}' action='get'>
  <!-- Criteria -->
</Item>

Attributes

Attribute	Type	Usage
select	String	A comma delimited list of property names (column names) to return which is the SELECT clause in the SQL statement. You can select all properties with a single star * which will return is_null='1' for empty properties. Nested properties can be included as well, e.g. item_number,created_by_id(first_name,last_name). You can also select all properties of a nested property with created_by_id(*). If you need all properties of the parent and the nested then you must put the non-nested star at the end like created_by_id(*),*. In addition, you can choose to not return null values with syntax such as owned_by_id[is_not_null()],managed_by_id[is_not_null()], team_id,id. Extended properties can be retrieved with xp-* or by name. In addition, you can request extra data such as xp-*(@explicit,@defined_as,@permission_id,$value).
orderBy	String	A comma delimited list of property names (column names) to order the results and is the ORDER BY clause in the SQL statement, e.g. sort_order, created_on DESC.
page	Integer	The page number for the results set.
pagesize	Integer	The page size for the results set.
maxRecords	Integer	This defines the absolute maximum Items to be searched in the database.
levels	Integer	The Item configuration depth to be returned. This should be used with caution because of the performance hit due to its lack of granularity in the data fetched. Use the nested Relationships style of defining your queries to do the same thing but with far greater performance.
serverEvents	Boolean	If 0 then disable the server events improving performance. Default is 1.
isCriteria	Boolean	If 0 then include the nested structure for the Item configuration in the response but don't use it as search criteria. Default is 1, which uses the nested structure in the request as search criteria.
related_expand	Boolean	If 0 then do not expand the related_id Property for the relationship Items to include the related Item. Otherwise, only return its ID.
language	String	A comma-delimited list of language codes, or * to return all languages. Multilingual property values is returned (if present) for all specified languages.
queryType	String	Defines which version of a versionable item to return based on the queryDate. Valid values include Effective, Latest, Released. See Action: Get for more information.
queryDate	DateTime	Date to use when the queryType attribute is Latest or Released.
relas_only	Boolean	If 1, only return the contents of the <Relationships> tag and not the parent item. Default is 0.
stdProps	Boolean	Whether to include standard system properties. Default is 1. If 0, properties such as config_id, created_by_id, current_state, modified_by_id, and permission_id are not returned.
expand	Boolean
config_path	String
returnMode	String	Valid values are itemsOnly or countOnly. With itemsOnly, page count data (e.g. pagemax and itemmax will not be returned). With countOnly, item data will not be returned, but page count data will be returned. With any other value, item data will be returned and page count data will be returned if the page* attributes are used.

Examples

Get multiple items by ID

<Item type="Identity" action="get" select="id"
  idlist="F13AF7BC3D7A4084AF67AB7BF938C999,A73B655731924CD0B027E4F4D5FCC999,2618D6F5A90949BAA7E920D1B04C7999"/>

Versions

With versionable items, specific rules dictate which version/generation of a matching item is returned:

• If IDs are specified (as an id attribute, idlist attribute, or id element), then the versions with those specific IDs are returned.
• If generation criteria is specified, then all versions matching the criteria (including the generation criteria) will be returned. For example, to return all versions of a particular item, use a query such as <Item><config_id>@id</config_id><generation condition="gt">0</generation></Item>
• If the queryType attribute is specified, then the maximum matching version will be returned that also matches the following criteria. (In these examples, @queryDate is the value of the queryDate attribute.)
  • Latest: modified_on <= @queryDate
  • Released: release_date <= @queryDate
  • Effective: effective_date <= GetUtcDate() and is_released = 1 and (superseded_date is null or superseded_date > GetUtcDate())
• In all other situations, the generation where is_current = 1 is returned. Aras maintains this field such that it always maps to the record that has the maximum generation for any given config_id.

Item Analysis

In server method code, you can combine AML and SQL with a query such as

<Item type="{ItemType}" action="get">
  <id condition="in">(select id from innovator.[ItemType] ...)</id>
</Item>

As of 11sp9, this cannot be done from client queries. In particular:

• Allowed: <Item where="[Part].keyed_name = 'Test Part'">
• Not Allowed: <Item where="[Part].created_on > DateAdd(d, -7, GetUtcDate())"> The only functions allowed are GetDate and GetUtcDate
• Not Allowed: <Item where="[Part].id in (select id from ...)"> or <Item><id condition="in">(select id from ...)</id></Item> Sub-selects are no longer allowed.
• Not Allowed: <Item type="Method" action="CustomMethod" where="user_name = 'John'"> Properties which appear in the where clause must belong to the item type in the type attribute

This extra security can be bypassed if the SQL is white-listed with a file under {InstallPath}Innovator\Server\App_Data\ItemAnalysis.Suppressions.File.xml. Alternatively, you could disable item analysis completely in your Innovator Server Config with the parameter <operating_parameter key="parse_item" value="false" />

Pipeline

Event	Context
onBeforeGet	<Item action='get'> <!-- Criteria --> </Item>
onAfterGet	<Result> <Item id='1234'> <!-- Properties --> </Item> <Item id='4567'> <!-- Properties --> </Item> </Result>