EnterpriseSearch-APP

 Funktionsumfang

Die App d.velop enterprise search ist die zentrale HTTP-Schnittstelle zur Durchsuchung deiner Systemlandschaft.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle von d.velop enterprise search für deine eigenen Entwicklungen nutzen kannst.

 Authentifizierung

Einige Schnittstellen von d.velop enterprise search benötigen eine gültige Authentifizierung von d.ecs identity provider.

Wie du eine solche Authentifizierung erhälst, kannst du der API-Dokumentation von d.ecs identity provider entnehmen.

 Bereitstellen von Providern

Mit dieser Funktion kannst du Provider bereitstellen. Provider sind Systeme, die durchsucht werden können. Die Provider werden innerhalb von d.velop enterprise search dargestellt.

Folgende Anforderungen müssen erfüllt sein, damit die Provider deiner App in d.velop enterprise search angezeigt werden:

• Die App muss an der http gateway-App registriert sein (nur On-Premises).
• Die App muss eine Linkrelation (enterprisesearchfeatures) zu der Enterprise Search-Konfiguration ausliefern.
• Die App muss für jeden Provider eine OpenSearch-Beschreibung ausliefern.

 Linkrelation (enterprisesearchfeatures) zu der Enterprise Search-Konfiguration ausliefern

Damit d.velop enterprise search die Provider deiner App anzeigt, muss deine App unter der Basisadresse auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" eine Linkrelation enterprisesearchfeatures ausliefern.

Repräsentation der Ressource:

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

Nachfolgend findest du ein Beispiel für eine solche Antwort im JSON-Format:

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

 Beschreibung der Enterprise Search-Konfiguration

Unter der URL href muss auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausgeliefert werden.

Repräsentation der Ressource:

{
  "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
    }
  ]
}

Nachfolgend findest du ein Beispiel für eine Enterprise Search-Konfiguration mit einem 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
      }
   ]
}

 Beschreibung der Login-Ressource

Unter der URL loginUrl muss auf eine GET-Anfrage der Benutzer zu einer Anmeldung an dem Fremdsystem umgeleitet werden. Die Authentifzierungsinformationen müssen in der jeweiligen App für den aktuellen Benutzer gespeichert und bei einer Suche entsprechend verwendet werden.

 Beschreibung der LoggedIn-Ressource

Unter der URL loggedInUrl muss auf eine GET-Anfrage geprüft werden, ob der aktuelle Benutzer Zugriff auf das Fremdsystem hat. Folgende Rückgabewerte sind zulässig:

 Beschreibung der Config-Ressource

Unter der URL ConfigUrl muss auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausgeliefert werden.

Repräsentation der Ressource:

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

Nachfolgend findest du ein Beispiel für eine Config-Ressource.

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

 Mitteilen von Änderungen der Suchproviderkonfiguration

Mit dieser Funktion kannst du - aus deiner Konfigurationsoberfläche heraus - die Suchproviderauflistung aktualisieren.

Angenommen, deine Konfigurationsoption ist in einem fehlerhaften Status, da beispielsweise Verbindungsdaten nicht korrekt sind. In diesem Fall navigiert der Administrator über Suchprovider verwalten zur Konfigurationsoberfläche. Nachdem du die Verbindungsdaten korrigiert hast, möchtest du, dass die Suchproviderauflistung neu geladen wird.

Neuladen der Suchprovider - So geht's

1. Versende ein ResourceEvent über die API der Shell-App.
2. Gib unter Eventname "changed" an. Die übermittelte URI muss der aktuell angezeigten Konfigurationsoption entsprechen.
3. Informationen über das Senden von RessourceEvents findest du in der API-Dokumentation der Shell-App.

Deine EnterpriseSearch-Konfiguration wird erneut abgerufen.

 Beschreibung der OpenSearch-Beschreibungsdatei (.osdx)

Unterhalb von provider[].description muss eine URL angegeben werden, die eine OpenSearch-Beschreibungsdatei zurückliefert.

