Customizing SAP ASE Management with Hook Operations
Delphix Administration / SAP ASE Environments and Data Sources / Customizing SAP ASE Management with Hook Operations

Hook operations allow you to execute an ordered list of custom operations at select hook points in linking, provisioning and virtual dataset management. For details on the types of operations that are available, see children of this page.

dSource Hooks

Hook
Description
Pre-Sync

Pre-sync hook operations are executed before a Snapsync of a dSource.

These operations can quiesce data to be captured during the Snapsync, or stop application processes that may interfere with the Snapsync operation.

Post-Sync

Post-Sync hook operations are executed after a Snapsync operation of a dSource.

These operations can undo any changes made by the pre-sync hooks. They will run regardless of the success of pre-sync hook operations or the Snapsync itself.

VDB and vFile Hooks

Hook
Description
Configure Clone

Operations performed after initial provision or after a refresh.

This hook will run after the virtual dataset has been started.
During a refresh, this hook will run before the Post-Refresh hook.

Pre-Refresh

Operations performed before a refresh.
This hook will run before the virtual dataset has been stopped.

These operations can cache data from the virtual dataset to be restored after the refresh completes.

Post-Refresh

Operations performed after a refresh.
This hook will run after the virtual dataset has been started and after the Configure Clone hook.
This hook will not run if the refresh or Pre-Refresh hook operations fail.

These operations can restore cached data after the refresh completes.

Pre-Rewind

Operations performed before a rewind.
This hook will run before the virtual dataset has been stopped. 

These operations can cache data from the virtual dataset to be restored after the rewind completes.

Post-Rewind

Operations performed after a rewind. This hook will not run if the rewind or Pre-Rewind hook operations fail.
This hook will run after the virtual dataset has been started.
This hook will not run if the rewind or Pre-Rewind hook operations fail.

These operations can restore cached data after the rewind completes.

Pre-Snapshot

Operations performed before a snapshot.

These operations can quiesce data to be captured during the snapshot, or stop processes that may interfere with the snapshot.

Post-Snapshot

Operations performed after a snapshot.
This hook will run regardless of the success of the snapshot or Pre-Snapshot hook operations.

These operations can undo any changes made by the Pre-Snapshot hook.

Pre-Start

Operations performed before startup of a VDB or vFile.

These operations can be used to initialize configuration files, or stop processes that might interfere with the virtual dataset.

Post-Start

Operations performed after startup of a VDB of vFile.

These operations can be used to clean up any temporary files, or restart processes that may have been stopped by a Pre-Start hook, or log notifications.

Pre-Stop

Operations performed before shutdown of a VDB or vFile.

These operations can quiesce data or processes prior to virtual dataset shutdown.

Post-Stop

Operations performed after shutdown of a VDB or vFile.

These operations can be used to log notifications, clean up any temporary files, or stop/restart related processes.

Operation Failure

If a hook operation fails, it will fail the entire hook: no further operations within the failed hook will be run.

You can leverage hooks to run required scripts which address several different use cases. For example, you may want to prevent your monitoring systems from triggering during VDB startup and shutdown, you can now leverage pre- and post-hooks to run required scripts for VDB start/stop operations.

Staging Source Hooks

HookDescription
Pre-Validated Sync

Operations performed on staging server before a validated sync.
This hook will run before the validated sync operation whenever the validated sync run is triggered.

Post-Validated SyncOperations performed on staging server after a validated sync.
This hook will run after the validated sync operation whenever the validated sync run is triggered.

Setting Hook Operations

You can construct hook operation lists through the Delphix Management application or the command line interface (CLI). You can either define the operation lists as part of the provisioning process or edit them on virtual datasets that already exist.

Setting Hook Operations through the Delphix Management Application

The provisioning wizard still imports hook operations from templates.

Hook operations can be provisioned in the Hooks tab of the Add dSource or Add VDB wizards.

  1. Select the type of operation and enter a name, operation type, and script.
  2. To remove an operation from the list, click the Trash icon on the operation.
  3. When you have set all hook operations, click Next to continue with the provisioning process.

To edit hook operations on a virtual dataset:

