Hooks

This topic explains the concept of HCL Compass hooks.

Hooks are entry points, like triggers, for scripts that run at specified times to control how users work in a HCL Compass 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 Compass 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 VBScript (for Windows™) and Perl (for the UNIX™ system and Windows). By default, hooks run in VBScript on Windows. For information about running hooks in Perl for Windows, see Scripting languages .

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

For convenient storage and reference, you can write both VBScript and 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 different Script editor for VBScript and 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. VBScript has access to COM objects, and Perl can gain access to COM objects through a independent software vendor package. In addition, Perl can take advantage of many independent software vendor packages. For example, a hook can interact with the user through windows, or read from and write to external files. You are responsible for ensuring that the proper independent software vendor objects are installed on the client 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 client machine.
  • Although it is possible to include SQL code in scripts, for best results, use the HCL Compass API to run queries and to retrieve data within script code. HCL Compass software 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 VBScript and Perl hooks is simplified because the operating context is consistent. Before a hook calls a VBScript or Perl script, HCL Compass software 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:

set curSession = GetSession

When you call methods in this manner, HCL Compass software 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: 

set curSession = GetSession  
 idName = GetFieldValue("id").GetValue  
 set currentObj = curSession.GetEntity("defect", idName)  
 ' Mark the entity with ID="SAMPL00000031" as a duplicate of this entity.
 ' Use the action named "duplicate".  
 set 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 HCL Compass Web, test them in the Web environment. For more information, see the Compass 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 HCL Compass software. For more information, see the Compass API Reference.

Hooks in a replicated environment

Many of the issues related to hooks running in a replicated environment are the same as for single site database locking issues. Functional testing of hooks is also the same in a single site or a replicated environment. However, the running of some HCL Compass hooks can be different in a replicated environment than in a single site environment. For example, hooks that update other records in the context of one record's action may encounter errors if the other record is not mastered at the current site, and therefore is not modifiable.

Each database record can only be updated at the site on which it is currently mastered (this is indicated by the replica site name in the record's ratl_mastership field). In complex applications multiple records may be updated as part of one complex transaction. When designing and testing hooks for a replicated environment, these principles should be taken into consideration.

For complex applications in a replicated environment with interlinked records, your schema design should handle the following cases:
  • The parent record is not modifiable due to mastership. For example, the parent record is not modifiable if it is not mastered at the current site.
  • The parent record is modifiable (mastered at the current site) but a subordinate record is not modifiable due to mastership (not mastered at the current site).

See also Record locking and Validating schemas.

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.