Roles Request Service
Roles Request Service🔗
If the Search! email alerting or sharing by email functionality is enabled, then the integrating application must also implement a roles request service. It enables Search! to check the current access rights of a user before sending scheduled email alerts.
Roles Request Service Specification🔗
Description:🔗
The roles request service is part of the integrating application and follows this specification.
- An HTTP GET service that accepts URL parameters as input and produces JSON as output.
Upon receiving a request with the user identifier and search environment name as URL parameters it must return the user's access roles for the environment. The roles are returned as a list of strings in JSON format. If the user is not authorized, it must return a USER_NOT_AUTHORIZED exception which disables email alerting for that user. Other errors must result in an EXTERNAL_ERROR exception message. See examples below.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | Search! environment to request access roles for. |
| user | string | The user id to request access roles for. |
Returns🔗
| Result format | Type | Description |
|---|---|---|
| roles | JSON list of String | the access roles, one or more strings. |
Pre-Condition🔗
No requirements. The service must return results without the user being logged in.
Post-Condition🔗
- On success, the list of access roles will be used for executing the user's saved search and sending email alerts in the given environment.
- On USER_NOT_AUTHORIZED error, the user's saved searches will be disabled for sending email alerts in the given environment.
- On EXTERNAL_ERROR error, no email alerts will be sent but the email alerting remains enabled.
Error Handling🔗
| Error Code | Description |
|---|---|
| USER_NOT_AUTHORIZED | The user is unknown or has no valid access roles for the environment. |
| EXTERNAL_ERROR | Another error occurred during processing of the authorization request (details in message). |
Examples🔗
JSON result for successful request returning two roles:
["account3","account50"]
JSON result for USER_NOT_AUTHORIZED:
{"errorCode": "USER_NOT_AUTHORIZED", "message": "User 'user500' is not known"}
JSON result for EXTERNAL_ERROR:
{"errorCode": "EXTERNAL_ERROR", "message": "Error reading users database."}