IOM Reference

The IOM Reference provides a general description of the IOM (Innovator Object Model or Item Object Model) API. A more detailed API reference may be obtained from one of the following:

• On-line: Go to https://www.aras.com/support/documentation/

Under the section Other Documents, click On-Line API Guide.html.

• From Aras Innovator Client UI: Login as Innovator Administrator. Under the Help menu, select API Reference.
• In Aras Innovator CD Image: Go to the documentation folder and open Aras Innovator - API Guide.html.

The IOM is an Object Model for the AML, but it is not purely Object Oriented. Using Object Oriented terms, an ItemType is like a ‘Class’ and the Item is like an ‘Object’. Although the Item is an Object with methods, there is only one Item Class for all ItemTypes. In a pure Object-Oriented representation, there would be a Class for each ItemType because each ItemType has its own set of Properties to describe the different Items. An Item Object is intended to be abstract and pliable. Depending on its internal structure, the Item Object usually represents one of five following supported types of IOM Items:

• Single Aras Innovator Item of an arbitrary ItemType.
• Set of Aras Innovator Items, as in the case for results of the action ‘get’ when more than one Item returns.
• Error, as in the case when an action request results in an error from the Aras Innovator Server.
• Result to represent an arbitrary text wrapped by <Result> XML tags.
• Logical to represent a set of properties wrapped in a logical statement by one of logical XML tags: <or>, <and>, or <not>; usually used to specify the search criteria for the action ‘get’.

The IOM is intended to be a generic and compact API for modeling the Item structure of the AML as abstract Objects. Most of the methods for the IOM deal with memory management of the AML document for the Item Object. The AML is a script sent as a message to the Aras Innovator Server. The IOM is an Object API to build the AML messages, submit them to the Aras Innovator Server and parse an AML document that is returned by the Server. There are two major types of methods in the Item Class:

• methods that only work with an item’s AML in memory.
• methods that communicate with the Server, i.e., send request(s) to and get response(s) from the server.

All get\set type of methods as well as isXXX(...) (e.g. isError(), isCollection(), etc.) and add\nemove methods (e.g. addRelationship(...), removeProperty(...), etc.) belong to the former group. Methods like fetchXXX(...) (e.g. fetchLockStatus()), apply(...), email(...), promote(...), lock\unlockItem(...), etc. belong to the latter group. In case a method sends a request to the server it must be explicitly mentioned in the API reference method comments.

The IOMCredentials Class defines the login credentials for connecting to the Aras Innovator Server. The Item Class has a credentials public property, which is an IOMCredentials Object. Typically, you do not need to know about or deal with the credentials Object because the Methods run in a logged in session. You can, however, set the credentials for the Item Object using these methods, if you want to submit the apply requests to a different Aras Innovator server. The IOMCredentials Class methods are mostly getters and setters for URLs (Innovator and Vault servers), DB name, and login name and password.

In Innovator Class, methods like applyAML(…), applyMethod(…), and applySQL(…), being type Item, send the apply request to the Aras Innovator Server. In response, the Server creates XML that apply_ methods use to construct an Item Object to return; methods like getItemById(…) and getItemByKeyedName(…) search the database the logged in session is connected to, and methods like newItem(…), newError(…) and newResult(…) construct a new instance of the Item Object. Other members of this class perform miscellaneous non-Item related operations. Use them if you need to get a new GUID (methods getNewID() ), generate a next sequence value (method getNextSequence(…) ), or calculate the MD5 hash value for a given string (method ScalcMD5(…) .)

An Item Object can represent an Item, a set of Items, or an Error. The Item public constructor has one required argument itemtype-name and one optional argument action. The new Item is only populated with the Properties and default values from the ItemType when the optional action argument is ‘add’. The Item Class public field dom represents a DOM Object that holds the data for the Item in the AML format.

