Damit aus einem anpassbaren Cockpit heraus Objekte für externe Anwendungen exportiert werden können, muss pro Cockpit eine Anwendung vom Typ „RPC-Dienst“ und der besonderen Verwendung „REST-Service“ entwickelt werden. In dieser Dokumentation wird beschrieben, wie diese Anwendung entwickelt und mit dem zugehörigen Cockpit verbunden wird.

1                     Zielgruppe

Entwickler

2                     Begriffsbestimmung

REST-konform

REST ist ein Akronym für Representational State Transfer. REST-konform bedeutet, dass auf eine einfache Art und Weise Anwendungen und Webservices miteinander kommunizieren. Dabei wird z. B. HTTP verwendet und die dadurch definierten Operationen. Der Web-Service ist durch einen URI direkt zugänglich und alle Informationen stecken im HTTP. Dadurch wird erreicht, dass weder auf dem Client noch auf dem Server ein Anwendungszustand gespeichert werden muss.

Web-Service

Ein Web-Service unterstützt die Kommunikation zwischen verschiedenen Anwendungen, die auf unterschiedlichen Plattformen betrieben werden. Ein Web-Service ist eine Anwendung, die mit einem Uniform Resource Identifier (URI) eindeutig identifizierbar ist. Die direkte Interaktion erfolgt über xml-basierter Nachrichten.

3                     Beschreibung

Ein REST-konformer Web-Service kann von REST-Clients aufgerufen werden, zu denen auch Web-Browser gehören.

Mit diesem Web-Service können Objekte, die in einem anpassbaren Cockpit abgefragt werden, auch von einer externen Anwendung abgefragt werden. Die Abfrage kann auf zwei Wegen erfolgen:

• Entweder fragt eine externe Anwendung die Objekte mithilfe eines REST-konformen URIs direkt vom System ab.
• Oder die Objekte werden mithilfe einer Hintergrund-Anwendung REST-konform in eine Datei gespeichert und diese wird im Knowledge Store abgelegt Eine externe Anwendung kann auf die Datei im Knowledge Store zugreifen.

Verbindung zum anpassbaren Cockpit

Ein REST-konformer Web-Service ist automatisch mit dem entsprechenden anpassbaren Cockpit verbunden, wenn die zugrunde liegenden Suchen übereinstimmen. Damit kann im Cockpit der REST-Service-URI abgefragt oder die Hintergrund-Anwendung aufgerufen werden. Weitere Informationen enthält das Kapitel „REST-konformen Web-Service und Cockpit verbinden“.

Basis für den REST-konformen Export

Ein REST-konformer Export basiert auf der Suche eines anpassbaren Cockpits. Im Gegensatz zum anpassbaren Cockpit werden die Detailsuchen nicht berücksichtigt. Nur die Objekte werden exportiert, die den Suchmerkmalen aus der Hauptsuche entsprechen. Zum Filtern stehen nur die Filterfelder aus der Hauptsuche zur Verfügung.

3.1               Dateiformate

Ein REST-konformer Web-Service bietet folgende Dateiformate zur Auswahl an:

• XLS (MS Excel)
• CSV
• XML
• HTML

Das HTML-Dateiformat kann über eine XSLT-Transformation angepasst werden. Erfassen Sie hierzu eine XSLT-Datei und speichern Sie diese im Knowledge Store mit folgendem Namen:

• Sprach- und Exportspezifische XSLT-Datei:
  kstore://<A>/Documents/CockpitDataSource/html/<S>-<L>.xslt
• Exportspezifische XSLT-Datei:
  kstore://<A>/Documents/CockpitDataSource/html/<S>.xslt
• Sprachspezifische, aber exportunabhängige XSLT-Datei:
  kstore://<A>/Documents/CockpitDataSource/html/Global-<L>.xslt
• Exportunabhängige XSLT-Datei:
  kstore://<A>/Documents/CockpitDataSource/html/Global.xslt

Erläuterung der Platzhalter:

