18 Workflow and Script Commands

This service is used to manage workflows. A workflow is a script that is uploaded to and managed by Oracle ZFS Storage Appliance. Workflows can be parameterized and executed in a first-class fashion from either the browser interface or the command line interface. Workflows can also be executed as alert actions or at a designated time; thus, they can allow the appliance to be extended in ways that capture specific policies and procedures, and they can be used to formally encode best practices for a particular organization or application.

Workflow and Script Service Commands

The following table shows the workflow service commands.

Table 18-1 Workflow Service Commands

Request	Append to Path /api/workflow/v{1|2}	Description
GET	Use only /api/workflow/v{1|2}	List the workflow service commands
POST	/workflows	Upload a new workflow onto Oracle ZFS Storage Appliance
GET	/workflows	List all workflows
GET	/workflows/workflow	List the specified workflow properties
PUT	/workflows/workflow	Modify the specified workflow properties
PUT	/workflows/workflow/execute	Execute the specified workflow
DELETE	/workflows/workflow	Destroy the specified workflow
POST	/scripts	Upload and run a script
GET	/scripts	List all running scripts
GET	/scripts/script	Reconnect to a running script
DELETE	/scripts/script	Stop a running script

Upload Workflow

Uploads a workflow to Oracle ZFS Storage Appliance.

Example Request:

POST /api/workflow/v1/workflows HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/javascript
Content-Length: 290

var workflow = {
    name: 'Echo',
    description: 'Echo bird repeats a song.',
    parameters: {
        song: {
            label: 'Words of a song to sing',
            type: 'String',
        }
    },
    execute: function (params) { return (params.song) }
};

Example Result:

HTTP/1.1 201 Created
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 268
X-Zfssa-Version: user/generic@2013.09.14,1-0
Location: /api/workflow/v1/workflows/f4fe892f-cf46-4d6a-9026-cd0c0cce9971

{
    "workflow": {
        "href": "/api/workflow/v1/workflows/f4fe892f-cf46-4d6a-9026-cd0c0cce9971",
        "name": "Echo",
        "description": "Echo bird repeats a song.",
        "uuid": "f4fe892f-cf46-4d6a-9026-cd0c0cce9971",
        "owner": "root",
        "origin": "<local>",
        "setid": false,
        "alert": false,
        "version": "",
        "scheduled": false
    }
}

List Workflows

Lists all workflows installed on an Oracle ZFS Storage Appliance system. If the query parameter showhidden=true is set, the list includes workflows that are normally hidden.

Example Request:

GET /api/workflow/v1/workflows HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json; charset=utf-8
Content-Length: 1908

{
    "workflows": [{
        "description": "Clear locks held on behalf of an NFS client",
        "href": "/api/workflow/v1/workflows/10f25f2c-3a56-e733-d9c7-d4c6fd84e073",
        ...
    },
    {
        "description": "Sets up environment for Oracle Solaris Cluster NFS",
        "href": "/api/workflow/v1/workflows/2793f2dc-72de-eac4-c58b-cfbe527df92d",
        ...
    },
    {
        "description": "Removes the artifacts from the appliance used by Oracle Solaris Cluster NFS",
        "href": "/api/workflow/v1/workflows/9e2d5eed-cc72-67b0-e913-bf5ffad1d9e1",
        ...
    },
    {
        "description": "Sets up environment to be monitored by Oracle Enterprise Manager",
        "href": "/api/workflow/v1/workflows/bb5de1b8-b950-6da6-a650-f6fb19f1172c",
        ...
    },
    {
        "description": "Removes the artifacts from the appliance used by Oracle Enterprise Manager",
        "href": "/api/workflow/v1/workflows/bd7214fc-6bba-c7ad-ed1f-942c0189e757",
        ...
    }]
}

Get Workflow

Gets properties for a single workflow. In the header, if Accept is specified as application/javascript, it returns the content of the workflow, otherwise it returns workflow properties.

Example request where Accept is specified as application/javascript:

GET /api/workflow/v1/workflows/cc574599-4763-4523-9e72-b74e1246d448 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/javascript

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/javascript; charset=utf-8
Content-Length: 916
            
    var workflow = {
    	name: 'Clear locks',
    	description: 'Clear locks held on behalf of an NFS client',
    	origin: 'Oracle Corporation',
    	version: '1.0.0',
    	parameters: {
    		hostname: {
    			label: 'Client hostname',
    			type: 'String'
    		},
    		ipaddrs: {
    			label: 'Client IP address',
    			type: 'String'
    		}
    	},
    	validate: function (params) {
    		if (params.hostname == '') {
    			return ({ hostname: 'Hostname cannot be empty.' });
    		}
    
    		if (params.ipaddrs == '') {
    			return ({ ipaddrs: 'IP address cannot be empty.' });
    		}
    	},
    	execute: function (params) {
    		try {
    			nas.clearLocks(params.hostname, params.ipaddrs);
    		} catch (err) {
    			return ('Failed to clear NFS locks: ' + err.message);
    		}
    
    		return ('Clear of locks held for ' + params.hostname +
    		    ' returned success.' );
    	}
    };

Example request where Accept is specified as application/json:

GET /api/workflow/v1/workflows/cc574599-4763-4523-9e72-b74e1246d448 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json; charset=utf-8
Content-Length: 649
            
{
    "workflow": {
        "href": "/api/workflow/v1/workflows/cc574599-4763-4523-9e72-b74e1246d448",
        "name": "Clear locks",
        "description": "Clear locks held on behalf of an NFS client",
        "uuid": "cc574599-4763-4523-9e72-b74e1246d448",
        "checksum": "695d029224f614258e626fe0b3c449c1233dee119571f23b678f245f7748d13c",
        "installdate": "Wed Apr 01 2015 17:59:44 GMT+0000 (UTC)",
        "owner": "root",
        "origin": "Oracle Corporation",
        "setid": false,
        "alert": false,
        "version": "1.0.0",
        "scheduled": false
    }
}

Modify a Workflow

You can modify properties for a single workflow by sending a PUT request to a workflow resource.

Example Request:

PUT /api/workflow/v1/workflows/6c2b6545-fa78-cc7b-8cc1-ff88bd628e7d HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/json
Content-Length: 28

{"setid": false}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 234

{
    "workflow": {
        "alert": false,
        "description": "Echo bird repeats a song.",
        "href": "/api/workflow/v1/workflows/448b78e1-f219-e8f4-abb5-e01e09e1fac8",
        "name": "Echo",
        "origin": "<local>",
        "owner": "root",
        "scheduled": false,
        "setid": true,
        "uuid": "448b78e1-f219-e8f4-abb5-e01e09e1fac8",
        "version": ""
    }
}

Execute a Workflow

Executes a workflow script and return the results. Any workflow parameters must be passed in a JSON object within the body. On success HTTP status 202 (Accepted) is returned along with a JSON object with a single result property containing the workflow output.

Example Request:

PUT /api/workflow/v1/workflows/6c2b6545-fa78-cc7b-8cc1-ff88bd628e7d/run HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/json
Content-Length: 28

{"song": "tweet tweet tweet"}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 34

{
    "result": "tweet tweet tweet\n"
}

Delete Workflow

Deletes a workflow script from Oracle ZFS Storage Appliance.

Example Request:

DELETE /api/workflow/v1/workflows/f4fe892f-cf46-4d6a-9026-cd0c0cce9971 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: */*

Example Result:

HTTP/1.1 204 No Content
X-Zfssa-Appliance-Api: 1.0

Upload and Run a Script

Uploads and runs a script on Oracle ZFS Storage Appliance.

A root user can view and access all scripts uploaded to the appliance. A non-root user can only view and access their own scripts.

For more information on scripting, see Working with CLI Scripting in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

This script lists all shares on the appliance.

Example Request:

$ curl -kv --user root:pw --data-binary @listShares.aksh \
         https://hostname:215/api/workflow/v1/scripts

POST /api/workflow/v1/scripts HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.45.0
Accept: */*
Content-Length: 12
Content-Type: application/x-www-form-urlencoded

