Methods

Business logic in Aras Innovator is implemented using Method Items and is written in JavaScript, C#, or VB.NET often using the IOM to interact with Aras Innovator Items.

There are three ways to implement Methods in Aras Innovator on the server side:

• Item Action Methods which extend the Item Class and perform logic on Item instances.
• Generic Methods, which implement arbitrary logic.
• Server Events which implement logic on the context Item before and\or after the server operates on the Item.

Similarly, there are three ways to implement Methods in Aras Innovator on the client side:

• Item Methods which extend the Item Class and perform logic on Item instances.
• Generic Methods, which implement arbitrary logic.
• Form, Field, and Grid Events which implement logic on client-side UI events.
• Client Events that can be attached to an Item Type; triggered when a user’s interaction with the Aras Innovator UI generates a new Item.

The Method Item has a comment Property that you can use to annotate the Method and can be seen when you search and review the Methods as mentioned above.

One purpose for Methods is to extend the Item Class. Methods extend the Item Class when they are bound as the related Item for ‘Item Action’ relationships on the ItemType. In the AML the Method name is the action attribute name for the Item tag.

<Item type="My ItemType” action="My Method” id="…"/>

The Method could be called using the IOM like this (all three examples below are equivalent and are written in C#):

1) Item myItem = this.newItem(“My ItemType”, “My Method”);

 myItem.setID(this.getID());

 Item results = myItem.apply();

2) Item myItem = this.newItem(“My ItemType”);

 myItem.setID(this.getID());

 Item results = myItem.apply(“My Method”); 

3) Item myItem = this.newItem();

 myItem.setID(this.getID());

 myItem.setType(“My ItemType”);

 myItem.setAction(“My Method”);

 Item results = myItem.apply();

As mentioned before Item Action Methods are executed on an instance of Item which is called a context item (read section 4.2 Built in Action Methods for more information on how a context item is obtained for Item Action Methods). The context item must be referenced inside Item Action Methods as this keyword in JavaScript, and C#, and the Me keyword Object in VB.NET. The context item is an instance of the IOM Item class; correspondingly any methods of the IOM Item class (see section 4.3 for more details) could be called on the context item, e.g this.getProperty(“foo”) (C#) or Me.getProperty(“foo”) (VB.NET).

Methods follow the Factory design pattern in that they return an Item or Error Object. The ‘Item Action’ Method must return an Item, which often is the result of an Item.apply() method call; typically, the last step in the business logic for the Method. There are several ways to create an Item; the following IOM methods return an Item Object: Item.apply(), Item.newItem(), Item.clone(), Innovator.newItem(), Innovator.newResult(), and Innovator.newError().

Item qryItem = this.newItem(this.getType(), “get”);

qryItem.setID(this.getID());

qryItem.setLevels(1);

return qryItem.apply();

If the Method needs to return an error then use the Innovator.newError(text) method.

Innovator innovator = this.getInnovator();

return innovator.newError(“This method has <b>failed</b>.”);

Sometimes it is desirable to share the same Method for many ItemTypes. However, there are cases in which the Method is intended to be used only by an Item of a specific ItemType.

The way you can prevent the use of a Method with a context item of a wrong type is to throw an exception when the wrong ItemType is used (this is what the core Item Class methods do when the ItemType is not of the specific desired value). Here is a sample of what should be done in a Method that needs to operate on a specific type of Item:

Innovator innovator = this.getInnovator();

if (this.getType() != “My ItemType”)

{

 return innovator.newError(“Item must be of type ‘My ItemType’”);

}

return null;

