Creating active links

Active link execution options cause the active link to execute based on actions taken by the user. For example, an active link might run when the user presses Enter in a specified field or clicks a button on the form.

Some actions are specific to the open request or the open window, while other actions are associated with fields in the referenced form. 

Active link execution options

If an active link is part of a guide, you do not need to select an execution option.

To define the execution options for active links

1. Open an existing active link or create a new one.
2. Make sure there is an associated form selected. Select one in the Associated Forms panel if necessary. See Associating workflow objects with forms.
3. Expand the Execution Options panel.
4. Set the State field to Enabled or Disabled. When the state is Enabled, the active link becomes active as soon as it is saved. You might want to set the state to Disabled during development or when troubleshooting.
5. If necessary, enter a number in the Execution Order field. The value that you enter in the Execution Order field determines the order in which this active link is executed relative to other active links with the same triggering conditions. Numbers between 0 and 1000 are valid execution order values; lower numbers are processed first. The default value is 0.

6. Select the execution options for request and window actions, if any.
   The execution options for request and window actions that trigger active links are described in the following table. You can select any combination of these execution conditions, or none of them, as appropriate. If you select multiple options, the active link or filter executes when any one of the selected operations occurs.

   Execution option	Description
   After Modify	Executes when a user modifies an existing request and after the request is written to the database. If the modification fails, the active link is not executed. (The active link does not execute during a Modify All operation.)
   After Submit	Executes after a user submits a new request and after the request is written to the database. If the submission fails, the active link is not executed. If you use this condition for a set fields action on the current entry, the set value is not stored in the database.
   Display	Executes after an existing request is loaded into a form, but before the request appears in the Details Pane.
   Event	Executes when a window has changed its application state, for example, when one window wants to send an event to one or more windows; when one window has caused data to change and another window references that data; or when one window is closed and other windows must be notified. This capability allows one part of an application in a client environment to notify other parts that an "event" has occurred. Other parts of the application can then react by performing actions such as refreshing table fields. The Event condition provides a mechanism in the context of a single client environment (for example, in a web client) for a parent window to be notified when a child window has been closed, so that workflow can refresh related data on the parent window. Events are constrained to the client environment. Windows in two separate client environments cannot send messages to each other. See Process command for highlighting required fields. Warning: In some cases, event driven workflow can fail when executed on the Mid Tier . To avoid this issue, explicitly define the parent-child relationship.
   Modify	Executes when a user modifies an existing request. The active link is executed before the request is sent to the server. (The active link does not execute during a Modify All operation.)
   Search	Executes when a user performs a search operation. The active link executes before the search operation so that, if the active link criteria is not met, the If actions are not performed. (If Else actions exist, they are performed.) To prevent a specific search from occurring (such as an unqualified search), you can have the active link return a message (such as an error); otherwise, the search is performed. You can also use active links to set fields to modify the search. The active link can access and assign values in the Search window, including the Search Bar if the reserved Search Bar field is present on the form.
   Set Default	Executes when the user selects Edit > Set to Defaults from the menu bar. It can also happen after Window Open if default field values have been set in the form through user preferences.
   Submit	Executes when a user submits a new request. The active link is executed before the request is sent to the server.
   Un-Display	Executes when a request is removed from the Details pane because a new request was selected in the Results pane or because the window is closing. The workflow actions execute before the request is removed from the form.
   Window Closed	Executes when a user closes a window. Important: With Google Chrome version 80 and later, the active links that run on the Close Window event might not work as expected. To ensure smooth operation, set the Execute-Window-Close-Undisplay-Activelinks parameter in Centralized Configuration to False. For more information about the Execute-Window-Close-Undisplay-Activelinks parameter, see Execute-Window-Close-Undisplay-Activelinks.
   Window Loaded	Executes after all the data values have been loaded into a Submit or Search window (from defaults, from a Copy to New action, or from an Window Open action).
   Window Open	Executes when any of the following actions occur: A form window opens in New, Search, Modify, or Modify All operation mode. The mode of the Detail pane switches to New, Search, Modify, or Modify All mode. The form is opened by using the Open Window action. This is useful for establishing the initial environment when a user opens a new window or changes modes. The active link is executed before any data is loaded into the window, except when the form is opened in Dialog mode by the Open Window action.     If you use a Set Fields action with the Window Open condition, the set fields values might be deleted if the user preference is set to Clear All Fields On Search or On New. To avoid this when using a Set Fields action, use the Window Loaded execution option, which executes after preferences are loaded, instead.
   Progressive View Execution Option	Description
   (Progressive Views) Run in parallel	When you enable progressive views for a form, you can choose to run two independent active links simultaneously. For active links to run in parallel, their form name, execution event, and orders must match. If you don't select the Don't wait for completion check box, the active links from the next execution order wait for completion of all parallel active links. You can run active links for the following events: Display Window Loaded Window Open When you enable active links for parallel execution, the Run in parallel information is shown in the Execute On column (object list).
   (Progressive Views) Run in Parallel and Don't wait for completion	For active links to run in parallel, their form name, execution event, and orders must match. If you don't select the Don't wait for completion check box, the active links from the next execution order wait for completion of all parallel active links. When you enable active links for parallel execution, the Don't wait for completion information is shown in the Execute On column (object list).
   (Progressive Views) Bulk with Entry	Use this option to specify service action and table refresh. You must make sure that the input and output mappings of the services action contain only static values or field references and do not contain any expressions, keywords, or functions. You can add inputs such as dynamic fields.
   (Progressive Views) Bulk with Group	Use this option to specify service action and table refresh. You must specify a group name in the Group Name field when you select this option. You must make sure that the input and output mappings of the services action contain only static values or field references and do not contain any expressions, keywords, or functions. You can add inputs such as dynamic fields.
   (Progressive Views) On Table/Column Filter Change	For table columns: Use this option to specify an action when a filter is changed. For tables: You can select this option for a table and is triggered when you select either the Cancel or Remove All button on the filter. Cancel or Remove All buttons are available only when you set Show Apply Button to True on the table field.

