dotCMS / dotCMS/core

[Task] v1 publishing async ops: polling status endpoint + optional webhook callback

Open
#36,047 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Team : Modernization
Dominant language
Java
Stars
970
Forks
486
Avg merge
3d 33m
Merged PRs (30d)
170

Description

Context

Surfaced by the Publishing Queue migration spike (#36039).

Several backend operations return immediately and complete asynchronously, with the result delivered only via a browser-side WebSocket system message:

  • DELETE /v1/publishing/purge (PublishingResource:894)
  • DELETE /bundle/ids (BundleResource:369)
  • DELETE /bundle/olderthan/{olderThan} (BundleResource:550)
  • DELETE /bundle/all, /all/fail, /all/success (BundleResource:604+)
  • POST /bundle (async upload, BundleResource:951)
  • POST /bundle/_generate (BundleResource:795)

Non-browser API clients (the dotCMS SDK, integration scripts, CI pipelines) cannot observe completion. They have to either poll the list endpoint with heuristics or just fire-and-forget.

The new Angular store will handle the browser case fine via the existing WebSocket plumbing, but the platform should offer a polling / callback alternative for non-browser clients.

Proposed change

Two complementary additions:

1. Operation tracking

Each async op returns an operation id in its 202 Accepted response body:

{
  "operationId": "01KT...",
  "kind": "purge|delete-bundles|delete-older-than|generate|upload-async",
  "submittedAt": "...",
  "message": "..."
}

Add a status endpoint:

GET /v1/publishing/operations/{operationId}
→ { operationId, kind, state: "pending|running|completed|failed", startedAt?, finishedAt?, message? }

State is read from a simple in-memory or persisted operation registry; entries TTL out after 24h.

2. Optional webhook

Accept an optional ?callbackUrl=... parameter on the async endpoints. On completion, POST the status payload to the URL with HMAC signing for verification. Behind a config flag.

Acceptance criteria

  • Async endpoints return an operationId
  • GET /v1/publishing/operations/{operationId} returns the current state of any in-flight or recently-completed operation
  • Webhook delivery has a single retry on 5xx and signs the body with an HMAC header
  • OpenAPI updated
  • Integration tests for the polling endpoint and the webhook path

Source links

  • Spike audit: #36039
  • Epic: #34734

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the async operations listed in PublishingResource:894 and BundleResource:369, 550, 604+, 795, and 951, then read spike #36039 to understand the existing completion flow. Done means the specified operations expose status tracking and optional signed callbacks, with OpenAPI coverage and integration tests for polling and webhooks.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.