- sara.next
- Technology
- Auto-implementation scripts
Technology · For developers
Auto-implementation scripts
Auto-implementation links the completed approval process with the technical execution of the entitlement. Both a correct change and proof that it actually happened are important.
- Groovy
- REST
- SQL
- queue
- verification
Context
From request to actual access
Once the approval process is complete, the request can be sent to the auto-implementation mechanism. sara.next maintains a queue of changes, and the scheduler processes requests cyclically. For each one a Groovy script is selected that uses the configured SQL or REST connection. An optional verification script checks the result. The workflow then receives the status "Implemented" or "Not implemented" with information about the error.
NoteIn the described configuration the scheduler runs every minute. This is how often the queue is checked in the documented mechanism, not an SLA for implementing a change.
Flow
The path of an approved change
Operations
What operations a script can handle
| Operation | Purpose | Important detail |
|---|---|---|
Create | Creating a new assignment | Available variables include user, role, dimensions |
Modify | Changing the dimensions of an existing assignment | The previous state can be read via request.oldAtar |
Replace | Replacing the user or assignment | If the script does not exist, a Delete → Create fallback is possible |
Delete | Removing an assignment | For the previous user, use oldUser |
Verification | Confirming the state after the operation | Different result semantics for creating and removing |
For Modify and Replace the documentation provides a Delete → Create fallback if the dedicated script is empty. This is convenient, but may cause a brief loss of access or a partial failure of the operation. For critical systems, the consequences of these semantics should be assessed first.
Verification
Verification logic by request type
The verification script runs after the implementation script and confirms that the change has been applied. It has access to the login variable: for Create, Modify and Replace this is the new user, for Delete — the previous one.
| Request type | Expected verification result |
|---|---|
Create | true — the user exists in the target system |
Modify | true — the new state exists in the target system |
Replace | true for the new user and false for the previous one |
Delete | false — the user no longer exists (inverted logic) |
Inversion for Delete: the scheduler inverts the result itself. The script is written as if it were checking for presence — verification passes when the user is not found.
For the script author
Variables, connection variants and verification
Input variables
Scripts use variables such as user, oldUser, role, dimensions, request, application. dimensions is a map of the attribute values of the current request. oldUser is not available in all operation types; in Delete it represents the user whose permission is being removed. Old dimension values can be obtained via request.oldAtar?.dimensionValues in the appropriate context.
SQL variant
The implementation script returns a single SQL string or a list of SQL statements; according to the documentation the list is executed in a single transaction, rolled back on error. The verification script returns a SELECT statement; the presence of at least one row gives the logical result true.
NoteSample text interpolations should not be copied into production code without validation. User identifiers, roles and database names should come from allowed value lists, and queries must be designed taking into account the risk of SQL injection and the system privileges of the integration account.
REST variant — configuration format
For a REST call the script returns a map with the fields method, path and the optional body and headers. The methods supported in the described mechanism include GET, POST, PUT, PATCH and DELETE.
// Educational example of the REST script response format.
// The /accesses endpoint is an example, not the sara.next API.
String login = user.samAccountName
String resource = dimensions["RESOURCE"]
if (!login || !resource) {
throw new IllegalArgumentException("Missing required identifier or resource")
}
return [
method: "POST",
path: "/accesses",
body: groovy.json.JsonOutput.toJson([login: login, resource: resource])
]This is an example of the structure returned by a script that sends a request to an external system, not a snippet of a sara.next API call. Additional validation of allowed values has to be matched to the model of the given application.
Verification after execution
In SQL mode the result of the verification query depends on whether a matching record exists. In REST the described mechanism interprets an HTTP 2xx response as true and any other as false. For Delete verification has an inverted interpretation: we check for presence, but revoking the permission succeeds when the resource is not found.
In practice it is worth distinguishing between "the endpoint responded", "the request was accepted" and "the permission actually exists or does not exist". In systems with eventual consistency an appropriate re-verification mechanism may be needed in the adapter or the operational process. The platform does not provide universal semantic verification of all APIs without configuration.
An implementation expert's view
Start with a simple role, not the most privileged one
Auto-implementation has the greatest effect where the role is well described and the target system's API behaves predictably. I would not start with the most privileged access.
I would first implement a simple role, monitor the results and only later extend support for modify, replace and destructive operations.
Scope
Limits of the mechanism
The mechanism covers the queue, the scripts and the result passed to the workflow.
NoteAs standard, the mechanism does not include general automatic retries, a global rollback across several external systems or an exactly-once guarantee. Such requirements have to be agreed separately in the project.
See how to automate the safe granting and revoking of permissions
We will show the mechanism using your application as an example.