EnterpriseSearch-APP

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

EigenschaftTypBeschreibungPflicht
_linksObjektLinkrelationen zu den Ressourcen einer AppJa
_links.enterprisesearchfeaturesObjektObjekt, welches den Pfad zu der Enterprise Search-Konfiguration einer App enthältJa
_links.enterprisesearchfeatures.hrefStringPfad, unter dem die Enterprise Search-Konfiguration abgerufen werden sollJa

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,
  "iconUrl": string,
  "loginUrl": string,
  "loggedInUrl": string,
  "configUrl": string,
  "provider": [
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "description": string
    },
    {
      "type": "OPENSEARCH",
      "iFrameCompatible": boolean,
      "description": string
    }
  ]
}

EigenschaftTypBeschreibungPflichtAnmerkung
nameStringEnthält den übergeordneten Name für die Provider, z.B. d.3ecm, Google oder MicrosoftJa
iconUrlStringEnthält die URL zu einem Icon der AppJaURL zu einem Icon mit der Größe 32 x 32 Pixel im PNG- oder SVG-Format.
loginUrlStringEnthält die URL zu einer Ressource, die die Authentifizierung im Fremdsystem durchführtNein, optional
loggedInUrlStringEnthält die URL zu einer Ressource, die angibt, ob der aktuelle Benutzer am Fremdsystem authentifziert istNein, optional
configUrlStringEnthält die URL zu einer Ressource, die die Konfigurationseinträge zurückgibtNein, optional
provider[]ListeProvider enthält ein oder mehrere Provider-ObjekteJa
provider[].typeStringEnthält den Typ der Provider-BeschreibungJaFolgende Typen an Provider-Beschreibungen werden unterstützt: OPENSEARCH
provider[].iFrameCompatibleBooleanGibt an, ob die Suchergebnisse in einem iFrame (innerhalb der ShellApp) angezeigt werden können.Ja
provider[].descriptionStringEnthählt die URL zu der OpenSearch-Beschreibungsdatei (.osdx)JaWeitere Informationen zum Aufbau der OpenSearch-Beschreibungsdatei findest du hier

Nachfolgend findest du ein Beispiel für eine Enterprise Search-Konfiguration mit einem Provider.

   
{
   "name": "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,
         "description": "/exampleapp/opensearch/description"
      }
   ]
}

 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.

Hinweis

Die URL wird nur aufgerufen, wenn die LoggedIn-Ressource mit dem HTTP-Statuscode 401 (UNAUTHORIZED) antwortet.

 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:

HTTP-StatuscodeBeschreibung
200Der Benutzer ist authentifziert und kann eine Suche im Fremdsystem durchführen
401Der Benutzer ist nicht authentifziert

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

EigenschaftTypBeschreibungPflichtAnmerkung
root[]ListListe aller MenüpunkteJa
root[].captionStringÜberschrift des MenüpunktesJa
root[].descriptionStringBeschreibung des MenüpunktesJa
root[].hrefStringLink zu der Konfiguration hinter dem MenüpunktJa
root[].keywordsString[]Liste von Schlüsselwörtern, die den Menüpunkt beschreiben, um eine Suche nach dem Menüpunkt zu ermöglichenNein, optional
root[].configurationStateNumberStatus der KonfigurationJa0: Die Konfiguration ist vollständig. 1: Die Konfiguration ist unvollständig und sollte vervollständigt werden.

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

Hinweis

Damit die Konfigurationseinträge unterhalb der Konfiguration von d.velop enterprise search angezeigt werden, muss die Konfiguration Suchprovider verwalten einmalig aufgerufen werden.

 Suche durchführen

Mit dieser Funktion kannst du eine Suche gegen alle in d.velop enterprise search bekannten Provider absetzen und die Ergebnisse in deiner App verwenden. Die Suche wird über das Format OpenSearch durchgeführt. Im Folgenden wird aufgezeigt, 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 können. 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, der 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 Dateiexplorer zu integrieren. Alternativ kann die Beschreibungsdatei auch direkt durch den Aufruf der folgenden URL abgerufen werden:

   
/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.

ParameterBeschreibungBeispiel
qMit dem Parameter q kannst du einen Suchbegriff übergeben, der in der unternehmensweiten Suche bei Aufruf direkt gesucht wird. Du musst den Suchbegriff als URL kodiert übergeben./enterprisesearch/search?q=Suchbegriff
pMit dem Parameter p kannst du eingrenzen, mit welchem Provider die Suche ausgeführt wird. Die ID des Providers kannst du der Providerverwaltung entnehmen./enterprisesearch/search?p=ProviderId
minimalViewMit dem Parameter minimalView kannst du festlegen, dass die Anzeige leichtgewichtig und minimalistisch erfolgen soll. Es wird kein Logo dargestellt./enterprisesearch/search?minimalView
hideProviderSelectionMit dem Parameter hideProviderSelection kannst du festlegen, ob die Providerauswahl angezeigt werden soll./enterprisesearch/search?hideProviderSelection
newTabMit dem Parameter newTab kannst du festlegen, dass sich nach einer Suche die Trefferliste in einem neuen Tab öffnet./enterprisesearch/search?newTab

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.

 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",
		"iFrameCompatible": true
	}]
}

