AML

AML must be written to support the multi-lingual properties and the locale neutral data. When querying for AML, you must understand the format of the return. When applying AML, you must be sure to apply multi-lingual values to the correct language, apply DateTimes in the correct time zone, and properties with locale neutral data must have the correct formats.

Multi-lingual properties should indicate the specific language being passed, if not the default (English). Multi-Lingual properties now contain the xml:lang attribute to indicate what language is returned.

Let us first consider a query with action=‘get’ from an English client.

<Item type="ItemType” id="B88C14B99EF44982…" action="get” select="label"/>

This query returns the label in the language of the client session established at the time of connection value of the label property. If there is no locale matching the client at the time the session is established, the default (English) is returned.

<Item type="ItemType” id=" B88C14B99EF44982…">

<label xml:lang="en">Document</label>

</Item>

From a German client, the return would include the German label

<Item type="ItemType” id="B88C14B99EF44982…">

<label xml:lang="de">Dokument</label>

</Item>

Requests may specify the language(s) desired in the response by including the ‘language’ attribute on the Item tag. The value of this attribute may either be a comma-delimited list of language codes or an asterisk (*) to request all languages.

<Item type="ItemType” id="B88C14B99EF44982…" action="get” select="label” language="en,de"/>

To return

<Item type="ItemType” id=" B88C14B99EF44982…" >

<i18n:label xml:lang="de” xmlns:i18n="http://www.aras.com/I18N">Dokument</i18n:label>

<i18n:label xml:lang="en” xmlns:i18n="http://www.aras.com/I18N">Document</i18n:label>

</Item>

If the language attribute is not present, the AML should be interpreted to be requesting session-language values for all multilingual properties. The fallback behavior is to return the default-language value for any property with no session-language value.

When adding or editing an Item through an AML query, the most important thing to keep in mind is that unless the namespace is defined, the session language is updated. This is either the language defined by the session locale, or the default(English) language for locales not defined in the Aras Innovator Database

<Item type="ItemType” id="B88C14B99EF44982…"action="edit">

<label>Document<label>

</Item>

The following is the result for an en-US session:

<Item type="ItemType” id=" B88C14B99EF44982…" >

<i18n:label xml:lang="de” is_null="1" xmlns:i18n=http://www.aras.com/I18N />

<i18n:label xml:lang="en” xmlns:i18n="http://www.aras.com/I18N">Document</i18n:label>

</Item>

While the same query displays the following result for a de-DE session:

<Item type="ItemType” id=" B88C14B99EF44982…" >

<i18n:label xml:lang="de” xmlns:i18n="http://www.aras.com/I18N">Document</i18n:label>

<i18n:label xml:lang="en” is_null="1" xmlns:i18n="http://www.aras.com/I18N” />

</Item>

In order to set a language value, other than the default, of a property you must specify the namespace as a property attribute.

<Item type="ItemType” id=" B88C14B99EF44982…" >

<i18n:label xml:lang="de” xmlns:i18n="http://www.aras.com/I18N">Dokument</i18n:label>

<i18n:label xml:lang="en” xmlns:i18n="http://www.aras.com/I18N">Document</i18n:label>

</Item>

If the namespace is not explicitly defined, then the value is assumed to be the value for the session language.

DateTime properties are passed to and from the Innovator Server in a neutral data format and the time zone may vary based on a fixed set of rules. DateTime values passed to\from the server don’t contain milliseconds as fractions of a second and are ignored by the Innovator. Milliseconds are saved on system properties.

When reading the returns of a query with action="get” there are two main rules to keep in mind.

• If the CorporateTimeZone variable is set in the database, refer to section Time Zones, then all DateTime properties are returned in the corporate time zone.
• If the CorporateTimeZone is NOT set, then all DateTime properties are returned in the local time zone of the client session that applied the AML.

This includes AML applied by methods executed as a result of client actions in the UI.

When applying AML to Aras Innovator, there are three main rules to keep in mind.

• If the CorporateTimeZone variable is set in the database, refer to section Time Zones, then all DateTime properties must be applied in the corporate time zone.
• If the CorporateTimeZone is NOT set, then all DateTime properties must be applied in the local time zone of the client session context that applied the AML.
• The DateTime applied in the AML must conform to the pattern yyyy-MM-dd[Thh:mm:ss]

This includes AML applied by methods executed because of client actions in the UI.

There is one special case when applying updates to datetime properties in AML to Aras Innovator. It is possible to specify ‘__now()’ as the value for properties of type datetime, instead of a specific value.

Example:

<Item type="Document” id="ACD123C46C1BFE8ED4E8BDDE0B009812">

<effective_date>__now()</effective_date>

</Item>

When a request similar to this is received by the server, it writes the value of the current moment of time into the database for the date property effective_date.

Date, decimal, and float properties are displayed in the Aras Innovator UI based on the patterns in the client sessions Regional and Language settings, however the AML does not follow this rule. AML for these property types is sent in a neutral data format.

An AML query with action=”get” returns date, decimal, and float properties in a data neutral format. Conversion of these values to a locale specific format should be done through client javascript.

<Item type="Test Item” id="D95C15B649AC46C1BFE8ED4E8BDDE0B0" action="get"/>

Returns

<Item type="Test Item” id="D95C15B649AC46C1BFE8ED4E8BDDE0B0">

<date_prop>2006-12-01T08:12:45</date_prop>

<decimal_prop>1234.56</decimal_prop>

<float_prop>-1234.56</float_prop>

</Item>

There are some external solutions where the AML returned must be in the patterned format, rather than the neutral data format. For these cases, you can use action=‘do_l10n’ initial_action=‘get’ to convert dates to the client session patterns. This is not recommended over the use of javascript on the client page, as it could have performance costs.

Example:

If you run the following query from a client with locale of ru-RU

<Item type="Test Item” id="D95C15B649AC46C1BFE8ED4E8BDDE0B0" action="do_l10n” initial_action="get/>

Aras Innovator returns

<Item type="Test Item” id="D95C15B649AC46C1BFE8ED4E8BDDE0B0">

<date_prop neutral_value="2006-12-01T08:12:45">01.12.2006</date_prop>

<decimal_prop neutral_value="1234.56">1234,56</decimal_prop>

<float_prop neutral_value="-1234.56">-1234,56</float_prop>

</Item>

Date, decimal, and float properties must be in a locale neutral data format for any applied AML query to Aras Innovator.

<Item type="Test Item” id="D95C15B649AC46C1BFE8ED4E8BDDE0B0" action="add">

<date_prop>2006-12-01T08:12:45</date_prop>

<decimal_prop>1234.56</decimal_prop>

<float_prop>-1234.56</float_prop>

</Item>