25.2 Customizing Workflow Forms

Workflow forms, when created or modified, are saved to the Web Server and accessed in the Web Console in the Customization > Workflow page. These forms are used to submit automated workflows that are created in the Workflow Automation server. You can customize the forms to further automate and improve form usability for assistant administrators when they use the forms to carry out object management tasks.

You can add and modify existing form properties and custom handlers. The interface behavior for adding and customizing properties is the same in a Workflow Automation form as it is when customizing object properties. Reference the topics below for more information about adding and modifying properties, adding custom handlers, and understanding Workflow Automation.

25.2.1 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.

A few examples of property custom handlers, include querying the value of other fields, updating values, toggling a field’s read-only state, and showing or hiding fields based on configured variables.

Form Load handlers enable users to customize forms by typically performing some initialization of controls. Form Submit Handlers enable users do some validation and potentially cancel the submission if something is not right.

DRA also simplifies the creation of custom handlers with several selectable JavaScript (JS) macros that you can choose from in the custom handler creation and validation process.

Basic steps for creating a custom handler:

The steps below begin from a pre-selected custom handler page. To get to that point, you access object property custom handlers via the edit button on a property field. You access Form Load and Form Submit handlers from Form Properties on a workflow form or a create object page.

  1. Click the applicable custom handlers tab and enable the page .

    • Custom Handlers

    • Form Load Handlers

    • Form Submit Handlers

  2. Choose a custom handler from the drop-down menu, and select an execution time. Normally, you would use the second or third options for Execution Time.

    NOTE:Typically you may only require one custom handler, but you can use more than one handler by configuring flow controls in the script to link handlers together.

  3. You will need to configure each custom handler that you add to the page. Configuration options vary by handler type, but all of the handlers execute from JavaScript.

    You can create your own Vanilla JavaScript entries or use the built-in macros.

    • 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 text in the mandatory fields. This is required in order for the script to execute. The script will override the fake values.

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

      2. In Pre-Query Action, select a macro type: Global, Query, or Form Field.

      3. Choose a macro from the drop-down list, and insert the macro (</> Insert Macro).

      4. Insert other macros as needed, and then provide the desired values to complete the script.

        As an example, in the Pre-Query Action we’ll use a script to validate that a group name entered by a user does not already exist in Active Directory when the form is submitted.

        We need to create an LDAP query using the name entered by the user. We use the Field() macro to access the value of the Name field and build the query string which we then set as the query filter using the Filter() macro.

        Filter() = '(&(objectCategory=group)(objectClass=group)(name=' + Field(name) + '))';

      5. Following through with the example above, in the Post-Query Action we'll check the results returned by the query. The results are returned as an array of objects that matched the query, so we just need to check if the length of the array is greater than 0.

        When a matching group is found, we use the Cancel() macro to cancel the form submission, passing the macro an optional message to display to the user.

        if (QueryResults().length > 0) { Cancel('A group with that name already exists, please enter a unique name.');}

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

    • DRA Query: For the Query Parameters, define a payload in JSON format. Then use macros in similar fashion as described above for LDAP and REST queries.

    • Message Box handlers: After defining the properties of the message box itself, use macros in similar fashion as described above for LDAP and REST queries, but instead of Pre-Query and Post-Query actions, you compose the macro scripts for Before-Show and After-Close actions.

  4. Click Test Handlers to validate your script before saving the form.

    This will generate a Test Result Summary where you can view the execution results.

NOTE:If the handler depends on the current state of the form (for example, the field has a value), it will not execute successfully, since no data is loaded when editing a form. In those cases the handler will needs to be tested outside the form editor by saving the customization, navigating to the appropriate form, and filling in the required data.