- sara.next
- Technology
- Error and exception handling
Technology · For developers
Error and exception handling
The most important test of an IGA integration begins when an approved change cannot be executed — or it is not known whether it was executed.
- Implemented / Not implemented
- timeout
- idempotency
Context
The difference between a technical error and a process error
Not all failures are the same. A request may be rejected at the authorisation stage, a script may fail to compile, a REST API may deny access, and the target system may make the change but fail to confirm it before a timeout. Each of these cases requires a different response, because the risk of leaving incorrect permissions in place is different.
The sara.next auto-implementation mechanism uses the states "Implemented" and "Not implemented", with an error message. The documentation discusses, among other things, a Groovy script compilation failure, exceptions when the oldUser or request.oldAtar variables are missing, incorrect identifier values, differences in the SQL schema, REST authentication errors and delays on the API side.
Handling matrix
Practical scenarios
| Problem | Potential cause | Recommended action |
|---|---|---|
| Groovy compilation error | Syntax, a missing variable, an incorrect data type | A fix in the test environment, unit tests of the script, re-acceptance |
NullPointerException | Using oldUser in the wrong operation or a missing oldAtar | Checking the variable contract and null-safe navigation |
| HTTP 401/403 | An incorrect or insufficient secret or account scope | Checking the connection configuration and permissions, without logging secrets |
| HTTP 429/503 | An API limit or temporary unavailability | Controlled rate-limit handling, agreeing on a retry approach |
| Timeout after sending | Uncertainty whether the request was executed | First read the target state, only then decide whether to retry |
| SQL returned an error | Permissions, a constraint, invalid data, a lock | Analysis of the transaction and data, a fix without granting excessive privileges |
| Verification failed | An inconsistent state, a query error or a propagation delay | Comparing the actual state with the expected one, identifying the point of discrepancy |
| Some changes in external systems succeeded | No distributed transaction | A compensation procedure, manual intervention, an incident or exception report |
Diagnostics
Typical script errors and their causes
Messages that most often appear when auto-implementation is first configured.
| Symptom | Cause | What to do |
|---|---|---|
Groovy script compilation failed: ... | A script syntax error: an unclosed string, a missing bracket or invalid Groovy syntax. | The error message contains the line number — start there. |
NullPointerException on oldUser | oldUser is only available for Delete and Replace requests. Referring to it in a Create script results in an exception. | If the script is shared, use safe navigation: oldUser?.samAccountName. |
NullPointerException on request.oldAtar | request.oldAtar is only set for Modify and Delete requests (it stores the previous access record). | Always use safe navigation: request.oldAtar?.dimensionValues. |
SQL verification unexpectedly returns false | The SELECT query returned no rows: login does not match the stored value (letter case, domain prefix), the table or view is different from what was assumed, or the implementation script did not make the change. | Check the comment on the queue item — it contains the details. |
REST verification unexpectedly returns false | The GET request returned a status other than 2xx: a wrong path or the resource was not created, failed authentication or a delay on the API side. | Check the REST connection credentials and consider whether verification has to happen immediately. |
Recovery
Four recovery rules
Don't retry "blindly"
After timeouts, check the state so as not to create duplicate accounts or conflicting assignments.
Separate retries from the business decision
Re-executing an approved operation may be technically justified, but changing the scope of a permission requires a new decision.
Use idempotency wherever possible
grantshould detect an existing assignment, andrevokea missing one; the final behaviour depends on the target API or SQL.Document discrepancies
Store the request identifier, the application, the operation type, the error information, the result of the state check and the decision on how to restore consistency.
Transactions
Dependence on the transaction model
For SQL the documentation indicates that a list of statements is executed in a single transaction. This conclusion should not be carried over to several HTTP calls or several target systems. In REST a POST operation that ended in a timeout gives no grounds to assume it did not work. A correct design uses a control query to read the actual assignment.
Logs
Error handling without disclosing sensitive data
Logs should contain a correlation identifier, the operation type, the status and the error code.
NoteLogs should not contain passwords, Bearer tokens, API keys, full personal data or the content of queries containing secrets.
In regulated environments a retention policy and access permissions for logs should be defined. The implementation of these controls should be verified in the specific configuration.
An implementation expert's view
The riskiest status: "I don't know"
In the permission granting process the riskiest status is: "I don't know whether the change was executed". That is exactly the kind of case I would design the integration for.
Error monitoring only makes sense when it is known who is responsible for the decision, how to check the actual state and how to close the exception without losing the audit trail.
Scope
What the documentation confirms and what requires design
Confirmed
- the basic auto-implementation result statuses,
- the possibility of verification,
- examples of Groovy, SQL and REST errors.
Recommended patterns, not platform guarantees
- retry and backoff policy,
- dead-letter queue,
- circuit breaker,
- central alerting,
- distributed compensation,
- automatic reconciliation.
Verify the integration failure scenarios with us
Ideally before going into production.