One of the principal concepts in programming Aras Innovator is to write Methods called on Items. The ‘Item Action’ relationships on ItemTypes simulate Object Oriented programming, where the ItemType is the Class and ‘Item Action’ relationships to Methods are the Class methods. Literally the Method code is compiled dynamically to extend the Item Class with this method and calls it. Like class instance in OO programming the context item is an object on which Methods are performed. At the same time there are some peculiarities in how to use a context item in Aras Innovator’s Item Action Methods. One important detail about Item Action Methods is that they must always return an Item which is the result of work done by the Item Action Method. An Item Action Method might work with a context item, but the context item is used here more as an input value (it still must be referenced as this or Me from inside Methods). It’s highly recommended that Item Action Methods do not change the context item but rather create a new item that is returned from the method. You can use the combination of the Item.getProperty(…) method with the Item.setProperty(…) method to populate the new temporary Item or use the Item.clone(…) method to construct the new Item from the context item. If the developer of the Method code chooses to modify the context item and not create a new item, the context item must be returned from the method.

The Method name is passed as the action attribute for the <Item> tag in AML.

<Item type="My ItemType” action="My Method” id="…"/>

In addition to Method names as the action attribute value there is also a set of ‘Built in Action Methods’. These are basically the same as Methods, but you cannot find them in the database when searching the Method Items. Nevertheless, they are called the same way as ordinary Methods via the action attribute.

The following table is a reference for Built in Action Methods.

Generic Methods are used to perform arbitrary business logic. They can be used to perform any logic you require, and its input Item is up to you. They are called in the IOM with the Innovator.applyMethod(…) method.

The context Item is this keyword Object in JavaScript and C# and is the Me Object in VB.NET. The XML data for the context Item is the XML submitted as the payload for the request and it may not be valid AML, just well formatted XML. It does not matter it is the input for the Generic Method and can be whatever you want it to be.

The Generic Method must return an Item or an Error like ‘Item Action’ Methods. Often the result of the Generic Method is some simple text or an HTML fragment. The text can be returned using the Innovator.newResult(text) method. If the Method needs to return an Error use Innovator.newError(text) method.

Innovator innovator = this.getInnovator();

return innovator.newResult(“This method was <b>successful</b>.”);

OR

Innovator innovator = this.getInnovator();

return innovator.newError(“This method has <b>failed</b>.”);

Innovator innovator = this.getInnovator();

Item item = this.newItem(“User”, “get”);

Item results = item.apply();

int count = results.getItemCount();

if (count<1) return innovator.newError(“No users found.”);

StringBuilder content = new StringBuilder();

content.Append("<table>");

for (int i=0; i<count; ++i)

{

 Item user = results.getItemByIndex(i);

 content.Append("<tr><td>Login Name:</td><td>");

 content.Append(user.getProperty(“login_name”));

 content.Append("</td></tr>");

}

content.Append("</table>");

return innovator.newResult(content.ToString()); 

Typically, all you need are simple name/value pairs as input for your Method and those are like Property tags for the Item. The body for the Generic Method is nested inside an <Item> tag so you can pass a name/value pair as arguments to the Generic Methods like ordinary Property tags.

The Item passed as the context Item can represent any Item you want including fictitious Items. You have the added advantage of continuing to use the IOM API to operate on the context Item Object.

The purpose of Server Event Methods is to perform some custom actions either before (OnBeforeXXX) or after (OnAfterXXX) a particular server action (like add, delete, etc.) or fully replace the action processing on server (OnXXX). Detailed information about Aras Innovator server events can be found in section 5.4.3.

