CRUD Extensibility with Events

CRUD extensibility refers to implementing a specific behavior when objects are Created, Updated or Deleted. This implementation assumes a piece of PHP code, injected by several means (See the related documentation).

• Why using events rather than previous methods?

Registering listeners for the different CRUD events allows to add features during ORM operations.

Registering events can be done in several ways: How to add events and listen to them to react.

To find the complete list of events available on a given class go the the Datamodel in iTop, open the class and go the the tab events

• Listening to an event and react

For each of the above events, you will find

• what data are provided with the event, data which can be used within the callback PHP method. The method always receive a single object which is the event itself. And the event has properties which you can get

Compute object fields when object is modified (can be called outside CRUD)

• EVENT_DB_COMPUTE_VALUES

The current object can be modified, therefore it is not necessary to call DBWrite() to save the modifications because the object is going to be written to the database.

• 'object' is the current object

• All the parent classes of the current object (up to cmdbAbstractObject)

• The current changes are available with DBObject::ListChanges()

Before the requested operation is started. In this phase, it is possible to modify the current object.

• EVENT_DB_BEFORE_WRITE
• EVENT_DB_ABOUT_TO_DELETE

• For CREATE and UPDATE it is possible to modify the object values.
• For DELETE the object is guaranteed to be deleted from the database. It is yet available, but read-only.

• 'is_new' if the object is in creation
• 'object' is the current object

• All the parent classes of the current object (up to cmdbAbstractObject)

Check if the requested operation is valid for this object. This can be called outside of CRUD by the console to check the uniqueness rules.

• EVENT_DB_CHECK_TO_WRITE
• EVENT_DB_CHECK_TO_DELETE

The object MUST NOT be modified at this point.

Attempting a call to Set() on any of the object field will throw a CoreException.

• 'object' is the current object
• 'is_new' if the object is in creation
• 'deletion_plan' is the current DeletionPlan to check for EVENT_DB_CHECK_TO_DELETE

• All the parent classes of the current object (up to cmdbAbstractObject)

• The current changes are available with DBObject::ListChanges()
• Problems can be reported using DBObject::AddCheckIssue() or DBObject::AddDeleteIssue(), this will prevent the object to be written to or deleted from the database.
• Warnings can be reported using DBObject::AddCheckWarning(), this won't prevent the object to be written to or deleted from the database.

The requested operation has been done in database. In this phase, it is possible to propagate the modifications to other objects.

• EVENT_DB_AFTER_WRITE
• EVENT_DB_AFTER_DELETE

For CREATE and UPDATE it is possible to modify again the object values, therefore it is not necessary to call DBWrite() to save the modifications because if the object is modified during this phase, a deferred DBUpdate() will be called. In this case the complete UPDATE process will be run again (with all the events).

• 'changes' array contains the changes done during this update (for UPDATE)
• 'is_new' if the object is in creation
• 'object' is the current object

• All the parent classes of the current object (up to cmdbAbstractObject)

For UPDATE, The current changes are also available with ListPreviousValuesForUpdatedAttributes()

When an n-n link is created, updated or deleted, all the objects linked (and also the objects previously linked in case of modification) are notified with the event.

• EVENT_DB_LINKS_CHANGED

The object can be modified at this point and a DBUpdate() is necessary to persist the modifications.

• 'object' is the linked object

• All the parent classes of the linked object (up to cmdbAbstractObject)

New in 3.1.2

Manage the allowed transitions. It only permits to reduce the allowed transitions in current object state.

• EVENT_ENUM_TRANSITIONS

• 'object' The object where the stimulus is targeted
• 'allowed_stimuli' The list of available stimuli in the current state

• All the parent classes of the current object (up to cmdbAbstractObject) have a life cycle

• The only action possible is to deny transitions with DBObject::DenyTransition()