Beispiel Beschreibungsdatei:

<?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>

Erläuterung der Eigenschaften:

Erläuterung der Platzhalter:

 CQL-Format

Wenn du das Format application/sru+xml als Ausgabeformat anbietest, wird der Platzhalter {query} im CQL-Format übertragen. Dieses Format übermittelt dir sowohl den Suchbegriff des Benutzers, als auch weitere Filterungen mithilfe der zuvor zurückgelieferten Facetten und Suchbegriffe. d.velop enterprise search verwendet nur einen kleinen Teil vom CQL-Format, daher reicht es aus, folgende Formate zu unterstützen:

• 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>")

Die Platzhalter <facetedResults.facet.index> und <facetedResults.facet.terms.query1> entsprechen den Werten des zuvor zurückgeliefertem Suchergebnisses. Weitere Details zu den Platzhaltern findest du hier.

 Suchergebnisse in application/rss+xml

Im Folgenden findest du ein Beispiel, wie ein Suchergebnis im Format application/rss+xml aussehen kann.

<?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>

 Suchergebnisse in application/sru+xml

Im Folgenden findest du ein Beispiel, wie ein Suchergebnis im Format application/sru+xml aussehen kann.

<?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>

 Suche durchführen

Mit dieser Funktion kannst du eine Suche mit allen in d.velop enterprise search bekannten Provider starten und die Ergebnisse in deiner App verwenden. Die Suche wird über das Format OpenSearch durchgeführt. Erfahre mehr darüber, wie du die OpenSearch-Beschreibungsdatei erhältst.

 OpenSearch-Beschreibungsdatei

Die URL /enterprisesearch/opensearch gibt eine HTML-Seite zurück, über die zwei OpenSearch-Beschreibungsdateien heruntergeladen werden können.

Beschreibungsdatei herunterladen
Der Link führt zu einer OpenSearch-Beschreibungsdatei, die du gemäß dem Format OpenSearch verwenden kannst. Alternativ kann die Beschreibungsdatei auch direkt durch den Aufruf der folgenden URL abgerufen werden:

/enterprisesearch/opensearch/description

Beschreibungsdatei für Windows herunterladen
Der Link führt zu einer OpenSearch-Beschreibungsdatei, die d.ecs identity tunnel für die Zwischenspeicherung des Cookies verwendet. Die Beschreibungsdatei kann gemäß des Formats OpenSearch verwendet werden. Verwende diese Beschreibungsdatei, um d.velop enterprise search in deinen lokalen Datei-Explorer zu integrieren. Alternativ kannst du die Beschreibungsdatei auch direkt mit der folgenden URL aufrufen:

/enterprisesearch/opensearch/description?identitytunnel=true

 Einbetten der enterprise search-App in Drittanwendungen

Um d.velop enterprise search aus beliebigen Drittanwendungen einfach verwenden zu können, kannst du die Darstellung durch folgende Einstellungen anpassen.

URL zum Einbetten der enterprise search-App

Mit folgender URL kannst du die unternehmensweite Suche ohne direkte Suchabfrage einbetten:

/enterprisesearch/search/

Nutzen von Parametern zur Beeinflussung des Verhaltens

Du kannst die Basis-URL mit Parametern erweitern, um das Verhalten der eingebetteten unternehmensweiten Suche zu steuern. In der folgenden Tabelle findest du die möglichen Parameter.

Beispiel:

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

Verwendungsmöglichkeiten des Parameters p

Mit dem Parameter p kannst du festlegen, mit welchem Provider die Suche durchgeführt werden soll. So ermittelst du die konkrete ID in der Konfigurationsoberfläche der unternehmensweiten Suche: 1. Navigiere zu Suchprovider verwalten. 2. Öffne das Kontextmenü des Providers. 3. Kopiere die ID.

Du kannst mehrere Provider mit einem Bindestrich als Trennzeichen übergeben.

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

