Entities and hooks

Inside a Perl hook, DevOps Plan supplies an implicit Entity object representing the current data record. DevOps Plan 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. See GetSession for details.

The following examples show how to get a fields value of the $entity object.

my $fieldvalue = $entity->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. DevOps Plan 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 Perl 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".

 # Call a method of the implicit Entity object.
 my $fieldvalue = $entity->GetFieldValue("fieldname");

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

 my $value = $fieldvalue.GetValue()

 # Call the same method for the duplicate object, by explicitly acquiring
 # the other entity, which is of the defect record type.
 my $otherEntity = $sessionObj->GetEntity("defect", "BUGID00000031");
 my $fieldvalue2 = $otherEntity->GetFieldValue("fieldname");
 my $value = $fieldvalue2->GetValue();

As demonstrated in the preceding example, to access an Entity object other than the implicit one from a Perl 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.