Hooks

This topic explains the concept of DevOps Plan hooks.

Hooks are entry points, like triggers, for scripts that run at specified times to control how users work in a DevOps Plan environment.

Hooks run with the super user privilege, and thus are not subject to the usual access control or field behavior restrictions. You can use hooks to set and reset values in fields that are usually read-only. (You cannot reset system fields, such as the History field.) Required fields remain required. For more information, see the DevOps Plan Schema API Reference and Actions and access control .

Four types of hooks are supported:

  • Field hooks

    Field hooks provide a way to check a field value at run time and to adjust other fields as necessary. For example, you can validate the contents of a field or assign it a default value.

  • Action hooks

    Action hooks provide a way to perform tasks at key points in the life cycle of a record. In general, action hooks are associated with events that affect the entire record. For example, you can validate the entire record and send notifications when the action is complete.

  • Record scripts

    Record scripts provide a way to perform specific tasks at run time. They are specific to a record type and are usually associated with form controls.

  • Global scripts

    Global scripts provide a way to define libraries of routines that all record types in the schema can share. For example, you can write a subroutine, such as an e-mail notification, that can be called from any hook in any record type.

Scripting languages for hooks

You can write hooks in Perl. For information about running hooks in Perl for Windows™, see Scripting languages .

You can add a script written in Perl to field and action hooks. If you are creating global scripts or record scripts, you must use Perl.

For convenient storage and reference, you can write Perl scripts in the same schema. However, a schema runs scripts only in the language specified for that schema. For more information, see Scripting languages).

Write or edit scripts in the Script editor. When you define a new script, the Designer adds the calling syntax for that hook to the Script editor window. The calling syntax cannot be edited. The Designer also adds sample body text that you can edit as necessary. (The initial body text is commented out and does not run unless you remove the comment markers.)

The Designer provides a Script editor for Perl, and indicates the editor type in the title bar of the window. Verify that you are in the correct editor before writing your code.

  • You can take advantage of outside code to extend hook capabilities. Perl can take advantage of many independent software vendor packages. You are responsible for ensuring that the proper independent software vendor objects are installed on the application machines, or read from and write to external files. You are responsible for ensuring that the proper independent software vendor objects are installed on the application machine.
  • Although it is possible to include SQL code in scripts, for best results, use the DevOps Plan Schema API to run queries and to retrieve data within script code. The DevOps Plan application allows you to rename record types and fields, and this capability creates problems in any SQL code that you include.

Operating context for hook scripts

The process of writing Perl hooks is simplified because the operating context is consistent. Before a hook calls a Perl script, the DevOps Plan application creates a Session object and logs in the user. Because all hooks (including global scripts) are run from the context of the current record, you are provided an Entity object that corresponds to that record. (Global scripts share the Entity object associated with the hook that called it.)

Within a script, you can call the methods of Entity without specifying a leading identifier. For example, you can call the GetSession method of Entity in the following manner:

my $curSession = GetSession();

When you call methods in this manner, the DevOps Plan application assumes that you are calling a method of the implicit Entity object passed to the hook. If you want to refer to this Entity object explicitly, you can use the name of the record type as an identifier for the object. Using this identifier can help clarify code that manipulates more than one Entity object at a time, as in the following example, which marks one entity as a duplicate of another: 

# Get the current session
my $curSession = GetSession();

# Get the ID value from the field "id"
my $idName = $curSession->GetFieldValue("id")->GetValue();

# Get the current defect entity using the ID
my $currentObj = $curSession->GetEntity("defect", $idName);

# Mark the entity with ID="SAMPL00000031" as a duplicate of this entity using the action "duplicate"
my $dupEntityObj = $curSession->GetEntity("defect", "SAMPL00000031");
$curSession->MarkEntityAsDuplicate($dupEntityObj, $currentObj, "duplicate");

Because scripts can affect the behavior of a field, design and test your hook code carefully. For example, if a hook requires that a field contain some sort of value, the field becomes mandatory even if its behavior is not set to MANDATORY.

Hooks testing considerations

Hook code can introduce subtle errors at run time if it not written correctly. A hook will be compiled when you validate the schema, and any syntax or grammar errors will be marked. Test a schema with a test database before checking it in, and back up your user database before applying schema changes to it. For more information, see Testing the schema with a test database.

Consider the following issues when you plan your hooks:

  • If you plan to run hooks on DevOps Plan, test them. For more information, see the DevOps Plan Schema API Reference.
  • Test and debug your hook code so that you do not write incorrect values into your database or cause the program to process an infinite loop or wait for nonexistent input. To view debugging information (the output of the OutputDebugString method), you can use dbwin32.exe, which is included with the DevOps Plan application. For more information, see the DevOps Plan Schema API Reference.

Scripts installed by packages

When you install a package, field hooks or record scripts might be added to your schema. These scripts are part of the package, not part of your hook code.

Package-owned scripts cannot be deleted or modified; they are not part of the code owned by a schema. For this reason, there is no relationship between the default language setting you choose for your hook code and the language in which hooks owned by a package are implemented.