Adapt Scripts for Confluence Cloud
Information to help your scripts keep running as expected after migrating between ScriptRunner for Confluence Server/DC and Cloud.
Before you start migrating your scripts, it's crucial to understand how scripts work in Confluence Cloud and the key differences from Server/Data Center. The following steps will guide you through understanding how scripts work in Confluence Cloud, enabling you to effectively rewrite your scripts.
Step one: Review imports and dependencies
Examine your scripts for any imported external libraries. These libraries can introduce additional complexity when migrating to Confluence Cloud. In addition you should identify plugins that the scripts rely on.
Determine if these libraries/plugins are supported or available in the Cloud environment. If they are not available you should identify alternative approaches or built-in functionalities in Confluence Cloud that can replace them.
Step two: Analyze API calls
Identify any API calls within your scripts, especially those that interact with Confluence's internal APIs. Since Confluence Cloud relies on REST APIs, you'll need to adapt these calls to use the appropriate cloud-based endpoints. Use the following tips to effectively analyze API calls:
For more details on APIs see the Best Practices and Supporting Technical Information page.
Step three: Understand and apply basic operations
It's important to understand the basic operations in Confluence Cloud's API before you migrate your scripts. This understanding will form the foundation for successfully adapting your existing scripts and ensuring they function correctly in the new environment.
Create a page
There are two scripts in this section; one is for Data Center and the other for Cloud. Both scripts could be run from the Script Console in each product, and they both create a page in Confluence by copying the content of an existing page.
You can see that both need to create a new object to represent the page. In the DC script, this is a Page object. In the Cloud script, this is a list of Map objects that matches the Cloud REST API data specification for pages.
Both also need to make a call to save the new page. In the DC script, this is a call to the PageManager#saveContentEntity method. In the Cloud script, this is a call to the post method, specifying the path to the Content REST API.
import com.atlassian.confluence.core.DefaultSaveContext
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 pageManager = ComponentLocator.getComponent(PageManager)
def spaceManager = ComponentLocator.getComponent(SpaceManager)
// Specify all the required parameters
def spaceKey = "DS"
def parentTitle = "Welcome to Confluence"
def pageTitle = "New Page"
def sourcePageId = 65556 // change out for source page ID
Space space = spaceManager.getSpace(spaceKey)
def parent = pageManager.getPage(spaceKey, parentTitle)
// Get the source page
def sourcePage = pageManager.getPage(sourcePageId) //Notably, you could use the source page's ID and title to get the page instead
// Specify details of the new page
def page = new Page()
page.with{
setTitle(pageTitle)
setSpace(space)
setBodyContent(sourcePage.bodyContent)
setParentPage(parent)
}
parent.addChild(page)
// create Confluence page
pageManager.saveContentEntity(page, DefaultSaveContext.DEFAULT)
return "New page ${page.title} created with id ${page.id}"// Specify all the required parameters
def sourcePageId = "<SourcePageIDHere>"
def parentPageId = "<ParentPageIDHere>"
def pageTitle = "<Page Title Here>"
def spaceKey = "<Space Key Here>"
// Get the content of the source page
def template = get("/wiki/rest/api/content/${sourcePageId}?expand=body.storage")
.asObject(Map)
.body
// Specify the body of the rest request
def body = [
type: "page",
title: pageTitle,
space: [
key: spaceKey
],
ancestors: [[
id: parentPageId
]],
body: template.body
]
//create confluence (cloud) page
def createPageResult = post("/wiki/rest/api/content")
.header("Content-Type", "application/json")
.body(body)
.asObject(Map)
assert createPageResult.status == 200Notice in the Cloud script you don't use Service or Manager classes, but the REST API. Check out the Cloud and Server documentation for more information.
assert resp.status == 200 (replace 200 with the correct response code). Successful APIs call may respond with 204, others with 200, 201, or 303 depending on the API in use.Step four: Leverage Unirest in ScriptRunner for Confluence Cloud
When working with ScriptRunner for Confluence Cloud, the Unirest library is a powerful tool for making HTTP requests to interact with Confluence's REST API and other web services. It's important to understand how to use Unirest effectively within ScriptRunner scripts to perform actions like retrieving, creating, or updating Confluence pages. Below we describe how to use Unirest in ScriptRunner for Confluence Cloud:
-
Unirest library: Unirest is a lightweight HTTP library that simplifies making HTTP requests in Java and Groovy. We recommend you research the ScriptRunner for Confluence Cloud style for writing HTTP calls using the Unirest library. This library is auto-imported into scripts, allowing you to directly use methods like
get(),put(), andpost()as documented in Unirest's documentation without additional import statements. - Example scripts: Review the available Example Scripts on the ScriptRunner website and within the Script Console in your Confluence Cloud instance. These examples provide insights into the style and code structure for common use cases.
By following these steps, you'll be well-prepared to rewrite your Server/Data Center scripts for Confluence Cloud, ensuring a smooth transition and maintaining the desired functionality in the new environment.
Step five: Test your scripts, API calls and integrations
Logging
Learn about script logs and how they are useful.
Logging in scripts is very helpful when debugging. In Cloud scripts, anything printed to stdout using println, or using a logger.info ( 'message') call will be available in the Script Logs page, and in the execution history of script listeners and script jobs. As noted above, usage of assertions can also help debugging and diagnosing the behaviour of scripts.
Step six: Migrate to production
The final step is to deploy the scripts in the production environment.
This is a manual process, so each script must be copied manually from the test environment to production environment (note that custom field IDs change per environment). Usually this process is scheduled outside working hours to reduce impact in service and needs to be heavily coordinated with the rest of the teams.