Use OAuth to Call a Workflow

Pliant utilizes a standard OAuth2 procedure per the following specification https://tools.ietf.org/html/rfc6749 and https://tools.ietf.org/html/rfc7519.

To generate a token, hit the /api/token endpoint as follows:

Generating OAuth2 Token

curl -k 'https://{pliant-host}/api/oauth/token' -H 'Authorization: Basic cGxpYW50LmlvLXNwYTpWN1VPR3pBbHZ4V0xVWDhGYzVhVA==' -d 'grant_type=password&scope=read+write+execute&username={username}&password={password}'

Where pliant-host is the IP or hostname of the pliant system, scopes can be used for limiting the token's authorization (scope-based authorization is currently not implemented, but for future-proofing scopes should be set when executing the token request).

(Do not use -k if this is a domain name with a valid certificate)

The result will contain the following information:

{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "refresh_token": "{refresh_token}",
  "expires_in": 43199,
  "scope": "execute read write",
  "jti": "e80da977-c8b4-49bf-a87f-7c7b57900f18"
}

To call a workflow, we can use the /api/v1/trigger endpoint:

curl -k 'https://{pliant-host}/api/v1/trigger/{username}?folder={folder}&name={ping}&sync=true' -H 'authorization: Bearer {access_token}' -H 'Content-Type: application/json' -d '{"input":"Hello Pliant!"}'

Where access_token is the token obtained with the /api/token endpoint, the username is the name of the user that owns the workflow, the folder is the folder where the workflow is located, and name is the name of the workflow. Any properties provided with the json body data will be passed on to the workflow as input parameters if they exist.

The sync=true option can be used to force a synchronous execution, blocking the request until execution completes, and returning the result.

The result will be something like:

{
  "output": "Hello Pliant!",
  "$uuid": "38f6d224-c67d-4da0-811f-e7bde3666c0b",
  "$runner": "74673c2c-b5fc-491b-be88-9c007e0b8ffd",
  "$status": "C"
}

$uuid is the id of the workflow instance that has been executed.

$runner is the id of the (last) worker node that has taken part in the execution

$status is the status, with "C" denoting "Completed"

If we want to perform an asynchronous execution, we can use sync=false or omit the sync parameter entirely.

The result then will look like:

{
  "$uuid": "b973f326-cba1-4b93-b96b-29ac2b9be51e",
  "$runner": "74673c2c-b5fc-491b-be88-9c007e0b8ffd",
  "$status": "R"
}

$status is "R" or "Running"

To query the result of the execution, we can use the /api/v1/stats/log/{logId} endpoint, where logId is the $uuid of the workflow instance.

E.g., calling:

curl -k "https://livedemo.pliant.io/api/v1/stats/log/b973f326-cba1-4b93-b96b-29ac2b9be51e" -H "authorization: Bearer {access_token}"

Will eventually return something like:

{
  "id": "b973f326-cba1-4b93-b96b-29ac2b9be51e",
  "flowUri": "admin/User/Test WorkFlows/ping",
  "userName": "admin",
  "runner": "74673c2c-b5fc-491b-be88-9c007e0b8ffd",
  "status": "COMPLETED",
  "timeStarted": 1560159332698,
  "timeEnded": 1560159332730,
  "timeQueued": 1560159332698,
  "timePaused": null,
  "timeRan": 1560159332714,
  "duration": 16,
  "durationQueued": 16,
  "durationPaused": 0,
  "success": true,
  "result": "{\"output\":\"Hello Pliant!\"}",
  "error": "",
  "state": null
}