EnterpriseSearch-APP

Scope of functions

The d.velop enterprise search app is the main HTTP interface for searching your system landscape.

Using the API function

You will learn how to use the d.velop enterprise search programming interface for your own developments below.

Authentication

Some interfaces from d.velop enterprise search require a valid authentication from d.ecs identity provider.

The API documentation for d.ecs identity provider describes how you can acquire this kind of authentication.

Deploying providers

You can use this function to deploy providers. Providers are systems that can be searched. The providers are displayed in d.velop enterprise search.

The following requirements must be met before your app’s providers can be displayed in d.velop enterprise search:

• The app must be registered with the http gateway app (only on-premises).
• The app must deliver a link relation (enterprisesearchfeatures) to the enterprise search configuration.
• The app must deliver an OpenSearch description for every provider.

Deliver link relation (enterprisesearchfeatures) with the enterprise search configuration

In order for d.velop enterprise search to display the providers of your app, your app must deliver a link relation enterprisesearchfeaturesunder the base address to a GET query with the request header "Accept: application/hal+json".

Representation of the resource:

{
  "_links": {
    "enterprisesearchfeatures": {
      "href": string
    }
  }
}

Below is an example of this kind of response in JSON format:

{
  "_links": {
    "enterprisesearchfeatures": {
      "href": "/exampleapp/enterprisesearchfeatures"
    }
  }
}

Description of the enterprise search configuration

Via the URL href, a JSON object with the following specifications must be returned in the event of a GET query with request header "Accept: application/hal+json".

Representation of the resource:

{
  "name": string,
  "translatedName": map[string]string,
  "iconUrl": string,
  "loginUrl": string,
  "loggedInUrl": string,
  "configUrl": string,
  "provider": [
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "loginUrl": string,
      "loggedInUrl": string,
      "configUrl": string,
      "iconUrl": string,
      "description": string,
      "activeByDefault": boolean
    },
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "loginUrl": string,
      "loggedInUrl": string,
      "configUrl": string,
      "iconUrl": string,
      "description": string,
      "activeByDefault": boolean
    }
  ]
}

Below is an example of an enterprise search configuration with a provider.

{
   "name": "Awesome App",
   "translatedName": {
      "de": "Super App",
      "en": "Awesome App"
   },
   "iconUrl": "/exampleapp/path/to/icon-thumbsup.png",
   "loginUrl": "/exampleapp/oauth2/login",
   "loggedInUrl": "/exampleapp/oauth2/loggedIn",
   "configUrl": "/exampleapp/config/features",
   "provider": [
      {
         "type": "OPENSEARCH",
         "iFrameCompatible": true,
         "loginUrl": "/exampleapp/oauth2/login?id=4711",
         "loggedInUrl": "/exampleapp/oauth2/loggedIn?id=4711",
         "configUrl": "/exampleapp/config/features?id=4711",
         "iconUrl": "/exampleapp/static/files/favicon.png",
         "description": "/exampleapp/opensearch/description",
         "activeByDefault": false
      }
   ]
}

Description of the login resource

Via the URL loginUrl, the user must be redirected to the external system in the event of a GET query. The authentication information must be saved in the corresponding app for the current user and used accordingly in a search.

info: The URL is only called if the LoggedIn resource responds with the HTTP status code 401 (UNAUTHORIZED).

Description of the LoggedIn resource

Via the URL loggedInUrl, a check must be performed in the event of a GET query to determine whether the current user has access to the external system. The following return values are allowed:

Description of the config resource

Via the URL ConfigUrl, a JSON object with the following specifications must be delivered in the event of a GET query with the request header "Accept: application/hal+json".

Representation of the resource:

[
   {
      "caption": string,
      "description": string,
      "href": string,
      "keywords": [string, string, ...],
      "configurationState": number
   }
]

You will find an example of a config resource below.

[
   {
      "caption": "Awesome App configuration",
      "description": "Short description of the configuration",
      "href": "/exampleapp/oauth2/config",
      "keyWords": ["oauth2", "awesome", "login"],
      "configurationState": 0
   }
]

Communicating changes in the search provider configuration

You can use this function to update the search provider listing from within your configuration interface.

Let us assume your configuration option has a status with errors, for example, because connection data is not correct. In this case, the administrator navigates to the configuration interface by choosing Manage search provider. After you have corrected the connection data, you want to reload the search provider listing.

Reloading the search provider - this is how it works

1. Use the API of the shell app to send a ResourceEvent.
2. Enter “changed” under Eventname. The URI transmitted must correspond to the currently displayed configuration option.
3. You can find information about sending ResourceEvents in the API documentation for the Shell app.

Your enterprise search configuration is retrieved again.

Description of the OpenSearch description file (.osdx)

Below provider.description, you must specify a URL that returns an OpenSearch description file.

OpenSearch description file:

<?xml version="1.0" encoding="UTF-8" ?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:sru="http://a9.com/-/opensearch/extensions/sru/2.0/">
    <ShortName>E-Mails</ShortName>
    <Description>Enterprise Search Provider for Mircosoft Exchange (E-Mails)</Description>
    <Url type="application/rss+xml" template="https://wathe02.d-velop.de/exchangeadapter/search/email?q={searchTerms}&amp;p={startPage}&amp;c={count}">Exchange</Url>
    <Url type="application/sru+xml" template="https://wathe02.d-velop.de/exchangeadapter/search/email?q={query}&amp;p={startRecord}&amp;c={maximumRecords}">Exchange</Url>
    <Image>/exchangeadapter/static/images/favicon.png</Image>
</OpenSearchDescription>

Explanation of the properties:

Explanation of the placeholders:

CQL format

If you offer the format application/sru+xml as an output format, the placeholder {query} is transferred in CQL format. This format uses the facets and search terms that were previously returned to transfer both the user’s search term and additional filterings to you. d.velop enterprise search uses only a small part of the CQL format, which is why it is enough to support the following formats:

• cql.anywhere=(“<User search term>“)
• cql.anywhere=(“<User search term>“) and <facetedResults.facet.index>=(“<facetedResults.facet.terms.query>“)
• cql.anywhere=(“<User search term>“) and <facetedResults.facet.index>=(“<facetedResults.facet.terms.query1>“ or “<facetedResults.facet.terms.query2>“)
• cql.anywhere=(“<User search term>“) and <facetedResults.facet.index1>=(“<facetedResults.facet.terms.query1>“ or “<facetedResults.facet.terms.query2>“) and <facetedResults.facet.index>=(“<facetedResults.facet.terms.query3>“ or “<facetedResults.facet.terms.query4>“)

The placeholders <facetedResults.facet.index> and <facetedResults.facet.terms.query1> correspond to the values of the search result that was previously returned. You can find additional detailed information about the placeholders here.

Search results in application/rss+xml

Below you will find an example of what a search result in the format application/rss+xml can look like.

<?xml version="1.0" encoding="UTF-8"?>
<rss version="" media="" dvelop="" win="">
    <channel>
        <item>
            <title>Example Title</title>
            <link>https://outlook.office365.com/owa/?ItemID=ITEM-ID</link>
            <description>Short abstract of the result item</description>
            <pubDate>Mon, 16 Sep 2019 12:58:01 UTC</pubDate>
            <thumbnail url="https://provider.org/resultitem.png"></thumbnail>
            <property id="sender" name="Sender" displayValue="richard.roe@mycompany.com" value="richard.roe@mycompany.com">Sender</property>
            <property id="reciever" name="Reciever" displayValue="john.doe@mycompany.com" value="john.doe@mycompany.com">Reciever</property>
            <property id="dvelop_es:IFrameCompatible" name="dvelop_es:IFrameCompatible" displayValue="false" value="false">dvelop_es:IFrameCompatible</property>
            <enclosure type="application/vnd.ms-outlook" url="https://outlook.office365.com/owa/?ItemID=AAMkAGZlZGU4NjdhLTNhNjQtNDkwNC1iMjk3LTU3YzA2MDQxOTU3OQBGAAAAAADWB3I3vPVHT7Za7LDOmNb%2FBwDRZC%2BUns%2BPQ6RauNKrXSp3AAAABS2GAABvU1ftEGTNTaVOlXfj0CFuAAAkGNWEAAA%3D&amp;exvsurl=1&amp;viewmodel=ReadMessageItem" length="">Neues Dokument in Google Drive</enclosure>
        </item>
        ...
    </channel>
</rss>

