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)

• EVENT_DB_BEFORE_APPLY_STIMULUS
  • A stimulus is about to be applied to the current object
  • The following data are sent with the event:
    • 'stimulus' ⇒ the code of the stimulus to apply
    • 'previous_state' ⇒ the current state of the object
    • 'new_state' ⇒ the new state after the application of the stimulus
    • 'save_object' ⇒ flag to indicate if the object will be saved to DB after the application of the stimulus
• EVENT_DB_AFTER_APPLY_STIMULUS
  • Sent if the application of the stimulus was OK
  • The following data are sent with the event:
    • 'stimulus' ⇒ the code of the stimulus to apply
    • 'previous_state' ⇒ the previous state of the object
    • 'new_state' ⇒ the current state of the object
    • 'save_object' ⇒ flag to indicate if the object has been saved to DB after the application of the stimulus
• EVENT_DB_APPLY_STIMULUS_FAILED
  • Sent if the application of the stimulus failed
  • The following data are sent with the event:
    • 'stimulus' ⇒ the code of the stimulus to apply
    • 'previous_state' ⇒ the previous state of the object
    • 'new_state' ⇒ the target state of the object
    • 'action' ⇒ the action that failed for this stimulus