Use project scripts to customize Web Client user interface

This section describes how to use project scripts to customize the Web Client user interface, so that end users can interact with Web Client in the way you intend.

Project scripts overview

You write project scripts to automate routine tasks and customize how end users interact with Web Client.

Project scripts are triggered by events while events are associated with user actions. During an ALM Web Client session, when a user initiates an action, such as clicking a button or editing a field, ALM triggers the corresponding event and behaves according to the JavaScript code defined in the event.

Example: When a user creates a defect in Web Client Defects module, the Bug_New event is triggered. The New Defect dialog box behaves according to the scripts written in the Bug_New event.

To customize the how the user interact with the New Defect dialog box, you may define the following in the Bug_New event:

  • Specify which defect fields are displayed.

  • Specify which defect fields are required.

  • Automatically fill a specific field with different default values for different user groups.

  • Add a template memo field into the dialog box.

Supported entities

You can customize workflows in Web Client for the following entities:

Entity Description
Req Requirement data
Test Test data
TestFolder Test folder data
TestSet Test set data
TestSetFolder Test set folder data
TestSetTests Test instance data
Bug Defect data

Back to top

Before writing project scripts

Before you write project scripts, you should be familiar with events, objects, and properties.

Events for project scripts

You place your code in the appropriate event so that it is invoked when a relevant user action is initiated.

For details about events, see Events.

Objects for project scripts

Your scripts perform customizations based on information obtained from the relevant objects, such as field information and user information.

For details, see Objects.

Properties for project scripts

You can use the ActiveModule and ActiveDialogName properties to obtain information about the active module and dialog box.

For details. see ActiveModule and ActiveDialogName properties.

Back to top

Write project scripts

To write project scripts, you add JavaScript code to events that are triggered by user actions. For example, the New event is triggered when an entity is added to Web Client.

To write scripts for an event:

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

  2. From the project scripts tree, the Workflow scripts > Project Scripts node, expand the target module and select the event to which you want to add code, depending on when you want your code to be triggered.

    • To write code that can be used by other events in the same module, look for an <module>_SharedFunction event.

    • To write code that can be used by events in multiple modules, look for the Common script > SharedFunction event.

    For detailed descriptions about events, see Events.

  3. Add your JavaScript code to the event.

    See Examples for references.

    Note: If you write date strings in the scripts, make sure the date string format is consistent with the date format setting of your browser.

    For example, if your browser sets the date string format as YYYY/MM/DD, use the same format for date strings in your scripts.

  4. Click Save.

Back to top

Examples

The following table provides some examples to help you write your own project scripts.

Workflow Task Examples
Customize dialog box

Example: Change tab names of entity details dialog box

Example: Customize fields in New Defect dialog box

Automate field value

Example: Add a template to a memo field

Example: Change a field based on the user group

Example: Change one field based on another field

Validate data

Example: Validate if an entity can be updated in specific cases

Example: Validate a field

Customize dynamic field

Example: Present a dynamic field list

Example: Change field properties when a field changes

Control user permission

Example: Prevent users from performing an action

Back to top

Debug project scripts

You can debug a workflow script to resolve its errors.

To debug a workflow script:

  1. From the project 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 Client.

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

  5. Debug the script in the browser console.

Back to top

Limitations

The project 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 project scripts tree are not available for use. They are displayed in gray.

See also: