Sample Scenario 3: Notification that includes an Old Value

You want to notify a group of inventory stock clerks automatically whenever an item’s lot size changes. In the message that is sent, you want to include both the previous lot size and the new lot size. You also want to let them know who initiated the change.

You can use an existing framework event, IdoOnItemUpdate, and create a handler for this application event. Because this handler needs to retrieve the before property values, you must make this synchronous, so that during handler execution you can retrieve from the database the original row that is being updated, before it is updated by the IDO request.

This event handler requires three actions:

  • Checks whether the Lot Size field has been changed and, if not, finish
  • Retrieves the row that is being updated and both the original and new values for the Lot Size field
  • Sends the notification to the inventory stock clerks

To accomplish this scenario:

  1. 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 SLItems.
      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
      Select this check box.
      Note: Because this notification requires both the original value and the new value, this handler must be run synchronously.
      Transactional
      Clear this check box.
    5. Click Save.
  2. Create an event global constant for the group of stock clerks.

    Putting the user IDs for the entire group into a global constant allows you to change the list, which can be used in other places as well, in a single place easily.

    1. Open the Event Global Constants form.
    2. Press F3.
    3. Press Ctrl + N.
    4. Specify this information:
      Name
      Specify StockClerks or the name for the global constant.
      Value
      Specify the user IDs for the stock clerks.
      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.
  3. Create the first action, which checks the condition of the Lot Size field when the item record is saved:
    1. On the Event Handlers form, select 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. On the Event Action Finish form, click the Condition button.
    6. On the Event Action Parameter Conditions form, click the Expression 1 button.
    7. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Select PROPERTYMODIFIED.
      Argument 1
      Specify LotSize.
    8. On the Event Action Parameter Condition form, select the NOT check box.
    9. Click OK.
    10. On the Event Action Finish form, click OK.
      This parameter tells the system to check the LotSize property. If this property is not modified, finish handler execution and exit. If this property is modified, continue with the second action.
    11. Save the action.
  4. Create the second action, which retrieves both the original and new values for the Lot Size field.
    As part of this step, the system retrieves the original value of the Lot Size field and stores the value to an event variable named OldLotSize.
    • Use the IDO( ) function to identify the same IDO that fired the application event.
    • Name the same property in the PROPERTIES( ) and SET( ) functions, and both must be the same as the field or component property value the user is changing.
    • Make sure the handler is synchronous.

    To create the action:

    1. Press Ctrl + N.
    2. Specify this information:
      Action Sequence
      Specify 20.
      Action Type
      Select Load IDO Row.
    3. Click Edit Parameters.
    4. On the Event Action Load IDO Row form, specify this information:
      IDO
      Specify SLItems.
      Note: You can also select the IDO you want from the drop-down list, but you have to filter on the field or increase the record cap for drop-down lists to see this one.

      Also, the procedure to determine what IDO collection you need is similar to the procedure to determine what property name you need.

      Properties
      Select LotSize.
    5. Click the Filter button.
    6. On the Event Action Expression Editor form, specify this information:
      Select a function
      Select SUBSTITUTE.
      Argument 1
      Specify Item = {0}.
    7. Place the cursor in the first row of the Arguments grid, and click Build Expression.
    8. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Select FILTERPROPERTY.
      Argument 1
      Specify Item.
    9. On the Event Action Load IDO Row form, click the Output button.
    10. On the Event Action Output Parameters form, specify this information, then click OK.
      Output Type
      Specify Return Variable.
      Output Object Name
      Specify OldLotSize.
      Value
      Specify LotSize.
    11. On the Event Action Load IDO Row form, click OK.
      Your resulting syntax statement must appear similar to this in the Parameters field of the Event Actions form:
      IDO("SLItems")
      PROPERTIES("LotSize")
      FILTER(SUBSTITUTE("Item = {0}", FP("Item")))
      SET(RV(OldLotSize) = "LotSize")
    12. To verify that there are no syntax errors, click Check Syntax.
    13. Save the action.
  5. Create the third action, which sends the notification:.
    1. Press Ctrl + N.
    2. Specify this information:
      Action Sequence
      Specify 30.
      Action Type
      Select Notify.
    3. Click Edit Parameters.
    4. On the Event Action Notify form, click the To button.
    5. On the Event Action Parameter Recipients form, click the Recipients button.
    6. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Select GC.
      Note: The GC function allows you to designate an event global constant to use for the recipients. In this case, designate the global constant you created earlier, StockClerks.
      Argument 1
      Select StockClerks.
    7. On the Event Action Parameter Recipients form, click OK.
    8. On the Event Action Notify form, click the Cc button.
    9. On the Event Action Parameter Recipients form, click the Recipients button.
    10. On the Event Action Expression Editor form, from the Select a function drop-down list, select ORIGINATOR.
      Notice that the ORIGINATOR function takes no arguments.
    11. Click OK twice.
    12. On the Event Action Notify form, specify this information:
      Subject
      Specify Lot size change.
      Category
      Specify Change Notification.
    13. Click the Body button.
    14. On the Event Action Expression Editor form, specify this information:
      Select a function
      Select SUBSTITUTE.
      Argument 1
      Specify The lot size has been changed for item: {1} The previous lot size was {2}, the new lot size is {3}. Please take note and adjust your activities accordingly. This change was made by {0}.
    15. Place the cursor in the first row of the Arguments grid, and click Build Expression.
    16. On the Event Action Expression Editor form, from the Select a function drop-down list, select ORIGINATOR then click OK.
      Notice that you can place this first property (ORIGINATOR) last in the message, and, as long as you have the appropriate index number assigned ( {0} ), it is correctly displayed in the message.
    17. Place the cursor in the second row of the Arguments grid, and click Build Expression.
    18. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Select FP.
      Argument 1
      Select Item.

      Because you want the item number to be enclosed in single quote marks, you use the FP (alternate for the FILTERPROPERTY) function. However, if you do not want single quote marks around the lot size amounts, you can let those values evaluate as their native datatypes.

    19. Place the cursor in the third row of the Arguments grid, and click Build Expression.
    20. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Specify V.
      Argument 1
      Specify OldLotSize.
    21. Place the cursor in the fourth row of the Arguments grid, and click Build Expression.
    22. On the Event Action Expression Editor form, specify this information, then click OK.
      Select a function
      Specify P or PROPERTY.
      Argument 1
      Select LotSize.
    23. Click OK.
      The resulting syntax statement looks similar to this:
      BODY(SUBSTITUTE("The lot size has been changed for item: {1} The previous lot size was {2}, the new lot size is {3}. Please take note and adjust your activities accordingly. This change was made by {0}.",
      ORIGINATOR(),
      FP("Item"),
      V(OldLotSize),
      P("LotSize"))
      Note: You can add line returns to make your syntax statement look similar to this example. The system ignores white space and line returns when processing the statements.
    24. On the Event Action Notify form, click OK.
  6. To verify that there are no syntax errors, click Check Syntax.
  7. Save the action and close the Event Actions form.
  8. Discard the cached metadata.

Test this event handler by using the Items form and locating an item that is lot-tracked. On the General tab, you can change the value in the Lot Size field. In the stockers’ Inbox forms, verify that the message is sent and contains the correct values.

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

  • To retrieve the existing value of a field for display in a message, you must make the handler synchronous.
  • To display both the original value of a field and the new one, use an event variable to temporarily store the original value.
  • Substituted values in a statement can be presented in any order as long as their index numbers match their positions in the list.
  • To prevent single quotes from being placed around a substituted value, use the PROPERTY function instead of the FILTERPROPERTY function.

Try to add an item description to the body of the message. This may require you to determine the name of the item description property.