The Item Class base method apply(…)submits the AML apply request to the Aras Innovator Server using the context Item DOM as the AML source and returns a new Item built on the XML returned by the Server. In contrast, the base method loadAML(…) does not return a new Item but rather rebuilds this.dom using AML taken as an argument. You can call the clone(…)method to get a new identical instance of the context Item and you can call the setNewID() method to replace the context Item id by the newly generated GUID.

Use Call method isCollection()to find out whether or not the Item represents a set of Items, e. g. whether or not its dom property holds more than one Item node. Use Call isError()method to find out whether or not the Item represents an Error. See the IOM API on-line reference for more boolean members of the Item Class.

Methods such as getAction(), getID(), and getType() return a value of Item node action, id, and type attribute respectively, while method getAttribute(…) takes an attribute-name as an argument and, therefore, can be used to get any attribute by name. Thus, getAction()is a short cut to getAttribute(“action”), getID() is a short cut to getAttribute(“id”), and so on. Each get method in this group has a corresponding set method: setAction(…), setID(…),setType(…), and setAttribute(…). Notice that method setAttribute(…) not only sets a new value for an existing attribute but can also add a new attribute to the Item node and then sets its value.

Property methods comprise a set of accessors to Item properties and Item property’s attributes: get_, set_ (which acts also as add_), and remove_. In addition, if a property has/needs a nested Item there are methods to get/insert these nested Items. Accessors to Properties are getProperty(…), setProperty(…), and removeProperty(…).These methods take the property name as an argument. Accessors to Property’s attribute are getPropertyAttribute(…), setPropertyAttribute(…), and removePropertyAttribute(…). These methods take property and attribute names as arguments. The method setProperty(…)/setPropertyAttribute(…)not only sets a new value for an existing Item property/ property’s attributes but creates new property/ property’s attributes and then sets its value if the property/ property’s attributes with a given name does not yet exist. The setProperty method requires property values to be in a locale-neutral format. Decimal and float values should use the period symbol (.) as the decimal separator and no digit separator (i.e. commas separating thousands). The dash symbol (-) should be used to denote a negative value. Date/Time values should be in ‘YYYY-MM-DD[Thh:mm:ss]’ format and in the local (or corporate) time zone. Language-specific values should be set using the language code as the third argument. Accessors to a Property’s nested Item are: getPropertyItem(…), setPropertyItem(…), and createPropertyItem(…). All these methods take property name as an argument, and method setPropertyItem(…) needs, in addition, an Item Object as the second argument to create a DOM for the nested Item.

Relationship methods are made up of a set of Item’s relationship accessors: getRelationships(…), addRelationship(…), createRelationship(…), and removeRelationship(…). The difference between createRelationship(…) and addRelationship(…), two methods that both are adding an Item node to the Relationship parent node, is subtle. Let’s consider the following server-side C# method to illustrate how createRelationship(…) works:

Item myInnovator = this.getInnovator();