• <A>

Arbeitsbereich (Repository-Arbeitsbereich für eine Suche, die im Entwicklungsobjekt nicht für OLTP-Datenbanken eingestellt ist, oder der aktuelle OLTP-Arbeitsbereich).

• <S>

Vollständiger Name der Suche, die im REST-konformen Web-Service verwendet wird

• <L>

Sprachkürzel (z. B. de für Deutsch).

Ein Beispiel einer XSLT-Datei finden Sie im Entwicklungsobjekt vom Typ „Datei“: com.cisag.sys.services.datasource.Html-transform

3.2               REST-konformen Web-Service aufrufen

Ein REST-konformer Web-Service exportiert Objekte aus einem anpassbaren Cockpit. Der Web-Service wird dazu von einer Client-Software per HTTP-GET aufgerufen und über den REST-Service-URI parametrisiert. Der REST-Service-URI enthält neben dem aufzurufenden REST-konformen Web-Service auch Parameter, die das Format und den Umfang der zu exportierenden Objekte steuern.

Die Rückgabe des HTTP-Aufrufs enthält die Objekte der Abfrage aus dem Cockpit im gewünschten Dateiformat, sofern der HTTP-Code 200 zurückgegeben wurde. Anderenfalls liegt ein Fehler vor.

3.2.1          REST-Service-URI im Cockpit erzeugen

Einen REST-Service-URI für einen REST-konformen Web-Service können Sie mit der Aktion „Verknüpfung mit Suchmerkmalen erzeugen“ im anpassbaren Cockpit erzeugen. Der URI enthält die Suchmerkmale aus dem anpassbaren Cockpit.

Hinweis:

Verwenden Sie beim Erzeugen des URIs die Option „Kurzer URI für MS Office“, wenn Sie den REST-konformen Web-Service als Datenquelle in MS Office verwenden möchten. Mit dieser Option wird der URI mit einer Maximallänge von 260 Zeichen erzeugt. In diesem Fall sind die Suchmerkmale nicht in dem URI enthalten, sondern im System persistent gespeichert.

3.2.2          Format der REST-Service-URI

Die REST-Service-URIs werden nach folgendem Schema gebildet.

• Schreibweise mit OLTP-Datenbank als Query-String:
• https://<sas>/services/rest/<service>/search.<extension>?<query>Schreibweise mit OLTP-Datenbank im Pfad:

https://<sas>/services/<oltp>/rest/<service>/search.<extension>?<query>

Hinweis:

Diese Schreibweise ist ab Releasestand CIS510PC-Fix16 verfügbar. Für einen Zugriff mittels Datenquelle in MS Office sollte diese Schreibweise verwendet werden.

Erläuterung der Platzhalter:

• <sas>

Host und Port des ERP-System-Application-Servers

• <oltp>
  Name der OLTP-Datenbank für den Zugriff. Wenn für den Zugriff keine OLTP-Datenbank benötigt wird, wird stattdessen „none“ angegeben.
• <service>

Entwicklungsobjektname der Service-Anwendung

• <extension>

Dateiendung gemäß des gewünschten Ausgabeformats (z. B. „xls“ für MS Excel, „csv“, „xml“, „html“)

• <query>

Query-Strings.

Um die OLTP-Datenbank im Query-String anzugeben, verwenden Sie „oltp=<oltp>“. Darüber hinaus werden für Exporte aus Cockpits die im Folgenden beschriebenen Query-Strings verwendet.

Hinweis:

Beachten Sie, dass für einen REST-konformen Web-Service, der eine OLTP-Datenbank benötigt, die anzumeldende OLTP-Datenbank angegeben werden muss. Je nach Schreibweise erfolgt die Angabe im Pfad oder als Query-String.

Query-Strings

Für REST-konforme Web-Services stehen die Query-Strings zur Verfügung, die in der Dokumentation „Schnittstelle für programmierbare Web-Services“ beschrieben sind.