Search results in application/sru+xml

Below you will find an example of what a search result in the format application/sru+xml can look like.

<?xml version="1.0" encoding="UTF-8" ?>
<searchRetrieveResponse
    xmlns:ns="http://docs.oasis-open.org/ns/search-ws/diagnostic"
    xmlns="http://docs.oasis-open.org/ns/search-ws/sruResponse" xsi:schemaLocation="http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/schemas/sruResponse.xsd"
    xmlns:dc="http://purl.org/dc/elements/1.1/">
    <version>1.1</version>
    <numberOfRecords>2</numberOfRecords>
    <records>
        <record>
            <recordData>
                <dc:title>Example Title</dc:title>
                <dc:description>Short abstract of the result item</dc:description>
                <dc:date>2019-09-16T12:58:01Z</dc:date>
                <dc:format>application/vnd.ms-outlook</dc:format>
                <dc:identifier>https://outlook.office365.com/owa/?ItemID=ITEM-ID</dc:identifier>
                <property id="sender" name="Sender" displayValue="richard.roe@mycompany.com" value="richard.roe@mycompany.com">Sender</property>
                <property id="reciever" name="Reciever" displayValue="john.doe@mycompany.com" value="john.doe@mycompany.com">Reciever</property>
                <icon>https://provider.org/resultitem.png</icon>
            </recordData>
        </record>
        ...
    </records>
    <facetedResults
        xmlns="http://docs.oasis-open.org/ns/search-ws/facetedResults" schemaLocation="http://docs.oasis-open.org/ns/search-ws/facetedResults schema.xsd" xsi="http://www.w3.org/2001/XMLSchema-instance">
        <facet>
            <facetDisplayLabel>Sender</facetDisplayLabel>
            <index>Sender</index>
            <terms>
                <term>
                    <actualTerm>richard.roe@mycompany.com</actualTerm>
                    <count>75</count>
                    <query>richard.roe@mycompany.com</query>
                </term>
                <term>
                    <actualTerm>roe.richard@mycompany.com</actualTerm>
                    <count>15</count>
                    <query>roe.richard@mycompany.com</query>
                </term>
            </terms>
        </facet>
        ...
    </facetedResults>
</searchRetrieveResponse>

Perform search

With this function, you can start a search with all providers that are known in d.velop enterprise search and use the results in your app. The search is performed using the format OpenSearch. Learn more about how you can get the OpenSearch description file.

OpenSearch description file

The URL /enterprisesearch/opensearch returns an HTML page that you can use to download the two OpenSearch description files.

Download description file
The link leads to an OpenSearch description file, which you can use according to the format OpenSearch. Alternatively, you can also call the description file directly by querying the following URL:

/enterprisesearch/opensearch/description

Download description file for Windows
The link leads to an OpenSearch description file that uses the d.ecs identity tunnel to cache the cookie. The description file can be used with the format OpenSearch. Use this description file to integrate d.velop enterprise search into your local file explorer. Alternatively, you can also call the description file directly with the following URL:

/enterprisesearch/opensearch/description?identitytunnel=true

Embedding the enterprise search app in third-party applications

You can adjust the display by configuring the following settings so you can easily use d.velop enterprise search from any third-party application.

URL for embedding the enterprise search app

You can use the following URL to embed the company-wide search without a direct search query:

/enterprisesearch/search/

Using parameters to influence the behavior

You can add parameters to the base URL to control the behavior of the embedded company-wide search. The following table contains the possible parameters.

Example:

/enterprisesearch/search?q=Suchbegriff&p=598238e4ed7df5505cdc9304e3371b88-7f0b4762571d05f45f62e4d43b8f6f05&hideProviderSelection&newTab&minimalView

Options for using the parameter p

You can use the parameter p to specify which provider should be used to execute the search. That way, you determine the specific ID in the configuration interface of the company-wide search:

1. Navigate to Manage search provider.
2. Open the context menu of the provider.
3. Copy the ID.

You can transfer several providers if you use a hyphen as a separator.

/enterprisesearch/search?q={search term}&p={ProviderID1-ProviderID2}

If you want to use all providers for the search, set the parameter p=””.

If you do not specify the parameter p, the company-wide search performs the search using the last user-specific provider selection made by the user.

Using the parameter d

