# Publish form definition API

## Availability

Since Orbeon Forms 2017.2.

This is an Orbeon Forms PE feature.

## Internal uses

The API is also used internally by Form Builder and by the Form Runner Home page.

## Purpose

The purpose of the `publish` API is to publish a form definition.

The form definition is:

* either provided as XHTML+XForms in the Orbeon Forms form definition format
* or stored in the database under the `orbeon/builder` app/form name

It is important to note that you cannot simply take a form definition and `PUT` it via the [persistence REST API](https://doc.orbeon.com/form-runner/api/persistence). The reason for this is that publishing requires adding some information to the form definition, such as:

* data migration information for repeated grids
* section templates must be included

Only Form Builder and Form Runner are able to provide this information consistently. So in order to publish a form definition, this API must be used.

## Interface

If the form definition is provided in the request:

* URL: `/fr/service/publish`
* Optional URL parameter:
  * Name: `document-id`
  * Value: Form Builder document id for retrieval of attachments
* Method: `POST`
* Request body: XHTML+XForms

If the form definition is NOT provided in the request:

* URL: `/fr/service/orbeon/builder/publish/$document`
  * `$document`: Form Builder document id for retrieval of attachments
* Method: `POST`
* Request body: empty

The following URL parameters apply in both cases:

* `form-definition-version`:
  * missing: indicates the latest published version, or `1` if there is no published version
  * `next`: to indicate that the form definition must be published under the next available version
  * or a specific version number: to indicate that the form definition must replace the given version
* `available`:
  * when `false`: make or keep the form definition unavailable
  * when `true` or missing: make or keep the form definition available
* `version-comment`:
  * when present, a [versioning comment](https://doc.orbeon.com/form-builder/form-editor/publishing#versioning-comments) to store with the form definition
* `upgrade-form-definition`:
  * when `true` or missing: upgrade the form definition
  * when `false`: do not upgrade the form definition
  * This should usually be `true` or missing, in order to allow:
    * form definition update to the latest format
    * inclusion of data migration information
    * embedding of section templates
  * See also [Upgrading form definitions](https://doc.orbeon.com/form-runner-pages/forms-admin-page#upgrading-form-definitions).

Response body:

* `Content-Type: application/xml`
* app/form name used

Example response body:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <app>acme</app>
    <form>sales</form>
    <published-attachments>2</published-attachments>
    <published-version>1</published-version>
</response>
```

*NOTE: When the form definition is `POST`ed as XML, form definition attachments such as PDF, XML Schema, or image attachments will not be published reliably if a `document-id` is not passed.*

## Example using curl

The following examples use the [curl](https://curl.haxx.se/) command-line utility. They are indented on multiple lines for clarity but in practice each command must be written on a single line.

### Publish a form definition stored in Form Builder

The following publishes the form definition saved with Form Builder under the `ef8b20715f447ef1ed6f2479161dc663b23f7cdc` document id:

```
curl    \
-v      \
-k      \
-X POST \
"http://localhost:8080/orbeon\
/fr/service/orbeon/builder/publish\
/ef8b20715f447ef1ed6f2479161dc663b23f7cdc"
```

### Publish a form definition provided via HTTP POST

The following publishes the form definition provided in the file `form.xhtml`:

```
curl                               \
-v                                 \
-k                                 \
-d @form.xhtml                     \
-H "Content-Type: application/xml" \
-X POST                            \
"http://localhost:8080/orbeon\
/fr/service/publish"
```

## Permissions

* The caller must either call the service internally or have [authorized the service](https://doc.orbeon.com/xml-platform/controller/authorization-of-pages-and-services).
* Appropriate container or permission headers must also be set to allow accessing the form definition and data.

## See also

* [Form Builder publishing](https://doc.orbeon.com/form-builder/form-editor/publishing)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/form-runner/api/other-apis/publish.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.