Item myItem = myInnovator.newItem(“myType”,"myAction”);

myItem.createRelationship(“User”,"add”);

This code results in the following myItem.dom XML:

<Item isNew="1" isTemp="1" type="myType” action="myAction">

 <Relationships>

 <Item isNew="1" isTemp="1" type="User” action="add” />

 </Relationships>

</Item>

Similar code that exercises addRelationship(…) methods is:

Item myInnovator = this.getInnovator();

Item myItem = myInnovator.newItem(“myType”,"myAction”);

Item relItem = myInnovator.newItem(“User”,"add”);

myItem.addRelationship(relItem)

And this code results in the following myItem XML:

<Item isNew="1" isTemp="1" type="myType” action="myAction">

 <Relationships>

 <Item isNew="1" isTemp="1" type="User” action="add” id="7EA3F18935CC493A900DAB63E839FDA2">

 <classification>/*</classification>

 <default_vault>67BBB9204FE84A8981ED8313049BA06C</default_vault>

 </Item>

 </Relationships>

</Item>

As you can see addRelationship(…) produces a more detailed Item node under the Relationship parent node. There are three methods getRelatedItem(…), setRelatedItem(…), and createRelatedItem(…) that are valid for relationship Items only and are used as a short cut to the Item.get/setPropertyItem() methods.

This group is comprised of methods to work with collections. Collection in this context is a set of Items as in the case for results from a query. The method appendItem(…) appends its Item Object argument to an existing collection or converts a single Item instance to a set of Items. This mechanism is illustrated in the following C# sample:

Innovator myInnovator = this.getInnovator();

Item myItem = myInnovator.newItem(“myType”,"myAction”);

At this point, myItem presents a single Item instance, myItem.dom XML looks like this:

<Item isNew="1" isTemp="1" type="myType” action="myAction” />

and myItem.isCollection() returns false. But three extra line of code:

Item addedItem = myInnovator.newItem(“added”,"myAction”);

// set ID to be able to remove addedItem later

addedItem.setID(myInnovator.getNewID());

myItem.appendItem(addedItem);

It converts myItem to a collection, e.g. myItem.isCollection() returns true, and myItem.dom XML becomes as follows:

 <AML>

 <Item isNew="1" isTemp="1" type="myType” action="myAction” />

 <Item isNew="1" isTemp="1" type="added” action="myAction” id="B12F9384B1DE4C4F8158C36D18269BE9" />

 </AML>

If the Item object id is not NULL it can be removed from the collection:

myItem.removeItem(addedItem); 

Use the getItemCount() method to determine the size of a collection, the getItemByIndex(…) method to get an instance of the Item Object based on its position inside of the collection, and method getItemsByXPath(…) to find an Item by its XPath.

The methods newOR(), newAND(), and newNOT() insert logical nodes with tag <or>, <and> and <not> respectively under the parent Item node and returns an Item Object that represents a newly inserted logical node. For example, the following code:

Innovator myInnovator = this.getInnovator();

Item myItem = myInnovator.newItem(“myType”,"myAction”);

Item logicalOR = myItem.newOR();

logicalOR.setProperty(“foo”, “bar”);

produces the following myItem.dom XML:

<Item isNew="1" isTemp="1" type="myType” action="myAction">

 <or>

 <foo>bar</foo>

 </or>

</Item>

The method removeLogical(…) removes a logical node specified by the method’s argument.

You can create a new item using method newItem(…). See code samples in sections 4.3.6-4.3.8 for the method usage illustration.

Error methods are comprised of a set of accessors to Error specific properties such as “faultcode” (methods get/setErrorCode(…),) “faultstring” (methods get/setErrorString(…) ,) “faultactor” (get/setErrorSource(…) ,) and “detail” (methods get/setErrorDetail(…) .) The code sample below:

Innovator myInnovator = this.getInnovator();

Item error = myInnovator.newError(“default detail”);

error.setErrorCode(“any number”);

error.setErrorString(“Hello, World”);

error.setErrorSource(“myMethod”); 

error.setErrorDetail(“new detail”);

produces the following Error Item DOM:

<Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 <Body>

 <Fault>

 <faultcode>any number</faultcode>

 <faultstring>Hello, World</faultstring> 

 <faultactor>myMethod</faultactor>

 <detail>new detail</detail>

 </Fault>

 </Body>

</Envelope>

This set of methods implements specific functionality on the Item, which extends the base Item Class. For reference purposes all the Extended Item Class methods are organized in the following four categories:

• Getting Innovator reference method:

getInnovator() – see examples of usage in section 4.2.

• Lock methods:

lockItem() unlockItem()

• Life Cycle method:

promote(…)

• Workflow methods:

instantiateWorkflow(…) The following methods are obsolete and will be removed from future releases: startWorkflow(…) –use Item.apply(“startWorkflow”) instead. cancelWorkflow(…) - use Item.apply(“CancelWorkflow”) instead. closeWorkflow(…) - use Item.apply(“closeWorkflow”) instead. The detailed characteristic and usage illustration of these methods is outside the scope of the document. See the on-line API reference for more details.