Categories
Related

An Overview of Server-Side Method Events

Sam Poe
An Overview of Server-Side Method Events

So you’re a programmer with an installation of Aras Innovator and you’ve built this amazing server-side method. You want to replace some AML calls to do that one thing, just the way your company needs… how do you go about attaching it to the process? You set an Event.

So, what’s this Event thing?

Server (or Client, but that’s a different blog post) Events are methods that are triggered by a particular system action, whether that is a Get, Edit, Save, et cetera. Setting another method on these events will extend or override the existing system functions. Events can be set at the Itemtype, Lifecycle, Workflow, and other levels. For the purposes of this blog post, we are going to work with Itemtype Events. You can add a Server Event from the tab of that name from the Itemtype’s definition.


There are 3 main types of Events in this category: Before, After and On. Before Events are typically used for validation. After Events are used to extend the processing of a returned AML statement after the response has been sent to the client. On Events override standard system behavior and are very complex to create as you must completely replace the behavior you are overriding as the system will no longer employ the out of the box methods for those events.

Generally, the Events fire in the following order:

  1. You make open or otherwise interact with an item.

  2. You click the button for the event in the UI. (New Item, Save, etc.)

  3. The OnBefore event is called.

  4. The OnX system function is called and the item is saved to or requested from the DB.

  5. The OnAfter event is called.

  6. A server response occurs, usually in the form of a SOAP message.

Lets cover the possibilities by group next, after a note about event versions:

Concerning Event Versions

The Event versions are something that was added to Aras version 11. Version 1 causes all events to execute normally, however Version 2 makes some specific changes:

  1. OnAfterAdd, OnAfterUpdate, and OnAfterVersion are amended so that they will only run once per modification action, instead of once per item listed.

  2. OnBefore and OnAfterCopy events will clone or version both the item, and the relationships attached to it, as compared to the normal usage that only replicated the item selected.

OK, back to the Events, I’ve provided some examples below to help make sense of them:

Add

  • OnBeforeAdd:

    • This is going to be for validation, essentially, does this new Item contain all the requested data in the proper format before it can be saved? If not, warn the user and do not complete the add statement.

  • OnAfterAdd:

    • A quick example here would be throwing in an email notification that the item was created successfully.

  • OnAdd:

    • The probable case for overriding the Add method would be federation, and telling the system to add by pulling the relevant data from another system.

Update and Version

Note: Update actions will also trigger versioning if enabled.

  • OnBeforeUpdate:

    • Reason: validation. Is all the right stuff there? If No, cancel and inform the user.

  • OnAfterUpdate:

    • Formatting the data the user sees that needs to be different than what was returned from the AML.

  • OnUpdate:

    • This is used in federation to pull info from an outside source into the Aras system.

  • OnBeforeVersion:

    • Validate that there are still numerals left in the versioning schema to use, otherwise cancel action and warn user.

  • OnAfterVersion:

    • Write to a log file that the current user created a new version at the current timestamp.

Delete

  • OnBeforeDelete:

    • This can be used to cache a deleted item either to another system or for output in an email notification after the delete happens (you can send an email using an OnAfterDelete method).

  • OnAfterDelete:

    • This would be used for any cleanup the system may miss, perhaps deleting related items or comments that are bound indirectly to the item but need to be removed when it is.

  • OnDelete:

    • Federation usage: remove item from both systems.

Get

  • OnBeforeGet:

    • Use this to verify a get query before running it. Especially if you are using some form of federation, you want to make sure the data exists before querying it.

    • Another example here would be validating permissions on some kind of external or even internal access, if you need to go beyond the standard permissions model.

  • OnAfterGet:

    • You can use this to show a response page or a count of returned items outside system parameters.

  • OnGet:

    • Probably the only case in which you want to override the get function is in a federated environment and need to query data in a non-standard manner.

Promote

  • OnBeforePromote:

    • Validate data exists before allowing the status change.

  • OnAfterPromote:

    • After promotion, change form displayed to another that shows different data, per the new state.

  • OnPromote:

    • Federation usage: change the state of the item in both databases.

Copy (AKA Cloning or Save As…)

Copying an item will also trigger an Add event.

  • OnBeforeCopy:

    • Verify the user is from an expected permissions group, otherwise cancel action and warn user.

  • OnAfterCopy:

    • Append a comment to show the item was branched from original item N.

Lock and Unlock

  • OnBeforeLock:

    • Validate with the user has permissions or the item is in the correct state to be edited.

  • OnAfterLock:

    • Write to a log file that the current user locked the item at the current timestamp.

  • OnBeforeUnlock:

    • Validate the user has saved their changes recently.

  • OnAfterUnlock:

    • Write to a log file that the current user unlocked the item at the current timestamp.

Method

These Events are triggered by an AML statement where the action is a custom method. The other side of this, is that this event will fire on any custom statement without some bypass logic in the code. I will leave this case to expert users who need it.

Special Event: GetKeyedName

There is one last Event that is non-standard: you can override the GetKeyedName event to assign a keyed name of your own devising. This will override the Keyed Name Order, if one was set, in the system as well. This event happens whenever an item is added or updated.

A Note on Event Ordering

The Event Ordering field gets its own section as it can easily break things and I also need to cover how to debug it. Generally speaking, the events you have listed will execute in the order listed. The main usage being if you have multiple instances of the same event and need them to fire in a specific order, such as an OnBeforeUpdate method for a specific Itemtype and then a general OnBeforeUpdate method for all Itemtype in your organization. The odd case is events that trigger multiple actions, such as Update and Copy which can also call Version and Add events alongside themselves. You might need to order these very specifically, and to debug them the best way is to add a line with a WriteDebug or StreamWriter call to log the order that events are actually executing in and then correct the ordering error via the field. As always, it is best to test functionality in another environment before loading new methods onto a production server.

Wrap Up

Well, that should cover almost everything on the list, the dropdown list anyway. If you're using 11.0 SP15+, you may notice some additional events not covered in this blog. These events are specific to the new synchronization actions added with Data Snyc Services (DSS) in 11.0 SP15. You can read more in the blog post here, and find some tips on writing server-side methods here. Oh and one more thing regarding AML and events: calling any of the above actions via AML will also trigger all of the above events, running the statement is the same as clicking the button, so if you are doing a lot of batch running of statements, you need to account for your event triggers.

Any further questions? Let us know in the comments, or on the Forums.