...
This page describes the use cases solved by the publishPage action. In it simplest terms, there are a a number of use cases around the need to take some source content and create a Confluence page. Basic support for this comes with standard storePage (or addPage) actions. These actions take wiki or storage formatted text in a file or specified directly with the content parameter and produce a page. However, there a are lots of other automation use cases that need more extensive support. The publishPage action is intended to cover these use cases. This page summarizes these scenarios.
For our purposes here, there is little difference between creating pages or updating existing pages, so we favor terminology of update and storePage in what follows.
For publishPage actions, the content can come from a source page or from content provided by the file or content parameters. Most of our internal use is from a file coming from a repository so that we have change control.
When rendering content on the source system from non-page sources like a file, we use the space (and title parameter if provided) to determine the source rendering context. If title is not provided, the space's home page is used.
Use Cases
| Table plus |
|---|
|
| Use Case | Discussion | Action | Examples |
|---|
| Update a page from wiki text | Simple case. Wiki text is an easy format for simple automation scripts to produce. | storePage |
| No Format |
|---|
-a storePage --space XXX --title "My page" --content "h1. Example" |
| No Format |
|---|
-a storePage --space XXX --title "My page" --file my.wiki |
| | Update a page from storage format | Simple case. In some cases, more complex storage format may be needed. | storePage |
| No Format |
|---|
-a storePage --space XXX --title "My page" --file my.stg |
| | Copy a page from one system to another | This is also relatively common use case and simply copies the storage format from the source page to the target system page. Defaults to the same space and title, but there are parameters making it more flexible. | copyPage |
| No Format |
|---|
-a copyPage --space XXX --title "My page" --newSpace YYY --targetServer ... |
| Render storage format content on one system and publish the resulting page on another system
| This is a scenario that takes advantage of more advanced Confluence rendering capabilities on one system that may not be available on the target system. Examples are the availability of macros and potential security restrictions on the target platform. A specific example is publishing SQL tables to Confluence Cloud using the SQL on a source system. This site contains a number pages created in this way. This works only for some wiki content that renders to a HTML that can be easily converted to XHTML storage format required to represent page source on the target system.
| publishPage |
| No Format |
|---|
-a publishPage --space XXX --title "My page" --newSpace YYY --noConvert --targetServer ... |
| | Render wiki content on one system and publish the resulting page on another system | Same as the above except the wiki content must first be converted to storage format. The difference is the noConvert parameter that determines whether the content is wiki or storage (need noConvert parameter) | publishPage |
| No Format |
|---|
-a publishPage --space XXX --title "My page" --newSpace YYY --targetServer ... |
| | From wiki content, provide a way to identify content blocks that represent content that needs to be rendered on the source server and included in the page source for a target page. | For instance identifying a SQL macro within the page source that needs to be rendered on the source system before producing the target page. | publishPage |
| No Format |
|---|
-a publishPage --space XXX --title "My page" --newSpace YYY --targetServer ... --options searchContent |
|
|
...