Workflows¶

log¶

A step that writes data about the current workflow invocation to the instance log. It also writes the messages in its parameters map.

{
   "provider":":internal",
   "stepType":"log",
   "parameters": {
       "aMessage": "message content",
       "anotherMessage": "message content, too"
   }
}

pause¶

A step that pauses the workflow. The workflow is paused until a POST request is sent to /api/workflows/{invocation-id}. Sending ‘fail’ in the POST body (Content-type:text/plain) will trigger a failure and workflow rollback. All other responses are considered as successes. The pause step is intended for testing - the invocationId required to end the pause is only available in the log (and database). Adding a parameter (see log step) with the key/value “authorized”:”true” will allow the invocationId to be used as a credential as with the http/authext step below.

{
    "provider":":internal",
    "stepType":"pause"
}

pause/message¶

A variant of the pause step that pauses the workflow and allows the external process to send a success/failure message. The workflow is paused until a POST request is sent to /api/workflows/{invocation-id}. The response in the POST body (Content-type:application/json) should be a json object (the same as for the http/extauth step) containing: - “status” - can be “success” or “failure” - “reason” - a message that will be logged - “message” - a message to send to the user that will be sent as a notification and as a banner on the relevant dataset page. An unparsable reponse will be considered a Failure that will be logged with no user message. (See the http/authext step for an example POST call)

{
    "provider":":internal",
    "stepType":"pause/message"
}

http/sr¶

A step that sends a HTTP request to an external system, and then waits for a response. The response has to match a regular expression specified in the step parameters. The url, content type, and message body can use data from the workflow context, using a simple markup language. This step has specific parameters for rollback. The workflow is restarted when the external system replies with a POST request to /api/workflows/{invocation-id}. Responses starting with “OK” (Content-type:text/plain) are considered successes. Other responses will be considered failures and trigger workflow rollback.

{
  "provider":":internal",
  "stepType":"http/sr",
  "parameters": {
      "url":"http://localhost:5050/dump/${invocationId}",
      "method":"POST",
      "contentType":"text/plain",
      "body":"START RELEASE ${dataset.id} as ${dataset.displayName}",
      "expectedResponse":"OK.*",
      "rollbackUrl":"http://localhost:5050/dump/${invocationId}",
      "rollbackMethod":"DELETE ${dataset.id}"
  }
}

Available variables are:

• invocationId
• dataset.id
• dataset.identifier
• dataset.globalId
• dataset.displayName
• dataset.citation
• minorVersion
• majorVersion
• releaseStatus

http/authext¶

Similar to the http/sr step. A step that sends a HTTP request to an external system, and then waits for a response. The receiver can use the invocationId of the workflow in lieu of an api key to perform work on behalf of the user launching the workflow. The invocationId must be sent as an ‘X-Dataverse-invocationId’ HTTP Header or as an ?invocationId= query parameter. Note that any external process started using this step then has the ability to access a Dataverse instance via the API as the user. Once this step completes and responds, the invocationId is invalidated and will not allow further access.

The url, content type, and message body can use data from the workflow context, using a simple markup language. This step has specific parameters for rollback. The workflow is restarted when the external system replies with a POST request to /api/workflows/{invocation-id} (Content-Type: application/json).

The response has is expected to be a json object with three keys: - “status” - can be “success” or “failure” - “reason” - a message that will be logged - “message” - a message to send to the user that will be sent as a notification and as a banner on the relevant dataset page.

export INVOCATION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export SERVER_URL=https://demo.dataverse.org
export MESSAGE={"status":"success", "reason":"Workflow completed in 10 seconds", "message":"An external workflow to virus check your data was successfully run prior to publication of your data"}

curl -H 'Content-Type:application/json' -X POST -d $MESSAGE "$SERVER_URL/api/workflows/$INVOCATION_ID"

{
  "provider":":internal",
  "stepType":"http/authext",
  "parameters": {
      "url":"http://localhost:5050/dump/${invocationId}",
      "method":"POST",
      "contentType":"text/plain",
      "body":"START RELEASE ${dataset.id} as ${dataset.displayName}",
      "rollbackUrl":"http://localhost:5050/dump/${invocationId}",
      "rollbackMethod":"DELETE ${dataset.id}"
  }
}

Available variables are:

• invocationId
• dataset.id
• dataset.identifier
• dataset.globalId
• dataset.displayName
• dataset.citation
• minorVersion
• majorVersion
• releaseStatus

archiver¶

A step that sends an archival copy of a Dataset Version to a configured archiver, e.g. the DuraCloud interface of Chronopolis. See the DuraCloud/Chronopolis Integration documentation for further detail.

Note - the example step includes two settings required for any archiver and three (DuraCloud*) that are specific to DuraCloud.

{
  "provider":":internal",
  "stepType":"archiver",
  "parameters": {
    "stepName":"archive submission"
  },
  "requiredSettings": {
    ":ArchiverClassName": "string",
    ":ArchiverSettings": "string",
    ":DuraCloudHost":"string",
    ":DuraCloudPort":"string",
    ":DuraCloudContext":"string"
  }
}