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