Sample Scenario 5: Requesting Approval by External Email for Changes to an Existing Record

You want the credit manager’s approval for the credit limit change, and you are sending the request to the manager’s external email address. If the credit manager approves the change, the system writes and saves the change. If the credit manager does not approve the change, the system rolls back the record to the previously approved credit limit.

You can use existing framework events and IDOs to accomplish this. However, because you are sending out a prompt and requiring a response from the credit manager, you must make a synchronous and suspending event handler.

This event handler requires these actions:

  • Checks whether the Credit Limit field has been changed. If not, the event action finishes with a status of Success.
  • Sends the prompt message and external email.
  • If the credit manager does not approve the change, the event action fails the application event and rolls back the record.

To accomplish this scenario:

  1. Set up the recipient in the Users form to allow external email and to have the appropriate default language code.
    • Select Send Email Prompts
    • Ensure that the Email Address is correct
    • Specify the Default Language to use for formatting text strings
  2. Create an event handler with these settings:
    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 Objects
      Specify SLCustomers.
    5. Click Save.
    Note: If the handler that you created for Sample Scenario 2: Notification of Changes to an Existing Record - Changing the Credit Limit is active, the clear the Active check box or select the Obsolete check box, so that this event handler and the existing one do not create duplicate messages.
  3. 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, click Event Actions for the handler that you created.
    2. Click Event Actions.
    3. On the Event Actions form, specify this information:
      Action Sequence
      Specify 10.
      Action Type
      Select Finish.
    4. Click Edit Parameters.
    5. Starting with the Event Action Finish form, use the associated forms to create these parameters:
      Field or Button Action Result or Comments
      Condition Click this button. The Event Action Parameter Condition form is displayed.
      Expression 1 Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select PROPERTYMODIFIED. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify CreditLimit.
      2. Click OK.
      		 The system returns the expression to the Event Action Parameter Condition form and disables the Operator and Expression 2 options.
      NOT
      1. Select this check box.
      2. Click OK.

      This check box tells the action to finish with a status of Success if the Credit Limit field has not been changed.

      The system returns the expression to the Event Action Finish form.
      OK Click this button. The system returns the entire parameter to the Event Actions form, correctly formatted.
    6. To verify that there are no syntax errors, click Check Syntax.
    7. Save the action.
  4. Create the second action, to send the prompt message.
    This action sends the prompt to the credit manager, through both the Inbox form and external email, and suspends the handler until the credit manager responds to the request.
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 20.
      Action Type
      Select Prompt.
    2. Click Edit Parameters.
    3. Starting with the Event Action Prompt form, use the associated forms to create these parameters:
      Field or Button Action Result or Comments
      To Click this button. The Event Action Parameter Recipients form is displayed.
      Recipients Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select GC. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify CreditMgr.
      2. Click OK.
      		 The system returns the expression to the Event Action Parameter Recipients form.
      OK Click this button. The system returns the expression to the Event Action Prompt form.
      Subject Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select SUBSTITUTE. The system displays the buttons and fields associated with the SUBSTITUTE function.
      Argument 1 Specify Credit limit change request for customer ID: {0}. Notice that the SUBSTITUTE function is used to present the customer’s ID number in the Subject line, so that messages can be saved and tracked more easily.
      Arguments row 1
      1. Place the cursor in this field.
      2. Click Build Expression.
      		 The Event Action Expression Editor form is displayed.
      Select a function Select P or PROPERTY. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify CustNum.
      2. Click OK.
      		 The system returns the expression to the Event Action Parameter Recipients form.
      OK Click this button. The system returns the expression to the Event Action Prompt form.
      Category Specify Financial.
      Body Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select SUBSTITUTE. The system displays the buttons and fields associated with the SUBSTITUTE function.
      Argument 1 Specify You have a request for a credit limit change to ${0} for {1}, Customer ID {2}. Please respond to the question and indicate your approval on the Response tab. This sets up the basic message with three replacement markers.
      Arguments row 1
      1. Place the cursor in this field.
      2. Click Build Expression.
      		 The Event Action Expression Editor form is displayed.
      Select a function Select P. The system displays the Argument 1 button and field.
      Argument 1
      1. Select CreditLimit.
      2. Click OK.
      		 The system returns the expression to the first row of Arguments grid on the parent Event Action Expression Editor form.
      Arguments row 2
      1. Place the cursor in this field.
      2. Click Build Expression.
      		 The Event Action Expression Editor form is displayed.
      Select a function Select P. The system displays the Argument 1 button and field.
      Argument 1
      1. Select Name.
      2. Click OK.
      		 The system returns the expression to the first row of Arguments grid on the parent Event Action Expression Editor form.
      Arguments row 2
      1. Place the cursor in this field.
      2. Click Build Expression.
      		 The Event Action Expression Editor form is displayed.
      Select a function Select P. The system displays the Argument 1 button and field.
      Argument 1
      1. Select Name.
      2. Click OK.
      		 The system returns the expression to the first row of Arguments grid on the parent Event Action Expression Editor form.
      Arguments row 3
      1. Place the cursor in this field.
      2. Click Build Expression.
      		 The Event Action Expression Editor form is displayed.
      Select a function Select P. The system displays the Argument 1 button and field.
      Argument 1
      1. Select CustNum.
      2. Click OK.
      		 The system returns the expression to the first row of Arguments grid on the parent Event Action Expression Editor form.
      OK Click this button. The system returns the entire SUBSTITUTE expression to the Event Action Prompt form.
      Question Specify Do you approve this credit limit change?

      Note that you have an 80-character limit in the Question field.
      Choices Click this button. The Event Action Prompt Choices form is displayed.
      Return Value row 1 Specify 1.
      Note: Theoretically, you can use any value as long as you remember what it is and use the same value later in the Fail action step.
      Button Caption row 1 Specify sYes. Notice that this is a translatable string from the Strings table. Also notice that you can select a string from the Strings table from the drop- down list.
      Return Value row 2 Specify 0.
      Button Caption row 2 Specify sNo.
      OK Click this button. The system returns the Choices values to the Event Action Prompt form.
      Save in Sent Items Select this check box. This sends a copy of the message to whomever initiated the credit limit change.
      OK Click this button. The system returns the entire set of Prompt action parameters to the Event Actions form.
      Note: You can incorporate other field values from the Event Action Prompt form before saving and closing.
    4. To verify that there are no syntax errors, click Check Syntax.
    5. Save the action.
  5. Create the third action, which tells the system how to respond if approval is not granted.
    This parameters tells the system to consider the action as having failed if the credit manager rejects the credit limit change. In other words, if the credit manager votes "No" [0] on the second action (Action Sequence = 20), then this action fails.
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 30.
      Action Type
      Select Fail.

      This action type ends handler execution with an error status. This effectively aborts the process and prevents the credit limit from being changed for the customer.

    2. Click Edit Parameters.
    3. Starting with the Event Action Fail form, use the associated forms to create these parameters:
      Field or Button Action Result or Comments
      Condition Click this button. The Event Action Parameter Condition form is displayed.
      Expression 1 Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select VOTINGRESULT. The system displays the Action drop-down list field.
      Action Select 20 Prompt. Notice that the system displays only the 20 in the field. The action type name in the drop- down list is there to help you select the correct action step.
      OK Click this button. The system returns the expression to the Event Action Parameter Condition form.
      Operator Select = (equal sign).
      Expression 2 Select 0 (zero).
      Note: This is a reference to the value you designated for a disapproval (sNo). If you used some value other than 0, that is what you must specify here.
      OK Click this button. The system returns the expression to the Event Action Fail form.
      Result Specify The credit manager has disapproved the credit limit change. This is the text that appears in the Result field of the Event Status form if the credit manager disapproves the change. Since that is the only time and place this message is displayed, you can use a literal value. To make it clearer, you can use a SUBSTITUTE function with the customer name and ID number.
      Note: You can also set another event action to notify the original sender by message that the change has been approved or disapproved.
    4. To verify that there are no syntax errors, click Check Syntax.
    5. Save the action.
  6. Return to the Event Handlers form and select the Suspend check box.
  7. Save the hanlder.
  8. Discard the cached metadata.
  9. Test this event handler:
    1. On the Customers form and change the credit limit for a customer and click Save.

      Notice that the entire record for this customer is now temporarily disabled, because the update has been suspended pending approval. Therefore, no further changes can be made to this customer record until this application event is resolved.

      Also notice that all fields, including the Credit Limit field, display their original values. Anyone who views this suspended record sees the original values, until this suspended event finishes successfully, at which time the new values are saved in the database and displayed on the Customers form.

    2. Optionally, open the Saved Messages form for your current logon ID and verify that a copy of the message has been saved there.
    3. Open the Inbox form for the individual designated as the credit manager and verify that the message is received and that the Response tab displays the question and choice buttons.
    4. Open the credit manager’s external email system and verify that the email is received, and the question and choice links display.
    5. Optionally, with the Customers form open and customer record that is changed selected, from the Actions menu, select View Event Status.

      This opens the Event Status form. Verify that the status for this event is Running. You can also open the Event Status form manually.

    6. In the credit manager’s email, click the link labeled Yes. Verify that the ASP processes the message and returns a success response.
    7. In the credit manager’s Inbox form, verify that the message is automatically marked as Expired, the Choices buttons are now disabled, and the Selected Choice is Yes.
    8. Refresh the collection on the Customers form and verify that the new credit limit was saved.
      Notice too that the entire customer record is once again enabled for editing.
    You can also do a second test by clicking the link labeled No to reject the request. In this case, when you refresh the Customers form, notice that the Credit Limit field has retained its original amount.

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

  • You can use the SUBSTITUTE function in other places other than the body of a message. You can use this function in the Subject line and other places. You can also use this function for purposes other than replacing text in messages.
  • When checking on a voting result, the number referred to in the syntax is the action sequence number for the action that contains the choice.

Extra challenges are:

  • Changing the body of the message to include both the original credit limit and the proposed new limit
    Note: You must save the old credit limit in an event variable.
  • Creating another event action to notify the original sender by message that the change has been approved or disapproved
Related topics