Introduction

This page documents topics related to authoring toolkits that are not specific to discovery, linking, or provisioning. Those topics are covered elsewhere.

Mount Specifications

For both virtual datasets, and for staged linked datasets, Delphix needs to mount dataset storage onto a remote host. By default, the user needs to specify where the storage should be mounted.

However, sometimes it does not makes sense to require the user to specify this mount location. For example, perhaps your toolkit works with a database system that requires a particular location for where the data to be. In such a case, a toolkit can elect to specify the mount location itself, rather than asking the user for it.

To enable this optional feature, the toolkit may supply a mountSpec hook. If supplied, the hook will determine the mount location(s), not the user. There are two of these mountSpec hooks, one for staged linked datasets, and one for virtual datasets.

mountSpec (for Linked Datasets)

If your toolkit uses the "staging" strategy for linking dSources, then you may provide a script named mountSpec in the "staged" directory.

Available Global State:

• remote – The remote object described in How to Write Lua Hooks.
• resources – The resources object described in How to Write Lua Hooks.
• repository – The repository object described in How to Write Lua Hooks.
• source – The source object described in How to Write Lua Hooks.
• parameters – The parameters object described in How to Write Lua Hooks.

Expected Output: A string which defines the mount path on the remote environment.

Execution Conditions:

• Executed whenever the Delphix Engine needs to mount storage for a linked dataset onto a staging environment.

mountSpec (for Virtual Datasets)

To control where virtual datasets are mounted, you may provide a script named mountSpec in the "virtual" directory. Because virtual datasets can be mounted to more than one location, the return type is more complicated here than in the linked case.

Available Global State:

• remote – The remote object described in How to Write Lua Hooks.
• resources – The resources object described in How to Write Lua Hooks.
• repository – The repository object described in How to Write Lua Hooks.
• source – The source object described in How to Write Lua Hooks.
• parameters – The parameters object described in How to Write Lua Hooks.

Expected Output: A MountSpecification array (see below)

Execution Conditions:

• Executed whenever the Delphix Engine needs to mount storage for a virtual dataset onto a target environment.

The MountSpecification Array

The mountSpec script must return an array. Each element of the array must be a Lua table with these properties:

• environment: Which environment to mount to.
• mountPath: The path on the environment where the mount is to appear.
• sharedPath (optional): The subdirectory within the Delphix storage area that is to be mounted. By default, no subdirectory is specified, and therefore the entire storage area is accessible at the mount location.

The returned array must satisfy these constraints:

• It must contain at least one item.
• On Windows, it must contain exactly one item.
• At least one item must reference the virtual dataset's target environment.
• sharedPath is not supported on Windows.

Localizable Error Messages

A toolkit may define any number of error messages that can be passed to the user. The toolkit can provide localized versions of these message for as many locales as desired.

Defining Error Messages

Each error message consists of three components: a message ID, a localized message string, and a set of parameters. In its messages subdirectory, the toolkit will provide a separate file for each supported locale. Each of these files will provide a localized message string for each message ID. The best way to understand this is probably by looking at an example. Following are two message files, each with two messages, one for English, and one for French.

permission=User {0} does not have permission to create DelphixDB databases on {1}.
name_clash=A database named {0} already exists on {1}.

permission=L'utilisateur {0} ne peut pas créer des bases de données sur {1} avec DelphixDB.
name_clash=Une base de données qui s'appelle {0} existe déjà sur {1}

These files create two message IDs, permission and name_clash, each of which has localized text for English and French. Each of these messages will take two parameters which will be filled in when the error is raised.

Raising Errors

A global table messages is provided to Lua hooks. Every message ID will have an entry in this table. The entry will be a Lua function that takes as many parameters as were defined in the toolkit's message file. Each of these functions will return an opaque object which represents the error message (localized, if possible, to the user's locale). In addition, a global function Fail is provided, which takes that opaque object, and raises a user-visible error in the Delphix Engine.

Here is an example of a Lua hook that will fail if it detects that the user's permissions are not suitable for configuring a new virtual dataset:

-- Run a helper shell script that will check permissions, and return "ERROR" if there is a problem.
output = RunBash {
        command     = "check_permissions.sh",
        environment = source.environment,
        user        = source.environmentUser,
        variables   = envVar,
        outputSchema= {type = "string"},
        loginShell = true
}

-- Raise an error if permissions are incorrect.
if output == "ERROR" then
  errorMessage = messages.permission(source.environmentUser, source.environment)
  Fail(errorMessage)
end