Die Parametrisierung der Datenquelle wird durch folgende Query-Strings vorgenommen:

Hinweis:

Für REST-konforme Web-Services können Sie sich, wie in der Dokumentation Schnittstelle für programmierbare Web-Services beschrieben, eine WADL-Datei vom System erzeugen lassen. Für REST-konforme Web-Services enthält die WADL-Datei jedoch weder den Service-Namen noch die beschriebenen Query-Parameter.

3.3               REST-konforme Web-Services entwickeln

3.3.1          Web-Service-Anwendung

Der Funktionsumfang des REST-konformen Web-Services hängt nur von der verwendeten Suche ab. Daher ist die Entwicklung eines REST-konformen Web-Services bei vorhandener Suche sehr einfach.

Benötigt werden folgende Entwicklungsobjekte:

• Anwendung

Anwendung mit dem Typ „RPC-Dienst“, der besonderen Verwendung „REST-Service“ und eingetragener Suche.

• Java-Klasse des Web-Services
• Suche (im Web-Service eingetragen)

Die Java-Klasse sollte so heißen wie die Anwendung. Die für einen programmierten Web-Service benötigte Service-Bean-Klasse ist in der Oberklasse com.cisag.pgm.services.datasource.DataSourceService als Inner-Class enthalten. Die Java-Klasse muss wie im Folgenden Beispiel implementiert werden:

public class XExport extends DataSourceService {

public XExport() {

super();

}

}

Die Klasse „XExport“ darf keine eigenen public- oder protected-Methoden deklarieren. Diese sind für zukünftige Erweiterungen vorgesehen.

3.3.2          REST-konformen Web-Service und Cockpit verbinden

Damit ein anpassbares Cockpit den Export mithilfe des REST-konformen Web-Services anbieten kann und der Dialog „Verknüpfung mit Suchmerkmalen kopieren“ verfügbar ist, muss im Entwicklungsobjekt der Cockpit-Anwendung dieselbe Suche eingetragen sein wie im Entwicklungsobjekt der RPC-Dienst-Anwendung. Eine Suche darf nicht in mehreren RPC-Dienst-Anwendungen eingetragen sein. Anderenfalls ist nur einer der REST-konformen Web-Services im Cockpit verfügbar.

Des Weiteren muss die für eine Anwendung eingetragene Suche denselben Entwicklungspräfix verwenden und bei Bedarf aus derselben APP stammen wie die Anwendung. Beachten Sie, dass diese Bedingungen nicht in der Anwendung „Entwicklungsobjekte“ geprüft werden.

3.3.3          Such-Hooks

Das Verhalten der Suchen kann über folgenden Hook beeinflusst werden: com.cisag.pgm.search.SearchHook

Dieser Hook wird sowohl im Cockpit als auch im REST-konformen Web-Service aufgerufen. Je Suche kann eine Hook-Implementierung verwendet werden. Weitere Informationen sind im JavaDoc der Klasse vorhanden.

3.3.4          Renderer und Formatter

Für die Ausgabe in ein Dateiformat werden Renderer und Formatter verwendet. Eine Spalte kann nur ausgegeben werden, wenn

• ein Renderer oder ein Formatter vorhanden ist, oder
• die Spalte auf dem Datentyp „String“ basiert.

Für einen Renderer werden jedoch nur Implementierungen der Schnittstellen „TextRenderer“ und „ToolTipRenderer“ verwendet.

Beachten Sie, dass Renderer und Formatter vom REST-konformen Web-Service in einer Nicht-Dialog-Session aufgerufen werden. Falls eine Spalte nicht ausgegeben werden kann, wird stattdessen ein Fehlerwert ausgegeben. Im Dateiformat „CSV“ ist dies die Zeichenkette „#####“.

3.4               Berechtigungen

Jeder REST-konforme Web-Service ist eine Anwendung, für die im System Berechtigungen vergeben werden können. Für den Aufruf ist die Berechtigung „Öffnen“ der Anwendung erforderlich.