Esc

↑↓ move↵ openIndex · Pagefind

Review native schedule publication through the API

Use an authorized inventory, explicit decisions and a verified preview to publish supported native activities without confusing planning with field updates.

Charley Forey3 min readScheduleAPITutorial
On this page
  1. 1. Confirm the supported plan and permissions
  2. 2. Obtain the decision candidates
  3. 3. Preview the complete decision set
  4. 4. Apply that exact review
  5. 5. Check the field consequences

A saved schedule is a planning record. Publishing field tasks is a separate decision: which activities become tasks, which existing tasks stay, and which exact identities should be restored rather than replaced?

The native publication API separates those decisions into inventory, preview and apply. This walkthrough focuses on integrations using the materialization endpoints. Operators can follow the separate Planner publication walkthrough on app versions with those controls. Reviewed task-date updates remain a distinct workflow for eligible adopted imports.

1. Confirm the supported plan and permissions

Use a saved native plan with flat tasks or start/finish milestones and unstarted progress. Hierarchy and derived summaries, progressed work, imported or mixed historical sources, unresolved manual edits and unsupported mappings or linked records can prevent publication.

The caller needs admin permissions for Schedule, Submittals and CRM, with all three tools enabled. Scoped tokens need schedule:read, submittals:read and crm:read for inventory and preview. Apply requires schedule:write plus the two linked-tool read scopes. Preview uses POST to carry decisions, but remains a read-only operation.

2. Obtain the decision candidates

Request GET /rest/v1.0/projects/{project_id}/schedule/materialization/inventory with the required expected_version_id and optional calculation_id.

The inventory identifies activities, existing tasks, eligible assignees and conditional actions. It provides expected_row_digest values for existing-task decisions. Similar names do not establish a match: keep the exact activity and task IDs.

Inventory does not run the engine or authorize a write. Its requires_preview is true and can_apply is false: submit the chosen decisions to the preview endpoint for engine verification. Its inventory_digest is not an apply token.

Choose the decisions deliberately:

  • create supplies an activity ID, privacy, assignee, baseline policy and unstarted-progress policy for a new task.
  • bind associates an eligible existing task with an exact activity.
  • restore reuses the original reserved retired identity, subject to current checks.
  • retain keeps an existing task without treating it as newly calculated work.
  • retire explicitly proposes retiring a task, subject to reference and ownership checks.

The result can also include project operations for already bound activities. Those are derived by the server; project is not an accepted input decision.

3. Preview the complete decision set

Send POST /rest/v1.0/projects/{project_id}/schedule/materialization/preview. This illustrative JSON assumes one eligible unbound activity and no other required decisions; replace the IDs with your saved plan’s values.

{
  "expected_version_id": 123,
  "calculation_id": 456,
  "decisions": [
    {
      "operation": "create",
      "activity_id": "excavation",
      "private": true,
      "assigned_id": null,
      "baseline_policy": "none",
      "progress_policy": "unstarted"
    }
  ]
}

For bind and restore, send activity_id, task_id and expected_row_digest. Retain and retire use the task ID and row digest. Create policies are explicit: the example creates private, unassigned work without initial baseline dates. initial_dates is the alternative baseline policy; do not choose it without reviewing that consequence.

The verified preview includes operation counts, before/after fields, lifecycle changes, calculated coverage, disclosures and blockers. A successful HTTP response is not permission to ignore blockers. Require apply_supported and can_apply to be true, then review the rows with the people responsible for the field schedule.

4. Apply that exact review

Send the same decision list to POST /rest/v1.0/projects/{project_id}/schedule/materialization/apply, adding the actual preview_digest from the verified preview. The expected version, calculation ID and 64-character digest are required.

The server rechecks authority and state before applying the supported operations atomically. The response includes publication_id, version/calculation IDs, creation time, replay status and operation counts. Counts include retained or projected tasks even when no dates changed.

An exact retry can return the existing result only while its applied state remains current. A conflict calls for a new inventory or preview and a fresh review, not guessed IDs or repeated submission of an old digest. Strict snake_case requests are limited to 10,000 decisions and 2 MiB. Oversized inventories fail rather than silently dropping records. Responses are private and not cached.

5. Check the field consequences

Publication does not copy dependencies, resource assignments, calendars or the data date into the field schedule. Do not infer that every Planner feature has been reproduced in the task views. Retained tasks outside calculated coverage have unknown criticality, not a confirmed noncritical result.

Linked submittal activity displays read task dates, but independent due and procurement dates do not move automatically. CRM reviewed snapshots can need follow-up; publication does not rewrite or publish customer updates. Review those connected records after the field update.

Use the Schedule API workflow and generated reference for complete schemas and errors. For the existing Planner controls, see the Schedule guide and adopted-import date-review tutorial.

Share this article

Written by

Charley Forey

Founder of os.construction. We're building the operating system for construction. Project Financials follows job money, and company Accounting covers the books and controls. AI agents remain planned. We write about how money and data actually move on a job, and we build in public.

Apply to the founding program →Start a free trial →
Open file