Task Stage Hooks

This chapter describes what stage hooks are and what they are typically used for.

What are Task Stage Hooks?

Task stage hooks are either JavaScript or XML documents containing Ant scripts (also known as build files). They can be used in a variety of scenarios, to modify test data between task stages or prepare data for specific tests. They can be used to insert or delete data from tables, or even remove entire tables from the database as required.

Task stage hooks also allow you to perform custom actions while running an XDM task, or as part of a workflow template. You can configure task templates and tasks so that stage hooks are executed before or after each of the individual stages of a task. Thus, stage hooks facilitate the integration of an XDM task into other processes. For example, a stage hook can invoke an external program as soon as an XDM task finishes, or send an email telling users that a target environment is about to be replaced with a fresh copy.

Further details and examples are provided in the examples below and the article task stage hooks in the chapter Useful Examples.

For technical details refer to the task stage hook description and the task stage hook usage description in the reference.

Create and Edit Task Stage Hooks

The following fields used when creating or editing a task stage hook.

General Settings

The general settings provide identification information.

Name specifies the name of the task stage hook.
Description is a free text field for an optional description.

Code

The code setting defines what the task stage hook does and how it functions.

Code type provides two options:
- Ant specifies that the code is an Ant project or task. This can in turn reference other Ant tasks, including those defined in XDM.
- JavaScript specifies that the code is a JavaScript program. It is also possible to execute JavaScript code using the Ant script task.
CODE is an editable text field in which to enter the Ant or JavaScript code.

Context

Task stage hooks have access to predefined runtime variables that can be used in the hook. These variables can be referenced depending on the used language:

JavaScript: Variables are referenced by name. If the value of a variable should be used in a string it must be concatenated using the plus (+) sign.
Ant: Variables are referenced by ${var}. Variables can also be embedded in strings by just referencing the variable in the mentioned form within the string started end terminated by apostrophe (").

Global variables

The following variables are available are always available and can be used in the hook context:

Ant

A Ant based hook additionally has the following variables in context:

requestedBy: The user that requested the execution
startedBy: The user that started the execution
taskTemplateName: Contains the name of the task template that is being executed
taskName: Contains the name of the task that is being executed

JavaScript

A JavaScript based hook additionally has the following variables in context:

execution: Class that represents the settings of the execution
generation: Class that represents the settings of the icebox generation. This variable is only available if the hook is called from a from icebox task.
properties: A map that contains all properties of the property files etc/task.properties and etc/runtime.properties. These files are only available if the hook is called from a task. Modifications or new variables will be available in further steps of the task execution.
task: Class that represents the settings of the task. This variable is only populated if the hook is called from a task.
taskStageHook: Class that represents the settings of the task stage hook.
taskStageHookUsage: Class that represents the settings of the task stage hook usage object. This variable is only populated if the hook is called from a task.
workflow: Class that represents the settings of the workflow. This variable is only populated if the hook is called from a workflow.

Task specific variables

Task stage hooks that are called directly by a task using Task Stage Hook Usage have access to all properties of the task. For historic reasons these parameters are stored in the files etc/task.properties and etc/runtime.properties in the tasks working directory.

Each of these properties can be accessed by a task stage hook by its name.

Modify or add variables

The XDM stage hooks allow the modification of task specific parameters and allow to set new parameters that are available in later steps of the task processing. For example, a task specific stage hook can prepare data or properties that influence the processing of a task.

New variables can be set or modified depending on the used language:

JavaScript: New variables can be set or modified by putting the name and the value in the global predefined properties map. This is a key/value map that contains the name of the variable as key and the value of the variable as value. All modifications that are made on this map will be accessible in later stages.
Ant: New variables can be set or modified with the Ant property task. The name of the variable must be prefixed with properties. so that it will survive the hook execution and is available in later steps.

Examples

The following example sets a variable customerNumber that is used in the start condition of an RLP task. The start condition selects all contracts of a specific customer number:

SELECT ID
FROM CONTRACTS
WHERE CUSTOMER_ID = ${customerNumber}

Ant

The following snippet shows show the customerNumber is populated by an ant stage hook:

<?xml version="1.0"?>
<project name="Hook" default="run">
    <target name="run">
        <!-- set a property-->
        <property name="properties.customerNumber" value="5"/>

        <!-- print this property-->
        <echo message="Customer number: ${properties.customerNumber}"/>

    </target>
</project>

property: Uses the ant property task to introduce a variable customerNumber that has the value 5. Notice that the variable must be prefixed with properties. so that is will be available in later stages.
echo: Prints the value of the previously set customerNumber variable.

JavaScript

In JavaScript the variables are set in the global property map called properties:

// set a property
var customerNumber = 5;
properties.put('customerNumber', customerNumber);

// print this property
print("Customer number: " + customerNumber);

properties.put: Set the variable customerNumber in the global scope so that is is available in later steps.
print: Prints the value of the customerNumber variable.

Using Task Stage Hooks in Task Templates

In many situations a task stage hook will be associated with a task template or task, though this need not be the case. When defining a task stage hook in association with a task template or task, the hook is entered on the Hook Usages tab. You can define which task stage hook should be executed, with which stage of the task it is associated, and whether it should run before or after that stage.

General Settings

The New Hook Usage panel has a single tab for General Settings with the following fields:

Description provides a text area to enter an optional description explaining the purpose of this task stage hook.
Active is a checkbox which allows the task stage hook to be activated or deactivated as required.
Stage defines the task stage with which this task stage hook will be associated.

The stage must be specified with its correct name. For example, "Stage1" not "1" or "stage 1".

Hook phase is a drop-down list with the choices Pre and Post. This defines whether the task stage hook should be executed before or after the specified stage.
Task stage hook is a drop-down list with which the user can specify which task stage hook should be executed.

Using Task Stage Hooks in a Workflow template

Task stage hooks can be used independently of any task using a workflow template. Task stage hooks are executed using the HookRunner() directive. See the linked documentation for further details.