Server Events

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 Available Server Events.

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.

C#

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.

Code sample below demonstrates custom Onlock event handler, which consists of 3 steps:

1. Method “ValidateInput” validates input item before lock action.
2. “eventData.BaseLockItem(outDom)” call executes default Innovator OnLock handler, which mark corresponding database items as locked and call OnBeforeLock and OnAfterlock event handlers.
3. Method “PostProcessOutput” changes output AML after items have locked.

If itemtype has no assigned OnLock handlers, default lock implementation consists of only second step, called by Innovator. First and third steps represent custom additional business logic.

It is possible not to call second step at all (for example, for federated itemtypes, which do not have corresponding database tables). However, in such case OnBeforeLock and OnAfterlock event handlers will not be called.

//MethodTemplateName=CSharpInOut;
  ValidateInput(inDom, eventData);
  // call base implementation with Before- and After- events
  eventData.BaseLockItem(outDom);
  PostProcessOutput(outDom);
}
private void ValidateInput(XmlDocument inDom)
{
  // perform input AML validation
}
private void PostProcessOutput(XmlDocument outDom)
{
  // perform output AML post-processing

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 <Item …> 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.