Entities and hooks

Inside a VBScript hook, HCL Compass supplies an implicit Entity object representing the current data record. If your VBScript hook calls a method of Entity without supplying a leading identifier, HCL Compass automatically uses this implicit Entity object. In addition, HCL Compass hooks define an explicit "entity" variable to use if you want to specify the object to which you are referring. The entity variable name is identical to the record type name. If you are accessing the API from outside of a hook, or if you are accessing an Entity object other than the implicit one, you must specify the other Entity object explicitly. (Also, if you are using Perl, you must always supply an explicit variable, and its name is "entity". See GetSession for details.)

The following examples show two ways to call the same method in a VBScript hook. In the second example, the value, defect, represents the current entity (record type) object.

fieldvalue = GetFieldValue("fieldname").GetValue() 

or

fieldvalue = defect.GetFieldValue("fieldname").GetValue() 

The Session object provides two methods to get an entity: BuildEntity (to build a new record) or GetEntity (for an existing record). When you submit a new record, BuildEntity automatically gets the entity. To get an existing record, you pass the GetEntity method the unique identifier of the record and the record type name.

You identify Entity objects using the display name of the corresponding record type. For stateless record types, you identify individual records using the contents of the unique key field of the record type. For state-based record types, you identify records using the record's visible ID. HCL Compass assigns each new record a visible ID string composed of the logical database name and a unique, sequential number. For example, the tenth record in the database "BUGID" can have the visible ID "BUGID00000010".

The following VBScript example is from a hook that accesses two Entity objects: the implicit object, and a duplicate object. The duplicate object corresponds to the record whose ID is "BUGID00000031".

set sessionObj = GetSession 

' Call a method of the implicit Entity object.
set fieldvalue = GetFieldValue("fieldname")

' VBScript assumes the current entity implicitly.

' The fieldname must be valid or 
HCL Compass returns an error.

value = fieldvalue.GetValue() 
' Call the same method for the duplicate object, by explicitly acquiring 
' the other entity, which is of the defect record type.
set otherEntity = sessionObj.GetEntity("defect", "BUGID00000031")

set fieldvalue2 = otherEntity.GetFieldValue("fieldname")

value = fieldvalue2.GetValue() 

As demonstrated in the preceding example, to access an Entity object other than the implicit one from a VBScript hook, you must first acquire that Entity object. From outside of a hook, you must always acquire the Entity object you are going to work with.