Archive a workflow instance

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

HTTP method and URI path

POST /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/archive
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 archived.

Query parameters

None.

Description

This operation archives a workflow instance, which is identified by the workflow key that is specified in the request URI.

You can archive any workflows that are completed or that you no longer need. Doing so removes the workflow from the Workflows table in the Workflows task and places it in an archive for your reference. An archived workflow is no longer active, but its information can be viewed by you at any time. You cannot undo this action.

After you archive a workflow, you can list it or delete it, or retrieve its properties.

When you no longer want to retain an archived workflow, you can delete it permanently from z/OSMF.

To be archived, a workflow must be in one of the following states:
  • In-progress
  • Complete
  • Canceled.
It is not possible to archive a workflow while it is involved in a workflow activity. Specifically, you cannot archive a workflow when it:
  • Is locked for an update operation
  • Contains an automated step that is running
  • Is called for processing by another workflow.

To do so, you must allow the processing to complete first.

On successful completion, HTTP status code 201 (Created) is returned, indicating that the request resulted in the archival of the workflow. The URI path for the workflow is provided in the Location response header and a response body is provided, as described in the Response content.

Request content

None.

Authorization requirements

See Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided, as described in Response content.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body that provides the reason code and the associated error message.

Table 1. HTTP error response codes for an archive workflow request
HTTP error status code Description
HTTP 400 Bad request The request contained an incorrect parameter, such as an incorrect workflow key.
HTTP 403 Forbidden The requestor user ID is not permitted to archive the workflow.
HTTP 404 Not found The specified workflow key was not found; the workflow does not exist.
HTTP 409 Request conflict Request cannot be performed because the specified workflow has a status that makes the workflow ineligible to be archived.

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

Response content

On successful completion, the service returns the response body, which contains a JSON object with the workflow key. Table 2 describes the contents of the response body.
Table 2. Response from an archive workflow request
Field name Type Description
workflowKey String Workflow key. A string value, generated by z/OSMF, which is used to uniquely identify the archived workflow instance.

Example HTTP interaction

In Figure 1, a request is submitted to archive the workflow that is identified by the workflow key 2535b19e-a8c3-4a52-9d77-e30bb920f912.
Figure 1. Sample request to archive a workflow
POST /zosmf/workflow/rest/1.0/workflows/2535b19e-a8c3-4a52-9d77-e30bb920f912/operations/archive
Host: zosmf1.yourco.com
Connection: close
A sample response is shown in Figure 2.
Figure 2. Sample response from an archive workflow request
HTTP/1.1 201 Created
{
"workflowKey": "2535b19e-a8c3-4a52-9d77-e30bb920f912"
}