Project script examples

This section provides some examples for your reference to help you write your own project scripts.

Example: Customize fields in New Defect dialog box

This example shows how you can customize the field layout and other field properties in the New Defect dialog box. You can create similar code to arrange the layout of the Defect Details dialog box.

This example involves the following example functions:

  • SetFieldApp function. Receives a field name and its properties as parameters, and assigns the properties to the field.

    Add the following code in the Bug_SharedFunction event. It assigns the following field properties: field visibility, whether the field is required, the number of the page (tab) on which the field should be displayed, and the view order (from left to right and from top to bottom).

    Copy code 
    function SetFieldApp(fieldName, Vis, Req, PNo, VOrder){
        var bugfield = Bug_Fields(fieldName);
        bugfield.IsVisible = Vis;
        bugfield.IsRequired = Req;
        bugfield.PageNo = PNo;
        bugfield.ViewOrder = VOrder;
        console.log("SetFieldApp");
    }

  • FieldCust_AddDefect function. Calls the SetFieldApp function for each field in the New Defect dialog box, to set the properties of the field. For some of the fields, FieldCust_AddDefect checks the user group to which the current user belongs, and customizes the field properties accordingly. A call to FieldCust_AddDefect is placed in the Bug_New event procedure.

    • In the Bug_New event, add the following example code that handles the fields that are common to all user groups. It uses conditional statements for the fields that appear in the dialog box only for specific user groups, or that have different properties for different users.

      JavaScript example:

      Copy code 
      function FieldCust_AddDefect()
      {
          // Initialize the fields of the defect 
          for (var i= 0; i<= Bug_Fields.Count -1; i++)
          {
              SetFieldApp(Bug_Fields.FieldById(i).FieldName, false, false, 100, 0);
          }
          var ViewNum = 0;
          var PageNum = 0;
          // Set fields that are in common for all user groups 
          SetFieldApp("BG_DESCRIPTION", true, false, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_SUMMARY", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_DETECTED_BY", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_DETECTION_DATE", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_DETECTION_VERSION", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_SEVERITY", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_PRIORITY", true, true, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_PROJECT", true, false, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_REPRODUCIBLE", true, false, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          SetFieldApp("BG_STATUS", true, false, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          // Set fields that are different for different user groups. 
          // Since one user can belong to multiple user groups, 
          // or none of these groups, there is no need for an Else statement.
          if (User.IsInGroup("Developer"))
          {
             SetFieldApp("BG_PLANNED_CLOSING_VERSION", true, false, PageNum, ViewNum);
             ViewNum = ViewNum + 1;
             SetFieldApp("BG_PLANNED_FIX_TIME", true, false, PageNum, ViewNum);
             ViewNum = ViewNum + 1;
          }
        
          if (User.IsInGroup("QATester")) 
          {
             PageNum = PageNum + 1;
             SetFieldApp("BG_USER_01", true, false, PageNum, ViewNum);
             ViewNum = ViewNum + 1;
             SetFieldApp("BG_USER_02", true, false, PageNum, ViewNum);
             ViewNum = ViewNum + 1;
          }
          
          SetFieldApp("BG_ACTUAL_FIX_TIME", true, false, PageNum, ViewNum);
          ViewNum = ViewNum + 1;
          // ...
          console.log("FieldCust_AddDefect");
      } 

    • Add a call to FieldCust_AddDefect in the Bug_New event procedure so that it will be triggered when a user adds a new defect:

      JavaScript example:

      Copy code 
      function Bug_New() {
          FieldCust_AddDefect();
      }

Back to top

Example: Prevent users from performing an action

This example demonstrates how you can prevent users from performing an action under a specific circumstance.

The code prevents users from deleting a defect if the defect status is New.

Add the following code to the ActionCanExecute event procedure so that the check is performed when a user attempts to execute an action.

Copy code 
function ActionCanExecute(actionName) {
   if (actionName === 'Defects.DeleteDefect') {
     if (Bug_Fields("BG_STATUS").Value === 'New') {
        MsgBox('Defect with New status cannot be deleted.');
        return false;
      }  
    }
    return true;
 }

Back to top

Example: Change tab names of entity details dialog box

This example demonstrates how to customize tab names in the New Defect dialog box. This example sets the tabs to General, Environments, and Business Case.

Add the following JavaScript code to the Defects_GetDetailsPageName event procedure, which is triggered before ALM opens the New Defect dialog box:

Copy code 
function GetDetailsPageName(pageName, pageNum) {
    if (ActiveDialogName === "New Bug") {
        var detailsPageName;
        switch (pageNum) {
            case 1:
                detailsPageName = "General";
                break;
            case 2:
                detailsPageName = "Environments";
                break;
            default:
                detailsPageName = "Business Case";
                break;
        }
        return detailsPageName;
    }
}

Back to top

Example: Add a template to a memo field

You can use project scripts to add a default template to a memo field. This example adds text to a user-defined memo field BG_USER_25 to display a template when a defect is added.

Add the following JavaScript code to the Bug_New event procedure:

Copy code 
    function Bug_New() {
        Bug_Fields("BG_USER_25").Value = "<html><body><b>Step by step scenario:</b>" + "<br><br><br><b>How it affects the user:</b></body></html>";
        console.log("Bug_New");
    }

Back to top

Example: Change a field based on the user group

This example demonstrates how you can change a field value according to the user group of the user entering the defect.

In this example, the user-defined field BG_USER_01 is a detection mode field in which the user who detected the defect can enter the way in which it was discovered. Possible values are Formal testing, Informal testing, and BTW.

The example sets the value of the detection mode field to BTW when a defect is opened by a user who is not in the QATester group. If the defect is opened by a user who is in the QATester group, the default value is set to Formal testing.

Add the following JavaScript code to the Bug_New event, so that it is triggered when a defect is added:

Copy code 
    function Bug_New() {
        if (!(User.IsInGroup("QATester")))
           {
             Bug_Fields("BG_USER_01").Value = "BTW";
           }
        else
        {
          Bug_Fields("BG_USER_01").Value = "Formal testing";
        }
        console.log("Bug_New");
}

Back to top

Example: Change one field based on another field

This example demonstrates how you can change a field value based on the value entered into another field.

For example, you can have defects assigned to the user alex_qc when the Category field is set to UI Suggestion, and to the user alice_qc when the Category field is set to Security Issue.

The example assumes that the user-defined field BG_USER_05 is used to store the category. When the Category field is changed in the Defects module, the BG_RESPONSIBLE field is assigned the appropriate value.

Add the following JavaScript code to the Bug_FieldChange event procedure so that it is triggered when a user changes a field value for a defect.

Copy code 
    function Bug_FieldChange(fieldName) {
        if (fieldName == "BG_USER_05") {
            switch (Bug_Fields("BG_USER_05").Value)
            {
                case "UI Suggestion":
                    Bug_Fields("BG_RESPONSIBLE").Value="alex_qc";
                    break;
                case "Security Issue":
                    Bug_Fields("BG_RESPONSIBLE").Value="alice_qc";
                    break;
                default:
                    Bug_Fields("BG_RESPONSIBLE").Value="non-assigned";
            }
        }
        console.log("Bug_FieldChange");
}

Back to top

Example: Change field properties when a field changes

This example demonstrates how you can change the properties of a field when a different field is changed.

In this example, if the status of the defect(BG_STATUS) is changed to Closed, the user must provide a value in the field Closed in Version (BG_CLOSING_VERSION).

Add the following JavaScript code to the Bug_FieldChange event procedure, to make the Closed in Version field a required field if the status is changed to Closed:

Copy code 
function Bug_FieldChange(fieldName) {
    if (fieldName == "BG_STATUS")
    {
        if (Bug_Fields("BG_STATUS").Value == "Closed")
        {
            Bug_Fields("BG_CLOSING_VERSION").IsRequired=true;
        }
        else 
        {
            Bug_Fields("BG_CLOSING_VERSION").IsRequired=false;
        }
    }
    else 
    {
        // Enter your code here.;
    }
    console.log("Bug_FieldChange");
}

Back to top

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

This example demonstrates how you can perform validations of all fields by using the CanPost event procedure. For example, this code segment ensures that a user cannot reject a defect without adding a comment.

In this example, a user cannot change the defect status (BG_STATUS) to Rejected unless some explanatory text has been entered in the Comment field (BG_DEV_COMMENTS).

Add the following JavaScript code to the Bug_CanPost event so that the check is performed when the user attempts to reject the defect.

Copy code 
    function Bug_CanPost() {
        // Initialize the function's return value to avoid unpredictable behavior.
        var Bug_CanPost = false;
        if (Bug_Fields("BG_STATUS").IsModified && Bug_Fields("BG_STATUS").Value == "Rejected" &&  !(Bug_Fields("BG_DEV_COMMENTS").IsModified))
        {
            Bug_CanPost = false;
            MsgBox("You must enter a comment when rejecting a defect.");
            return Bug_CanPost;
        }  
        else
        {
            Bug_CanPost = true;
            return Bug_CanPost;
        }     
        console.log("Bug_CanPost");
}

Back to top

Example: Validate a field

This example demonstrates how to validate a single field value. For example, the following code segment shows how you can ensure that a user in a specific group cannot lower the priority of a defect.

In this example, if the user is in the QATestergroup and updating the BG_PRIORITY field, the new value of the BG_PRIORITY field cannot be lower than the current value.

This example assumes that in the Priority field list for the project, lower priorities come first when the values are sorted in ascending order. For example, the list meets this requirement if the elements are as follows: 1-Low, 2-Medium, 3-High.

Add the following JavaScript code to the Bug_FieldCanChange event procedure so that it is triggered when the user attempts to change a defect field value.

Copy code 
function Bug_FieldCanChange(fieldName, newValue) {
   // Initialize the function's return value to avoid unpredictable behavior.
   var Bug_FieldCanChange = true;
   if (User.IsInGroup("QATester") && fieldName == "BG_PRIORITY") 
      {
          if (newValue < Bug_Fields("BG_PRIORITY").Value) 
             { 
                Bug_FieldCanChange = false;
                MsgBox("You do not have permission to lower " + "defect priority.");
                return Bug_FieldCanChange;
              }
              else
              {
                Bug_FieldCanChange = true;
                return Bug_FieldCanChange;
              }
      }
    else
      {
      // Enter your code here.
      }       
    console.log("Bug_FieldCanChange");                
}

Back to top

Example: Present a dynamic field list

This example demonstrates how you can present a different field list in a field, depending on the value of another field.

The user-defined function SW_SetLists_Environment checks the value of the Environment Specification field (BG_USER_02) and assigns the appropriate field list to the Environment Type field (BG_USER_01).

This example assumes that the field lists have been defined in the project. For details, see Customize field lists.

  • Add the following JavaScript code to the Bug_MoveTo event procedure so that the user-defined function SW_SetLists_Environment is called when the user changes focus in the defects module.

    Copy code 
    function Bug_MoveTo() {
        SW_SetLists_Environment();
        console.log("Bug_MoveTo");
    }

  • Add following JavaScript code to the Bug_FieldChange event procedure so that the user-defined function SW_SetLists_Environment is called when a user changes the value of the Environment Type field (BG_USER_01)in the Defects module.

    Copy code 
    function Bug_FieldChange(fieldName) {
        if (fieldName  == "BG_USER_01")
        {
            SW_SetLists_Environment();
        }
        else
        {
            // Enter your code here.
        }
        console.log("Bug_FieldChange");
    }

  • The user-defined function SW_SetLists_Environment checks the value of the Environment Specification field (BG_USER_02) and assigns the appropriate field list to the Environment Type field (BG_USER_01).

    Copy code 
    function SW_SetLists_Environment() 
    {
        var listName;
        switch (Bug_Fields("BG_USER_01").Value) 
          {
                case "Browser":
                    listName = "Browsers";
                    break;
                case "Database Type":
                    listName = "Database Type";
                    break;
                case "Operating System":
                    listName = "Platform";
                    break;
                case "Web Server":
                    listName = "Web Server";
                    break;
                default:
                    listName = "Environment Specification";
            }
        Bug_Fields("BG_USER_02").List = Lists(listName);
        console.log("Set Environment List");
    }

Back to top