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

 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:

EigenschaftTypBeschreibungPflicht
ShortNameStringKurze Bezeichnung des Providers. Der Anwender entscheidet anhand dieser Bezeichnung, ob er eine Suche in dem Provider absetzen möchte.Ja
DescriptionStringKurze Erläuterung, was mit diesem Provider durchsucht wird.Nein
UrlStringURL-Vorlage, die bei einer Suche aufgerufen wirdJa
Url.typeStringAusgabeformat der Suchergebnisse. Interpretiert werden application/rss+xml und application/sru+xml. Der Typ application/sru+xml muss angeboten werden, um Facetten zurückgeben zu können.Ja
Url.templateStringURL, die bei der Suche aufgerufen wird. Die möglichen Platzhalter können der nachfolgenden Tabelle entnommen werden.Ja
ImageStringURL zu einem Icon für den ProviderNein

Erläuterung der Platzhalter:

PlatzhalterBeschreibungFormat
{searchTerms}Suchbegriff des Benutzersapplication/rss+xml
{startPage}Index der Seite, die zurückgeliefert werden soll, beginnend bei 1.application/rss+xml
{count}Maximale Anzahl an Suchergebnissen, die pro Seite zurückgegeben werden sollen.application/rss+xml
{query}Suchbegriff des Benutzers im CQL-Format inklusive Filterungenapplication/sru+xml
{startRecord}Index des Eintrags (Record), der als nächstes zurückgeliefert werden soll, beginnend bei 1.application/sru+xml
{maximumRecords}Maximale Anzahl an Suchergebnissen, die pro Seite zurückgegeben werden sollen.application/sru+xml

 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>
EigenschaftenBeschreibungPflicht
itemPro gefundenem Ergebnis wird ein Eintrag (Item) zurückgegebenNein
item.titleTitel des gefundenen ErgebnissesJa
item.linkLink zum ErgebnisJa
item.descriptionZusammenfassung, die auf Basis der Sucheingabe erstellt wurde.Nein
item.pubDateLetztes Bearbeitungsdatum des Ergebnisses im Format RFC 822Ja
item.thumbnailSpezielles Icon zum Ergebnis. Alternativ wird das Icon des Providers angezeigt.Nein
item.thumbnail.urlURL zum IconNein
item.propertyAuflistung sämtlicher Eigenschaften zum ErgebnisNein
item.property.idID, welche die Eigenschaft eindeutig kennzeichnet. Mit der Eigenschaft dvelop_es:IFrameCompatible kannst du optional die Anzeige im neuen Fenster übersteuern.Ja
item.property.nameBezeichnung der Eigenschaft in der Sprache des AnwendersJa
item.property.displayValueWert der Eigenschaft, falls notwendig für den Anwender formatiert oder übersetzt.Ja
item.property.valueWert der EigenschaftJa
item.enclosureAnhang, der das gefundene Ergebnis besser beschreibt.Ja
item.enclosure.typeMimeType des ErgebnissesJa
item.enclosure.urlLink zum ErgebnisJa

 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>
EigenschaftenBeschreibungPflicht
recordPro gefundenem Ergebnis wird ein Eintrag (Record) zurückgegebenNein
record.recordData.dc:titleTitel des gefundenen ErgebnissesJa
record.recordData.dc:descriptionZusammenfassung, die auf Basis der Sucheingabe erstellt wurde.Nein
record.recordData.dc:dateLetztes Bearbeitungsdatum des Ergebnisses im Format RFC 3339Ja
record.recordData.dc:formatMimeType des ErgebnissesJa
record.recordData.dc:identifierLink zum ErgebnisJa
record.recordData.propertyAuflistung sämtlicher Eigenschaften zum ErgebnisNein
record.recordData.property.idID, welche die Eigenschaft eindeutig kennzeichnet. Mit der Eigenschaft dvelop_es:IFrameCompatible kannst du optional die Anzeige im neuen Fenster übersteuern.Ja
record.recordData.property.nameBezeichnung der Eigenschaft in der Sprache des AnwendersJa
record.recordData.property.displayValueWert der Eigenschaft, falls notwendig für den Anwender formatiert oder übersetzt.Ja
record.recordData.property.valueWert der EigenschaftJa
record.recordData.iconSpezielles Icon zum Ergebnis. Alternativ wird das Icon des Providers angezeigt.Nein
facetedResults.facetPro Facette wird ein Eintrag (Facet) zurückgegebenNein
facetedResults.facet.facetDisplayLabelAnzeigename der FacetteJa
facetedResults.facet.indexID der FacetteJa
[]facetedResults.facet.termsAuflistung der Begriffe für die FacetteJa
[]facetedResults.facet.terms.actualTermAnzeigename des aktuellen SuchbegriffsJa
[]facetedResults.facet.terms.countAnzahl der Treffer mit diesem SuchbegriffJa
[]facetedResults.facet.terms.queryID bzw. technische Bezeichnung für den SuchbegriffJa

 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.

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. Mögliche Werte: start (Die Providerauswahl auf der Startseite wird ausgeblendet), all (Die Providerauswahl auf der Start- und auf der Ergebnislistenseite wird ausgeblendet),/enterprisesearch/search?hideProviderSelection=start
newTabMit dem Parameter newTab kannst du festlegen, dass sich nach einer Suche die Trefferliste in einem neuen Tab öffnet./enterprisesearch/search?newTab
providerViewMit dem Parameter providerView kannst du festlegen, wie die Providerauswahl auf der Ergebnisseite dargestellt wird. Mögliche Werte: dropdown (Standardwert), smallcards, bigcards/enterprisesearch/search?providerView=bigcards

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",
		"openInNewWindow": 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>

 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