7. Define the execution options for field actions, if any. To do so:

   1. Click the Field ellipsis button. The fields that appear in the field list are taken from the Primary Form defined in the Associated Forms panel. To locate a field quickly in a long list, use the Filtering Options or the Locate field in the Field Selector dialog box. See To filter the contents in an object list.

      Tip

      Instead of clicking the ellipsis button, you can also press Ctrl+Space with the cursor in the Field field. This brings up a list of the available fields from the form. Begin to type the field name to narrow the list, and then select the field you want.

   2. Select the appropriate field from the Field Selector dialog box and then click OK.
      When you select a field, the field execution options appropriate to the field type become active. The field-based, button, and menu execution options for active links are described in the following table.

   3. Select one or more field execution options for the field.

      Execution option	Description
      Button/Menu Field	Executes when a user selects a button or a navigation field item.
      Collapse	Appears when the selected field is a Panel field type. For Accordion and Stacked panel fields, executes when the user collapses a panel field. For a panel field of the Splitter type and Tabbed type, this option causes no action.
      Drag	Executes when the mouse moves over a field, and the user presses the left mouse button and drags the mouse. See Allowing users to drag and drop data.
      Drop	Executes when the left mouse button is released over a "droppable" field after being dragged from a "draggable" field. See Allowing users to drag and drop data.
      Expand	Appears when the selected field is a panel field type. For Accordion and Stacked panel fields, executes when the user expands a panel field. For a panel field of the Splitter type and Tabbed type, this option causes no action.
      Gain Focus	Executes when the specified field receives the focus. If you select this option, the Field list is enabled so that you can specify the field that causes the active link to execute. If you use the Gain Focus condition to execute an active link on a view field, the active link might not execute as expected. This is because the HTML page in the view field is taking the focus. If the Gain Focus option is defined on a column field and if the table does not currently have focus, the Gain Focus is also fired for the table. For example, if a table has columns A and B and if the current focus is on column A and the user shifts focus to column B, the Gain Focus is not fired on the table because the table already has the focus. However, if the current focus is on another field outside the table and the user shifts focus to a column inside the table, the Gain Focus will be fired for the table. This Gain Focus option for column fields is applicable only for cell based and list view tables. For list view tables, only the columns with display type not set to "read only" fire focus events.
      Hover On Field Hover On Data Hover On Label	Executes when the user hovers the mouse pointer over a field, field data, or a field label in the web client. Along with the Message active link action, enables the use of tooltips to display a brief informational message. If the selected field is a data field, all three options are enabled. If the selected field does not have distinguishable label and data areas, only the "Hover on field" option is enabled. For information about creating tooltips, see Defining Message active link or filter actions.
      Level Choice	Appears when the selected field is a tree-view table field type. Executes when a user selects a level in the tree.
      Level Double Click or Return	Appears when the selected field is a tree-view table field type. Executes when a user double-clicks a leaf in a tree view table or selects a leaf and then presses Enter to drill down to the source form. (If a user double-clicks on a parent node with child nodes under it, the node collapses or expands or no workflow is executed.) For more information, see Tree view table fields.
      Lose Focus	Executes as the focus is changed, for example, by clicking in another field. If you select this option, the Field list is enabled so that you can specify the field that causes the active link to execute. An existing panel field loses focus when a new panel of the set appears at the front. Panels can gain focus whenever a user clicks a tab, an active link sets focus to a panel or a field on a panel, or another panel is hidden. Panel focus is independent of data field focus. If you use the Lose Focus condition to execute an active link on a view field, the active link might not execute as expected. This is because the HTML page in the view field is taking the focus. If the Lose Focus option is defined on a column field and the focus is moving to a field outside the table, the Lose Focus is also fired for the table. For example, if a table has columns A and B and if the current focus is on column A and the user shifts focus to column B, the Lose Focus is not fired on the table because the table still has the focus. However, if the current focus is on a column inside the table and the user shifts focus to a field outside the table, the Lose Focus will be fired for the table.  This Lose Focus option for column fields is applicable only for cell based and list view tables. For list view tables, only the columns with display type not set to "read only" fire focus events.
      Menu Choice	Appears as an execution option when the selected field has an associated menu. Executes when a user makes a selection from a character menu attached to the field or selects a node in a tree view table field.
      Return	Executes when any of the following actions occur: A user presses Enter on the keyboard. A user presses Shift-Enter in a multirow character field. A user selects a check box, drop-down menu item, or radio button.
      Row Choice	Appears as an execution option when the selected field is a table field. Executes when a user selects a row in the table.
      Row Double Click or Return	Appears when the selected field is a table field type. Executes when a user double-clicks a row in a table field or selects a row and then presses Enter to drill down to the source form. This execution condition works independently of whether the table drill-down option has been selected for the table field. This execution option works only if the user has been granted permission to fields on the supporting form, the column fields, and the table field.
      Table Refresh	Appears as an execution option when the selected field is a table field. Executes when the user updates the table contents by loading the field, sorting, refreshing, or displaying the previous or next chunk.

