Retry Organization App Library Distribution

Tool Name: Not defined in the current tool contract

Risk Level: High

Execution Mode: Synchronous

Category: Organization App Library

Quick Start (Copy and Use)

Summary: Request another delivery attempt for eligible failed devices of one Organization App Library application release.

Prerequisites: A positive ReleaseId, an existing distribution in Releasing or Rolled out to all devices state, and at least one failed device within your scope. Obtain explicit user approval for the named release before invoking this tool.

Success Criteria: Succeeded is true, ErrorMessage is empty, and ErrorCode is empty. StatusCode alone is not sufficient because a business rejection can return StatusCode 200 with Succeeded false.

What to Do Next: Use List Organization App Library Distribution Status to verify the distribution before and after retry. A positive RetryRequestedDeviceCount is the number selected for another attempt.

Minimal Request Example:

{
  "ReleaseId": 1
}

Minimal Response Example:

{
  "RetryRequestedDeviceCount": 0,
  "Succeeded": true,
  "ErrorCode": "",
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Inspect Before Retry

When to use: Before any write, confirm the named release has relevant Failed records.

{
  "ReleaseId": 1,
  "SortBy": "status",
  "SortOrder": "desc",
  "PageIndex": 1,
  "PageSize": 20
}

Use this request with List Organization App Library Distribution Status, not with this retry tool.

Recipe 2: Request a Retry After Explicit Approval

When to use: The release is eligible and the user explicitly approved retrying that named release.

{
  "ReleaseId": 1
}

No Confirm or Reason input is defined. The current workflow does not enforce confirmation; explicit approval is still required before this high-risk write.

Recipe 3: Verify After Retry

When to use: Succeeded is true, or a timeout/network failure leaves the write outcome uncertain.

{
  "ReleaseId": 1,
  "SortBy": "status",
  "SortOrder": "desc",
  "PageIndex": 1,
  "PageSize": 20
}

Use this request with List Organization App Library Distribution Status. No polling interval is defined by the current contract.

1. Overview

1.1 Description

Retries delivery for the failed-device portion of one Organization App Library application release. It does not target a caller-supplied device list.

1.2 When to Use

• Distribution status shows one or more failed devices in your scope.
• The release already has a distribution and is Releasing or Rolled out to all devices.
• The user explicitly approves retrying the named release.

1.3 Execution Mode and Response

This is a synchronous write that returns acceptance information, not final device completion. Succeeded: true means the upstream accepted a valid retry receipt. Use distribution status to inspect device outcomes afterward.

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Similar Tools

This tool does not start a general rollout and does not retry Processing, Not Installed, or already successful records. Use List Organization App Library Distribution Status when inspection rather than a retry is required.

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`ReleaseId`

Pass a positive latest_release.release_id returned by List Organization App Library Applications or Search Organization App Library Applications. It selects one release; there is no input for a group, device list, confirmation flag, or reason.

Before sending the request, query List Organization App Library Distribution Status for the same ID and verify the release and failed-device scope. After the request, query it again before deciding whether another retry is necessary.

2.3 Parameter Combination Logic

The only request parameter is ReleaseId. Retry selection is determined by eligible failed records within your device scope. This action is not idempotent: another call can start another attempt, so do not repeat it after a timeout, network error, rate limit, or other uncertain write outcome until status has been checked.

3. Outputs

3.1 Response Examples

The Quick Start response is a successful receipt with no selected devices. A successful empty receipt is distinct from a business rejection; use Succeeded, ErrorCode, and ErrorMessage together.

Release not retryable:

{
  "RetryRequestedDeviceCount": 0,
  "Succeeded": false,
  "ErrorCode": "RELEASE_NOT_RETRYABLE",
  "Hint": "Retry only when this release is Releasing or Rolled out and distribution status shows at least one failed device you can manage; in-progress-only or success-only releases cannot be retried.",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": "This release cannot be retried in its current distribution state."
}

3.2 Field Descriptions

3.3 Status and ErrorCode Values

3.4 Completion Tracking

There is no completion ID or polling interval defined. Re-query List Organization App Library Distribution Status for the same ReleaseId; Processing is not final, while Success and Failed are final per-device outcomes.

4. Examples

4.1 Basic Example: Retry One Eligible Release

{
  "ReleaseId": 1
}

Invoke only after explicit approval and a status check confirms eligible failed records.

4.2 Advanced Example: Verify an Uncertain Write

If the retry returns WRITE_OUTCOME_UNKNOWN, do not submit the same request again immediately. Query the same release:

{
  "ReleaseId": 1,
  "SortBy": "status",
  "SortOrder": "desc",
  "PageIndex": 1,
  "PageSize": 20
}

Use that request with List Organization App Library Distribution Status to determine the current distribution state.

4.3 Error Example: Invalid Release ID

{
  "ReleaseId": 0
}

This returns Succeeded: false, ErrorCode: INVALID_REQUEST, StatusCode: -1, and ErrorMessage: ReleaseId must be a positive integer.

5. Error Handling

6. Best Practices

6.1 Performance

Read distribution status first and keep scope focused. Retry is release-wide within the eligible device scope; it cannot be narrowed by an input device list.

6.2 Safety

This is a high-risk write. The workflow has no Confirm or Reason parameter and does not enforce confirmation, so explicit user approval for the named release is required before invocation.

6.3 Idempotency

Not idempotent. Another call can start another attempt. After any uncertain result, verify distribution status instead of blindly repeating the request.

7. Related Tools

8. Tool Chains

8.1 Retry Failed Delivery Safely

List Organization App Library Applications or Search Organization App Library Applications -> List Organization App Library Distribution Status -> Retry Organization App Library Distribution -> List Organization App Library Distribution Status

1. Obtain latest_release.release_id for the intended application.
2. Inspect the release's status and confirm eligible Failed records in scope.
3. Obtain explicit user approval for the named release, then call this retry tool.
4. Re-query distribution status before deciding whether any further retry is appropriate.