Webservice

Einstellungen des Webservice-Anbieters

Um einen eigenen Webservice anzubieten, hinterlegen Sie im Modul "Integration" im linken Bereich unter dem Punkt "Daten anbieten / Webservice" die erforderlichen Einstellungen. Den entsprechenden Dialog erreichen Sie im Kontextmenü "Einstellungen", wenn der Eintrag "Webservice" markiert ist.

Für die Konfiguration von Webservices ist das Portalrecht "Webservices anbieten" und das Recht am Modul "Werkzeuge" erforderlich.

Bindungsadresse

Definiert, wer auf den Webservice zugreifen darf. Wird "localhost" eingetragen, so ist der Webservice nur lokal verfügbar. Alternativen sind

  • jede (IPv4)

  • jede (IPv6)

  • eine IP-Adresse

Wählen Sie "localhost", wenn Sie Ihren ersten Webservice lokal testen wollen.

Port

Legt fest, unter welchem TCP-Port der Webservice erreichbar sein soll. Idealerweise nutzen Sie eine Portnummer zwischen 49152 und 65535, einen so genannten "Private Port". Diese lassen sich variabel einsetzen, da sie nicht registriert und damit keiner Anwendung zugehörig sind.

Host / Port

Bilden zusammen die Endpoint-URL, unter der ihr Webservice erreichbar sein soll. Der Webservice kann für die öffentliche Verwendung auch einfach unter Ihrer Domain eingebunden werden.

Endpoint-URL

Wird automatisch aus den vorhergehenden Einträgen erzeugt.

Anbieter Aktiv

Mit dieser Einstellung ist der Webservice ab sofort unter der Endpoint-URL erreichbar.

Klicken Sie "OK", um die Einstellungen zu speichern.

Webservice erstellen

Ein neuer Webservice kann über das Hauptmenü "Webservice / Neuer Webservice" erstellt werden. Dazu muss der der Eintrag "Webservice" unter "Daten anbieten" markiert sein. Damit selbst erstellte Webservices genutzt werden können, müssen die Einstellungen des Webservice-Anbieters entsprechend konfiguriert sein.

Allgemeine Eigenschaften des Webservice

Tragen Sie hier einen eindeutigen Namen ein. Unter dem hier eingetragenen Namensraum ist der Webservice später erreichbar. Auch eine kurze Beschreibung des Webservices kann hier erfasst werden.

Abweichende Service-Location

Für Netzwerk-Szenarien, in denen Clients den Webservice über die hier definierte Location unabhängig von der auf Intrexx-Seite definierten Bindungsadresse und Port aufrufen. Die abweichende Service-Location wird im WSDL eingetragen.

Klicken Sie "Weiter".

Operationen

Hier wird der Name und die Beschreibung von bestehenden Operationen angezeigt.

Hinzufügen einer Operation / Bearbeiten einer Operation

Öffnet einen jeweils einen Dialog, in dem eine Operation erstellt oder bearbeitet werden kann. Weitere Informationen dazu finden Sie hier.

Löschen einer Operation

Löscht die aktuell markierte Operation.

Wenn Sie die gewünschte(n) Operation(en) definiert haben, klicken Sie hier "Weiter".

Fertig stellen

Webservice konsumieren

Wenn Sie den Webservice im selben Portal verwenden wollen (z.B. mit einer Webservice-Aktion in Prozessen), aktivieren Sie hier die Einstellung "Webservice konsumieren und konfigurieren Sie dann im nächsten Schritt die Registrierung des Webservices. Alle Informationen dazu finden Sie hier.

Operationen

Einfügen

Mit diesem Operationstyp wird ein neuer Datensatz, z.B. ein neuer Artikel, an den Webservice geliefert, der im Original-Datenbestand eingefügt werden soll.

Aktualisieren

Hier wird ein bestehender Datensatz in der Quellapplikation geändert.

Löschen

