Dieses Dokument beschreibt REST-Webservices in CEE für den Business Integration Service (BIS) Datenexport und Datenimport.

Informationen zu den Grundlagen des Datenaustauschs in CEE erhalten Sie in der Dokumentation Einführung: Datenaustausch. Zu den Grundlagen der externen Schnittstellen steht Ihnen die Dokumentation Einführung: Externe Schnittstellen zur Verfügung.

Begriffsbestimmungen

• REST – Abkürzung für Representational State Transfer. Ein Architekturstil für den
  Austausch von Nachrichten in verteilten Hypermedia-Informationssystemen auf
  HTTP-Basis. Es besitzt keinen Protokollcharakter und ist momentan nicht standardisiert. Es müssen keine Protokoll-Konventionen im Unterschied zum SOAP
  bekannt sein, damit Client und Server sich verständigen können. Die zentrale
  Rolle spielen die folgenden Grundprinzipien:
  • Adressierbarkeit der Ressourcen.
  • Verwendung von Hypermedia auf Basis von HTML oder XML.
  • Nutzung der Standard-HTTP-Operationen.
  • Zustandslosigkeit der Kommunikation, die sich nicht etwa auf den serverseitigen Zustand bezieht. REST schreibt vor, dass dieser Zustand entweder vom Client gehalten oder vom Server in einen Ressourcenstatus umgewandelt wird. Nicht gewollt ist ein serverseitig abgelegter, transienter, clientspezifischer Status über die Dauer eines Requests hinweg.
• REST-konforme HTTP-Nutzung – Englisch RESTful http. Die Nutzung der HTTP-Operationen wie folgt:
  • GET: Anfordern von Daten vom Server.
  • POST: neue Daten auf dem Server ablegen.
  • PUT: vorhandene Daten aktualisieren.
  • DELETE: Daten löschen.
  • HEAD: Metadaten zu einer Ressource anfordern.
  • OPTIONS: prüfen, welche Operationen auf einer Ressource zur Verfügung
    stehen.
• REST-Service – Ein Web-Service, bei dem der REST-Architekturstil eingesetzt wird.
• SOAP – Abkürzung für Simple Object Access Protocol. Ein XML-basiertes Protokoll für den Austausch von Nachrichten in verteilten Systemen. SOAP wird zur Kommunikation zwischen Web-Services-Clients und –Servern verwendet.

BIS REST Export

Webservices Addresse: https://<application-server-host>/services/rest/com.cisag.sys.tools.bi.rest.Export/<data-format>

HTTP-Methode: GET

Authentifizierung mithilfe eines CEE-Benutzerzertifikats oder -Kennworts, wie bei der Dialoganmeldung. Der Benutzer muss vom Typ interaktiv sein.

Berechtigungen: Der CEE-Benutzer muss dem System mit aktiviertem SOAP-Zugriff (der den Zugriff auf SOAP- und REST-Webdienste ermöglicht) zugewiesen sein. Der Benutzer muss für den Zugriff auf die Anwendung com.cisag.sys.tools.bi.rest.Exportund für das zu exportierende Business Entity berechtigt sein.

Unterstützte Dateiformate:

• json: JSON
• xml: XML (unterstützt ab CEE 6.2 Fix13)
• csv: CSV. Formatieren Sie die Eigenschaften wie im Filter angegeben.
  (unterstützt ab CEE 6.2 Fix13)
• excel: Unicode-Text. (unterstützt ab CEE 6.2 Fix13)
  
  Hinweis

  Beachten Sie bitte, dass dies keines der nativen Dateiformate von Microsoft Excel (.xls oder .xlsx) ist.

Die Struktur des Dateiformats entspricht derjenigen in der Anwendung Daten exportieren. Das Dateiformat wird in der Webservice-URL und nicht im Filter angegeben.

Abfrage-Strings der URL-Anfrage:

Rückgabe: Wenn der Export erfolgreich war, lautet der HTTP-Statuscode 200 und der HTTP-Body enthält die exportierten Daten.

Wenn ein Fehler auftritt, wird ein HTTP-Statuscode 4xx oder 5xx zurückgegeben. In den meisten Fällen enthält der HTTP-Body eine HTML-Detailmeldung. Fehler in Abfrage-Strings werden als Statuscode 4xx zurückgegeben.

Beispiel für den Antwort-Body einer erfolgreichen Anfrage, der ein Item-Objekt enthält, das mit zwei Attributen number und MaintainingOrganization.code exportiert wurde, die im Filter ausgewählt wurden:

{
  "semiramis" : {
    "entity" : "com.cisag.app.general.obj.Item",
    "nlsMode" : "SINGLE_LANGUAGE",
    "created" : "2020-01-15T08:43:07.284Z",
    "dateTimeMode" : "COMPACT",
    "Item" : [ {
      "number" : "0500000000",
      "MaintainingOrganization" : {
        "code" : "10010"
      }
    } ]
  }
}

BIS REST Import

Webservices-Adresse: https://<application-server-host>/services/rest/com.cisag.sys.tools.bi.rest.Import/<data-format>

HTTP-Methode: POST

Authentifizierung mithilfe eines CEE-Benutzerzertifikats oder -Kennworts, wie bei der Dialoganmeldung. Der Benutzer muss vom Typ interaktiv sein.

Berechtigungen: Der CEE-Benutzer muss dem System mit aktiviertem SOAP-Zugriff (der den Zugriff auf SOAP- und REST-Webdienste ermöglicht) zugewiesen sein. Der Benutzer muss für den Zugriff auf die Anwendung com.cisag.sys.tools.bi.rest.Import und für das zu importierende Business Entity berechtigt sein.

Unterstützte Dateiformate:

• json: JSON
• xml: XML (unterstützt ab CEE 6.2 Fix13)

Die Struktur des Dateiformats entspricht derjenigen in der Anwendung Daten importieren. Das Dateiformat wird in der Webservice-URL und nicht im Filter angegeben.

URL Abfrage-Strings:

Es wird erwartet, dass der HTTP-Body der Anfrage die Importdaten im JSON-Format enthält. Es können mehrere Objekte des Business Entitys enthalten sein.

Ein erfolgreicher Import wird durch einen HTTP-Statuscode 200 und einen leeren HTTP-Body angezeigt.

Die Statuscodes 4xx und 5xx weisen auf eine fehlgeschlagene Anfrage hin. Fehler in Abfrage-Strings werden als 4xx-Statuscode und HTML-Body mit detaillierter Meldung zurückgegeben. Mögliche Ursachen für einen HTTP-500-Statuscode sind Fehler in den Importdaten. In diesem Fall sollte das Datenaustauschprotokoll in CEE auf detaillierte Fehlermeldungen überprüft werden.

POST https://sr-citrix-01.semiramis.local:34500/services/rest/com.cisag.sys.tools.bi.rest.Import/json/?oltp=C20761DV02&FilterName=PARTNER&context=10000 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Content-Length: 463
Host: sr-citrix-01.semiramis.local:34500
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "semiramis" : {
    "entity" : "com.cisag.app.general.obj.Partner",
    "nlsMode" : "MULTI_LANGUAGE",
    "dateTimeMode" : "COMPACT",
    "Partner" : [ {
      "number" : "I0173",
      "type" : "INTERNAL",
      "searchString" : "Doe Jane Hannover",
      "person" : {
        "givenName" : "Jane",
        "surname" : "Doe",
        "fullName" : "Jane Doe"
      },
      "human" : "true"
    } ]
  }
}