WebAPI (server scripting)

Server-side scripts run as GSP (Groovy Server Pages) or .groovy endpoints. Scripts receive a number of globals — WebAPI among them — for working with HTTP and content (JCR).

Execution model

Scripts are stored as JCR content and invoked at:

/bin/cms.cgi/<workspace>/content/<path>/<script.groovy|.gsp>

Example: GET /bin/cms.cgi/web/content/commerce/endpoints/health.groovy?days=7

Script globals (main ones)

Name	Type	Purpose
`out`	`Writer`	write to the response body
`request` / `response`	`HttpServletRequest` / `HttpServletResponse`	HTTP in/out
`session` / `application`	`HttpSession` / `ServletContext`	session / app-shared state
`repositorySession`	`Session` (script resource API)	the main way to read/write JCR content
`resource`	`Resource`	the JCR resource being processed
`WebAPI`	`WebAPI`	include / fetch / parameters / encoding (only when `request` exists)
`log` (`LoggerAPI`)	`LoggerAPI`	logging (debug/info/warn/error)
`JSON` / `YAML`	—	JSON / YAML parse & serialize
`XPath` / `MetadataAPI`	—	query / metadata
`ProcessAPI` / `IntegrationAPI`	—	BPM / EIP integration
`EventAdminAPI` / `cluster` / `CryptoAPI` / `MimeTypeAPI` / `SessionAPI`	—	events / cluster / crypto / MIME / session creation

(request / response / out are available only when the script is triggered over HTTP.)

WebAPI methods

Method	Purpose
`include(path)`	include another resource (e.g. a GSP); a leading `/` is workspace-relative
`forward(path)`	forward to another resource
`importContent(path[, encoding])`	write file / HTTP content (`jcr://`, relative/absolute path, or HTTP URL)
`getParameter(name)`	a request parameter (single value or an uploaded file)
`fetch(uri)`	HTTP GET (3s connect / 10s request timeout); returns a `WebResource`
`encodeURIComponent` / `encodeURI` / `decodeURIComponent`	URI encode/decode

Session (script resource API)

Operate on content through repositorySession.

getResource(absPath) / getResourceByIdentifier(id) / getRootFolder() — get resources
commit() / rollback() — save / discard
deploy() — apply etc/jcr/deploy and etc/jcr/provisioning
adaptTo(javax.jcr.Session) — adapt to the low-level JCR session
impersonate(userId) / newSession() — another user / a new session
isAdmin() / isAnonymous() / isService() / getUserID() — who is running

Main Resource operations

read: getContent() / getContentAsStream() / getProperty(name) / list()
write: write(content) / setProperty(name, value) / createFile() / createFolder() / getOrCreateFile(name)
move, etc.: moveTo(path) / copyTo(path) / remove()
versioning: addVersionControl() / checkout() / checkin() / checkpoint()
locking: lock() / unlock() / isLocked()
ACL: getAccessControlList() / setAccessControlList(acl) / canRead() / canWrite()

Examples

GSP include:

<% WebAPI.include("/content/public/inc/head_start.gsp") %>

A JSON endpoint (.groovy):

int days = (request.getParameter("days") ?: "7") as int
try {
  def snapshot = Health.snapshot(repositorySession, days)
  response.setStatus(200)
  response.setHeader("Content-Type", "application/json")
  response.getWriter().write(new ObjectMapper().writeValueAsString(snapshot))
} catch (Exception e) {
  log.error("health endpoint error: \${e.message}", e)
  response.setStatus(500)
}

Create and save content:

def res = repositorySession.getRootFolder().getOrCreateFile("content/notes/hello.json")
res.write('{"hello":"world"}')
res.setProperty("jcr:mimeType", "application/json")
repositorySession.commit()

For authorization and service accounts, see "Users, roles & permissions".