Sending events between windows

To send events between windows, you coordinate the following mechanisms in Developer Studio:

• The PERFORM-ACTION-SEND-EVENTtargeteventTypeeventData Run Process command, which identifies the window to which to send the event. (For more information, see Process-command-for-highlighting-required-fields.)
• On Event active link execute condition. (For more information, see Creating-workflow-objects.)
• Keywords to identify the event:
  • Current event ($EVENTTYPE$ ).
  • Current event data ($EVENTDATA$ ).
  • Current window ($CURRENTWINID$ ).
  • Window that sent the event ($EVENTSRCWINID$ ).

  • Last opened window ($LASTOPENEDWINID$ ).
    For more information, see Keywords.

    In a web browser, opening windows from workflow is not synchronous. For example, if an active link contains an Open Window action and the next action is a Send Event Run Process action, the child window does not receive the event. To solve this issue for the web client, create the workflow so that the parent or child window is loaded, and then the send event action is executed.

Additional considerations for sending events

Using the $EVENTTYPE$ keyword, the active link running on the Event condition can access the eventType specified in the PERFORM-ACTION-SEND-EVENT target eventType eventData command. (The $EVENTDATA$ keyword can represent event data to be attached.) Likewise, the recipient using the $EVENTSRCWINID$ keyword can access the window ID of the window sending the event. 

When using the Run Process Send Event action with web browsers, sending a message to a parent window or child windows behaves in an undefined fashion if the contents of the windows are changed by:

• Navigating to a new URL.
• Clicking the Back, Forward, or Reload buttons on the browser.
• Using an Open Window active link action that reloads new data into an existing window, causing the form to be unloaded.

If this event is sent to a data visualization field, the target must be F dataVisualizationFieldID. 

An example of Run Process syntax that sends the ChildClosed event to the current window's parent is: 

PERFORM-ACTION-SEND-EVENT @ ChildClosed 

The syntax that sends the ParentClosed event to the current window's children is: 

PERFORM-ACTION-SEND-EVENT # ParentClosed

Quotation marks are optional in the Run Process command if the eventType does not contain a space. For example, they are optional for: PERFORM-ACTION-SEND-EVENT @ EventA but you must use them for: PERFORM-ACTION-SEND-EVENT @ "This is the event".

If you are using field references for the target and eventType, make sure the field is set properly prior to executing the Run Process command.

Example

The following example describes how you can send an event from a child window to a parent window. When a user modifies a record in the Child Window form, an After Modify condition in the active link automatically sends an event to the Parent Window form and updates a table field. 

Sending event from child window to parent window

The concepts used in the following procedure are straightforward, so that you can easily reverse sending the event from a parent window to a child window.

You cannot have workflow that opens a dialog box and then sends an event to the dialog box. Dialog boxes are modal, and subsequent Send Event actions or active links do not fire until the dialog box closes. In this case, the dialog box no longer exists. Instead, use an On Loaded active link condition in the dialog box to send an event to itself, using the keyword $LASTOPENEDWINID$ as the target.

To send an event to a parent window

1. Create a form (for example, Parent Window).
2. Create another form (for example, Child Window).
3. Add a table field to the Parent Window form.
4. Select the new table field.
5. Edit the properties of the table:
   1. In the Properties tab, select the Tree/Table Property value, and click its ellipsis button.
   2. Enter Child Window in the Form Name field.
      The columns of the table field in Parent Form must point back to the Child Window form.
   3. Add the following fields to the Table Columns list:
      • Request ID (Column)
      • Submitter (Column2)
      • Short Description (Column3)
      • Assigned To (Column4)
        These columns help you identify which records in the table field to modify.
6. Create an active link (Child Send Event to Parent After Modify) with a Run Process action.
   1. Configure the settings in the following panels:
      • Associated Forms: Child Window
      • Execution Options: After Modify
      • Run If:'Submitter' != 'Assigned To'
        You want the active link in the child window to fire if the submitter and assignee are not the same user.
   2. Right-click on the If Actions tab, and select Add Action > Run Process.

   3. In the Command Line field, enter:
      PERFORM-ACTION-SEND-EVENT @ "RefreshTable"
      This Run Process command sends the RefreshTable event to the parent window. You will use this same event string later in active link workflow to catch the sent event in the parent window.

      Tip

      Make sure the target symbols (@, #, *) are used correctly. If you are trying to send an event to a parent window, do not use #.

      The Run Process command sends the RefreshTable event to the parent window in the same browser window when used in the Mid Tier. But when you use the User Tool, the Run Process command sends the RefreshTable event to the parent window in the same form or to the parent window in the different form.

      If you manually make any changes to the browser window or tabs (for example, open in new tab, open in new window, refresh page), the events communication may break.

      This Run Process command and its special syntax can send messages to one or more windows. For example, to send an event to all windows, use PERFORM-ACTION-SEND-EVENT * "All Windows". You can also send events to a specific window:

      PERFORM-ACTION-SEND-EVENT $536870921$ Processing
      PERFORM-ACTION-SEND-EVENT $Short Description$ "network is down"
      PERFORM-ACTION-SEND-EVENT $My Field$ "process request"
      PERFORM-ACTION-SEND-EVENT $LASTOPENEDWINID$ "close now"

      This command uses an established mechanism in the client environments to support special commands that are not run as executables, but as internal commands within the client. For detailed information about the command syntax, see Using-Run-Process-and-PROCESS-commands.

      Events are asynchronous, and the Run Process command returns immediately. Other windows receive the events and process the workflow at a later time.

7. Create an active link (Parent Catch Event) with a Change Field action to catch the sent event.
   1. Configure the settings in the following panels:
      • Associated Forms: Parent Window
      • Execution Options: Event

      • Run If:$EVENTTYPE$ = "RefreshTable"
        Because event names are intended to be unique, this active link fires only if it receives the RefreshTable event.

        You must use quotation marks in the Run If qualification for the event type.

        You can trigger active links by examining the values of the EVENTSRCWINID, CURRENTWINID, or EVENTTYPE keywords in the Run If qualification. Here, the EVENTTYPE keyword is used in the Run If qualification to fire the active link if the parent window catches the RefreshTable event sent by the child window.

   2. Right-click on the If Actions tab, and select Add Action > Change Field. 
   3. Enter the table field's name in the Field field.
   4. Select the Refresh Tree/Table check box.
      Here the rows in the table field are automatically refreshed after changes are made to the underlying request.
8. Open the Child Window form.
9. As a test, create several tickets in the Child Window form, but create one ticket with John as the value of the Submitter and Assigned To fields.
10. Open the Parent Window form, and click the table field to refresh it.
11. Double-click the request assigned to John in the Results List to open the Child Window form.

12. Change the assignee to another name and make changes in the Short Description field (for example, enter Catch event in parent window), and then save the request.
    When you modify the request, the active link workflow is triggered and sends the child window event to the parent window. The table field in the parent window is refreshed automatically.
    If the target window is in the process of executing workflow, that workflow completes beforethe event is received.

    Tip

    If the active links do not run in the target window, make sure the event type string in the Run If qualification matches the event type string in the Run Process command.