Sample Scenario 4: Approval for a New Record

You want to send a message to the purchasing manager whenever a purchase order (PO) is added. This message prompts the purchasing manager for approval of the PO. The purchasing manager can indicate approval (or disapproval) by clicking a button in the message itself. If approved, the system adds the PO; if not, the system does not add the PO.

You can use the system framework built-in event, IdoOnItemInsert and create a handler. The handler itself requires two actions:

  • Sends the prompt
  • Tells the system what to do if approval is denied

To set the system up to handle this:

  1. Create a global constant for the purchasing manager.
    1. Open the Event Global Constants form.
    2. Press F3.
    3. Press Ctrl + N.
    4. Specify this information:
      Name
      Specify PurchasingMgr.
      Value

      Specify the purchasing manager’s user ID.

      Note: To add multiple recipients, specify the user IDs separated by semi-colons only and no spaces.
    5. Save the global constant and close the form.
  2. 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 IdoOnItemInsert.
      Applies to Initiators
      Leave this field blank.
      Applies to Objects
      Specify SLPos.
      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.
      Note: Because this notification requires a response from the purchasing manager, it must run synchronously and be suspended.

      However, you cannot select this (and make it "stick") until at least one adjourning action exists. So, you must leave this cleared for now and come back to it after your actions have been defined.

      Obsolete
      Clear this check box.
      Synchronous
      Select this check box.
      Note: Because this notification requires a response from the purchasing manager, it must run synchronously and be suspended. When you later select the Suspend option, this option is automatically selected.
      Transactional
      Clear this check box.
    5. Click Save.
  3. Create the first action, which sends the message:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 10.
      Action Type
      Select Prompt.

      This action type sends a notification to the designated recipient and prompts the recipient for a response.

    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 PurchasingMgr.
      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 Select New purchase order needs your approval.
      Category Specify Order Approval.
      Body Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select SUBSTITUTE. The Argument 1 field and drop-down list, Arguments grid, and buttons are displayed.
      Argument 1 Specify A new purchase order has been requested for vendor {0}, {1}. Please review the details on the Variables tab and register your approval on the Response tab.
      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. Select VendNum.
      2. Click OK.
      		 The system returns the expression to 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 or PROPERTY. The system displays the Argument 1 button and field.
      Argument 1
      1. Select VendorName.
      2. Click OK.
      		 The system returns the expression to the parent Event Action Expression Editor form.
      OK Click this button. The system returns the entire BODY parameter content to the Event Action Prompt form.
      Question Specify Do you approve this new PO?

      Note that when the handler runs, the QUESTION parameter is presented on the Response tab of the recipient’s Inbox.
      Choices Click this button. The Event Action Prompt Choices form is displayed.

      Note that the CHOICES parameter creates, displays, and enables the voting buttons that will be required for the purchasing manager to signal approval or rejection. When the handler runs, these CHOICES buttons appear directly beneath the QUESTION in the recipient’s Inbox.
      Return Value row 1 Specify 1. Note that you can specify any value that you want.
      Button Caption row 1 Specify sYes. Note that you can use translatable strings from the Strings table. These strings appear in the drop-down list for this field.
      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.
      OK Click this button. The system returns all defined parameters to the Event Actions form, correctly formatted.
    4. To verify that there are no syntax errors, click Check Syntax.
    5. Save the action.
    If you have done everything correctly, your syntax for this action step must look similar to this: 
    TO(GC(PurchasingMgr))
SUBJECT("New purchase order needs your approval")
CATEGORY("Order Approval")
BODY(SUBSTITUTE("A new purchase order has been requested for vendor {0}, {1}. Please review the details on the Variables tab and register your approval on the Response tab.", 
P("VendNum"), P("VendorName") )
SAVEMESSAGE(FALSE)
QUESTION("Do you approve this new PO?")
CHOICES("1,sYes,0,sNo")
  4. Create the second action, which tells the system how to respond if approval is not granted:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 20.
      Action Type
      Select Fail.

      This action type ends handler execution with an error status. This effectively aborts the process and prevents the PO from being added to the database.

    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.

      This function and action evaluate the results of whatever action is selected from the list. The action refers by number to the action type.

      In this case, you only have one other action, and that is the correct action, the Prompt action.
      Action Select 10 Prompt.
      OK Click this button. The system returns the expression to the Expression 1 field on the Event Action Parameter Condition form.
      Operator Select = (equal sign).
      Expression 2 Select 0 (zero).

      This value tells the system to fail the handler with an error if the recipient responds with a "No" (0).
      OK Click this button. The system returns the expression to the Event Action Fail form.
      Result Specify The PO request was rejected by the purchasing manager. This message is displayed on the Event Status form if the purchasing manager responds with a "No."
      OK Click this button. The system returns both parameters to the Event Actions form, correctly formatted.
    4. To verify that there are no syntax errors, click Check Syntax.
    5. Save the action.
  5. Return to the Event Handlers form and select the Suspend check box.
  6. Save the hanlder.
  7. Discard the cached metadata.
  8. Test this event handler:
    1. On the Purchase Orders form, create a new purchase order and click Save.

      After you save the PO, when the Purchase Orders form refreshes the display, the new record should disappear from the display. The record remains hidden until approved.

      If you do not assign a PO number, the generated message is displayed with a PO number of TBD.

    2. Open the Inbox form for the individual designated as the Purchasing Manager and verify that the message is received and that the Response tab displays the question and choice buttons.
    3. Optionally, with the Purchase Orders form selected, from the Actions menu, select View Event.

      This opens the Event Status form. Navigate to the last row and verify that the status for this application event is Running.

    4. On the Inbox form, click the Yes button.
    5. Refresh the collection on the Purchase Orders form and verify that the new PO now displays in the list.

    You can also do a second test by clicking the No button to reject the request. In this case, when you refresh the Purchase Orders form, the new PO record is never added to the database and does not appear in the list of POs.

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

  • When creating a message that requires a response from the recipient (usually a Prompt action type), you must mark the handler so that it suspends when executed. This means that it is also automatically marked as a synchronous handler.

  • Because these event handlers must be suspended, pending the purchasing or credit manager’s response, the Framework Event Service must be enabled for the configuration in which you are logged on.

Note: When you try to change the Subject line so it displays the user ID of the person who created the new PO and the PO number, you must use the SUBSTITUTE function.
Related topics