Draft/published system
You can decide to activate the draft/published system on a per-model basis:
If you do so:
When you create a new record, it will be put into a Draft status. This means that the record is still not published: you can continue making changes and saving the record without having to worry about showing unfinished content to your end users.
Once you're satisfied with the changes, you can click on the Publish button: the latest revision of your record will be marked as the Published version, and it will be instantly available in the DatoCMS APIs:
With the Content Delivery API and the Realtime Updates API, the default is to return only the published record, but you can request to consider the draft with the header
X-Include-Drafts: true.With the Content Management API, you can request to consider the published or draft versions of records with the parameter
?version=currentor?version=published.
If you make a change to a published record, its status will be become Updated. Again, those changes won't be visible to end users and published until you explicitly click on the Publish button again.
For more information on how the system manages the draft/published status, you can refer to this in-depth guide: Data consistency: key concepts and implications.
Saving Invalid Drafts
In some instances you may need to create posts via the UI or the API that may not have all validations in place (for instance, bulk creating records missing a specific required field like a title).
In these cases, if you have the Draft/Published flow enabled, you can also choose to allow saving records on a draft stage without passing all validations.
The feature affects the CMS and, of course, the CMA (Content Management API). When draft saving is active, it's possible to POST/PUT invalid records to CMA and have them saved: the endpoints respond with a 200, and the record just saved as a payload.
However, validations will take effect when the record is published. If the record is not valid, publication fails, and editors need to fix the content to ensure all rules are handled before proceeding to move the record into the Published stage.
Linked records must be published together
When a record links to other records, they all have to be published together — a published record cannot link to an unpublished draft, or your visitors would just see a broken link! Our system prevents this.
For example:
You have an article, "🟠 Easiest Headless CMS". This is the one you've edited and want to publish.
But it links to another article, "⚪ CMS Comparison". This is currently a draft (never published).
If you try to publish 🟠 Easiest Headless CMS without first publishing ⚪ CMS Comparison, the publish will fail.
In the CMS, a colored dot before the record name shows its current status:
🟢 Green = Published
🟠 Orange = Updated (changed since the previous publish)
⚪ Gray = Draft (never published)
To resolve this, you can tell our system which behavior you prefer: whether we should fail such attempts, or try to publish the linked records ourselves.
In the field's settings, under its Validations tab, there is an option:
"When a publishing is requested and this field references some unpublished records:"
"Fail the operation and notify the user": The publish will be stopped and you'll see an error (or an email, in the case of a scheduled publish). In our example, that means neither article will be published. ⚪ CMS Comparison will stay a unpublished draft and 🟠 Easiest Headless CMS will still show its older published version, not your latest changes.
"Publish also the referenced records": Our system will try to automatically publish all the linked-to records before publishing the linking-from record. In the example, that means it will automatically try to publish ⚪ CMS Comparison first, and then publish 🟠 Easiest Headless CMS. Both will be published at the end (assuming every linked-to record successfully published).
Keep in mind that every linked-to record might, itself, have additional links and validations, subject to the same criteria. The entire "tree" of references (every linked record, and every record THEY link to) must successfully publish or the overall operation will fail — if any linked record would fail a publish, then the entire attempt is aborted and nothing is published. (In software developer terms, the entire chain of publish operations is atomic — it all happens together or not at all.)
Video tutorial
To learn more about how DatoCMS saves versions, check out this video tutorial:
