External Search API

External Search Configuration

Currently, you can only create external search configurations in the django admin. The respective fields are:

  • Organization: The respective organization.

  • Verbose name: A name that describes the service best. It will be displayed in the grape search on filtering.

  • Key: A name that is internally used to filter only for items of this external search. (Note: If multiple items share the same key, all of them will be queried when a single one is filtered.)

  • Search url: The full url of the search endpoint.

  • Access token: A secret token that is sent in the Authorization header to verify grape as the caller.

  • Impersonation: The type of impersonation that is used for requests. This can be

    • email - Unique email of the user (string)
    • grape user id - The grape internal user id
    • sam account name - The samAccountName of the user (requires AD)
    • empty - No impersonation is used.

      More types might be added later. Search requests will contain the selected attribute of the acting user in the Impersonating header.

  • Explicit: Activate this checkbox if the search should only be used when the user explicitly filters for it.

  • Config: Currently not in use.

  • Timeout: Read only - How long does Grape wait for a response from the search endpoint.

Object permission

In order to allow users to search the external service, object permissions need to be set.

  • Permission: This has to be set to use (default)
  • Access Group: Select the access group you want to grant the permission to use this external service. You can select any organization, room, member or ad group. All members of this access group will have access to the configured search.

Django Admin Interface

Request

The search request sent to external search servers will contain these variables from the search configuration.

  • SEARCH_URL- The full url to the search endpoint of the external service
  • ACCESS_TOKEN - A secret token that is sent in the Authorization header to verify grape as the caller.
  • IMPERSONATION_TYPE - The type of impersonation that is used for requests. This can be
    • EMAIL - Unique email of the user (string)
    • GRAPEID - The grape internal user id
    • SAM - The samAccountName of the user (requires AD)

An external search request can be simulated by the following equivalent curl command. Here, the IMPERSONATION_KEY is the user identifier as specified by the value of IMPERSONATION_TYPE. Although not enforced, we recommend using https even in internal networks.

curl "{SEARCH_URL}?q={SEARCH_STRING}" \
     -H "Authorization: Token {ACCES_TOKEN}" \
     -H "Impersonating: {IMPERSONATION_TYPE}:{IMPERSONATION_KEY}" \
     -H "Accept: application/json"

Examples:

A search for the text “hello” to an endpoint without impersonation where

  • SEARCH_URL = "https://external.service.com/search"
  • ACCES_TOKEN = "ABC"

would look like this:

curl "https://external.service.com/search?q=hello" \
     -H "Authorization: Token ABC" \
     -H "Accept: application/json"
     

The same search with email impersonation requested from user ab@external.com

  • IMPERSONATION_TYPE = "EMAIL"
curl "https://external.service.com/search?q=hello" \
     -H "Authorization: Token ABC" \
     -H "Impersonating: email:ab@external.com" \
     -H "Accept: application/json"

Response

We expect the response to be of the content type “application/json”

{
  "results": [
    {
        "id": UNIQUE_ID,
        "name": "The name/title of the item you want to reference. This will be the main name in the the autocompleter.",
        "container": "An optional string that can help you identify the item, will be shown in the autocompleter e.g the file path.",
        "url": "A URL that we will link to from autocompleted items.",
        "state": "an optional state of the object. (e.g. open/close for issues, read/unread for mails)", 
        "detail": {
            "meta": [
                {
                    "value": "Stefan Kröner",
                    "label": "Modified by"
                },
                {
                    "value": "2015-07-28T08:35:08+00:00",
                    "label": "Modified"
                }
            ],
            "preview": {
                "image": {
                    "url": "https://example.com/objects/3/preview_image.png"
                }
            },
            "title": "an optional title",
            "subtitle": "an optional subtitle",
            "description": "an optional description",
            "score": 1.0
        }
    }
  ]
}
  • id (mandatory) - Every item needs to have an unique id. Items with the same id (or None) are merged into one.
  • detail(optional) - Some details to be shown when focusing on the object. Its meta list allows an arbitrary amount of sub-objects.
  • score(optional) - a value between 0 and 1 that represents the quality of the hit.

Screenshot Grape Search