Write advanced project scripts

This section describes when you need to use advanced project scripts and how.

In this topic:

Advanced project scripts overview

You define advanced project scripts to process project data in the back-end. They help you manipulate project users' permissions that are tailored to your project's specific needs for entity creation, updating, and deletion. They also ensure data integrity and behavior consistency among applications that use ALM REST API.

When advanced project scripts are triggered

Advanced project scripts are triggered by requests which are sent to the database after a user completes an action in the Web Client user interface.

Advanced project scripts take effect after project scripts which are triggered by events, serving as a supplementary mechanism to ensure everything works as expected.

For example, when a user clicks New Defect in the Web Client user interface, the Bug_New event is triggered. ALM listens to the project scripts written in the the Bug_New event, and the New Defect dialog box is customized accordingly. After the user submits the defect, a request of creating a defect is sent to the background, and the Bug_Create request is triggered. ALM handles the defect data based on the scripts written in the Bug_Create request.

Where advanced project scripts apply

By default, advanced project scripts apply to Web Client only. If you want to apply them to all your applications that use ALM REST API, change the CLIENT_TYPES_BYPASS_REST_WF site parameter to None. For details about this parameter, see ALM Site Parameters.

Back to top

Use cases of advanced project scripts

Here are some use cases where advanced project scripts can help.

Use case 1: Consistent validation among applications

Suppose you already define project scripts to define that when a user creates a defect, the Detected in Release field (BG_DETECTED_IN_REL) is required for all user groups.

function SetFieldApp(fieldName, Req){
    var bugfield = Bug_Fields(fieldName);
    bugfield.IsRequired = Req;
       console.log("SetFieldApp");
}

function FieldCust_AddDefect()
{
    for (var i= 0; i<= Bug_Fields.Count -1; i++)
    {
        SetFieldApp(Bug_Fields.FieldById(i).FieldName, false, false, 100, 0);
    }
    SetFieldApp("BG_DETECTED_IN_REL", true);
}

The scripts above work fine when the user is creating a defect from the Web Client user interface.

However, if a user is creating a defect from another application that consumes ALM REST API, for example, the Excel add-in, then the defect can be submitted even when the Detected in Release field is not filled. To ensure the Detected in Release field is always filled for new defects regardless of how they are created, you need to write advanced project scripts to extend the validation.

Your advanced workflow scripts may look like the following:

function setFieldProperties(fieldName, Req){
    var bugfield = Bug_Fields(fieldName);
    bugfield.IsRequired = Req;
}

function Bug_Create(){
    setFieldProperties("BG_DETECTED_IN_REL", true);
}

Use case 2: Tailored user permission management

Suppose you already define project scripts as follows to automatically fill the Priority field of a defect with Urgent when the value of the Severity field is set to High, Very High, or Urgent:

function Bug_FieldChange(fieldName){
     if(fieldName === 'BG_SEVERITY'){
        var severity = Bug_Fields("BG_SEVERITY").Value ;
        if(severity === '3-High'||severity === '4-Very High'||severity === '5-Urgent'){
            Bug_Fields("BG_PRIORITY").Value = '5-Urgent';
        }
    }
}

The scripts above work fine for users who have the permission to edit the Priority field.

However, if a user group does not have the permission to edit the Priority field, then the field cannot be auto-filled when any user from the user group sets the Severity field to High, Very High, or Urgent. Therefore, you need to write advanced project scripts if you want to achieve both the following:

• Still disallow the user group to edit the Priority field in Web Client.

• Ensure the Priority field is updated accordingly as long as the Severity field is set to a specific value, regardless of user's edit permission on the Priority field.

Your advanced project scripts may look like the following:

function Bug_Update(){
    var severity = Bug_Fields("BG_SEVERITY").Value ;
    if(severity === '3-High'||severity === '4-Very High'||severity === '5-Urgent'){
        Bug_Fields("BG_PRIORITY").Value = '5-Urgent';
    }
}

Back to top

Before writing advanced project scripts

Before you write advanced project scripts, you should be familiar with requests and objects.

Requests for advanced project scripts

You place your code in the appropriate request so that it is invoked when a request is sent to the database.

The following table describes when each request is triggered and what you can achieve by editing the request:

Objects for advanced project scripts

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

For details, see Objects.

Back to top

Write advanced project scripts

To write advanced project scripts, you add JavaScript code to requests that are triggered by REST requests. For example, the Create request is triggered when the database receives a request to add an entity.

To write scripts for an request:

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

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

   • For requests that create entities, look for an <entity>_Create request.

   • For requests that update entities, look for an <entity>_Update request.

   • For requests that delete entities, look for an <entity>_Delete request.

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

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

   For detailed descriptions about requests, see Requests for advanced project scripts.

3. Add your JavaScript code to the request.

   See Write advanced project scripts for references.

   Note: For dates in the script, use the YYYY-MM-DD format.

4. Click Save.

Back to top

See also:

• Use project scripts to customize Web Client user interface

• Best practices for writing workflow scripts