Common API calls

This topic lists the basic building blocks from which you can create hooks.

Each API call is shown in Perl. The syntax uses an <object.><method> format.

In Perl, the current Entity object and Session object are predefined as entity and session (lowercase).

For more information, see the DevOps Plan Schema API Reference.

API Call (Perl)

Function

$entity->GetSession

Gets the session, which is necessary to invoke many other APIs.

$session->OutputDebugString

Outputs to the debug stream information that you can use for debugging your hook code or external application.

$session->GetEntity

Retrieves a record from the database.

$session->EditEntity

Edits a record retrieved from the database.

$entity->SetFieldValue

Assigns a value to a field.

$entity->Validate

Ensures that the data in a record is acceptable before the record is saved to the database.

$entity->Commit

Commits the record, including any edits, to the database.

$entity->Revert

Cancels the changes. A good method to use if validation fails and the record is not committed.

$entity->GetFieldValue

Retrieves the field info object for the specified field.

$FieldInfo->GetValue

Retrieves the values of a field.

$session->BuildQuery

Builds a query.

$QueryDef->BuildField

Includes a field in a query result set.

$QueryDef->BuildFilterOperator $QueryFilterNode->BuildFilter Operator

Builds a filter operator for a query such as "equal to" or "greater than."

$QueryFilterNode->BuildFilter

Creates support for a complex query.

$session->BuildResultSet

Creates the ResultSet object necessary to run a query.

$ResultSet->Execute

Runs the query with the current ResultSet object.

$ResultSet->MoveNext

Moves the cursor to the next record in the data set.

$ResultSet->GetColumnValue

Retrieves the value in the column you specify of the current row.

$session->GetUserLoginName

Gets the user's login ID.

$entity->Revert

Discards any changes made to the Entity object. Do not use the Revert API to stop the current action from within a hook. This API is only for reverting an action that was explicitly started within a hook or script. If you must stop the current action, use the exception mechanisms of the scripting language to throw an exception or cause the action-validation hook to return "false."