EigenschaftTypBeschreibungPflicht
idStringLegt den eindeutigen technischen Namen fest, der verwendet wird, um die Erweiterung von anderen Erweiterungen zu unterscheiden.Ja
activationConditions[]Objekt-ArrayDie Anwendung teilt für jede Erweiterung mit, unter welchen Aktivierungsbedingungen die Kontextaktion angezeigt werden soll. Eine Kontextaktion wird dann angezeigt, wenn alle Einzelbedingungen zutreffen. Enthält die Liste der Aktivierungsbedingungen keinen Eintrag, ist die Erweiterung generell aktiv. Gib die Aktivierungsbedingungen als Array an.Nein
activationConditions[].propertyIdStringGibt die ID der Eigenschaft an, die für die Aktivierungsbedingung geprüft wird. Mögliche Werte findest du weiter unten.Ja
activationConditions[].operatorStringGibt an, auf welche Art und Weise eine Einzelbedingung ausgewertet wird. Du kannst die folgenden Operatoren wählen: or: Eine ´or´-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft einem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt. notOr: Eine notOr-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft keinem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.Ja
activationConditions[].valuesString-ArrayGibt die Werte in Form eines Arrays an, die mit dem Wert der propertyId-Eigenschaft verglichen werden.Ja
captions[]Objekt-ArrayJede Kontextaktion teilt mit, unter welchem Namen die Kontextaktion angezeigt wird. Sie können auch verschiedene Sprachen berücksichtigen, wobei Sie die sprachabhängigen Namen als Array angeben. Für eine vollständige Kompatibilität von Sprachpaketen geben Sie die Übersetzung für folgende Sprachen an: cs (Tschechisch), da (Dänisch), de (Deutsch), en (Englisch), es (Spanisch), fr (Französisch), hr (Kroatisch), it (Italienisch), nl (Niederländisch), pl (Polnisch), sr (Serbisch)Ja
captions[].cultureStringGibt die Sprache der Kontextaktion an. Die Angabe enthält den Sprachcode (z.B. en) und optional einen zusätzlichen Regionscode (z.B. en-GB).Ja
captions[].captionStringGibt den sprachabhängigen Namen der Kontextaktion an.Ja
contextStringGibt den gewünschten Erweiterungspunkt an, zu dem die Kontextaktion hinzugefügt werden soll. Geben Sie für Kontextaktionen zur Detailansicht folgenden Wert an: EsObjectDetailsContextActionJa
uriTemplateStringDefiniert die URL, die aufgerufen werden soll, wenn der Anwender auf die Kontextaktion klickt. Du kannst Platzhalter definieren, um weitere Informationen zum aktuellen Kontext zu erhalten. Die Platzhalter werden beim Aufrufen der Erweiterung durch die tatsächlichen Eigenschaften ersetzt. Die Eigenschaften werden URL-codiert in die URI übernommen. Mögliche Platzhalter findest du weiter unten.Ja
iconUriStringGibt den Link zum Symbol an, das für Kontextaktion angezeigt wird. Die Datei für das Symbol muss im PNG-Format vorliegen.Ja
openInNewWindowBooleanGibt an, ob die Kontextaktion innerhalb von d.3one geöffnet werden kann (false) oder ein neues Fenster dafür geöffnet werden muss (true). Standardmäßig ist false eingestellt.Nein

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
ThemaWertNutzungBeschreibung
Providerprovider.idA/PID des Suchproviders. Die ID kann von der Ressource /enterprisesearch/provider abgefragt werden.
Providerprovider.nameA/PName des Suchproviders z.B. (Produktivsystem). Der Name kann von der Ressource /enterprisesearch/provider abgefragt werden.
Providerproviderconfig.idA/PID der Providerkonfiguration. Die ID kann von der Ressource /enterprisesearch/provider abgefragt werden.
Providerproviderconfig.nameA/PName der Providerkonfiguration z.B. d.3 ecm. Der Name kann von der Ressource /enterprisesearch/provider abgefragt werden.
Benutzeruser.idp.group_idA/PAktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist. Platzhalter uriTemplate: Liste der GUIDs der Benutzergruppen der identity provider-App als Array im JSON-Format, in denen der aktuell angemeldete Anwender Mitglied ist.
Eigenschaften zum Elementesobject.titleA/PTitel des Suchergebnisses
Eigenschaften zum Elementesobject.mime_typeA/PMIME-Typ des Suchergebnisses (z.B. image/jpeg oder application/vnd.ms-outlook).
Eigenschaften zum Elementesobject.datePLetztes Änderungsdatum des Suchergebnisses im Format RFC822.
Eigenschaften zum Elementesobject.linkPLink auf das Suchergebnis
Eigenschaften zum Elementesobject.iframe_compatibleA/PEnthält die Information, ob das Suchergebnis in einem IFrame angezeigt werden kann. Nur der erste angegebene Wert wird berücksichtigt.
Eigenschaften zum Elementesobject.attributes.<attributeId>A/PWert des Attributes mit der ID <attributeId>