8. Select one or more field events to be honored when an action happens in a progressive view.

   Progressive View Field Event	Description
   On Content Change	Developer Studio enables this field event when the selected field is of type Table - List View and if the Display Type property for a column in this table is set as Editable. Executes when there is any change in the content of the field.
   On Clear	Developer Studio enables this field event when the selected field is of type Drop-Down List. Executes when the field doesn't contain any value, that is, it's clear.
   On URL Click	Developer Studio enables this field event when the selected field is of type Table - List View, and if the Display Type property is set to Read Only, and if the Show as URL property is set to True. Executes when a URL is clicked.
   On Row Unselect	Developer Studio enables this field event when the selected field is of type Table. Executes when the focus on the current row is lost.
   On Row Expansion	Developer Studio enables this field event when the selected field is of type Table. Executes when the current row is expanded.
   On Row Collapse	Developer Studio enables this field event when the selected field is of type Table. Executes when the current row is collapsed.
   On Attachment Start	Developer Studio enables this field event when the selected field is of type Attachment Pool. It allows developers to execute an active link when an attachment upload starts.
   On Attachment End	Developer Studio enables this field event when the selected field is of type Attachment Pool. It allows developers to execute an active link when an attachment upload completes.
   On Attachment Cancel	Developer Studio enables this field event when the selected field is of type Attachment Pool. It allows developers to execute an active link when an attachment upload is canceled.

