Recover Publication and Withdrawal

Use this task when a policy reports a publication or removal error after approval or archive. Policy performs these operations in the background, so the approval or archive request can succeed before delivery finishes. Withdrawal means removing this policy’s previously published configuration from the receiving products.

Prerequisites

Prepare the following:

• Identify the policy and failed publication or withdrawal.
• Obtain policy:audit for operation inspection, or involve an authorized auditor.
• Obtain policy:approve for publication retry or policy:archive for withdrawal retry.
• Follow the diagnostic request setup for application programming interface (API) examples.

In Policy Panel, open the affected policy’s Operations tab for visible evidence. If you cannot open it, send the policy name and visible error to your Policy administrator. The remaining steps require the permissions listed above.

Find the Latest Publication or Removal Request

Each publication or removal request has a generation number. A larger number identifies a later request for the same policy. Retries remain part of the same request and increase its attempt count.

Complete the following steps:

1. Read GET /policies/{policy_id}/operations with policy:audit, or open the policy’s Operations tab.
2. Select the entry with the largest generation number. For example, if the response contains generations 7 and 8, investigate 8 rather than retrying 7.
3. Copy that entry’s deploymentId, operation, lastError, and diagnostics into your incident record. The operation field distinguishes publication from removal. diagnostics can provide a message, remediation, and support reference.
4. Match the error description to the next-action table below. If the message does not explain the failure, send these details to your Policy administrator rather than guessing a repair.

If replacedByGeneration names a later request, investigate that request instead. An earlier failed publication might precede a later removal request. Retrying the earlier work is not the intended recovery.

An operations 404 can mean no recorded deployments. Confirm the policy separately before concluding that it does not exist.

Choose the Authorized Recovery Path

The descriptions below illustrate failure types. They are not exact error-message strings.

Use this table to match a failure description with its next action:

If requiresOperatorAction is true, include the diagnostic message, remediation, and supportReference in your administrator handoff. If retryable is false, investigate the diagnostic rather than forcing a retry.

If Guardrails retrieval succeeds but the policy remains Published, check the consumer identity and current receipt. The empty-string consumer setting accepts absent or empty request identity, not named requests. A nonempty setting requires an exact gateway-verified username match. A missing qualifying receipt is not failed retained publication work. Retrying publication cannot repair an identity mismatch or establish runtime activation.

Retry Retained Work

Complete the following steps:

1. Ask the administrator identified in the table to confirm that the reported problem is resolved.

2. Read the operation list again and confirm that the same request remains the latest and has retryable: true. If a later request exists, investigate it instead.

3. Set DEPLOYMENT_ID to that operation’s exact deploymentId. Use the appropriate publication or withdrawal capability.

4. Send the retry request:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" --request POST \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/policies/${POLICY_ID}/deployments/${DEPLOYMENT_ID}/retry"
   

   An empty 204 response means Policy reset eligible retained work.

5. Read the operations list again. Check for a later attempt and a new error, then follow Data verification or Guardrails verification for the policy’s targets.

If Panel offers Retry publication or Retry archive, use the same safety checks. Do not use both the button and API request for the same attempt. An absent retry control does not authorize a manual bypass.

This endpoint requires no request body, If-Match, or general Idempotency-Key. A 409 can mean that automatic processing is still active or a later request exists. Read the operation list again before selecting another deployment identifier.

Correct Inputs and Seek Reapproval

Retry reuses retained deployment artifacts. It does not compile a corrected draft or incorporate later source configuration.

Complete the following steps:

1. Ask the policy author to correct rejected policy fields, or the integration administrator to correct the named connection setting.
2. Ask the PIM administrator to check whether the failed request created or changed any PIM objects. A timeout or error does not guarantee that PIM made no changes.
3. After the administrator resolves the previous request, follow the normal draft correction, submission, and approval journey. Policy can block reapproval while prior publication remains incomplete or uncertain.
4. Inspect the new governed revision and deployment after successful approval. Follow the Data or Guardrails verification guide linked above.

If approval reports pim-publication-incomplete, send the error and previous deploymentId to the PIM integration administrator. Do not repeatedly approve or delete the policy to clear this error. Refer to authoring and review troubleshooting for the current draft handoff.

Record Manual Archive Evidence

Use this path only for evidence tied to an active withdrawal. It requires policy:archive, not merely audit access.

Complete the following steps:

1. Copy deploymentId from the latest removal request in Operations or the operation-list response.
2. Ask the PIM or Traverse integration administrator for the location identifiers associated with that removal request. Do not submit evidence until the administrator supplies and checks those identifiers.
3. Prepare the ticket reference, description, and distinct location identifiers. Explain what the operator actually observed.
4. Submit POST /policies/{policy_id}/archive-evidence using the archive evidence contract. The request includes deploymentId, ticketReference, description, and locationIds.
5. Retain the returned event identifier and recording time. A 201 response records immutable audit evidence, not completed deprotection.
6. Follow withdrawal verification. Confirm that the policy finishes archiving. Recording manual evidence alone does not complete removal.

This evidence endpoint requires no general If-Match or idempotency key. It appends an event. Inspect an uncertain result before submitting duplicate evidence. A 409 can identify inactive withdrawal or unexpected locations. Stop if you cannot obtain the expected location scope.

Verification and Escalation

Read the latest operation again and check whether its error persists. For publication, follow the Data or Guardrails verification guide for the policy’s targets. For removal, follow withdrawal verification rather than treating an accepted archive request as completion.

If uncertainty remains, preserve the current generation and escalate. Do not claim recovery from approval, retry acceptance, or an evidence event alone.

Related: recovery reference and policy lifecycle tasks.