Sample Scenario 2: Notification of Changes to an Existing Record - Changing the Credit Limit

You want to create an application event and handler that notifies the credit manager whenever a customer’s credit limit is changed. Because the credit manager prefers email and is not always signed in to the system, you want to send the notification as an email.

Note: For this scenario to work properly, you must enable and configure SMTP on the Intranets form of the application (utility) server. You must set up your SMTP server to relay the emails that are sent. For information on how to do this, consult your Windows operating system documentation. Finally, any recipients must also have email addresses saved as part of their user profiles.

You can use an existing framework event, IdoOnItemUpdate, and create our own handler. Because you are simply sending out a notification and the system is not waiting for a response from the credit manager, you can make an asynchronous event handler.

This event handler requires two actions:

Checks whether the Credit Limit field has been changed
Sends the email notification

To accomplish this scenario:

Create the event handler:
1. Open the Event Handlers form.
2. Press F3.
3. Press Ctrl + N.
4. Create the handler with these settings:
  
  Event Name
  
  Select IdoOnItemUpdate.
  
  Applies to Initiators
  
  Leave this field blank.
  
  Applies to Objects
  
  Specify SLCustomers.
  
  Keep With
  
  Leave this field blank.
  
  Chronology
  
  Leave this field blank.
  
  Initial State
  
  Leave this field blank.
  
  Initial Action
  
  Leave this field blank.
  
  Active
  
  Select this check box.
  
  Can Override
  
  Select this check box.
  
  Ignore Failure
  
  Clear this check box.
  
  Suspend
  
  Clear this check box.
  
  Obsolete
  
  Clear this check box.
  
  Synchronous
  
  Clear this check box.
  Note: Because this notification does not require any response from the credit manager, it can run asynchronously.
  
  Transactional
  
  Clear this check box.
5. Click Save.
Create the first action, which checks the condition of the Credit Limit field when the customer record is saved:
1. On the Event Handlers form, select the handler you created in Step 1.
2. Click Event Actions.
3. On the Event Actions form, specify this information:
  
  Action Sequence
  
  Specify 10.
  
  Action Type
  
  Select Finish.
  Note: This action type tells the system to finish executing the handler when a particular condition has been met and exit.
4. Click Edit Parameters.
5. On the Event Action Finish form, click the Condition button.
6. On the Event Action Parameter Condition form, click the Expression 1 button.
7. On the Event Action Expression Editor form, specify this information:
  
  Select a function
  
  Specify PROPERTYMODIFIED. The PROPERTYMODIFIED function checks to see whether the named property has been modified since the last save. If the property has been modified, the expression returns a value of TRUE.
  
  Argument 1
  
  Specify CreditLimit, which is the name of the property that you want to check.
8. Click OK.
  
  Notice in the Event Action Parameter Condition form that the expression has been returned and that double quotation marks have been automatically inserted around the name of the property.
  
  Notice also that the Operator and Expression 2 fields have been disabled. This is because the PROPERTYMODIFIED function is a Boolean expression; thus, no comparison is needed to return a Boolean value.
9. On the Event Action Parameter Condition form, select the NOT check box.
  If this check box is cleared, the expression returns a value of TRUE whenever the CreditLimit property has been modified and the handler is finished. But you want the system to continue to the next action when the CreditLimit property has been modified; you want the system to finish at this point only if the CreditLimit property has not been modified.
10. Click OK.
  Notice that the system returns the expression to the Event Action Finish form correctly formatted.
11. On the Event Action Finish form, click OK.
  Notice that the system returns the entire parameter to the Event Actions form with the syntax correctly formatted.
12. To verify that there are no syntax errors, click Check Syntax.
13. Save the action.
Create the second action, which sends the email notification:
1. Press Ctrl + N.
2. Specify this information:
  
  Action Sequence
  
  Specify 20.
  
  Action Type
  
  Select Send Email.
3. Click Edit Parameters.
4. On the Event Action Send Email form, click the To button.
5. On the Event Action Parameter Recipients form, select the user ID for the credit manager.
  
  If the credit manager has an email address set up as part of the user profile, the email address displays to the right of the user ID. If the credit manager’s user ID does not display an email address, you must add the email address to the credit manager’s user profile on the Users form.
  
  Notice that you can use a global constant for the credit manager’s email address. However, because you are sending email, you cannot reuse the existing CreditMgr global constant, but must create a new global constant for the credit manager’s email address. The reason for not using an event global constant in this case was simply to give you some experience with the Event Action Parameter Recipients form’s other capabilities, but in most scenarios, a global constant is used.
6. Click Update.
  Notice that the system places the email address for the credit manager in the Recipients field.
7. Click OK.
8. On the Event Action Send Email form, specify this information:
  
  Subject
  
  Specify Credit limit change!.
  
  Category
  
  Specify Financial.
9. Click the Body button.
10. On the Event Action Expression Editor form, specify this information:
  
  Select a function
  
  Specify SUBSTITUTE.
  
  Argument 1
  
  Specify The credit limit has been changed to ${0} for customer {1}, customer number {2}.
11. Place the cursor in the first row of the Arguments grid, and click Build Expression.
12. On the Event Action Expression Editor form, specify this information:
  
  Select a function
  
  Specify FILTERPROPERTY.
  
  Argument 1
  
  Specify CreditLimit.
13. Click OK.
14. Place the cursor in the second row of the Arguments grid, and click Build Expression.
15. On the Event Action Expression Editor form, specify this information:
  
  Select a function
  
  Specify FILTERPROPERTY.
  
  Argument 1
  
  Specify Name.
16. Click OK.
17. Place the cursor in the third row of the Arguments grid, and click Build Expression.
18. On the Event Action Expression Editor form, specify this information:
  
  Select a function
  
  Specify FILTERPROPERTY.
  
  Argument 1
  
  Specify CustNum.
19. Click OK.
  
  Notice that the system returns the entire SUBSTITUTE expression to the Event Action Send Email form, correctly formatted.
  
  Notice also that there is no option to save the message to the user’s Sent Items folder. This is because this notification is being sent as an email. That being the case, you cannot use the SAVEMESSAGE parameter to have the system save a copy of the notification in the Sent Items folder of the person who added the new customer.
20. On the Event Action Send Email form, click OK.
21. Save the action and close the Event Actions form.
To verify that there are no syntax errors, click Check Syntax.
Discard the cached metadata.

Test this event handler by changing a customer’s credit limit and saving the record. The system generates an email message that gets sent to the credit manager.

In creating this kind of event handler, keep these points in mind:

To create an event handler that sends an email, you must have the SMTP set up on the Intranets form. Also, the email service on that computer must be set up to enable the relaying of email automatically.
To have the handler perform an action only when certain conditions are met, use the Finish action type and the CONDITION(NOT PROPERTYMODIFIED) parameter and function.
To eliminate the single quotes that appear around replacement values in the generated messages, use the PROPERTY function in place of the FILTERPROPERTY function we used in this scenario.