Mit diesem Operationstyp wird ein bestehender Datensatz in der Quellapplikation gelöscht. Im Wesentlichen unterscheidet sich die Vorgehensweise bei der Definition der Operation nicht vom Operationstyp "Aktualisieren". Der zu löschende Datensatz wird auch hier anhand der übergebenen ID ermittelt. Zusätzliche Übergabeparameter, also weitere Datenfelder, die beim Abgleich berücksichtigt werden, können nicht definiert werden. Beim Löschen eines Datensatzes wäre dies ohnehin nicht erforderlich.

Lesen

Bei diesem Operationstyp werden die Daten von bestehenden Datensätzen lediglich gelesen. Auch hier erfolgt die Identifikation automatisch über die ID. Als Rückgabeparameter können alle Datenfelder der Quellapplikation gewählt werden.

Auflisten

Dieser Operationstyp unterscheidet sich von den anderen Typen insofern, als das hier mehrere Datensätze, vergleichbar mit einem Array, gelesen werden können. Der Operationstyp kann z.B. für die Suche nach dem Vorkommen einer bestimmten Zeichenfolge in Artikelnummern verwendet werden.

Klicken Sie "Weiter", wenn Sie den gewünschten Operationstyp ausgewählt haben.

Datengruppe auswählen

Hier kann nach dem Namen oder der GUID der Applikation gesucht werden. Wählen Sie die gewünschte Applikation mit einem Klick aus. Wählen Sie anschließende die gewünschte Datengruppe, deren Daten per Webservice zur Verfügung gestellt werden sollen, aus.

Klicken Sie "Weiter".

Übergabeparameter und Rückgabeparameter

Dieser Dialog wird auch für die Definition von Rückgabeparametern verwendet.

Der Parametername kann hier mit einem Doppelklick geändert werden. In der zweiten Spalte wird der Name des Datenfeldes aus der Quellapplikation angezeigt. Dieser Name kann nicht geändert werden. In der Spalte "Optional" kann festgelegt werden, welche Datengruppenfelder bei einem Input als Pflichtfelder gelten. Ist ein Feld als optional markiert, ist die Eingabe eines Wertes nicht zwingend erforderlich.

Hinzufügen eines Datenbankparameters / Bearbeiten eines Parameters

Diese Schaltfläche ist nur bei den Operationstypen "Einfügen" oder "Auswählen" aktiv. Sie öffnet einen Dialog, in dem Datenfelder ausgewählt werden können. Damit wird festgelegt, welche Daten bei einem Input erhoben werden müssen.

Datenfeldauswahl

Wählen Sie hier das gewünschte Datenfeld aus.

Wenn Sie einen Parameter erneut bearbeiten, finden Sie an dieser Stelle zusätzlich den Reiter "Allgemein".

Parameter ID bearbeiten

Hier kann der Name des Parameters geändert werden.

Klicken Sie anschließend "OK", um die Änderungen zu speichern und den Dialog wieder zu schließen.

Hinzufügen eines Requestparameters / Bearbeiten eines Parameters

Öffnet einen Dialog, in dem ein Requestparameter definiert werden kann. Dazu muss der Operationstyp "Auflisten" ausgewählt sein.

Parameter hinzufügen

Geben Sie der Requestvariablen einen eindeutigen Namen. Dieser Name wird für die Zuordnung in der WSDL-Datei verwendet.

Die Bezeichnung der Requestvariablen muss in Intrexx mit "rq_" beginnen. Andernfalls wird die Variable nicht als Requestvariable erkannt. Dieses Präfix wird hier automatisch eingefügt, wenn Sie den Namen der Requestvariablen eintragen. Der Wert wird automatisch in der hier definierten Requestvariablen abgelegt.

Die Requestvariable wiederum wird bei der Rückgabe verwendet, um den Datenbestand auf den Inputwert zu filtern. Wenn Sie z.B. nach Artikelnummern suchen, die die Zeichen "SW" für Software enthalten, wird der Wert SW in der Requestvariablen abgelegt. Der Operationstyp "Auflisten" setzt dann eine Abfrage nach dieser Zeichenfolge in den Quell-Daten ab und gibt alle Datensätze zurück, die die Zeichen SW in der Artikelnummer enthalten.

Klicken Sie "OK", um Eingaben zu speichern und den Dialog wieder zu schließen.

