24.3 Adding Custom Handlers

Custom handlers are used in DRA for property attributes to interact with each other to accomplish a workflow task and for Load and Submit customizations in a workflow, property, or create form.

Property custom handlers

A few examples of property custom handlers, include:

  • querying the value of other fields

  • updating field values

  • toggling a field’s read-only state

  • showing or hiding fields based on configured variables

Page load handlers

Page load handlers typically perform initialization and are mostly used in custom property pages. They are only executed the first time a page is selected and in the case of property pages, they are executed after data is loaded from the server.

Form load handlers

Form load handlers typically perform initialization controls. They are executed only once when the form initially loads. In the case of property pages, they are executed before the server is queried for the properties of the selected object.

Form submit handlers

Form submit handlers enable users do some type of validation and potentially cancel form submission if something is not right.

For more detailed examples of using custom handlers and customizations in the Web Console, reference the Web Console Customization and Workflow Customization sections in the Product Customization reference on the DRA Documentation page.

See the following topics for more information about custom handler behavior and how to create them:

24.3.1 Basic Steps for Creating a Custom Handler

Before attempting to create a custom handler, ensure that custom JavaScript is enabled in the console configuration. For more information, see Enabling Custom JavaScript.

The steps below begin from a pre-selected custom handler page. To get to that point, you navigate to different handlers as follows:

  • Object properties custom handlers: Click the edit icon on a property field.

  • Page load handlers: Select the page’s Properties. For example, General > More Options > Properties.

  • Form Load or Submit Load handlers: Click the Form Properties button on a selected Workflow form, a Create Object page, or an Edit Properties page.

Creating a custom handler:

  1. Select the applicable handler tab based on the property or page you are customizing:

    • Custom Handlers

    • Page Load Handlers

    • Form Load Handlers

    • Form Submit Handlers

  2. Enable the handler page and do one of the following:

    • Property field custom handler:

      1. Select an execution time. Normally, you would use the second option.

        The execution time controls when the change handlers are executed in response to user input. Note that this setting does not apply when the field's value is updated by another custom handler using the draApi.fieldValues interface.

      2. Click + Add and choose a custom handler from the Add Custom Handler menu.

    • Page or form handler:Click + Add and choose a custom handler from the Add Custom Handler menu.

    NOTE:Typically you may only require one custom handler, but you can use more than one handler. Multiple handlers are executed sequentially in the order listed. If you want to change the order of handlers or skip a handler that is not needed, you can add flow control APIs in the script.

  3. You will need to configure each custom handler that you add to the page. Configuration options vary by handler type. The script editor has built-in Help and dynamic Intellisense code-completion assistance that also references snippets from the Help. For more information about using these features, see Using the Script Editor.

    You can create your own handler types.

    • LDAP or REST Query handlers:

      1. If you want your query to be based on static values, define Connection Information and Query Parameters.

        If you want your query to be dynamic, enter placeholder values in the mandatory fields. This is required in order for the handler to execute. The script will override the placeholder values.

        NOTE:You can also configure Headers and Cookies for the REST Query.

      2. In Pre-Query Action, use the script editor to write custom JavaScript code that will execute before the query is submitted. This script has access to all the connection information and query parameters and can modify any of them to customize the query. For example, setting query parameters based on values the user has entered in the form.

      3. In the Post-Query Action, include script to process the results of the query. Common tasks include checking for errors, updating form values based on the results returned, and validating object uniqueness based on the number of objects returned by the query.

    • Script: Insert custom JavaScript code to build the script.

    • DRA Query: Specify the JSON payload in the Query Parameters tab. The payload format must match the VarSet key or value pairs that will be sent to the DRA server. Similar to REST and LDAP queries, you can specify a Pre-Query Action that can be used to modify the payload before it is submitted to the server and a Post-Query Action to process the results.

    • Message Box handlers: After defining the properties of the message box itself, you can also write the JavaScript segments for Before-Show Action and After-Close Action.

      These actions are optional. Before-Show is used to customize any of the message box properties before it is shown to the user and the After-Close Action is used to process the user's button selection and perform any additional logic based on it.

  4. Click OK to save the handler.

For more detailed examples of using custom handlers and customizations in the Web Console, reference the Web Console Customization and Workflow Customization sections in the Product Customization reference on the DRA Documentation page

24.3.2 Enabling Custom JavaScript

For security reasons, custom JavaScript is disabled by default. Enabling custom JavaScript allows administrators to write snippets of JavaScript code, which the Web Console will execute as-is. You should only enable this exception if you understand and accept the risks.

To enable customizations to include custom JavaScript code:

  1. Navigate to the C:\ProgramData\NetIQ\DRARESTProxy location.

  2. Open the restProxy.config file.

  3. Add allowCustomJavaScript="true" to the <consoleConfiguration> element.

24.3.3 Using the Script Editor

The script editor enables free-form typing and pasting of JavaScript methods using DRA APIs to create custom handlers in DRA. The editor includes dynamic Intellisense code-completion and a fly-out Help panel to assist you when writing the script.

Intellisense Code-Completion

Intellisense in the script editor provides selectable code-completion snippets, tab-completion, and fly-out panels of API summaries with descriptions of the APIs.

NOTE:Intellisense code-completion is dynamic. This means that it can provide you with syntax options based on the type of handler you are defining the script for, but it also stores strings previously entered by the user and provides those prompts as well.

Script Editor Help

When you click the option in the script editor, a panel opens that explains the general purpose of custom handler APIs, where they are used, and also lists the APIs with descriptions of their functions by API type:

  • Global APIs include:

    • Form Access

    • Flow Control

    • Constants

  • Message Box APIs include:

    • Before-Show Action

    • After-Close Action

  • Query APIs include:

    • Query Results

    • DRA Query

    • LDAP Query

    • REST Query

24.3.4 About Custom Handler Execution

DRA provides the ability to customize web form behavior at several points in the forms execution life-cycle through custom handlers. Each type of custom handler has a specific execution window which in turn affects the scope of object data available during the execution of the customization, as follows:

  1. Form load handlers. Executed when the form loads prior to the collection of object attributes that the form is connected to. These handlers do not have access to attribute values for the target object.

  2. Page load handlers. DRA executes page load handlers the first time a page of a form is accessed. These handlers are guaranteed access to attribute values for the target object that are contained on that page.

  3. Attribute handlers. DRA executes attribute handlers when an attribute value on the form is accessed. Furthermore, each form attribute can be configured to execute its custom handlers at one of three specific points during the users interaction: (1) immediately (when the attribute gains focus), (2) when the attribute loses focus, or (3) a specified amount of time after the attribute loses focus.

  4. Form submit handlers. Form Submit handlers are executed when the form is saved or changes are applied to the form.