Objects

You code can reference ALM objects to obtain and change project values. This section lists the objects that are available for use when writing scripts.

Available objects

The following table lists the ALM objects that are available for use when you write workflow scripts in Web Client:

Object Description
Fields objects

You can use the Fields objects in workflow scripts to access the fields of ALM modules. For example, you can use the Req_Fields object to access the fields of the Requirements module.

For details, see Fields object.
Field object

You can use the Field object to access the properties of an entity field.

For details about the properties of the Field object, see Field object.

Lists object

Not available for:Advanced project scripts

You can use the Lists object to limit field input to a specific list of values.

For details, see Lists object.

User object

You can access the User object to retrieve the user name of the current user and to check whether the user belongs to a particular user group. You can retrieve or modify the first and last name of the user.

For details, see User object.

Back to top

Fields object

Web Client supports the following Fields objects:

Object

Description

Bug_Fields

Provides access to the fields of the defects in the Defects module and the Manual Runner dialog box.

Req_Fields

Provides access to the fields of the Requirements module.

Test_Fields

Provides access to the fields of tests in the Test Plan module.
TestFolder_Fields Provides access to the fields of test folders in the Test Plan module.

TestSet_Fields

Provides access to the fields of the test sets in the Test Lab module.
TestSetFolder_Fields Provides access to the test set folders in the Test Lab module.

TestSetTest_Fields

Provides access to the fields of the test instances in the Test Lab module.

Each of the Fields object has the following properties:

Property

R/W

Type

Description

Count

R

Number

Returns the number of fields in the current object.

Limitation: You may encounter differences in the behavior of TestSetTest_Fields.Count based on where it is called. If you call it in Web Client project scripts, it returns a bigger number than when you call it in Desktop Client workflows. That's because Web Client returns more fields for entities such as test, test set, and test configuration.

Field(FieldName)

R

Function

Accesses the fields by field name or field label.

FieldById(FieldID)

Not available for: Advanced project scripts

R

Function

Accesses the fields by the field ID number.

Back to top

Field object

The Field object has the following properties:

Property

R/W

Type

Description

FieldLabel

R

String

The displayed label of the field.

FieldName

R

String

The logical name of the field.

IsModified

R

Boolean

Specifies whether the value has been modified.

IsMultiValue

R

Boolean

Specifies whether the field can contain multiple values from a lookup list.

IsNull

R

Boolean

Specifies whether the field value is absent.

IsReadOnly

R/W

Boolean

Specifies whether the field is read-only.

IsRequired

R/W

Boolean

Specifies whether a field value is required. This enables you to override field customization information. To modify the IsRequired property of a field, the IsVisible property must be True. Changes to IsRequired are ignored if the field is not visible.

Users must always enter a value for a field that is set as required by the workflow. This applies whether they are modifying an existing record or adding a new record, and even if the field is already empty.

IsVisible

Not available for: Advanced project scripts

R/W

Boolean

Specifies whether the field is displayed.

List

Not available for: Advanced project scripts

R/W

List

Sets or retrieves the field list attached to a field of type lookup list.

PageNo

Not available for: Advanced project scripts

R/W

Integer

Sets or retrieves the page (tab) on which the field is displayed in the New <entity> and <entity> Details dialog boxes.

Value

R/W

Variant

Sets or retrieves the value of the field.

ViewOrder

Not available for: Advanced project scripts

R/W

Integer

Sets or retrieves the order in which the fields are displayed in the New Defect and Defect Details dialog boxes. You must set the value for every field in the dialog box.

For example, to display a message box when a user does not have permission to change a value in the Status field, you can use the following code:

Copy code 
MsgBox('You do not have permission to change "_& "Bug_Fields.Field("BG_STATUS").FieldLabel field."');

Back to top

Lists object

The Lists object can be used only with fields that are defined as the Lookup List type or the String type in Project Customization of project entities.

For example, to set the list in the Planned Closing Version field, depending on the Project field value, you can use the following code:

Copy code 
if (Bug_Fields.Field("BG_PROJECT").Value === "Project 1") {
    Bug_Fields.Field("BG_PLANNED_CLOSING_VER").List = Lists("All Projects");
}

Back to top

User object

The User object has the following properties:

Property

R/W

Type

Description

FullName

R/W

String

Sets or retrieves the first and last name of the current user.

IsInGroup (GroupName)

R

Boolean

Checks whether or not the current user is a member of a predefined or user-defined group.

UserName

R

String

Returns the user name used when logging in to ALM.

For example, to have a message box open when the user has project administrator permissions, use the following code:

Copy code 
if (User.IsInGroup === "TDAdmin") {
    MsgBox('"The user has administrative permissions for this project.');
}

Back to top