qbo.Application: IMethodListener

Background


Method listeners are called at the end of executing native operations. Method listeners should be used when real-time or near-real time performance is needed.

For example:
  • Email a user each time their password has been changed
  • Post a payment to a servicing system each time a payment is made
If you do not need immediate performance, consider using a data listener instead of a method listener.

The QBO Application module includes two standard classes that implement the IMethodListener interface:
  • OperationListener: executes some QBO 3 operation synchronously
  • QueueListener: queues some QBO 3 operation for asynchronous execution

Use Case: Password Change Emails

For security reasons, it may be useful to email a user each time their password is changed, just in case they did not initiate the password change. To configure this use case:
  • Create a Message Template called 'Password Change Email'
  • From Design > Configuration > Modules > Person > Method Listeners, create a new Listener called PasswordChange:
    • Name: Password Change Email
    • Type: qbo.Application.Listeners.QueueListener, qbo.Application
    • Methods: PasswordReset
    • MethodSignature: Message/Send?Template=Password Change Email&Object=Person&ObjectID={PersonID}&ToAddress={Person}

Use Case: Import Success Email Delivery

When an import is successfully complete, we may wish to send an email an administrator. To configure this use case:
  • From Design > Configuration > Modules > ImportFile > Method Listeners, create a new Listener called EmailOnSuccess:
    • Name: Email On Success
    • Type: qbo.Application.Listeners.QueueListener, qbo.Application
    • Method: Save
    • Parameters: Status=Complete
    • MethodSignature: Message/Send?ToAddress=admin@acme.com&Subject=Import {ImportFile} Completed on {UpdatedDate}&BodyText=All Done!
This may look nearly identical to the Password Change Emails use case above, with a notable difference: use of the Parameters property of a method listener. When specified, the Parameters are used to restrict when a MethodListener is fired. Specifically, each parameter required by a method listener is compared to the parameters passed to the Method (in this case: Save):
  • If a Listener.Parameter is specified and not present in the parameters passed to the Method, the listener is not fired
  • If a Listener.Parameter is specified and matches the parameters passed to the Method, the listener is fired
  • If a Listener.Parameter is specified as *, and it is present in the parameters passed to the Method, the listener is fired
Thus, in the example above:
  • calling ImportFile/Save?ID=X&Status=Awaiting Import would not fire the listener, since Status != "Complete"
  • calling ImportFile/Delete?ID=X&Status=Complete would not fire the listener, since Method != "Save"
  • calling ImportFile/Save?ID=X&Status=Complete would fire the listener


Comments