Identities Request Service

Identities Request Service🔗

The integrating system needs to implement this service to support the following features:

Project Sharing: users can select other users and roles to share a project with.
Email Alerts: selection of users or roles to email (instead of manual entry of email addresses). This requires the Email Address Service as well.
Sharing results by email: selection of users or roles to email (instead of manual entry of email addresses). This requires the Email Address Service as well.
User Activity Reporting: for mapping user/role IDs to their labels.

The Identities Request Service. needs to output he user and role IDs accompanied by labels to display them in the user interface. The service is accessed from within the user’s browser, in the same manner that the _Token Request Service_is called. Therefore the service should identify the user by the cookie that is sent along with the HTTP request.

Identities Request Service Specification🔗

Description:🔗

The Identities 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/JSONP as output.

The service must return lists of other users and/or roles that the current user may share projects with, as well as the current user him/herself. Note that the current user can be identified by use of a web session (i.e. HTTP cookie) in order to return a user-specific list. If the service cannot fulfill its request, for example when the user cannot be identified, then it must return an error message with error code EXTERNAL_ERROR.

Parameters🔗

If the following URL parameters were provided when opening Search, they will be included in the Identities Service Request call.

Parameter Name	Type	Description
environment	string	Search! environment.
externalToken	string	The identification token from external service

Returns🔗

Result format	Type	Description
JSON identities object	JSON	JSON encoded object with three object fields: `users`, `roles` and `currentUser`. All three object fields should contain IDs as keys and labels as values. The `currentUser` object should have just one key.
callback(JSON identities object)	JSONP	Same as for JSON but enclosed by a javascript function callback, if request parameter callback is given (cross-domain only)

Pre-Condition🔗

The user is logged in to the integration application and has a cookie for identification and authentication.

Post-Condition🔗

On success, the list of users and access roles will be available for selection when sharing projects; or when for email-alert of email-export recipient selection when Email Address Service is configured.
On error, the user will not be able to share projects.

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": {
    "A12": "Kevin Bacon",
    "CX3": "Alice Bush"
  },
  "roles": {
    "staff": "Office staff",
    "admin": "Administrators"
  },
  "currentUser": {
    "B00": "Bob Davidson"
  }
}

Example JSON result for EXTERNAL_ERROR:

    {
  "errorCode": "EXTERNAL_ERROR",
  "message": "No user logged in."
}