The parameter d requires a JSON with the following properties:

Start time must be before the end time.

Adding own functions

Extension points give you the option or adding your own functions to d.velop enterprise search. For example, you can add context actions to the detail view.

Preparing your app

So that extensions for context actions are found, your app must provide an interface, which you will learn about below. d.velop enterprise search uses the HTTP GET request concept for the root resource (systemBaseUri path with the app name) of apps that provide extensions. All apps that are registered in the HttpGateway app are queried.

Providing the URL for extensions

The administrator can manually update root resources of apps on the page /enterprisesearch/extensions. An app’s response is checked in terms of the link relation enterprisesearchextensions. This link relation is a signal that the app offers extensions for d.velop enterprise search. d.velop enterprise search executes an HTTP GET query for the specified links and expects a normed JSON object with the HTTP status code 200 from the responding app.

Request

GET /myapp/
Accept: application/hal+json

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links" : {
        "enterprisesearchextensions" : {
            "href" : "/myapp/enterprisesearchextensions"
        }
    }
}

Displaying extension points

You can display the registered extension points. To do so, call the URL /enterprisesearch/extensions in the browser.

Request

GET /enterprisesearch/extensions
Accept: text/html

Adding context actions to the detail view

You can add context actions to the detail view for a search result. These context actions are also summarized for a search result in the menu for context actions. The app that wants to provide an extension must return an HTTP response in JSON format under the link relation enterprisesearchextensions. The following information must be provided for every context action:

• Context of the extension point: ESObjectDetailsContextAction
• Activation conditions for displaying the context action
• Display name of the context action in the available translations
• Link to the symbol of the context action
• The action that should be executed if the user has clicked on the context action. This is where you need to specify a relative link that is called by d.velop enterprise search via HTTP GET.

Example The example shows how you can structure the HTTP response of the link relation enterprisesearchextensions to add a context action using an extension point ESObjectDetailsContextAction. You define different properties for every context action.

{
    "extensions": [
    {
        "id": "myapp.openExternalApp",
        "activationConditions": [{
            "propertyId": "mimetype",
            "operator": "or",
            "values": ["application/pdf","image/jpeg"]
        }],
        "captions": [{
            "culture": "de",
            "caption": "Externe Applikation öffnen"
        },
        {
            "culture": "en",
            "caption": "Open external application"
        }],
        "context": "ESObjectDetailsContextAction",
        "uriTemplate": "/myapp/dosomething?id={esobject.attributes.document_id}",
        "iconUri": "/myapp/images/goto.png",
        "openInNewWindow": true
    }]
}

You can use the following values to define context actions for the detail view in the following areas:

• A: Definition of activation conditions for the property propertyId
• P: Defining placeholders in the property uriTemplate

Manually adding extension points

By making the following HTTP calls, you can manually add, edit or remove an extension.

Add

POST /enterprisesearch/extensions
Accept: application/json
Body:
{
    "id": "myapp.openExternalApp",
    "activationConditions": [{
        "propertyId": "mimetype",
        "operator": "or",
        "values": ["application/pdf","image/jpeg"]
    }],
    "captions": [{
        "culture": "de",
        "caption": "Externe Applikation öffnen"
    },
    {
        "culture": "en",
        "caption": "Open external application"
    }],
    "context": "ESObjectDetailsContextAction",
    "uriTemplate": "/myapp/dosomething?id={esobject.attributes.document_id}",
    "iconUri": "/myapp/images/goto.png",
    "openInNewWindow": true
}

Edit

PUT /enterprisesearch/extensions/<extension.id>
Accept: application/json
Body:
{
     "id": "myapp.openExternalApp",
     "activationConditions": [{
         "propertyId": "mimetype",
         "operator": "or",
         "values": ["application/pdf","image/jpeg"]
     }],
     "captions": [{
         "culture": "de",
         "caption": "Externe Applikation öffnen"
     },
     {
         "culture": "en",
         "caption": "Open external application"
     }],
     "context": "ESObjectDetailsContextAction",
     "uriTemplate": "/myapp/dosomething?id={esobject.attributes.document_id}",
     "iconUri": "/myapp/images/goto.png",
     "openInNewWindow": true
}

Remove

DELETE /enterprisesearch/extensions/<extension.id>
Accept: application/json