Cancel a workflow

You can use this operation to cancel a z/OSMF workflow on a z/OS system.

HTTP method and URI path

PUT /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/cancel

In this request, the URI path variables are described, as follows:

<version> identifies the version of the z/OSMF workflow service. The following value is valid: 1.0.
<workflowKey> identifies the workflow to be canceled.

Query parameters

None.

Description

This operation is used to cancel a workflow. Canceling a workflow does not undo any actions that were already performed on the system as part of the workflow.

When canceled, the workflow cannot be resumed. You can view the workflow properties through a GET request, as described in Get the properties of a workflow. Also, you can delete a canceled workflow, as described in Delete a workflow.

When canceled, the name of workflow is changed. The name is appended with the text |Canceled|, followed by a timestamp (the date and time expressed in milliseconds since midnight on January 1, 1970 UTC). An example is shown in Example HTTP interaction.

This request is failed for a workflow with the status Automation in Progress. That is, it is not possible to cancel the workflow while an automated step is running. You must either allow the processing to complete, or you can stop the processing through the Workflows task.

Request content

None.

Authorization requirements

This request is available to the workflow owner only. A cancel request from another user is rejected with HTTP status code 403 (Forbidden) and an appropriate error message in the JSON response object.

For other authorization requirements, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned. Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code that is indicated and associated error message.

Table 1. HTTP error response codes for a cancel workflow properties request
HTTP error status code	Description
`HTTP 403 Forbidden`	The request was submitted from a user ID that is not the workflow owner.
`HTTP 404 Not found`	The specified workflow key was not found; the workflow does not exist.
`HTTP 409 Request conflict`	The request cannot be processed because the workflow has the status Automation in Progress.

Additional standard status codes can be returned, as described in HTTP status codes.

Response content

On successful completion, the response body contains one property, workflowName, which specifies the new name of the canceled workflow.

Example HTTP interaction

In the following example, the PUT method is used to cancel an instance of a workflow. Here, the workflow is identified by the workflow key, which is the following string value: d043b5f1-adab-48e7-b7c3-d41cd95fa4b0.

Figure 1. Sample request to cancel a workflow

PUT /zosmf/workflow/rest/1.0/workflows/d043b5f1-adab-48e7-b7c3-d41cd95fa4b0/operations/cancel HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Content-Type: application/json
Content-Length: 0
Authorization: Basic em9zbWZhZDp6b3NtZmFk

For a successful request, HTTP response code 200 is returned with the canceled workflow name in response body.

Figure 2. Sample response from a cancel workflow request

HTTP/1.1 200 OK
content-length: 59
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
date: Wed, 11 Feb 2015 18:30:33 GMT
content-type: application/json; charset=UTF-8

{
    "workflowName": "AutomationExample|Canceled|1423679433714"
}