Hinzufügen eines Datensatzanzahlparameters

Setzt den rowcount-Parameter ein. Dazu muss der Operationstyp "Auflisten" ausgewählt sein. Mit diesem Parameter wird die maximale Anzahl der Datensätze festgelegt, die zurückgegeben werden soll. Auch hier kann entschieden werden, ob der Parameter optional angegeben werden kann oder zwingend erforderlich ist.

Klicken Sie "Weiter".

Listenfilter

Wenn Sie die Operation "Auflisten" ausgewählt haben, können Sie hier einen Filter erstellen, um die Liste einzuschränken. Weitere Informationen zu diesem Dialog finden Sie hier.

Klicken Sie "Weiter".

Weitere Einstellungen

Wenn Sie die Operation "Auflisten" ausgewählt haben, können Sie hier die folgenden Einstellungen bearbeiten:

Werte

Anzahl Datensätze

Wenn der Parameter "rowcount" nicht als Übergabeparameter definiert wurde, so kann hier die maximale Anzahl der zurückgegebenen Datensätze festgesetzt werden.

Sortierung

Spalte verfügbare Felder

Hier werden alle Felder aufgelistet, nach denen sortiert werden kann.

Spalte ausgewählte Sortierfelder

Die hier aufgelisteten Felder sortieren den Datenbestand. Ob auf- oder absteigend sortiert wird, kann über das Kontextmenü der Felder festgelegt werden.

Verschiebt das aktuell markierte Feld von einer Liste in die andere.

Ändert die Reihenfolge der Sortierfelder.

Klicken Sie "Weiter".

Allgemeine Eigenschaften der Operation

Legen Sie hier wird den Namen der neuen Operation fest. Auch eine Beschreibung, die die Operation erläutert und später bei der Registrierung bzw. der Auswahl einer Operation angezeigt wird, kann hier eingetragen werden.

Klicken Sie "OK", um Eingaben zu speichern und den Dialog wieder zu schließen.

HTTPS-Verschlüsselung

Im Folgenden wird davon ausgegangen, dass bereits entsprechende Zertifikate sowie keystore und truststore vorliegen. Es ist darauf zu achten, dass keystore und truststore vom Typ Java-Keystore sind.

AXIS2 konfigurieren

Um einen Transport per HTTPS einzurichten, müssen Änderungen an der Axis2-Konfigurationsdatei vorgenommen werden. Wechseln Sie dazu in das Portalverzeichnis "internal/webservice/provider/axis2/conf/" und öffnen Sie die Datei "axis2.xml" in einem Texteditor. Suchen Sie nun nach folgendem Eintrag: 

<!-- ================================================= -->
<!-- Non-blocking http/s Transport Listener  -->
<!-- the non blocking http transport based on HttpCore + NIO extensions -->
<transportReceiver class="de.uplanet.lucy.server.webservice.provider.axis2.transport.nhttp.HttpCore NIOListener" name="http">
	<parameter locked="false" name="port">"WS_PORT"</parameter>
	<parameter locked="false" name="non-blocking">true</parameter>
	<parameter locked="false" name="hostname">"HOST_NAME"</parameter>
</transportReceiver>

Unterhalb dieses Eintrags finden Sie das auskommentierte Element <transportreceiver>. Entfernen Sie die Kommentar-Tags, um den Eintrag zu aktivieren.

<!-- the non blocking https transport based on HttpCore + SSL-NIO extensions -->
<transportReceiver class="de.uplanet.lucy.server.webservice.provider.axis2.transport.nhttp.HttpCore
NIOSSLListener" name="https">
	<parameter locked="false" name="port">SSL_WS_PORT</parameter>
	<parameter locked="false" name="non-blocking">true</parameter>
	<parameter locked="false" name="keystore">
		<KeyStore>
			<Location>KEYSTORE.jks</Location>
			<Type>JKS</Type>
			<Password>KEYSTORE_PASSWORD</Password>
			<KeyPassword>KEY_PASSWORD</KeyPassword>
		</KeyStore>
	</parameter>
	<parameter locked="false" name="truststore">
		<TrustStore>
			<Location>TRUSTSTORE.jks</Location> 
			<Type>JKS</Type>
			<Password>TRUSTSTORE_PASSWORD</Password>
		</TrustStore>
	</parameter>
	<parameter name="SSLVerifyClient">require</parameter>
