Projects, plans and billing
Desk projects bundle the tickets and tasks of a customer project: a schedule with milestones and
dependencies, a time budget and a payment plan with interim and final invoices. The hours worked on a
project are work entries in HR (Leistungserfassung), which also bills them. Everything below is under https://api.mbcom.cloud/api/desk/v1. Project types,
workflows and fields are tenant configuration – read them from GET /bootstrap,
never hard-code keys.
| Step | Operations | Permission |
|---|---|---|
| Create and plan | createProjectFromTemplate, getProjectPlan, milestones, dependencies |
desk:write (read: desk:read) |
| Approve hours (HR) | approveWorkEntries, unapproveWorkEntries, correctWorkEntry |
hr:work:manage (or the chain of command) |
| Bill | payment plan; hours: createWorkBatch, listWorkRates (HR) |
hr:work:billing |
Create a project from a template
A template of a project type creates the project with its tasks (ordinary desk items), milestones
and dependencies in one transaction. Dates count from startOn. Every project has a home space (spaceId, a space id or key, required; 422 when it is
missing, unknown or archived). List a space's projects with GET /projects?spaceId=. Send dryRun=true first to see
the plan without storing anything:
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/from-template?dryRun=true' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"templateId": "erp-einfuehrung", "startOn": "2026-11-02",
"project": {"title": "ERP Müller GmbH", "spaceId": "SUPPORT", "customer": {"id": "10042", "name": "Müller GmbH"}}}'
Plan: milestones, dependencies, findings
GET /projects/{id}/plan returns the project's items with start
and end dates, its milestones, the dependencies and findings as of today: late (end passed,
not done), at_risk (a predecessor is late), blocked, conflict (a successor starts too early),
milestone_late and undated. Dates are never moved for you – reschedule items with
PATCH /items/{ref} (startOn, dueAt).
Dependencies are finish-to-start between two items of the same project, with a lag in days
(negative = overlap); a cycle is refused with 409 dependency_cycle:
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/P-12/dependencies' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"predecessorId": "<item id>", "successorId": "<item id>", "lagDays": 1}'
A milestone (createProjectMilestone) is reached by hand (achieveProjectMilestone)
or, with completion: "items", when all its items are done.
React to delays
Every 10 minutes desk looks for project items that are late or at risk and writes the events
desk.plan.late and desk.plan.at_risk – once per item and finding, again only after the
finding went away. The payload field planDays holds the delay. React to them with an automation
(POST /automations, desk:admin or a maintainer of the
space) or a flow, to comment, send a message, set a priority or a label; without one nothing
happens. Automations are definitions in the flow language that desk runs inside the change – see
"Immediate automations in desk and forge" in the Flows guide; forge projects have the
same under /api/forge/v1/projects/{key}/automations
(listForgeAutomations).
Payment plan
A project's payments (createProjectPayment) are interim
payments and one final invoice, each a fixed net amount or a percentage of budgetAmount, due with
a milestone (milestoneId) or on a date (dueOn). requestProjectPayment
builds the invoice and hands it to trade as a draft under the reference
desk:project-payment:<id>:<attempt>; a person releases it in trade, which assigns the invoice
number. The final invoice bills the whole contract value and deducts the interim invoices per tax
rate. States: planned → due → requested → drafted → invoiced (or skipped); a deleted draft or a
revoked invoice makes the payment due again.
Hours
Work is booked, approved and billed in HR (createWorkEntry): on a ticket
with the subject desk:item:<id>, on a project with the project reference desk:project:<id> (an entry on a
ticket of a project gets the project from desk). A project's spentMinutes and the summary
(getProjectSummary) are HR's totals of that reference; when HR does not
answer they are null (unknown), never an error. Crossing the warning share or the budget writes
desk.project.budget, once per threshold.
Approval (approveWorkEntries), corrections and hourly billing per project,
contract or customer (createWorkBatch with dryRun=true as preview; rates:
listWorkRates) are HR's; the batch goes to trade as a draft under
hr:work-batch:<id>.
Show and filter project tickets
ticketDisplay on a project (createProject,
updateProject) decides where its tickets show in the portal's ticket
list: tickets (default, as ordinary tickets), projects (only on the projects page) or hidden
(not in the lists; tickets assigned to the viewer still show). A PUT without ticketDisplay keeps the
stored value. In project lists, itemsByPhase counts the project's tickets per phase (new, active,
waiting, done); it is read-only. listProjects also filters by
type and by responsible=me. Every item carries the read-only projectTicketDisplay of its project
(empty without project).
listItems takes projectTickets: view applies the portal's ticket-list
rule (no project, a project with ticketDisplay=tickets, or assigned to the caller), none returns
items without project, only items with a project. Without it all items are returned, as before.
projects limits the list to comma-separated project ids:
curl 'https://api.mbcom.cloud/api/desk/v1/items?projectTickets=view&limit=25' \
-H "Authorization: Bearer $ACCESS_TOKEN"
A child ticket always has the project of its parent: a different projectId on a child is refused
with 422, and changing the project of a parent moves all its descendants along (their milestones
are cleared).