From the Datasets panel, you can create hook operations from a template. 
  1. In the Datasets panel, click the virtual dataset.
  2. Click the Configuration tab.
  3. Within the Configuration tab, click the Hooks tab.
  4. Select the hook to edit.
  5. The current operations at this hook will be displayed. To edit this list of operations, click the Pencil icon in the top right-hand corner of the tab.
  6. Click the Plus icon to add a new operation.
  7. Select the type of operation or click  to load a hook operation template.
  8. Click the text area and edit the contents of the operation.
  9. To remove an operation from the list, click the Trash icon on the operation.
  10. When you have set all hook operations, click the checkmark to save the changes.

The provisioning wizard still imports hook operations from templates.

Setting Hook Operations through the CLI

To specify hook operations during linking, edit the relevant hook's array of operations defined on the LinkingParameters > Source > Operations object.

To specify hook operations during provisioning, edit the relevant hook's array of operations defined on the ProvisionParameters > Source > Operations object.

To edit hook operations on a dSource that already exists, edit the relevant hook's array of operations defined on the Source > Operations object.

To edit hook operations on a virtual dataset that already exists, edit the relevant hook's array of operations defined on the Source > Operations object.

For more information about these CLI objects, see the following documentation in the Help menu of the Delphix Management application:

  •  LinkedSourceOperations
  • VirtualSourceOperations
  • RunCommandOnSourceOperation
  • RunExpectOnSourceOperation API

Example of Editing Hook Operations through the CLI

  1. Navigate to the relevant source's  VirtualSourceOperations  object.
  2. Select a hook to edit.


    delphix> source
delphix source> select "pomme"
delphix source "pomme"> update
delphix source "pomme" update *> edit operations
delphix source "pomme" update operations *> edit postRefresh
  3. Add an operation at index 0.


    delphix source "pomme" update operations postRefresh *> add
delphix source "pomme" update operations postRefresh 0 *> set type=RunCommandOnSourceOperation
delphix source "pomme" update operations postRefresh 0 *> set command="echo Refresh completed."
delphix source "pomme" update operations postRefresh 0 *> ls
Properties
    type: RunCommandOnSourceOperation (*)
    command: echo Refresh completed. (*)
delphix source "pomme" update operations postRefresh 0 *> commit
  4. Add another operation at index 1 and then delete it.


    delphix source "pomme" update operations postRefresh *> add
delphix source "pomme" update operations postRefresh 1 *> set type=RunCommandOnSourceOperation
delphix source "pomme" update operations postRefresh 1 *> set command="echo Refresh completed."
delphix source "pomme" update operations postRefresh 1 *> back
delphix source "pomme" update operations postRefresh *> unset 1
delphix source "pomme" update operations postRefresh *> commit

Hook Operation Templates

You can use templates to store commonly used operations, which allows you to avoid repeated work when an operation is applicable to more than a single virtual dataset. You manage templates through the Delphix Management application.

Hook Operations Templates Not Available via CLI

Hook operation templates cannot be fully utilized from the CLI. Manage and use hook operations through the Delphix Management application.

Creating a Hook Operation Template

The provisioning wizard still imports hook operations from templates.
  1. Login to the Delphix Management application.
  2. Click Manage.
  3. Select Operation Templates.
  4. Click the Plus icon to add a new operation template.
  5. Enter a Name for the template.
  6. Select an operation Type.
  7. Enter a Description detailing what the operation does or how to use it.
  8. Enter operation Contents to implement the operation partially or fully.
  9. Click Create.

Importing a Hook Operation Template

To import a hook operation template:
  1. In the Datasets panel, select a dataset.
  2. Click the Configuration tab.
  3. Within the Configuration tab, click the Hooks tab.
  4. Select the hook to edit.
  5. Click the Plus icon to add a new operation.
  6. Click Import.
  7. Select the template to import.
  8. Click Import.
  9. When you have set all hook operations, click Check to save the changes.

Exporting a Hook Operation Template

To export a hook operation template:
  1. In the Datasets panel, select a dataset.
  2. Click the Configuration tab.
  3. Within the Configuration tab, click the Hooks tab. 
  4. Select the hook to edit.
  5. Click the Plus icon to add a new operation.
  6. Select the type of operation.
  7. Click the text area and edit the contents of the operation.
  8. Click Export.
  9. Enter a Name for the template.
  10. Enter a Description detailing what the operation does or how to use it.
  11. Click Export.

Validated Sync Hooks

