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. When you no longer want to retain an archived workflow, you can delete it permanently from z/OSMF.

After you archive a workflow, you can only list or delete it, or retrieve the workflow properties. You cannot undo this action.

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 waiting for a called workflow to complete
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 providing the reason code that is indicated and 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, which is generated by z/OSMF 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"
}