Create a Confluence Page with ScriptRunner: Server vs Cloud

June 16, 2021

#Cloud Migration #Confluence #Jira Cloud #ScriptRunner

ScriptRunner can extend the functionality of Atlassian products, such as Confluence and Jira Software. From creating pages or tickets within the script console to setting up jobs and listeners, ScriptRunner is an excellent add-on. In our previous article, <a href="/blog/the-scriptrunner-rundown" data-type="URL" data-id="/blog/the-scriptrunner-rundown" target="_blank" rel="noreferrer noopener">The ScriptRunner Showdown</a>, we explored possible limitations of ScriptRunner for Atlassian’s Cloud products when compared to the capabilities available for their Server products. Essentially, Atlassian’s Server products allow for more actions than Cloud products, largely because Cloud products are restricted to the Cloud REST API while Server products have access to both the Server REST API and Java REST API. Our script uses a simple example, but one that is likely to be at the heart of much more complicated scripts: create a page. To make things a bit interesting, and to diverge from the ‘copy page tree’ built-in script provided by ScriptRunner, we want the new page to appear under the home page of the target space page hierarchy. In our example script the space key is <code>TESTSPACE</code>. <h2 class="wp-block-heading">Create a page script with ScriptRunner for Confluence Server</h2> <div class="wp-block-columns is-layout-flex wp-container-core-columns-is-layout-1 wp-block-columns-is-layout-flex"> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:33.33%"> <div class="wp-block-image"><figure class="aligncenter size-large"><img loading="lazy" decoding="async" width="181" height="184" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/server-icon-1829170068-1623798240379.png" alt="" class="wp-image-45"></figure></div> </div> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:66.66%"> It turns out there are actually two approaches that can be used to create a page using ScriptRunner for Confluence Server: via the Java REST API components or using the Server REST API. We will demonstrate both approaches. </div> </div> <h3 class="wp-block-heading">Using Confluence Server Java REST API Components</h3> <div class="wp-block-columns is-layout-flex wp-container-core-columns-is-layout-2 wp-block-columns-is-layout-flex"> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:66.66%"> One way of creating a page in a space would be to use components from the Java REST API. </div> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:33.33%"> <div class="wp-block-image"><figure class="aligncenter size-large"><img loading="lazy" decoding="async" width="96" height="96" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/Java.png" alt="" class="wp-image-46"></figure></div> </div> </div> Confluence Server has been around for a while and there is plenty of documentation on the internet to assist with learning the broad scope of the Java REST API, whether through Atlassian community Q&As or <a href="https://developer.atlassian.com/server/confluence/java-api-reference/">documentation</a>. This article will not provide any further background or explanation of the provided script example. The following code example uses the <code>PageManager</code> and <code>SpaceManager</code> components found in the API to create a page in the space with key <code>TESTSPACE</code>: <pre class="wp-block-code language-groovy"><code>import com.atlassian.confluence.pages.Page import com.atlassian.confluence.pages.PageManager import com.atlassian.confluence.spaces.Space import com.atlassian.confluence.spaces.SpaceManager import com.atlassian.sal.api.component.ComponentLocator def spaceManager = ComponentLocator.getComponent(SpaceManager) def pageManager = ComponentLocator.getComponent(PageManager) def spaceKey = "TESTSPACE" def space = spaceManager.getSpace("${spaceKey}") def homePage = space.getHomePage() Page parentPage = pageManager.getPage(homePage.id); Page page = new Page(); page.setSpace(space); page.setParentPage(parentPage); page.setTitle("Title of Page"); page.setBodyAsString("Body of page. Bolded text."); parentPage.addChild(page); pageManager.saveContentEntity(page, null, null);</code></pre> When creating a new page, the ‘set’ functions within the Page class (<a href="https://docs.atlassian.com/ConfluenceServer/javadoc/7.12.2/index.html?com/atlassian/confluence/pages/Page.html">API 7.12.2 documentation</a>) can be used to add values to the page being created. Recall that one requirement for this example is for the new page to be created below the homepage in the space page tree hierarchy. Therefore the new page must <code>setParentPage</code> as the homepage, and the homepage must add the new page as its child. This example does not care about the history of the new page so it can be saved with a context of null. <h3 class="wp-block-heading">Using Confluence Server REST API</h3> <div class="wp-block-columns is-layout-flex wp-container-core-columns-is-layout-3 wp-block-columns-is-layout-flex"> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:66.66%"> The Confluence REST API Documentation may not seem as extensive as the Java REST API, but for our comparison it will get the same job done. The Confluence Server Developer even includes an example on how to create a new page. </div> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:33.33%"> <div class="wp-block-image"><figure class="aligncenter size-large"><img loading="lazy" decoding="async" width="96" height="96" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/API-Gear.png" alt="" class="wp-image-47"></figure></div> </div> </div> The following is the code to create a new page, using our requirements and the REST API: <pre class="wp-block-code language-groovy"><code>import com.atlassian.confluence.spaces.SpaceManager import com.atlassian.confluence.spaces.Space import groovy.json.StreamingJsonBuilder import com.atlassian.sal.api.component.ComponentLocator def spaceManager = ComponentLocator.getComponent(SpaceManager) def server = 'YOUR SERVER BASE URL' def authString = 'username:password'.getBytes().encodeBase64().toString() def spaceKey = "TESTSPACE" def space = spaceManager.getSpace("${spaceKey}") def homePage = space.getHomePage() def pageParams = [ title: "Title of Page", type: "page", space:[ key:"${spaceKey}" ], ancestors: [ [id:homePage.id] ], body: [ storage: [ value: "Body of page. Bolded text.", representation: "storage" ] ] ] def createPageResult = new URL("${server}/rest/api/content").openConnection() as HttpURLConnection createPageResult.requestMethod = 'POST' createPageResult.setRequestProperty('Authorization', "Basic ${authString}") createPageResult.doOutput = true createPageResult.setRequestProperty('Content-Type', 'application/json;charset=UTF-8') createPageResult.outputStream.withWriter('UTF-8') { new StreamingJsonBuilder(it, pageParams) } createPageResult.connect() log.warn"${createPageResult.getResponseCode()} created Page ${pageParams.title} for Space ${spaceKey}" //Close POST createPageResult.disconnect()</code></pre> Using the Server REST API involves more set up or configuration, specifically, the script must specify: <ul><li>The base URL of the instance</li><li>The credentials (username and password) of a user who has permission to create a page in the target space.</li></ul> In the Adaptavist ScriptRunner for Confluence’s console, this code will create a page identical to the one made by the components script shared above. <h2 class="wp-block-heading">Create a page script with ScriptRunner for Confluence Cloud</h2> <div class="wp-block-columns is-layout-flex wp-container-core-columns-is-layout-4 wp-block-columns-is-layout-flex"> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:33.33%"> <div class="wp-block-image"><figure class="aligncenter size-large"><img loading="lazy" decoding="async" width="178" height="177" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/Cloud-plain.png" alt="" class="wp-image-48" srcset="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/Cloud-plain.png 178w, https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/Cloud-plain-150x150.png 150w" sizes="(max-width: 178px) 100vw, 178px"></figure></div> </div> <div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow" style="flex-basis:66.66%"> Adaptavist ScriptRunner for Confluence Cloud includes a few example code snippets which are helpful to kickstart your introduction to the Cloud REST API. The code below is similar to ScriptRunner’s <code>Create page in space</code>, with a few changes to fit this example. As with the previous code snippets, this creates a page in the Confluence space with key <code>TESTSPACE</code>. </div> </div> <pre class="wp-block-code language-groovy"><code>def spaceKey = "TESTSPACE" def createPageResult = post('/wiki/rest/api/content') .header('Content-Type', 'application/json') .body([ space: [ key: spaceKey ], status: "current", title: "Title of Page", type: "page", body: [ storage: [ representation: "storage", value: "Body of page. Bolded text." ] ] ]) .asObject(Map).body</code></pre> Instead of requiring the base url and authentication be added into the console by the user, the <code>post</code> function applies the values associated with the Cloud instance. That’s great news as it means less work for the developer. If you have seen the ScriptRunner console’s example, you may have noticed they use a body format <code>view</code> while this example has <code>storage</code>. Depending on what the body content of the page is will help determine which format should be used. The <a href="https://developer.atlassian.com/cloud/confluence/rest/api-group-content/#api-api-content-post">Confluence REST API</a> states only one body format should be used, and it includes a list to choose from in its example. Definitions for the body formats can be found in the <a href="https://docs.atlassian.com/ConfluenceServer/javadoc/7.12.2/com/atlassian/confluence/api/model/content/ContentRepresentation.html">Server ContentRepresentation class</a>. <h2 class="wp-block-heading">What did we learn?</h2> We have shown three possibilities to script creating a page in a Confluence space. By demonstrating a Server script that uses the Server REST API we were able to see how that is similar to what can be expected when migrating to the Cloud. We were also able to clearly see Server scripts based upon the Java REST API components will require considerable more re-development than ones using the Server REST API. If you will continue to develop new scripts for Server, you should consider switching to the Server REST API as much as possible to reduce the effort required to convert the scripts when you migrate to the Cloud. We have summarized our findings in the following table. <figure class="wp-block-table is-style-h3-table"><table><thead><tr><th>Method</th><th>Create Page</th><th>User Requirements</th></tr></thead><tbody><tr><td>Components</td><td>– Get and add Space – Set values – Get and add Parent Page – Add Child Page to Parent Page – Save configuration</td><td>– Space Key – Permission to access Space and add Page</td></tr><tr><td>Server REST API</td><td>– Get Space – Create parameters – POST parameters</td><td>– Space Key – Base URL – Username – Password – Permission to access Space and add Page</td></tr><tr><td>Cloud REST API</td><td>– Create parameters – POST parameters</td><td>– Space Key – Permission to access Space and add Page</td></tr></tbody></table></figure> We know our example was very simple, but it does demonstrate key differences between the three approaches, what you can do in the short term, and how you can plan for the long term as you look towards your Cloud migration. As part of your migration planning it is especially important to check if any components in a ScriptRunner script have an equivalent API call that can be made in Cloud. If there are none, then you may need to consider alternate designs and exploring other approaches, like Automation. Knowing what to expect and planning with that in mind will help smooth out your migration path. <div class="wp-block-buttons is-content-justification-center is-layout-flex wp-block-buttons-is-layout-flex"> <div class="wp-block-button is-style-h3-cta-button"><a class="wp-block-button__link" href="/contact?subject=ScriptRunner for Cloud" target="_blank" rel="noopener">Need help configuring ScriptRunner for Cloud?</a></div> </div>