Events

During an ALM Web Client user session, as the user initiates various actions, events are triggered in Web Client. You can place code in these events to customize the execution of the associated user actions.

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

Event Description
New

This event is triggered when an entity is added to Web Client.

You can add code to this event procedure to perform an action when a new object is added.

Syntax: <entity>_New

For examples, see Example: Add a template to a memo field.

MoveTo

This event is triggered when a user changes focus from one object to another.

You can add code to this event procedure to perform actions when the user changes the focus.

Syntax: <entity>_MoveTo

For examples, see Example: Present a dynamic field list.

FieldCanChange

This event is triggered before Web Client changes a field value, to determine whether the field can be changed. It returns true or false.

You can add code to this event procedure to prevent a field from being changed in specific cases.

Syntax: <entity>_FieldCanChange(fieldName, newValue)

where fieldName is the name of the field.

newValue is the new value of the field.

For examples, see Example: Validate a field.

FieldChange

This event is triggered when the value of the specified field changes.

Every change of value triggers the FieldChange event when the field loses focus.

You can add code to this event procedure to perform an action when the value of a particular field is changed.

Syntax:  <entity>_FieldChange(fieldName)

where fieldName is the name of the filed.

For examples, see Example: Change one field based on another field.

CanPost

This event is triggered before Web Client updates an entity, to check whether the entity can be updated. It returns true or false.

You can add code to this event procedure to prevent an entity from being updated in specific cases.

Syntax: <entity>_CanPost

For examples, see Example: Validate if an entity can be updated in specific cases.

CanDelete

This event is triggered before Web Client deletes an entity, to check if the entity can be deleted. I returns true or false.

Syntax: <entity>_CanDelete(entity)

AfterPost

This event is triggered after an entity has been updated in Web Client.

Project fields should not be changed after they have been posted, because then the new value is not stored in the database.

Syntax: <entity>_AfterPost

CanAddTests

This event is triggered before Web Client adds tests to a test set, to check whether the specified tests can be added. It returns true or false.

Syntax: TestSet_CanAddTests(tests)

where Tests is an array of test IDs.

CanRemoveTests

This event is triggered before Web Client removes tests from a test set, to check whether the specified tests can be removed. It returns true or false.

Syntax: TestSet_CanRemoveTests(tests)

where Tests is an array of test IDs.

RunTestsManually

This event is triggered when a user clicks the Run with Manual Runner button to run tests in the Test Lab module.

Syntax: RunTestsManually(tests)

where tests is an array of Test Instance IDs.

Available for: Test Lab module script only, starting from 24.1 P1

DefaultResult

This event is used to determine the default return value for ALM events, such as FieldCanChange.

All ALM events call this event (unless explicitly omitted by user) to determine the default return value. DefaultResult can be used to quickly replace the default return values of all ALM events.

Available in: Common script node

Syntax: DefaultResult

CanLogin

This event is triggered to check whether the specified user can log in to the specified project. It returns true or false.

Syntax: CanLogin(domainName, projectName, userName)

where domainName is the domain name.

projectName is the project name.

userName is the user name.

Available in:Common script node

CanLogout

This event is triggered to check whether the current user can log out of the current project. It returns true or false.

Syntax: CanLogout

Available in:Common script node, starting from 24.1 P1

CanEnterModule

This event is triggered before a user enters or switches to a module in Web Client. It returns true or false.

Syntax: CanEnterModule(moduleName)

where moduleName is the ALM module name.

Available in:Common script node, starting from 24.1 P1

EnterModule

This event is triggered when a user enters or switches to a module in Web Client. It is also triggered when the user logs in to Web Client.

Syntax: EnterModule

Available in:Common script node, starting from 24.1 P1

ExitModule

This event is triggered when a user exit a module in Web Client.

Syntax: ExitModule

Available in:Common script node, starting from 24.1 P1

DialogBox

This event is triggered when a dialog box is opened or closed.

Syntax: DialogBox(dialogBoxName, isOpen)

where dialogBoxName is the name of the dialog box.

isOpen indicates whether the dialog box is open.

Available in:Common script node, starting from 24.1 P1

CanCustomize

This event is triggered when a user attempts to open the Workflow window, to check whether the specified user can customize the workflow scripts of the project. It returns true or false.

Syntax: CanCustomize(domainName, projectName, userName)

where domainName is the domain name.

projectName is the project name.

userName is the username of the user.

Available in:Common script node, starting from 24.1 P1

Attachment_CanPost

This event is triggered before Web Client updates an attachment, to check whether the attachment can be updated. It returns true or false.

Syntax: Attachment_CanPost(attachment)

Available in:Common script node, starting from 24.1 P1

Attachment_CanDelete

This event is triggered before Web Client deletes an attachment, to check whether the attachment can be deleted. It returns true or false.

Syntax: Attachment_CanDelete(attachment)

Available in:Common script node, starting from 24.1 P1

Attachment_New

This event is triggered when an attachment is added to Web Client, to check whether the attachment can be opened. It returns true or false.

Syntax: Attachment_New(attachment)

Available in:Common script node, starting from 24.1 P1

GetDetailsPageName

This event is triggered by Web Client to retrieve the name of the page (tab) that has the index number specified in PageNum in the following dialog boxes:

  • The Details dialog box for an entity

  • The New <entity> dialog box for an entity

You can add code to this event to customize the tab names for the Details dialog box.

Syntax: GetDetailsPageName(pageName, pageNum)

where pageName is the default page (tab) name (for example, Page 1).

pageNum is the page (tab) number.

Available in:Common script node

For examples, see Example: Change tab names of entity details dialog box.

ActionCanExecute

This event is triggered before Web Client performs an action that has been initiated by the user, to check whether the action can be executed.

You can add code to this event procedure to perform actions when the user has initiated a particular action, or to prevent the action from being executed in specific cases.

Available in: Common script node

Syntax: ActionCanExecute(actionName)

where actionName is the action that the user has initiated.

An action name is in the format of context.action. For example, Defect.DeleteDefect.

Important: You can use the ActionCanExecute event for main entity actions only. For details about supported actions, see Supported actions.

For examples, see Example: Prevent users from performing an action.

SharedFunction

You can define global constants or functions in the SharedFunction event.

  • Scripts included in the <module>_SharedFunction events can be used by any other event in the same module.

  • Scripts included in the Common scripts node > SharedFunction event can be used by events in any module.

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.

For examples, see Example: Customize fields in New Defect dialog box.