Identity Governance & Administration
sara.next
  1. sara.next
  2. Technology
  3. REST scripts: response format and an example

Technology · Documentation

REST scripts: response format and an example

A REST script describes the HTTP request that sara.next will send to the target system through the configured connection. It returns a map with the method, the path and optionally the body and headers.

  • Groovy
  • REST
  • example

Principles

What the implementation script returns

The Create, Replace, Modify and Delete scripts return a Map<String, Object> with the following keys.

What the implementation script returns
KeyTypeRequiredDescription
methodStringYesHTTP method: GET, POST, PUT, PATCH, DELETE
pathStringYesA relative path, appended to the connection's baseUrl
bodyStringNoThe request body, e.g. a JSON string
headersMap<String, String>NoAdditional request headers

The verification script returns a map in the same format — usually a GET request. Result: true if the HTTP response has a 2xx status; otherwise false.

Example

Full example: REST Demo

The example assumes a role with the dimensions RESOURCE (the resource) and PERMISSIONS (a comma-separated list of permissions). When a dimension has no value, the script assumes default and read.

NoteThe /accesses endpoint belongs to the sample target system — it is not the sara.next API. Values inserted into the path and the request body should be validated in line with the model of the given application.

Create script

A POST request creates an assignment for the login, resource and list of permissions.

String login = user.samAccountName
String resource = dimensions["RESOURCE"] ?: "default"
String perms = dimensions["PERMISSIONS"] ?: "read"
def permList = perms.split(",").collect { '"' + it.trim() + '"' }.join(",")

[method: "POST", path: "/accesses",
 body: '{"login":"' + login + '","resource":"' + resource + '","permissions":[' + permList + ']}']

Modify script

A PUT request changes the list of permissions of an existing assignment.

String login = user.samAccountName
String resource = dimensions["RESOURCE"] ?: "default"
String perms = dimensions["PERMISSIONS"] ?: "read"
def permList = perms.split(",").collect { '"' + it.trim() + '"' }.join(",")

[method: "PUT", path: "/accesses/" + login + "/" + resource,
 body: '{"permissions":[' + permList + ']}']

Delete script

The login comes from oldUser, and the resource from the previous dimension values read from request.oldAtar.

String login = oldUser.samAccountName
def oldDims = [:]
request.oldAtar?.dimensionValues?.each { dv ->
    if (dv.dimension != null) oldDims[dv.dimension.systemName] = dv.value
}
String resource = oldDims["RESOURCE"] ?: "default"

[method: "DELETE", path: "/accesses/" + login + "/" + resource]

Verify script

A GET request checks whether the assignment exists. A 2xx status means true; for a Delete request the result is inverted by the scheduler.

String resource = dimensions["RESOURCE"] ?: "default"
[method: "GET", path: "/accesses/" + login + "/" + resource]

A 2xx response confirms that the endpoint responded. In systems that make changes asynchronously, it is worth considering whether verification should happen immediately.

Prepare REST scripts with our team

We will check the target system's API and how the change is verified.