Sample Scenario 7: Adding Information to a Record

In this scenario, you want to notify a credit manager that a new customer is added and ask the credit manager to determine what is the credit limit for that customer. So, you must send a notification that prompts the credit manager for a response and then uses the data from that response to add data to the pending new customer record and commit the changes to the database.

For this scenario:

  • Use the same global constant (CreditMgr) the you used for previous scenarios.
  • Use the IdoOnItemInsert framework event.

To accomplish this scenario:

  1. Create and save an event handler with these settings:
    Event Name

    Select IdoOnItemInsert.

    Applies to Objects

    Specify SLCustomers.

  2. Create one action, which sends a prompt to the credit manager requesting a response:
    1. On the Event Actions form, specify this information:
      Action Sequence

      Specify 10.

      Action Type

      Select Prompt.

    2. Use the Event Action Prompt form and associated event action parameter forms to create these parameters:
      TO
      Specify GC(CreditMgr).
      SUBJECT
      Specify SUBSTITUTE("Need credit limit for customer ID {0}, {1}", FP("CustNum"), P("Name")).
      CATEGORY
      Specify "Financial".
      BODY
      Specify SUBSTITUTE("Please use the Variables tab to provide a credit limit for customer ID {0}, {1}. Then use the Post button on the Response tab to register the new credit limit.", FP("CustNum"), P("Name") ).
      SAVEMESSAGE
      Specify FALSE.
      QUESTION
      Specify To post the credit limit, click the button below.
      CHOICES
      Specify 1,sPost.
      FILTERFORM
      Specify Customers.
      FILTER
      Specify SUBSTITUTE("CustNum={0}", FP("CustNum")).
    3. On the Variable Access tab, specify this information:
      Name

      Specify CreditLimit.

      Access

      Select Mandatory.

      This forces a response from the credit manager.

    4. Save the action.
    5. Close the Event Actions form.
  3. Return to the Event Handlers form and select the Suspend check box.
  4. Save the handler.
  5. Discard the cached metadata.
  6. Test the event handler:
    1. Open the Customers form.
    2. Create a new customer record and click Save.
      Notice that the newly saved record does not appear in the list of customers at this point when you refresh the Customers form.
    3. Using the credit manager’s logon, open the credit manager’s Inbox.
      The new message should appear in the Inbox.
    4. On the Variables tab, locate the Row.CreditLimit variable and specify an amount.
    5. Save the record.
    6. On the Response tab, click Post.
    7. On the Customers form, refresh the form and verify that the newly created record appears in the list.
      You can also devise other test to verify that the system behaves as expected when the credit manager posts the response without specifying a value in the Row.CreditLimit variable field.

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

  • Because the variables are listed on the Variables tab and the question and response buttons are on the Response tab of the message, you should design your message body to include brief but detailed instructions for responding to the request. Do not assume the recipient knows or remembers.
  • Because you did not specify variable access rules to address property variables other than the CreditLimit variable, all the variable property values associated with the Customers form are displayed and writable. That means that the credit manager, if desired, can change any variable data before saving and posting the data to the database by clicking Post. To make other variables non-writable, you must set the variable access for each individually.
  • The fact that the prompt message is sent to a single recipient means that only one vote is required for a quorum. Once the credit manager posts the response, the vote is final and the database is updated. If there are multiple recipients associated with the CreditMgr global constant, then you also need to set voting rules to determine how the responses are handled. In this case, it is not necessary, because the system assumes a Plurality voting rule, and with only one recipient, that means that the first to respond is the one whose data is committed.
  • If the credit manager never votes, the record is never committed to the database, but remains adjourned indefinitely.
  • The QUESTION parameter has a limit of 80 characters.