In the case of the Server Event Method, the context item is a direct analogy of a class instance (i.e., object) in OO programming in the sense that the Method operates on its context item (as it was mentioned above the context item could be referenced as this keyword in JavaScript and C#, and the Me keyword Object in VB.NET from inside the Method). In other words, the purpose of a Server Event can be defined as ‘changing the context item’, so the modified context item is the result of work done by the Server Event Method. Of course, the Server Event Method doesn’t necessarily have to alter its context item but rather perform some other actions (e.g. log some info; send e-mail; etc.); this is usually typical for Methods performed on OnAfterXXX event.

A Server Event Method might return an Item only if it wants to return an error. Otherwise, the Server Event Method may not have a return statement.

Innovator innovator = this.getInnovator();

return innovator.newError(“This method failed.”);

In the case where a Method is called as the OnBeforeXXX event and it returns an error, the context Item is replaced with an Error Item and is simply passed on through to the client. No further server action is taken. In the case of an OnAfterXXX event the server rolls back the transaction and passes the Error back on through to the client.

It’s important to understand that Server Event Methods that are called on OnBeforeXXX events operate on the request AML sent from the client. Server Event Methods that are called on OnAfterXXX events operate on the response AML that the server is about to send back to the client and Server Event Methods that fully replace server actions (OnXXX) get client request AML as a context item and must replace it with the response AML that is passed on through to the client. In other words, it’s important to remember that Server Event Methods called on OnBeforeXXX events are invoked before the server parses the request and after the Method is done the context item must have a valid request AML format (it could be modified by the method, but it still should have a valid format so that server would be able to parse it). From the other side, Server Event Methods called on OnAfterXXX events are invoked after the server processed the request, and after the Method is done the context item must have a valid response AML format (it could be modified, e.g., Method could populate it with federated data, but it should be valid response AML, so that the client is able to parse it.)

The following Server Events are currently available in Aras Innovator. Each of the following events is followed by a short description and an example of common use.

• OnBeforeAdd
• Runs before an item is added to the database (through the add, create, or merge actions.)
• OnBeforeAdd methods are often used for validation purposes (e.g., to make sure the property values do not violate a business rule). The same method that is called OnBeforeAdd is often also called OnBeforeUpdate, to perform the same validation.
• OnAfterAdd
• Runs after an item is added to the database (through the add, create, or merge actions), but before it is returned to the client.
• OnAfterAdd methods are used to synchronize with other items or with external systems (e.g., add a new part number to ERP).
• OnAdd
• Runs in place of the built-in add action (via add, create or merge). Neither OnBeforeAdd nor OnAfterAdd events are called when using OnAdd.
• An OnAdd method completely replaces the built-in add action and is typically used for federated items. The method is expected to create the appropriate records in the database and form a proper AML response. Failure to do either is likely to result in an error.
• OnBeforeUpdate
• Runs before an item is updated in the database (through the update, edit or merge actions.)
• OnBeforeUpdate methods are often used for validation purposes (often along with OnBeforeAdd). The request may either be rejected completely (by returning an error) or modified to conform to the proper rules.
• OnAfterUpdate
• Runs after an item is updated in the database (through the update, edit or merge actions), but before it is returned to the client.
• OnAfterUpdate methods can be used to synchronize with other items or with external systems (e.g., updating a part description in ERP).
• OnUpdate
• Runs in place of the built-in update action (via update, edit or merge). Neither OnBeforeUpdate nor OnAfterUpdate events are called when using OnUpdate.
• An OnUpdate method completely replaces the built-in update action and would typically be used for federated items. The method is expected to modify the appropriate records in the database and form a proper AML response.
• OnBeforeDelete
• Runs before an item is deleted (through the delete or purge actions.)
• OnBeforeDelete methods are typically used to cancel a delete operation based on a business rule.
• OnAfterDelete
• Runs after an item is deleted (through the delete or purge actions.)
• OnAfterDelete methods would be used to synchronize with other items or with external systems (e.g., remove a record from ERP.)
• OnDelete
• Runs in place of the built-in delete action. Neither OnBeforeDelete or OnAfterDelete events are called when using OnDelete.
• An OnDelete method completely replaces the built-in delete action and is typically used for federated items. The method is expected to remove the appropriate records in the database and form a proper response.
• OnBeforeGet
• Runs before a search.
• OnBeforeGet methods are typically used to add additional criteria to a search, based on business rules. For example, the method might find the default location of the user and add that location as criteria for the query.
• OnAfterGet
• Runs after a search is executed, but before the results are returned.
• OnAfterGet methods are commonly used to populate federated properties. This might involve performing calculations on other properties or extracting data from an external system. Once the value of the federated property is set, it appears to the client like any other property.
• OnGet
• Runs in place of the built-in get action. Neither OnBeforeGet nor OnAfterGet events are called when using OnGet.
• An OnGet method completely replaces the built-in get action and is typically used for federated items. The method is expected to retrieve the appropriate records in the database and form a proper AML response.
• OnBeforeCopy
• Runs before an item is copied (via the copy action.)
• An OnBeforeCopy method might be used to cancel a copy operation that violates a business rule.
• OnAfterCopy
• Runs before an item is copied (via the copy action.)
• OnAfterCopy methods can be used to set properties of the new item created by the copy.
• OnBeforeLock
• Runs before an item is locked (via the lock or edit actions)
• An OnBeforeLock method may be used to prevent an item from being locked based on business rules.
• OnAfterLock
• Runs after an item is locked (via the lock or edit actions.)
• OnAfterLock methods may be used to synchronize locks with other items.
• OnBeforeUnlock
• Runs before an item is unlocked.
• An OnBeforeUnlock method may be used to prevent an item from being unlocked based on business rules.
• OnAfterUnlock
• Runs after an item is unlocked.
• OnAfterUnlock methods may be used to synchronize locks with other items.
• OnBeforeVersion
• Runs before an item is versioned (through the version, update, edit or merge actions.)
• OnBeforeVersion methods are typically used to cancel a version operation based on a business rule.
• OnAfterVersion
• Runs after an item is versioned (through the version, update, edit or merge actions.)
• An OnAfterVersion method might be used to set properties of the new item version.
• OnBeforeMethod
• Runs before Server Action Method.
• OnAfterMethod
• Runs after Server Action Method.
• OnGetKeyedName
• Runs when the system generates the keyed_name for an item.
• Used to override the standard logic for generating keyed names.

Administrators can define a server event against a Polymorphic ItemType. The benefits of defining the server event against the Polymorphic ItemType is that the event will be processed for all poly-sources.

For example, if you want a single server event to be triggered against all CAD, Document, and Part ItemTypes, you could simply add an event handler to a server event on the Change Controlled Item ItemType. Once defined against the Polymorphic ItemType, all poly sources will inherit the event handler which will be executed every time the event occurs on any of poly sources.

You can view all inherited methods against an ItemType by selecting the Inherited Server Events tab for the ItemType you are working with.

Administrators can mark a server event as “required”. Server Events that are marked as required cannot be ignored by using the serverEvents=0 attribute as part of AML request.

To set a server event as required, so that it is not ignored, you need to set the is_required Boolean property to 1 for the ServerEvent.

The new version of server events allows for improved performance when there is a group of items passed to be acted upon.

By default, all server events follow the standard behavior that has been seen in previous releases of Aras Innovator (Version 1). The new version (Version 2) is described for each operation in the following sections.

The onAfterUpdate, onAfterAdd, and onAfterVersion Version 2 event is designed for use when the where or idList attribute is specified on the node of the AML request. The server event is executed only once for the entire group, as opposed to once per item as the Version 1 event does. The context item contains the results of all the items applied as part of the update statement.

When a source item is versioned or is cloned it forces cloning of all existing relationships that belong to the Item. The onBeforeCopy and onAfterCopy Version 2 allows for onBeforeCopy and onAfterCopy server events to be triggered on the relationship items when a version/copy of a parent item exits. These events are not triggered on a Version 1 server event. These events should be placed on the is_relationship=1 ItemType.

There are several Events available on the client side, including:

• Form Events
• Field Events
• Grid Events
• Data Store Events
• Item Type Events
• Item Actions

The this keyword context Object is an Item Object for Item Actions. However, the context Object is not the Item Object for Form, Field, and Grid Events. This context Object is the browser document (DOM) Object for the Form and Grid Events and is the Field Object for Field Events.

The context Item Object for Form, Grid, and Field Events is the document.thisItem Object, which is an Item Object and should be used with the IOM API. For relationship grid events use parent.thisItem, which is a pointer to the document.thisItem Object.

The Form Events are the HTML page events; for example, onLoad, onUnload, onResize, onMouseDown, onMouseUp, and others (refer to the ‘Form Events’ List in Aras Innovator for the complete list of available events.)

You bind your Method to the Form Event using the Form Tool. Select the Form Event tab and add the event relationships as shown below:

The Field Events are the HTML field events; for example, onSelect, onClick, onChange, onBlur, onFocus, and others (refer to the ‘Field Events’ List in Aras Innovator for the complete list of available events.) Use the following procedure:

1. Bind your Method to the Field Event using the Form Tool.
2. Select the Field by clicking on it in the canvas area in form Tool or from the Fields grid in the upper left-hand corner of the Form Tool.
3. Select the Field Event tab and add the event relationships as shown here:

Grid Events are the events for the grid control, which is used in the Relationships tab area for tear off Item windows. The grid events occur on the row (section 5.5.4.1) and on the cell (section 5.5.4.2.)

Like Server Events you bind a Method as the callback for the event as the Grid Event relationship on the RelationshipType Item, and as the Grid Event relationship on the Property Item.

The Method gets at least three arguments: relationshipID, relatedID, gridApplet. The relationshipID is the ID for the relationship Item for the selected row. The relatedID is the ID for the related Item for the selected row. And the gridApplet is a handle to the grid control object. The relatedID may be empty if there is no related Item for the relationship row. The relationshipID is also the ID for the grid control row. Edit the RelationshipType Item and add Grid Events relationships as shown here:

The row events include:

The Method for the event is called with three arguments:

Edit the Property Item and add Event relationships as shown here:

The cell events include:

The Method for the event is called with five arguments:

Data Store Events are client-side events that trigger when the Aras Innovator client tries to update its internal data store. The data store is a mechanism that helps sync the state of data across the client. This means that a data store event will trigger regardless of the UI control that updates the data store. So instead of creating multiple client events for grids, forms, fields, etc., a developer can create a single event that will execute if data is updated in any of those controls.

There are 2 event types implemented for the data store.

• Validate: Method runs prior to updating the property in the data store. The method logic may cancel the update and return an error message to the user.
• Change: Method runs after a property has been updated in the data store. The method logic may manipulate the item in the data store.

Data store events are configured similarly to grid cell events – on an ItemType’s properties.



It is important to note the following about data store events:

• Data store events are client-side events and do not directly update the data in the database.
• Data store events cannot directly manipulate UI controls in the client. For example, a Validate data store event could prevent a user from updating a property and return an error message telling them why. However, the event could not disable a grid cell or form field for the property, because those are UI controls.
• Data store events should not be configured on the properties of Poly ItemTypes. These events should be configured on the properties of the poly source ItemTypes instead.

Client Events that can be attached to an Item Type are triggered when your UI actions generate a new Item. These events are triggered from the client interface regardless of UI context or where in the GUI the new Item creation was initialized. These events would be triggered universally from the Main Menu, the TOC RMB menu, the Main Grid RMB menu, Relationship Grid, etc. For Item Type new item creation, 3 events have been implemented. One event is triggered before a new Item is created; another event is triggered after an Item has been created; the third event replaces the standard client ‘new Item’ logic.

• onBeforeNew: Method runs prior to a new Item creation. It can cancel subsequent client operations (i.e., form opening). It can cancel creation of new Items.

This event is often used to validate current conditions and determine if it is ok to create a new Item.

• onAfterNew: Method runs after a new Item is created. Subsequent standard client logic is executed following method completion (i.e., form opening). Method is passed a new Item.

This event is often used to populate a new item with data and open custom dialogs.

• onNew: The method replaces the standard ‘new Item’ client behavior.

This event is used in special situations where a solution must maintain full control over the new Item creation process.

The Methods related to the ItemType via the ‘Item Action’ relationship are called via the action attribute and the Item.apply() method. Review them by searching the ‘Item Actions’ Tab on the ItemType. The Methods related to the ItemType via the ‘Server Event’ relationship are called by the server as pre and post event callbacks for the primitive server actions: add, update, delete, and get. Review them by searching the ‘Server Events’ Tab on the ItemType. Review the Generic Methods by searching the Method Items.