Example Result:

HTTP/1.1 201 Created
Date: Mon, 27 Mar 2017 22:16:38 GMT
X-Zfssa-Workflow-Api: 1.1
X-Zfssa-Version: user/generic@2017.02.27,1-0
X-Zfssa-Api-Version: 1.0
Content-Type: plain/text; charset=utf-8
Transfer-Encoding: chunked

default
share1
share2
fs1
lun1

List All Running Scripts

Use the following command to list all running scripts.

A root user can view and access all scripts uploaded to Oracle ZFS Storage Appliance. A non-root user can only view and access their own scripts.

For more information on scripting, see Working with CLI Scripting in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

$ curl -kv --user root:pw https://hostname:215/api/workflow/v1/scripts

GET /api/workflow/v1/scripts HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.45.0
Accept: */*

Example Result:

HTTP/1.1 200 OK
Date: Mon, 27 Mar 2017 22:41:06 GMT
Content-Length: 96
X-Zfssa-Workflow-Api: 1.1
X-Zfssa-Api-Version: 1.0
Content-Type: application/json; charset=utf-8

{
    "scripts": [
        {
            "time": 4,
            "href": "/api/workflow/v1/scripts/1",
            "user": "root",
            "script": "1"
        },
        {
              "time": 39, 
              "href": "/api/workflow/v1/scripts/9", 
              "user": "root", 
              "script": "9"
        }
    ]
}

Reconnect to a Running Script

A root user can reconnect to any running script uploaded to Oracle ZFS Storage Appliance. A non-root user can only reconnect to their own running scripts.

For more information on scripting, see Working with CLI Scripting in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

$ curl -kv -H "Accept: text/plain" --user root:pw \
         https://hostname:215/api/workflow/v1/scripts/9

GET /api/workflow/v1/scripts/9 HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.45.0
Accept: text/plain

Example Result:

{
    "test2": {,
        "str": "this is a string",
        "bool": "True",
        "posint": 994,
        "int": 1123,
        "address": "",
        "host": "192.0.2.0",
        "hostname": "example.com",
        "color": "red",
        "languages": "latin",
        "size": "red",
        "onoff": "off",
        "number": 0,
        "stringlist": "this is another string",
        "emptystringlist": "this is another string",
        "yetanotherstr": "You can't change me",
        "emptystr": "Any string",
        "password": "password",
        "longpassword": "longpassword",
        "permissions": "022",
        "nonnegativeint": 42,
        "port": 21,
        "time": "Thu Jan 01 1970 15:22:30 GMT+0000 (UTC)",
        "date": "Sun Jun 17 2007 00:00:00 GMT+0000 (UTC)",
        "datetime": "Sun Jun 17 2007 15:22:00 GMT+0000 (UTC)",
        "hostport": "ipaddr-1",
        "dn": "uid=root,ou=people,dc=fishpong,dc=com",
        "commalist": "foo,bar"
    }
},
    "utask": []
}

Stop a Running Script

A root user can delete any running script uploaded to Oracle ZFS Storage Appliance. A non-root user can only access and delete their own running scripts.

For more information on scripting, see Working with CLI Scripting in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

$ curl -kv -X DELETE --user root:l1a \
         https://hostname:215/api/workflow/v1/scripts/9

DELETE /api/workflow/v1/scripts/9 HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.45.0
Accept: */*

Example Result:

HTTP/1.1 204 No Content
Date: Mon, 27 Mar 2017 22:59:12 GMT
Content-Length: 0
X-Zfssa-Workflow-Api: 1.1
X-Zfssa-Version: build/generic@2017.02.27,1-0
X-Zfssa-Api-Version: 1.0
Content-Type: application/json; charset=utf-8