Customize workflow scripts

You can edit project workflow scripts to customize the actions that users can perform and the fields that are available to users in the Web Runner user interface.

Note: Ensure you have the Set up Workflow permission to customize workflow scripts.

Overview

During an ALM Web Runner user session, when a user initiates an action, ALM triggers the corresponding event procedure. For example, when a user submits a defect, the Bug_New event is triggered.

To customize the Web Runner interface and control the actions that users can perform, you add JavaScript code to the appropriate events.

Example: To customize user actions when a defect is submitted, you can edit the Bug_New event under the Defects module script.

You can customize the following for defect submission:

  • Which fields are displayed.

  • Which fields are required.

  • Whether a field is auto-filled with a default value.

  • What are the valid values of a field.

Back to top

Considerations for cross project customization

If you are working in a template or linked project, the workflow scripts tree displays the following sections:

Template Scripts

Workflow scripts listed in this section are the scripts applied from the template to the linked project. They are prefixed with Template_.

If you are working with a linked project, this section is displayed only when there are template scripts defined in the template. The template scripts cannot be edited in the linked project. If you unlink a project from a template, the template scripts are removed from the project.
Project Scripts

Workflow scripts listed in this section apply only to the template or linked project in which you are working. Scripts of a template in this section are not applied to linked projects.

By default, Web Runner triggers events in template scripts. If an event does not exist in template scripts, Web Runner triggers the event in project scripts. For example, if the Bug_New event does not exist in template scripts but exist in a project script, when a defect is being submitted, Web Runner triggers the Bug_New event in the project script.

Back to top

Edit scripts

To edit a workflow script, you add JavaScript code to event procedures that are triggered by user actions.

To edit a script:

  1. In the top right corner of Web Runner, click Settings > Workflow.

  2. From the workflow scripts tree, under the node for the target module, select the event procedure to which you want to add code, depending on when you want your code to be triggered.

    Tip: The Common script node contains events that can be used by multiple modules.

    For detailed descriptions about event procedures, see Reference for ALM Events.

  3. Add your JavaScript code to the event.

  4. Click Save.

Back to top

Workflow script examples

The following table lists JavaScript examples for some events:

Event Example
Bug_New

Example: Customizing a Defects Module Dialog Box

Example: Adding a Template to a Memo Field

Example: Changing a Field Based on the User Group

Bug_FieldChange

Example: Changing One Field Based on Another Field

Example: Changing Field Properties when a Field Changes

Bug_CanPost Example: Object Validation
Bug_FieldCanChange Example: Field Validation
Bug_MoveTo Example: Presenting a Dynamic Field List

Back to top

SharedFunction event

You can define global constants or functions in the SharedFunction event. Scripts included in this event can be used by any other event.

If a script calls the SharedFunction event and changes the constants or variables of this event, the changes take effect only in this script and only in the current execution.

Back to top

Debug workflow scripts

You can debug a workflow script to resolve its errors.

To debug a workflow script:

  1. From the workflow scripts tree, select the workflow script.

  2. In the editor area, add the following statement:

    Copy code 
    debugger
    console.log("<script_name> triggered")

    For example:

    Copy code 
    function Bug_New() {
      debugger
      console.log("Bug_New triggered")
    }

  3. Press the F12 key to open the browser console.

  4. Trigger the script in Web Runner.

    For example, click the Create button in the New Defect window.

  5. Debug the script in the browser console.

Back to top

Limitations

The workflow scripts include the following limitations:

  • Not all objects or methods that are auto-suggested when editing script can be called. An error occurs if you call an unsupported object or method.

  • Some scripts listed in the workflow scripts tree are not available for use. They are displayed in gray.

See also: