CLI automation

This topic describes using automation with both the Delphix Engine command-line interface (CLI) and the web service API.

All functionality is available in both because the CLI is built upon the web services API. The CLI enables you to create scripts for simple automation, and it is a useful aid in the development of more complex code that uses the web service API.

Using the CLI for simple scripts

For simple automation, you can build routines that make CLI calls through SSH.

This snippet lists all environment names. It leverages the SSH key exchange explained in CLI cookbook: Configuring Key-Based SSH Authentication for Automation so that no password is required for the user named "automation".

ACTIONSCRIPT3

DELPHIX_ENGINE=172.16.180.33
SSH_CMD="ssh automation@${DELPHIX_ENGINE}"


${SSH_CMD}  "cd host; list display=name"

Backward compatibility

Both the CLI and web services API are versioned to support backward compatibility. Future Delphix versions are guaranteed to support clients that explicitly set a version provided the major version identifier is compatible. For more information, see the Web Service API Guide. The CLI will always connect with the latest version, but the version command can be used to both display the current version and explicitly bind to a supported version.

Users building a stable set of scripts can run version to get the current version. Scripts can then run the version <id> command to guarantee that their scripts will be supported on future versions. For more information on the different API versions and how they map to Delphix versions, see the API Version Information section.

Parsing CLI output

The default text output of the CLI is unstable. Any attempt to parse the output is certain to run into difficulties in repeatable results for unknown input, as well as instability as the text output is changed in subsequent releases. Column headings, column order, and the number of columns will change in subsequent releases.

You can specify a version in your scripts to counteract this, but you will not be able to take advantage of new features and fixes.

CLI as a development tool for complex automation

While the CLI is useful for simple automation tasks, it can be slow and overly complicated due to the many round trips needed to control the automation logic. For example, to disable all the environments for an engine, you could write a script which lists the environments and modifies each one:

ACTIONSCRIPT3

DELPHIX_ENGINE=172.16.180.33
SSH_CMD="ssh automation@${DELPHIX_ENGINE}"
env_array=(`${SSH_CMD}  "version 1.5.0; cd environment; list display=name" | grep -v NAME` )
for i in "${env_array[@]}"
do
  ${SSH_CMD} "version 1.5.0; cd environment; select $i; disable; commit"
done

This script works, but it will be slow on systems with many environments since each SSH command will start a new session.

The web service APIs are superior when performing many operations as a single logical unit. The web service APIs also provide substantially more data with a single call than what is shown in the CLI output, which can greatly simplify your code and avoid multiple round trips.

However, the input and output of web service API calls are JSON data, and it can be difficult to quickly determine what the input and output will look like.

For this reason, the CLI provides two options that can greatly assist you in the development of complex automation: JSON Output and Tracing.

(setopt format=json) changes the CLI to the output of all results to parseable JSON (javascript object notation). This is the fastest and easiest way to quickly see what the JSON output will look like when executed via the Web Service APIs. The JSON format has wide support in a variety of programming languages; see http://www.json.org for more information.

(setopt trace=true) will display the underlying HTTP calls being made with each operation and their JSON payload. This allows you to determine the GET and POST calls, and their JSON payloads, which perform the actions that you need to power your automation.

(setopt format=text) changes the CLI back into its regular output mode. (setopt trace=false) turns off the trace display.

Using both options will show the JSON output twice

The fastest way to develop complex automation is to experiment with the CLI and copy the underlying API calls to a custom system for better control over behavior.

ACTIONSCRIPT3

delphix421> setopt trace=true
delphix421> cd user
delphix421 user> create
delphix421 user create *> ls
Properties
    type: User
    name: (required)
    authenticationType: (unset)
    credential: (unset)
..... (Output Truncated) .....
    userType: DOMAIN
    workPhoneNumber: (unset)
delphix421 user create *> set name=Jose
delphix421 user create *> set authenticationType=NATIVE
delphix421 user create *> set credential.password=Password1
delphix421 user create *> commit;
=== POST /resources/json/delphix/user ===
{
    "type": "User",
    "name": "Jose",
    "authenticationType": "NATIVE",
    "credential": {
        "type": "PasswordCredential",
        "password": "Password1"
    }
}
=== RESPONSE ===
{
    "type": "OKResult",
    "status": "OK",
    "result": "USER-35",
    "job": null,
    "action": "ACTION-107"
}

Using the output above, you can see that to create a user you must use the URL "http://myengine/resources/json/delphix/user". You will use a POST command and pass a JSON payload which looks like the above. You will get a JSON response like the above, and can validate that the status is "OK".