9. To cause the active link to execute when the user clicks a button:
   1. Click the Button/Menu Field ellipsis button.

   2. Select the appropriate button field and then click OK.

      Tip

      You can also associate an active link with a button by selecting the active link in the button's field properties.

10. In the Interval field, select an execution interval, if any. The minimum interval is three seconds, and the maximum interval is 7200 seconds. When this is selected, the active link executes when the form is open at the specified time interval. (If two or more active links on a form have the same interval, they execute at the same time unless the execution order is set.)

    Warning

    In workflow triggered by the Interval condition, avoid the use of Message actions and Open Window (of type Dialog) actions. This is to prevent an uncontrolled loop of messages or opened windows, which could consume resources on the client computer and make it difficult for the user to close the form.

11. Expand a Run If Qualification panel, and enter a qualification, if needed. For more information, see Using buttons and menu bar items to execute active links.
12. Enter If and Else actions, as needed. For more information, see Using buttons and menu bar items to execute active links.
13. Complete the following properties:
    1. Grant the necessary Permissions for the active link.
    2. For the Change history property, enter a description of your changes.
       This object property automatically records the owner, the user who last modified the active link, and the date of the modification.
       
    3. For the Help text property, enter help text to describe what the active link does or how it is used.
14. Save the active link.

Ability to run the active links in parallel

When you want to fetch related or unrelated data from the AR System server, the data is fetched sequentially because the active links run in sequence one after the other. This can result in performance issue because the data is fetched only when all active links execution is complete. To avoid the wait, when you enable progressive views for a form, you can select to run those active links in parallel that have the same execution event and execution order.

For example, when you are fetching related information for an incident such as tasks or attachments, select the active links fetching the tasks or attachment information to run in parallel.

You can run the active links in parallel for the following events:

• "Display"
• "Window Loaded"
• "Window Open"

Consider the following rules for enabling active links to run in parallel:

• You can run active links in parallel only when you enable the Progressive view for your form. For information about enabling progressive view, see Enabling Progressive Web Application.
• Only the active links with same execution event and same execution order can run in parallel.
• Active links running in parallel must be independent in terms of data access or modification. For example, active links should not change value of the same fields. This might result into unexpected results.
• The active links running in parallel must not operate on the same UI object. 
• For an active link to run in parallel with the other active links with higher execution order, you must select the Don't wait for completion option. For example, one active link tries to hide a field and the other tries to enable it. This might result in inconsistency.
• When you select the Don't wait for completion option, other active links from next execution order do not wait for this (the active link for which the Don't wait for completion option) active link to complete execution.
   

Examples of running active links in parallel

Scenario 1

There are five active links. AL1, AL2, AL3, and AL4 with execution order 10. AL5 with execution order 20. Active links AL2 and AL3 are set to run in parallel. The Don't wait for completion option is not selected for active links AL2 and AL3.

The following table shows the active links and execution order:

The following diagram shows that active links AL2 and AL3 are running in parallel:

Scenario 2

There are five active links. AL1, AL2, AL3, and AL4 with execution order 10. AL5 with execution order 20. Active links AL2 and AL3 are set to run in parallel to the main thread, where AL1 and AL4 run. However, for AL2, the Don't wait for completion option is selected.

The following table shows the active links and execution order:

The following diagram shows that active links AL2 and AL3 are running in parallel, and the Don't wait for completion option is selected for AL2. Active link AL5 will execute after AL3 and AL4 complete execution without waiting for AL2 to complete execution:

Scenario 3

There are 10 active links. AL1, AL2 with execution order 10. AL3, AL4, AL5, AL6, AL7, and AL8 with execution order 20. AL9, and AL10 with execution order 30. AL6, AL7, and AL8 are set to run in parallel. The Don't wait for completion option is selected for AL7.

The following table shows the active links and execution order:

The following diagram shows that active links AL6, AL7, and AL8 are running in parallel running in parallel to the main thread where AL3, AL4, AL5 execute. The the Don't wait for completion option is selected for AL7. Active link AL9 will execute after AL3 and AL4, and AL5 complete execution without waiting for AL7 to complete execution: