Creating a Draft Form

POSTing here will create a new Draft Form on the given Form. For the most part, it takes the same parameters as the Create Form request: you can submit XML or Excel files, you can provide ignoreWarnings if you'd like.

Additionally, however, you may POST with no Content-Type and an empty body to create a Draft Form with a copy of the definition (XML, XLS, etc) that is already published, if there is one. This can be useful if you don't wish to update the Form definition itself, but rather one or more Form Attachments.

If your Draft form schema contains any field path which overlaps with a field path of a previous version of the Form, but with a different data type, your request will be rejected. You can rename the conflicting field, or correct it to have the same data type as it did previously.

When a Draft is created, the expected Form Attachments are computed and slots are created, as with a new Form. Any attachments that match existing ones on the published Form, if it exists, will be copied over to the new Draft.

Even if a Draft exists, you can always replace it by POSTing here again. In that case, the attachments that exist on the Draft will similarly be copied over to the new Draft. If you wish to copy from the published version instead, you can do so by first DELETEing the extant Draft.

Draft version conflicts are allowed with prior versions of a Form while in Draft state. If you attempt to publish the Form without correcting the conflict, the publish operation will fail. You can request that Central update the version string on your behalf as part of the publish operation to avoid this: see that endpoint for more information.

The xmlFormId, however, must exactly match that of the Form overall, or the request will be rejected.

Starting from Version 2022.3, a Draft Form can also create or update a Dataset by defining a Dataset schema in the Form definition. The state of the Dataset and its Properties is dependent on the state of the Form, see Creating a new form for more details.