tibet-tws(1) -- manage the TIBET Workflow System (TWS)

SYNOPSIS

tibet tws [--confirm[=true|false]] [--no-confirm] <cancel|disable|enable|init|list|push| remove|restart|retry|submit|validate> [<flags>]

DESCRIPTION

Interacts with a CouchDB database specifically with respect to TIBET Workflow Sytem (TWS) operation. The TWS leverages CouchDB for storage of both workflow definitions and active workflow job execution. The tibet tws command allows you to view, cancel, retry, and otherwise interact with the TWS engine and the data which drives it.

Required CouchDB parameters such as server URL and database name are first checked against ENVIRONMENT VARIABLES, then against a set of TIBET configuration values rooted on tds.tws.

If the --confirm flag is active (the default) parameter values that are discovered are presented to you for confirmation/adjustment. Prompting can be turned off via the --no-confirm flag or the cli.tws.confirm configuration value.

For example:

$ export COUCH_DATABASE=dbtest_tasks
$ export COUCH_USER={username}
$ export COUCH_PASS={password}
$ export COUCH_KEY={api_key}  # optional

$ tibet tws list --flows
mailtest::Team TIBET => ["smtp"] (31ee427eac51b94470bdfd14da00715e)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004abd)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004d32)
mailtwo::Team TIBET => ["formatter","mailer"] (e52b072b50c597298c310ea9c80050b2)
sample::Team TIBET => ["sample","smtp"] (e52b072b50c597298c310ea9c800af06)

OPTIONS

CONFIGURATION SETTINGS

ENVIRONMENT VARIABLES

EXAMPLES

Initialize The Workflow Database

Use the `tibet tws init` command:

$ tibet tws init
CouchDB url [http://127.0.0.1:5984] ?
using base url 'http://127.0.0.1:5984'.
Database name [testcouch_tasks] ?
Application name [tws] ?
confirming TWS database
creating TWS database
confirming TWS design doc
inserting TWS design doc
confirming TWS core views
inserting TWS flows view
inserting TWS jobs view
inserting TWS jobs_active view
inserting TWS jobs_cancelled view
inserting TWS jobs_failed view
inserting TWS jobs_complete view
inserting TWS tasks view
TWS initialized

Enable / Disable The Workflow Engine

$ tibet tws enable --engine
Updating development configuration.
TWS enabled in development.

$ tibet tws disable --engine
Updating development configuration.
TWS disabled in development.

Enable / Disable A Flow

To enable or disable a flow you need to access the flow document's ID. You
can get this information by listing the flows. Each flow's ID will be shown
in parenthesis behind the flow.

$ tibet tws list --flows
mailtest::Team TIBET => ["smtp"] (31ee427eac51b94470bdfd14da00715e)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004abd)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004d32)
mailtwo::Team TIBET => ["formatter","mailer"] (e52b072b50c597298c310ea9c80050b2)
sample::Team TIBET => ["sample","smtp"] (e52b072b50c597298c310ea9c800af06)

Use `tibet tws disable --flow` to disable a specific flow:

$ tibet tws disable --flow e52b072b50c597298c310ea9c8004abd
{
    "ok": true,
    "id": "e52b072b50c597298c310ea9c8004abd",
    "rev": "2-9a9c8c21cfbebe25c1a55d48396f1599"
}

$ tibet tws enable --flow e52b072b50c597298c310ea9c8004abd
{
    "ok": true,
    "id": "e52b072b50c597298c310ea9c8004abd",
    "rev": "3-502d6a76bf49442e8fe822b95c39a178"
}

List Flows/Jobs/Tasks/Views

$ tibet tws list --flows
mailtest::Team TIBET => ["smtp"] (31ee427eac51b94470bdfd14da00715e)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004abd)
mailtest::Team TIBET => ["mailer"] (e52b072b50c597298c310ea9c8004d32)
mailtwo::Team TIBET => ["formatter","mailer"] (e52b072b50c597298c310ea9c80050b2)
sample::Team TIBET => ["sample","smtp"] (e52b072b50c597298c310ea9c800af06)

$ tibet tws list --jobs
sample::Team TIBET => $$ready (e52b072b50c597298c310ea9c800ef49)
sample::Team TIBET => $$ready (e52b072b50c597298c310ea9c8011ce9)
sample::Team TIBET => $$ready (e52b072b50c597298c310ea9c8015de3)

$ tibet tws list --tasks
s3 => plugin s3-upload (e52b072b50c597298c310ea9c8010560)
sample => plugin sample (e52b072b50c597298c310ea9c8010885)
sample => plugin sample (e52b072b50c597298c310ea9c801059a)
sendmail => plugin mail-sendmail (e52b072b50c597298c310ea9c8007e07)
smtp => plugin mail-smtp (e52b072b50c597298c310ea9c8005852)

$ tibet tws list --views
flows
jobs
jobs_complete
tasks
jobs_cancelled
jobs_failed
jobs_active
everything
sample

Push Workflow Design Document

$ tibet tws push --design
Design document is already up to date.

Push Core Tasks, Flows, and Views

Pushing the "map" uploads the latest version of all the defined tasks and
flows for the current tws project. Note that any files with a leading
underscore are considered private and are ignored by this command.

$ tibet tws push --map
ignoring: /Users/ss/temporary/dbtest/couch/tws/tasks/_sample.json
uploading: /Users/ss/temporary/dbtest/couch/tws/tasks/s3.json
uploading: /Users/ss/temporary/dbtest/couch/tws/tasks/sendmail.json
uploading: /Users/ss/temporary/dbtest/couch/tws/tasks/smtp.json
ignoring: /Users/ss/temporary/dbtest/couch/tws/flows/_sample.json
uploading: /Users/ss/temporary/dbtest/couch/tws/flows/mailtest.json
/Users/ss/temporary/dbtest/couch/tws/tasks/sendmail.json =>
{
    "ok": true,
    "id": "30692839999368e55ac62c52b6000a27",
    "rev": "1-4e84e92a45eb82a91b9a01f1d32390de"
}
/Users/ss/temporary/dbtest/couch/tws/tasks/s3.json =>
{
    "ok": true,
    "id": "30692839999368e55ac62c52b6000687",
    "rev": "1-7cca9c410498195b08162b357ab36fbf"
}
/Users/ss/temporary/dbtest/couch/tws/flows/mailtest.json =>
{
    "ok": true,
    "id": "30692839999368e55ac62c52b6000ca2",
    "rev": "1-5ca1b0d30afe66c43cef856366d6eb93"
}
/Users/ss/temporary/dbtest/couch/tws/tasks/smtp.json =>
{
    "ok": true,
    "id": "30692839999368e55ac62c52b600144f",
    "rev": "1-ce25bc7f6540153d4eb6f51220fa08ee"
}

Push Flows/Jobs/Tasks/Views

Use the `tibet tws push` command and provide either a specific document path
or one of the flags intended to push a particular class of document:

$ tibet tws push [<path>|--design|--flows|--map|--tasks|--views]

Cancel a Job

Cancelling a job requires a job id. You can view these in the output from
the `tibet tws list --jobs` command or you can use `tibet tws view` to run a
view to help limit the output so you find the job ID you need.

$ tibet tws cancel e52b072b50c597298c310ea9c8011ce9
{
    "ok": true,
    "id": "e52b072b50c597298c310ea9c8011ce9",
    "rev": "3-2c46abf2b79be87f7be0fbb7056a5e92"
}

Submit a Job

The `tibet tws submit` command lets you specify a job document from the
~/couch/tws/jobs directory for your project. Any entries in the JSON
document delimited by `[[` and `]]` will be replaced after you are prompted
for their values.

For example, if you submit the `sample.json` job document below:

{
    "type": "job",
    "flow": "sample",
    "owner": "Team TIBET",
    "params": {
        "smtp": {
            "to": "[[to_address]]",
            "subject": "[[subject]]"
        }
    }
}

You will be prompted for `to_address` and `subject` since this job will
trigger an email workflow.

$ tibet tws submit sample
[[to_address]] ? ss@dbsa.com
[[subject]] ? testing
{
    "ok": true,
    "id": "30692839999368e55ac62c52b6001d60",
    "rev": "1-64cbec7b86393bcf02ef81db283f721f"
}

TIBET SHELL

This command has no client-side TSH peer command.

TROUBLESHOOTING

During any operation if you receive a message including output to the effect that You are not a server admin. either export the the proper environment variables or provide your credentials in your CouchDB url prompt response.

SEE ALSO