Email Address Service

Email Address Service🔗

When project sharing and/or sharing of search results by email is enabled and the Identities Request Service is implemented to retrieve users and roles to share with, it is possible to set up an additional Email Address Service to look up email addresses belonging to those users and roles. The recipients of email alerts and email exports can then be chosen from the list of known users and roles instead of requiring manual entry of email addresses.

The service is called from the back-end in a similar fashion as the Roles Request Service: all processing is done in the back-end, no user sessions or access tokens are used in the making of these service calls.

Email Address Service Specification🔗

Description:🔗

The Email Address 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.

The service must return an object containing all email addresses associated per user in one map and all email addresses associated with the roles in another map.

If the service cannot fulfill its request, for example when the user ID is invalid or unknown, then it must return an error message with error code EXTERNAL_ERROR.

Parameters🔗

Parameter Name	Type	Description
users	comma-separated string	list of user IDs to request email addresses for
roles	comma-separated string	list of role IDs to request email addresses for

Returns🔗

Result format	Type	Description
JSON email addresses object	JSON object	JSON encoded object with two object fields: `users_emails` and `roles_emails`. Both containing IDs as keys and a list of associated email addresses as values.

Pre-Condition🔗

No requirements. The service must return results without the user being logged in.

Post-Condition🔗

On success, the user is able to send emails to all of the requested users and roles.
On error, the user will not be able to send an email.

Error Handling🔗

Error Code	Description
EXTERNAL_ERROR	Any error occurred during processing of the request (details in message).

Examples🔗

JSON result for successful request:

{
    "users_emails": {
        "A12" : [ "kevin@mycompany.net" ],
        "42" : [ "jones@mycompany.net", "j.j.jones@home.net" ]
    },
    "roles_emails": {
        "staff" : [ "staff@mycompany.net" ],
        "42" : [ "jones@mycompany.net", "woolley@mycompany.net" ]
    }
}

Example JSON result for EXTERNAL_ERROR:

    {"errorCode": "EXTERNAL_ERROR", "message": "User unknown: A12"}