The ASE pre and post validated sync hooks is a new feature that allows users to specify code to be run on the staging server before and after a validated sync is run. As with other hooks, users may specify multiple hooks to be run in sequence. By default, the ordering of the sequence of hooks is the order in which the hooks were specified. Using the GUI, hooks can be edited and their order of execution can be changed.

There are a few important differences between hooks and scripts. A hook specify lines of code to be run, whereas a script specifies a path to an executable file. For a given dSource, only one pre script and one post script can be specified, but multiple pre validated sync hooks and post validated sync hooks can be specified. As mentioned earlier, the order or hooks can be manipulated in the GUI.

In a future release, the existing pre and post staging scripts will be upgraded to validated sync hooks (and the staging server scripts will be removed), so it is recommended to use hooks instead of scripts.

Operations Order and Exception Handling (Hooks and Scripts)

This is the order in which hooks and scripts will be run by the validated sync thread (if all staging server hooks and scripts are used):

  1. Pre validated sync hooks
  2. Staging pre script
  3. Validated sync operation
  4. Staging post script
  5. Post validated sync hooks

If any script or hook is not specified, the validated sync thread will simply move on to the next operation. 

Exception Handling

If there is a fault thrown (non-zero error code) by any of the operations before the post validated sync hook, then the validated sync thread will jump to the post validated sync hook without executing any of the intermediate operations. In this case, if the post validated sync hook executes successfully, then the earlier fault will be thrown as the primary exception. If the post validated sync hook does not execute successfully, then the primary exception will be that of the post validated sync hook, and there will be a suppressed exception logged from the earlier fault.

To put it another way, when a validated sync is triggered, the post validated sync hook will always be attempted even if one of the previous operations failed. If an error occurs in the post validated sync hook, then the primary exception will be that of the post validated sync hook, and there may be a suppressed exception if there were earlier failures. Otherwise, the earlier failure (if there was one) will be the primary exception that is thrown.

Note that if the post validated sync hook failed (but all previous operations passed), then the snapshot will still have been taken even though a validated sync failed fault is thrown.

Setting Staging Hook Operations through the Delphix Management Application

The process of adding staging hooks via the Delphix Management Application GUI is identical to that of other hooks.

Setting Staging Hook Operations with the CLI

The process of adding staging hooks via the CLI is very similar to that of other hooks which are created when linking (adding) or attaching a dSource. The only difference is that instead of navigating to the operation object, you will instead need to navigate to the stagingOperations object. Then you can choose the type of hook to be created, and then add a new hook to the array.

Strings with spaces in the CLI

In order to use the CLI to set a string that included space characters, the string must be enclosed in double quotes. For example, if a name field should be set to be My Name, then the following will work:

set name="My Name"

But both of the following will fail:

set name=My Name
set name='My Name'

Example of adding validated sync hooks in the CLI

The following is an example of how to add a post validated sync hook when linking a dSource. This hook will be added at index 0 in the postValidatedSync array.

link *> edit linkData
link linkData *> edit stagingOperations
link linkData stagingOperations *> edit postValidatedSync
link linkData stagingOperations postValidatedSync *> add
link linkData stagingOperations postValidatedSync 0 *> set name=set name="Post Validated Sync Hook 0"
link linkData stagingOperations postValidatedSync 0 *> set type=RunBashOnSourceOperation 
link linkData stagingOperations postValidatedSync 0 *> set command="echo 'Post Validated Sync Hook 0'"

A slightly different way to add more elements to the list of post validated sync hooks would be to specify the next index (which would be index 1 in this case), instead of using the add command.

link linkData *> set linkData.stagingOperations.postValidatedSync.1.name="Post Validated Sync Hook 1"
link linkData *> set linkData.stagingOperations.postValidatedSync.1.type=RunBashOnSourceOperation
link linkData *> set linkData.stagingOperations.postValidatedSync.1.command="echo 'Post Validated Sync Hook 1'"

Using Validated Sync Hooks with Dump History

In some cases, it may be necessary to enable dump history in order for the hooks to work properly.

Consider the following use case. A backup file is moved from the backup directory path to some other folder. Then a pre-validated sync hook is used to copy the backup file back to the backup directory path so that validated sync can restore this backup file successfully. In this case, dump history needs to be enabled in order to discover the backup files for validated sync.

Related Links