Wenn du möchtest, dass mit allen Providern gesucht wird, setze den Parameter p="".

Wenn du den Parameter p nicht angibst, sucht die unternehmensweite Suche mit der letzten benutzerspezifischen Providerauswahl des Anwenders.

Verwendung des Parameters d

Der Parameter d erwartet ein JSON mit folgenden Eigenschaften:

Der Startzeitpunkt muss vor dem Endzeitpunkt liegen.

 Erweitern um eigene Funktionen

Mit Erweiterungspunkten hast du die Möglichkeit, d.velop enterprise search um eigene Funktionen zu erweitern. Füge zum Beispiel Kontextaktionen zur Detailansicht hinzu.

 Vorbereiten deiner App

Damit Erweiterungen zu Kontextaktionen gefunden werden, muss deine App eine Schnittstelle bereitstellen, die du im Folgenden kennenlernst. d.velop enterprise search nutzt das Konzept HTTP GET-Anforderung für die Rootressource (systemBaseUri-Pfad mit dem App-Namen) von Apps, die Erweiterungen bereitstellen. Es werden alle Apps abgefragt, die an der HttpGateway-App registriert sind.

 Bereitstellen der URL für die Erweiterungen

Die Rootressourcen von Apps können manuell vom Administrator auf der Seite /enterprisesearch/extensions aktualisiert werden. Die Antwort (Response) einer App wird hinsichtlich der Linkrelation enterprisesearchextensions geprüft. Diese Linkrelation gilt als Signal, dass die App Erweiterungen für d.velop enterprise search anbietet. d.velop enterprise search führt eine HTTP-GET-Anfrage auf den angegebenen Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200.

Request

GET /myapp/
Accept: application/hal+json

Response

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

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

 Anzeigen von Erweiterungspunkten

Du kannst die registrierten Erweiterungspunkte anzeigen. Rufe dazu die URL /enterprisesearch/extensions im Browser auf.

Request

GET /enterprisesearch/extensions
Accept: text/html

 Hinzufügen von Kontextaktionen zur Detailansicht

Du kannst Kontextaktionen zur Detailansicht für ein Suchergebnis hinzufügen. Diese Kontextaktionen werden auch im Menü für Kontextaktionen für ein Suchergebnis zusammengefasst. Die App, die eine Erweiterung bereitstellen möchte, muss unter der Linkrelation enterprisesearchextensions eine HTTP-Antwort im JSON-Format zurückgeben. Zu jeder Kontextaktion müssen folgende Informationen bereitgestellt werden:

• Kontext des Erweiterungspunkts: ESObjectDetailsContextAction
• Aktivierungsbedingungen zum Anzeigen der Kontextaktion
• Anzeigename der Kontextaktion in den verfügbaren Übersetzungen
• Link zum Symbol der Kontextaktion
• Die Aktion, die ausgeführt werden soll, wenn der Anwender auf die Kontextaktion geklickt hat. Gib an dieser Stelle einen relativen Link an, der per HTTP GET von d.velop enterprise search aufgerufen wird.

Beispiel Das Beispiel zeigt, wie du die HTTP-Antwort der Linkrelation enterprisesearchextensions gestaltest, um eine Kontextaktion mithilfe eines Erweiterungspunkts ESObjectDetailsContextAction hinzuzufügen. Je Kontextaktion definierst du verschiedene Eigenschaften.

{
	"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
	}]
}

Die nachfolgenden Werte kannst du bei der Definition von Kontextaktionen zur Detailansicht in folgenden Bereichen nutzen:

• A: Definition von Aktivierungsbedingungen für die Eigenschaft propertyId
• P: Festlegen von Platzhaltern in der Eigenschaft uriTemplate

 Manuelles Hinzufügen von Erweiterungspunkten

Durch die folgenden HTTP-Aufrufe kannst du eine Erweiterung manuell hinzufügen, bearbeiten oder entfernen.

Hinzufügen

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
}

Bearbeiten

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
}

Entfernen

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