<!--supports optional|require or defaults to none -->
</transportReceiver>

Geben Sie die folgende Werte korrekt an:

Parameter

Beschreibung
SSL_WS_PORT

Port, über den der https-Webservice aufgerufen werden kann. Es ist darauf zu achten, dass dieser Port vom Port für ungesicherte Webserviceaufrufe unterscheidet.

KEYSTORE.jks

Pfad zum Keystore im Format JKS. Der Pfad muss relativ zum Portalverzeichnis "internal/webservice/provider/" angegeben werden.

KEYSTORE_PASSWORD

Passwort für den angegebenen Keystore.

KEY_PASSWORD

Passwort für den verwendeten Key.

TRUSTSTORE.jks

Pfad zum Truststore im Format JKS. Der Pfad muss relativ zum Portalverzeichnis "internal/webservice/provider/" angegeben werden.

TRUSTSTORE_PASSWORD

Passwort für den angegebenen Truststore.

Wurden die Werte korrekt gesetzt, ist nach folgendem Eintrag zu suchen:

<transportSender class="org.apache.axis2.transport.http.CommonsHTTPTransportSender" name="https">
	<parameter name="PROTOCOL">HTTP/1.1</parameter>
	<parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

Unterhalb dieses Eintrags finden Sie ein weiteres, noch auskommentiertes Element <transportsender>. Entfernen Sie die Kommentar-Tags, um den Eintrag zu aktivieren.

<!-- the non-blocking https transport sender based on HttpCore + NIO SSL extensions-->
<transportSender name="https" class="de.uplanet.lucy.server.webservice.provider.axis2.transport.nhttp.Http
CoreNIOSSLSender">
<parameter name="non-blocking" locked="false">true</parameter>
<parameter name="keystore" locked="false">
	<KeyStore>
		<Location>KEYSTORE.jks</Location>
		<Type>JKS</Type>
		<Password>KEYSTORE_PASSWORD</Password>
		<KeyPassword>KEY_PASSWORD</KeyPassword>
	</KeyStore>
</parameter>
<parameter locked="false" name="truststore">
	<TrustStore>
		<Location>TRUSTSTORE.jks</Location>
		<Type>JKS</Type>
		<Password>TRUSTSTORE_PASSWORD</Password>
	</TrustStore>
</parameter>
<parameter name="HostnameVerifier">DefaultAndLocalhost</parameter>
	;<!--supports Strict|AllowAll|DefaultAndLocalhost or the default if none 	specified-->
</transportSender>

Geben Sie die folgende Werte korrekt an:

Parameter

Beschreibung
KEYSTORE.jks

Pfad zum Keystore im Format JKS. Der Pfad muss relativ zum Portalverzeichnis internal/webservice/provider/ angegeben werden.

KEYSTORE_PASSWORD

Passwort für den angegebenen Keystore.

KEY_PASSWORD

Passwort für den verwendeten Key.

TRUSTSTORE.jks

Pfad zum Truststore im Format JKS. Der Pfad muss relativ zum Portalverzeichnis "internal/webservice/provider/" angegeben werden.

TRUSTSTORE_PASSWORD

Passwort für den angegebenen Truststore.

Speichern Sie die Datei und starten Sie anschließend den Portaldienst neu. Rufen Sie den im Browser die WSDL-Datei auf, um die HTTPS-Authentifizierung zu testen. Achten Sie hierbei auf die Angabe von HTTPS statt HTTP und des Ports. Ist die URL korrekt angegeben, muss das verwendete Zertifikat akzeptiert werden. Danach wird die WSDL-Datei im Browser angezeigt.

Weitere Informationen

Allgemeines

Webservice-Angebot bearbeiten

Webservice-Operation bearbeiten

Webservice registrieren

Webservice-Aktion in Prozessen