1                     Themenübersicht

Durch den Business Integration Service (BIS) können Sie Daten aus Datenbanken exportieren und in Datenbanken importieren. Der BIS lässt sich beispielsweise für folgende Aufgaben verwenden:

• Altdatenübernahmen vor dem Produktivstart
• Datenaustausch mit Fremdsystemen oder anderen Comarch-ERP-Enterprise-Systemen während des Produktivbetriebs
• Massenänderungen von Daten im System

Dieses Dokument beschreibt die Grundlagen des BIS. Weiterhin ist eine Übersicht über die weitere vorhandene Dokumentation enthalten.

2                     Zielgruppe

• Berater
• Anwendungsentwickler

3                     Begriffsbestimmung

Controller

Der Controller ist eine Java-Klasse, die den Import bzw. Export eines Business Entitys realisiert. Die zugehörigen Schnittstellen sind „com.cisag.pgm.bi.ImportController“ und „com.cisag.pgm.bi.ExportController“. Der Controller liefert das für den Import bzw. den Export zu verwendende Datenmodell und bestimmt damit die Menge der für das Business Entity zur Verfügung stehenden Objekte, Attribute und Beziehungen. Das Datenmodell kann dabei für den Import und für den Export unterschiedlich sein. Für einfache Business Entitys kann der Import bzw. der Export auch ohne vorhandenen Controller und somit generisch erfolgen.

Extensible Markup Language (XML)

Mit XML können strukturierte Daten in einer Text-Datei gespeichert werden. Die Beschreibungssprache ermöglicht die Definition, Übertragung, Überprüfung und Interpretation von Daten zwischen Anwendungen und eignet sich besonders für den strukturierten Datenaustausch. Bei XML-Dokumenten erfolgt eine Trennung von Inhalt, Struktur und Information zur Darstellung. XML wird vom W3C als Standard koordiniert und definiert.

Extensible Stylesheet Language Transformations (XSLT)

XSLT, ist eine Programmiersprache zur Transformation von XML-Dokumenten. XSLT baut auf der logischen Baumstruktur eines XML-Dokumentes auf und dient zur Definition von Umwandlungsregeln. Sie beschreibt die Umwandlung eines XML-Dokuments in ein anderes Dokument.

Filter

Das BIS-Datenmodell zu einem Business Entity kann sehr umfangreich sein. Ein Filter ist ein Ausschnitt des BIS-Datenmodells zu einem Business Entity. Er definiert, welche Objekte, Attribute und Beziehungen eines Business Entitys bei einem Import- bzw. beim Exportvorgang berücksichtigt werden sollen.

Fehler-Datei

Die Datei, in die beim Import von Daten im BIS diejenigen Daten aus der Quell-Datei geschrieben werden, die als fehlerhaft erkannt werden. Abhängig von der Art des Fehlers kann die Fehler-Datei manuell korrigiert und erneut importiert oder in der Korrektur-Anwendung schrittweise eingelesen und abgearbeitet werden.

Korrektur-Anwendung

Die Korrektur-Anwendung ist diejenige Dialog-Anwendung, die verwendet wird, um einfache Fehler-Dateien interaktiv im System zu bearbeiten. Zu einem Business Entity kann eine oder können mehrere Korrektur-Anwendungen existieren. Im Allgemeinen ist die Korrektur-Anwendung die jeweilig zum Business Entity gehörende Anwendung (z. B. die Anwendung „Partner“ für das Business Entity „com.cisag.app.general.obj.Partner“), die in einem speziellen Modus geöffnet wird. In diesem Modus können die Business-Entity-Instanzen aus der Fehler-Datei einzeln geöffnet, interaktiv bearbeitet und gespeichert werden.

Quell-Datei

Die Quell-Datei ist die Datei, die beim Import von Daten im BIS eingelesen wird. Eine Quell-Datei enthält immer nur die Daten zu einem Business-Entity-Typ. Bei einigen Dateitypen können die zu importierenden Daten über mehrere Quell-Dateien verteilt sein. In diesem Fall spricht man von der Haupt-Quell-Datei und den verknüpften Quell-Dateien. Während des Importvorgangs werden die Haupt-Quell-Datei und die verknüpften Quell-Dateien zu einer neue Datei zusammengefasst, mit welcher der eigentliche Import durchgeführt wird. Die Daten aus der Quell-Datei, die nicht erfolgreich importiert werden können, werden zusammen mit den zugehörigen Fehlermeldungen in die Fehler-Datei geschrieben.

Text durch Trennzeichen getrennt (CSV)

CSV (comma separated values) ist ein Dateityp, in dem die Werte der einzelnen Spalten durch ein Trennzeichen getrennt werden. Zeilen werden durch Zeilenumbrüche getrennt. Dieses Trennzeichen muss bekannt sein, um die Datei importieren zu können. Übliche Trennzeichen sind beispielsweise das einfache Komma und das Semikolon. In diesem Format gespeicherte Daten können in zahlreichen Programmen verwendet und bearbeitet werden. Durch die einfache, nicht hierarchische Struktur von CSV ist der Dateityp zur Abbildung komplexer Datenstrukturen nicht geeignet.

Unicode

Im System wird durchgängig Unicode verwendet. Deshalb können faktisch sämtliche weltweit gebräuchlichen Zeichen benutzt und auf Formularen gedruckt werden. Vor der Verfügbarkeit von Unicode waren sehr viele unterschiedliche Kodierungssysteme für die Zeichendarstellung erforderlich. Keines dieser Kodierungssysteme umfasste je genug Zeichen. Allein in der Europäischen Union waren mehrere Kodierungssysteme notwendig, um die verschiedenen Sprachen der Mitgliedsländer darstellen zu können. Durch die Unicode-Verwendung kann Comarch ERP Enterprise für viele Systeme direkt eingesetzt werden. Unterschiedliche Länder und Sprachen stellen kein Problem dar. Spezielle und aufwendige Anpassungen sind nicht erforderlich, denn Text kann mit Unicode weltweit ohne Informationsverluste ausgetauscht werden, denn Unicode gibt jedem Zeichen seine eigene Nummer – plattformunabhängig, programmunabhängig, sprachunabhängig.

Unicode-Text durch Tabulator getrennt

Dieser Dateityp ist ähnlich wie CSV, jedoch ist als Trennzeichen der Tabulator und als Zeichencodierung Unicode festgelegt. Dateien in diesem Format können unter anderem von Microsoft Excel verwendet werden. Um diesen Dateityp in Excel zu speichern, müssen Sie in Excel den gleichnamigen Dateityp angeben.

XML-Schema (XSD)

Ein XML-Schema (XML-Schema-Definition, XSD) ist eine formale Spezifikation der Regeln eines XML-Dokuments, das anzeigt, welche Elemente in einem Dokument in welchen Kombinationen zulässig sind.

Ziel-Datei

Die Datei, die beim Export von Daten im BIS erzeugt wird.

4                     Einführung in den Business Integration Service (BIS)

Der Business Integration Service (BIS) ist die universelle Datenaustauschschnittstelle im System.

Der BIS ist grundsätzlich in der Lage, mit allen Business Entitys zu arbeiten. Die relevanten betriebswirtschaftlichen Business Entitys, die vom BIS offiziell unterstützt werden, sind in der Dokumentation „Export- und Import-Schnittstellen“ aufgeführt.

Der BIS kann über verschiedene Kanäle angesteuert werden, wodurch sich der BIS manuell, automatisiert vom System gesteuert oder automatisiert über entfernte Aufrufe verwenden lässt. Eine Übersicht ist in Abschnitt 4.1 zu finden.

Für die exportierten bzw. zu importierenden Daten unterstützt der BIS verschiedene Dateitypen. Die Struktur der Daten wird durch das BIS-Datenmodell des entsprechenden Business Entitys vorgegeben. Das BIS-Datenmodell und die Dateitypen sind in den Abschnitten 5 und 6 beschrieben. Die Funktionsweise von Exporten und Importen ist in Abschnitt 7 beschrieben.

Mit Hilfe von XSLT können die Daten Innerhalb des BIS in ein anderes Format transformiert werden, damit externe Programme nicht mehr auf das das Datenformat der BIS-Controller angewiesen. Im Exportvorgang können die Daten aus dem BIS-Datenformat, das durch den Exportcontroller erzeugt wird, in ein anderes Format umgewandelt werden. Die Umwandlung wird durch die angegebene XSLT-Datei bestimmt. Beim Import werden die Daten als erstes vom externen Format in das BIS-Datenformat umgewandelt, bevor sie an den Importcontroller weitergegeben werden.

Beim Import durchlaufen die zu importierenden Daten dieselben Prüfungen, die beim manuellen Erfassen der Daten angewendet werden. Damit ist sichergestellt, dass inkonsistente Daten nicht importiert werden können. Optional besteht bei Importfehlern für viele Fälle die Möglichkeit, die fehlerhaften Daten in den ebenfalls für das manuelle Erfassen verwendeten Anwendungen zu korrigieren und danach zu speichern.

Mithilfe einer Protokollierung wird ermöglicht, durchgeführte Importe oder Exporte im System aufzurufen, um sich das Ergebnis oder Details zu dem Vorgang anzusehen. Die Protokollierung ist ab Release 4.4 verfügbar. Die Beschreibung finden Sie in Abschnitt 7.1.1.

In einer Adaptierung lässt sich der BIS für spezielle Anforderungen in bestimmten Business Entitys anpassen, und auch für adaptierte Business Entitys verwenden.

BIS über verschiedene Kanäle

Import- und Exportvorgänge können über verschiedene Kanäle stattfinden. Dabei wird unterschieden, wie ein Vorgang gestartet wird.

Im Folgenden sind die vom BIS angebotenen Möglichkeiten dargestellt:

Vorgang	Export	Import
Manuell	Anwendung „Daten exportieren“	Anwendung „Daten importieren“
Automatisiert von Comarch ERP Enterprise gesteuert	Export bei Workflow-Aktivität	Import bei Workflow-Aktivität
	Export im Hintergrund als zeitgesteuerte Serie (erfasst in der Anwendung „Daten exportieren“)	Import im Hintergrund als zeitgesteuerte Serie (erfasst in der Anwendung „Daten importieren“)
		Verarbeitungsauftrag auf Basis der Hintergrund-Anwendung „Automatischer Datenimport“ (erfasst in der Anwendung „Daten automatisch importieren“)
	Belegdokument-Ausgabe mit Exporteinstellungen (siehe Dokumentation „Belegdokument-Vorlagen“)
Automatisiert als entfernter Aufruf	CORBA	CORBA
	SOAP	SOAP
	Entfernte Suche (CORBA und SOAP)

5                     Das BIS-Datenmodell

Ein Import- oder Exportvorgang über den BIS findet immer für ein bestimmtes Business Entity statt. Für jedes Business Entity gibt sein BIS-Datenmodell an, welche Daten des Business Entitys importiert bzw. exportiert werden können und in welchem Format diese Daten in den Quell- bzw. Ziel-Dateien vorliegen.

Hinweis:
Beachten Sie, dass sich das BIS-Datenmodell eines Business Entitys von den zugehörigen Entwicklungsobjekten (Business Objects, Parts) unterscheiden kann.

Für besondere Zwecke sind auch Importvorgänge möglich, für die ein Part anstatt eines Business Entitys verwendet wird. Jeder Part, der in dieser Weise für einen Import verwendet werden kann, ist dafür im Anwendungs-Code registriert. Was ein Import für einen Part bewirkt, ist ebenfalls durch den Anwendungs-Code festgelegt.

5.1               Attribute und Beziehungen

Das BIS-Datenmodell enthält die Business Objects und deren Attribute, die für einen Import-/Exportvorgang des Business Entitys zur Verfügung stehen. Das BIS-Datenmodell können Sie sich in den Anwendungen „Daten importieren“ und „Daten exportieren“, jeweils auf dem Karteireiter „Filter“, anzeigen lassen.

Das oberste Element im BIS-Datenmodell ist jeweils das Hauptobjekt des Business Entitys. Insgesamt enthält das BIS-Datenmodell folgende Bestandteile:

• Einfache Attribute stehen für einen einzelnen Wert, der importiert bzw. exportiert werden kann. Im Filterbaum sind einfache Attribute mit einer Checkbox dargestellt.
• Komplexe Attribute (Parts) enthalten selbst weitere Elemente. Sie sind mit den enthaltenen Attributen Teil des Business Objects, in dem Sie aufgeführt sind. Dargestellt sind sie mit einem Ordnersymbol. Ihr Name ist per Konvention im ersten Buchstaben klein geschrieben.
• Beziehungen zu abhängigen Business Objects (Dependents).

Dependents sind Teil des Business Entitys. Die exportierten Dependents können zusammen mit dem Business Entity importiert werden.

Dependents werden nicht kursiv und per Konvention im ersten Buchstaben groß geschrieben.

• Beziehungen zu unabhängigen Business Objects (Nicht-Dependents).

Diese Business Objects sind nicht Teil des Business Entitys. Ihre Daten können zusammen mit dem Business Entity exportiert werden. Beim Import werden sie jedoch nur verwendet, um Fremdschlüssel angeben zu können. Die dabei referenzierten Objektinstanzen müssen auf der Datenbank bereits existieren.

Nicht-Dependents werden kursiv und per Konvention im ersten Buchstaben groß geschrieben.

Komplexe Attribute und Beziehungen enthalten selbst Attribute und weitere Beziehungen. Im Filterbaum werden sie mit Ordnersymbolen dargestellt.

Beziehungen können Einfach- oder Mehrfachbeziehungen sein. Bei einer Mehrfachbeziehung kann die Business-Object-Instanz (Quelle der Beziehung) mit beliebig vielen Instanzen (Ziel der Beziehung) verknüpft sein. Im Filterbaum werden Einfachbeziehungen als „1..1“ und Mehrfachbeziehungen mit „1..n“ gekennzeichnet.

Die Bedeutung der Elemente des BIS-Datenmodells für ein bestimmtes Business Entity finden Sie in der Dokumentation zu den Vorgehensweisen für den Datenaustausch des jeweiligen Business Entitys. Einige häufig vorkommende Bestandteile der BIS-Datenmodelle sind auch in Kapitel 10 beschrieben.

5.2               Technische und betriebswirtschaftliche Fremdschlüssel

Fremdschlüssel stellen die Verbindung zwischen Objekten verschiedener Business Entitys her. Der BIS unterstützt im Datenmodell sowohl technische als auch betriebswirtschaftliche Fremdschlüssel:

• Beim Datenaustausch mit Fremdsystemen wird man im Allgemeinen mit betriebswirtschaftlichen Fremdschlüsseln arbeiten, da die technischen Fremdschlüssel nur innerhalb des Systems von Bedeutung sind.
• Beim Datenaustausch zwischen Systemen kann erwünscht sein, dass die technischen Schlüssel erhalten bleiben. In dem Fall sollten Sie diese Schlüssel mit in den Datenaustausch übernehmen.

Fremdschlüssel sind im BIS-Datenmodell im Allgemeinen wie folgt enthalten:

• Technischer Schlüssel ist normalerweise die GUID des Ziel-Objekts, dafür ist im Quellobjekt ein Attribut des Typs GUID enthalten.
• Betriebswirtschaftlicher Schlüssel ist der Business Key, und damit ein oder mehrere Attribute des Ziel-Objekts. Die Beziehung ist immer eine Nicht-Dependent-Beziehung. Sie heißt per Konvention so wie das Quellattribut, aber mit groß geschriebenem ersten Buchstaben.
  Enthält ein Business Key selbst Fremdschlüssel, dann müssen sie wiederum zu den jeweiligen Business Keys aufgelöst werden, um die betriebswirtschaftlichen Schlüssel zu erhalten. Dies ist beispielsweise bei den Identifikationen von Belegen der Fall, die aus Auftragsart und Auftragsnummer bestehen. Im technischen Schlüssel des Auftrages ist die GUID der Auftragsart enthalten. Im betriebswirtschaftlichen Schlüssel muss die zugehörige Identifikation der Auftragsart verwendet werden.

Hinweis:
Beachten Sie den Abschnitt 5.5. Beim Export mit Controllern können alle Daten mit ihren betriebswirtschaftlichen Schlüsseln (Business Keys) exportiert und somit auch in andere Systeme importiert werden. Beim generischen Export können zum Teil nur technische Schlüssel (GUIDs) exportiert werden.

5.3               Mehrsprachigkeit im Datenmodell

5.3.1          Mehrsprachige Attribute

Mehrsprachige Attribute sind Attribute, für die Werte in verschiedenen Sprachen in der Datenbank vorhanden sind. In der Ansicht des BIS-Datenmodells ist ein mehrsprachiges String-Attribut durch „ml“ gekennzeichnet.

Mit dem BIS können Sie mehrsprachige Attribute entweder in einer oder in allen Sprachen, die auf der Datenbank zur Verfügung stehen, exportieren bzw. importieren. Dies steuern Sie mit der Spracheinstellung des Filters, die in Abschnitt 5.4.2 erläutert ist.

5.3.2          Beziehung „Texts“

Über die Dependent-Beziehung „Texts“, die in einigen Business Entitys enthalten ist, steht der Inhalt des Karteireiters „Texte“ zur Verfügung und enthält ebenfalls mehrsprachige Texte. Diese Texte werden unabhängig von der Spracheinstellung des Filters mehrsprachig exportiert bzw. importiert.

5.4               Filter

Filter bestimmen den Umfang des BIS-Datenmodells, das für einen Datenaustausch zur Verfügung steht. Ein Filter besteht aus der Attributauswahl und der Spracheinstellung.

5.4.1          Attributauswahl

Filter enthalten eine Auswahl von Attributen aus dem BIS-Datenmodell eines Business Entitys, um nur eine bestimmte Teilmenge der Attribute eines Business Entitys zu importieren bzw. zu exportieren.

Die genaue Auswirkung der Attributauswahl auf Import- und Exportvorgänge ist in Kapitel 7 beschrieben.

5.4.2          Spracheinstellung

Die Spracheinstellung eines Filters bestimmt, wie mehrsprachige Attribute importiert bzw. exportiert werden.

• In der Einstellung „Einsprachig“ werden die mehrsprachigen Attribute in der Standardsprache der Datenbank exportiert bzw. importiert. Für Business Entitys auf der OLTP- oder OLAP-Datenbank ist dies die Inhaltssprache der jeweiligen Session, für Business Entitys auf der Repository-Datenbank ist dies die Anzeigesprache der Session. Dies entspricht dem Verhalten des BIS bis einschließlich Release 4.1. Wie die Inhalts- bzw. Anzeigesprache einer Session bestimmt wird, ist in Abschnitt 1.2 beschrieben.
• In der Einstellung „Mehrsprachig“ werden die mehrsprachigen Attribute in allen Sprachen importiert bzw. exportiert, die auf der Datenbank, aus der das mehrsprachige Attribut stammt, existieren.

5.4.3          Zeitformat

Das Zeitformat eines Filters bestimmt, wie Zeitattribute in den Dateien serialisiert werden.

• In der Einstellung „Kompakt“ ist die Serialisierung kompatibel mit dem System bis einschließlich Release 4.1.
• In der Einstellung „Normalisiert“ werden Zeitattribute in ihre Bestandteile (Datum, Uhrzeit, Zeitzone) aufgeteilt und komplex serialisiert.

Die Beschreibung der genauen Auswirkungen dieser Einstellungen finden Sie im Abschnitt „Datumsangaben und Zeitstempel“.

Für das manuelle Bearbeiten ist der Modus „Normalisiert“ besser geeignet. Für EDI sowie Altdatenübernahmen aus Fremdsystemen muss individuell entschieden werden, welcher Modus besser geeignet ist.

Beachten Sie, dass das Zeitformat für die gesamte Datei Gültigkeit hat.

5.4.4          Transformationsdatei

Die XSLT-Datei als Transformationsdatei bestimmt, wie die Daten formatiert werden sollen. Hier kann man die URI der XSLT-Datei angeben. Ist keine URI angegeben, findet der Import bzw. Export ohne Transformation statt

5.4.5          Verwendung von Filtern

Filter können Sie in den Anwendungen „Daten importieren“ und „Daten exportieren“ erfassen und bearbeiten. Wenn in den Anwendungen ein Filter geöffnet ist, sehen Sie im Karteireiter „Filter“ die ausgewählten Attribute durch einen Haken markiert. Durch Setzen und Entfernen von Haken können Sie den Filter verändern.

Zur späteren Verwendung können Filter auf der OLTP-Datenbank gespeichert werden. Sie können zu einem Business Entity beliebig viele Filter speichern.

Es ist auch möglich, Filter in eine Datei zu exportieren bzw. sie aus einer Datei zu importieren. Dies ist in der Dokumentation „Filter importieren“ beschrieben.

5.5               BIS generisch oder durch Controller

Der Import bzw. Export von Business Entitys wird durch eine generische Import- bzw. Exportfunktion oder durch spezielle Controller unterstützt. Ein Controller ist eine Java-Klasse des Anwendungs-Codes, die den Import bzw. den Export eines bestimmten Business Entitys realisiert. Sie können sich in den Anwendungen „Daten importieren“ bzw. „Daten exportieren“ anzeigen lassen, ob für ein Business Entity ein Controller verwendet wird. Informationen dazu finden Sie in den Dokumentationen „Daten importieren“ und „Daten exportieren“

Für die generischen Funktionen gelten folgende Besonderheiten:

• Mit dem generischen Export können alle Business Entitys exportiert werden.
• Mit dem generischen Import können nur Business Entitys ohne Dependents importiert werden.
• Mit dem generischen Export können zum Teil nur technische Schlüssel (GUIDs) exportiert werden. Damit ist der Import dieser Daten auf die Datenbank beschränkt, von der die Daten exportiert wurden.

6                     Quell- und Ziel-Dateien

Der Datenaustausch durch den Business Integration Service findet zwischen einer Datenbank und Dateien statt.

6.1               Datenquellen/-ziele

Der BIS unterstützt den Knowledge Store des Systems und das lokale Dateisystem des Application-Servers, um die Dateien zu lesen bzw. zu schreiben.

Pfade zu Dateien werden als URIs mit den Schemata „kstore://“ oder „file:///“ angegeben. Beachten Sie, dass für den Knowledge Store zwei Schrägstriche und für ein Dateisystem drei Schrägstriche verwendet werden.

Ab Release 4.2 wird die „GZIP“-Komprimierung unterstützt. Wird beim Import zusätzlich zur normalen Endung des Dateinamens „.gz“ angehängt, so wird die Datei als Datei im „GZIP“-Format erkannt und vor dem eigentlichen Import dekomprimiert. Beim Export werden durch das Anhängen der zusätzlichen Endung „.gz“ die exportierten Daten im „GZIP“-Format komprimiert.

Werden beim Import mehrere Dateien auf einmal importiert (verknüpfte Dateien), so können auch diese im „GZIP“-Format angegeben werden. Eine eventuell erzeugte Fehler-Datei wird nur dann komprimiert, wenn für die Fehler-Datei explizit ein Dateiname mit der Endung „.gz“ angegeben wurde. Wenn der Name der Fehler-Datei automatisch vergeben wird, so wird immer eine nicht komprimierte Fehler-Datei erzeugt. Dadurch wird insbesondere das manuelle Bearbeitern der Fehler-Datei im Falle von nicht korrigierbaren Fehlern erleichtert.

Hinweis:

Die „GZIP“-Komprimierung ist eine reine Dateikomprimierung und kein Archivformat wie beispielweise „.zip“. Insbesondere enthält eine „GZIP“-komprimierte Datei genau eine unkomprimierte Datei. Das gebräuchliche Archivformat „.zip“ kann hingegen mehrere Dateien unterschiedlichen Namens enthalten inklusive den Informationen zu ihren Ordnern. Das „.zip“-Format wird vom BIS nicht verwendet.

Hinweis:
Der Import oder Export im Dateisystem bezieht sich immer auf das Dateisystem des Application-Servers, auf dem die eigentliche (Hintergrund-)Verar­beitung läuft, und damit im Allgemeinen nicht auf den Client-Rechner, von dem aus Sie an das System angemeldet sind. Auch ist zu beachten, dass Pfade in das Dateisystems eines Application-Servers je nach Betriebssystem des jeweiligen Application-Servers unterschiedlich angegeben werden müssen.

6.2               Dateitypen

Als Dateitypen stehen „XML (*.xml)“, „Text durch Trennzeichen getrennt“ (CSV, *.csv) und „Unicode-Text durch Tabulator getrennt“ (*.xls) zur Verfügung. Nachfolgend finden Sie eine Beschreibung der Dateitypen mit ihren Besonderheiten und Einschränkungen.

6.2.1          XML

XML-Dateien bieten Vorteile durch ihre Standardisierung und ihre hohe Verbreitung. Wir empfehlen die Nutzung von XML, da beliebig komplexe Daten in einer einzigen Datei gespeichert werden können, das Schema der Datei vorgegeben und überprüft werden kann und Änderungen des Datenmodells problemlos integriert werden können.

Der Datenaustausch im Sprachmodus „Mehrsprachig“ steht nur für den Dateityp XML zur Verfügung. Beispiele für das Format der Dateien erhalten Sie, wenn Sie das gewünschte Business Entity im jeweiligen Dateityp exportieren.

Für XML können Sie sich ein zu einem Filter passendes XML-Schema erzeugen lassen. Verwenden Sie dazu die Anwendungen „Daten exportieren“ bzw. „Daten importieren“. Das erzeugte XML-Schema kann mit externen Programmen zur Validierung von XML-Dateien verwendet werden. Mit geeigneten externen Programmen ist es auch möglich, mithilfe des XML-Schemas Import-Dateien zu erzeugen. Beispiele für Dateien erhalten Sie durch den Datenexport.

Jede XML-Datei für den BIS enthält im Element „<semiramis>“ einen Dateikopf mit einigen grundlegenden Angaben. Beachten Sie für eine XML-Import-Datei, dass das XML-Attribut „locale“ entweder in der Form

locale=”en-US-XMLSchemaCompliant”

angegeben wird, oder (mit gleicher Bedeutung) weggelassen wird. Andere Angaben werden nicht unterstützt und können zu Fehlern beim Import führen.

6.2.2          Text und Unicode-Text

Der Dateityp „Text“ entspricht den von Fremdsoftware häufig verwendeten  CSV-Dateien. Mit dem Dateityp „Unicode-Text“ steht eine Unicode-fähige Variante von CSV zur Verfügung, die für die Verwendung in Microsoft Excel optimiert ist.

Bei Verwendung der Dateitypen „Text durch Trennzeichen getrennt“ und „Unicode-Text durch Tabulator getrennt“ müssen die in diesem Abschnitt beschriebenen Besonderheiten beachtet werden.

6.2.2.1      Dateiformat

Das Dateiformat der Dateitypen „Text“ und „Unicode-Text“ wird durch die verwendete Kodierung, das Trennzeichen und das Texterkennungszeichen bestimmt. Sie sind für „Unicode-Text“ festgelegt, während sie für „Text“ frei wählbar sind.

Die Besonderheiten bei der Verwendung des Trennzeichens und des Texterkennungszeichens brauchen Sie nur beim Editieren in einem Texteditor beachten. Microsoft Excel berücksichtigt sie automatisch.

• Es handelt sich um Text-Dateien, die eine bestimmte Kodierung (Zeichenkodierung) verwenden. Microsoft Excel erfordert dabei für den Dateityp „Unicode-Text“ die spezielle Kodierung „UTF16LE with BOM“ um Unicode-Zeichen auch wirklich korrekt darzustellen. Sie können diese Kodierung auch beim Dateityp „Text“ einstellen um so eine kompatibles Dateiformat erzeugen.
• Das Trennzeichen trennt einzelne Werte („Spalten“) eines Datensatzes voneinander, es sei denn, es wird in einem durch Texterkennungszeichen eingefassten Wert verwendet.
• Mit dem Texterkennungszeichen können Werte eingefasst werden, um das Trennzeichen, Texterkennungszeichen und Zeilenumbrüche (nur im Dateityp „Unicode-Text“) als Bestandteil eines Wertes zu verwenden. Enthält ein Wert diese Zeichen nicht, braucht er nicht mit Texterkennungszeichen eingefasst werden.
  Um das Texterkennungszeichen als Bestandteil eines Wertes zu verwenden, muss es doppelt angegeben sein, anderenfalls wird es nicht erkannt.

Beachten Sie für den Dateityp „Text“, dass sie jeweils die richtigen Einstellungen für die Kodierung, das Trennzeichen und das Texterkennungszeichen verwenden. Insbesondere müssen beim Import die Einstellungen der Quell-Datei entsprechen.

6.2.2.2      Eine Mehrfachbeziehung pro Objekt

Bei diesen beiden Dateitypen können die Daten zu maximal einer Mehrfachbeziehung pro Objekt in der Quell- bzw. Ziel-Datei vorhanden sein. In einer Datei besteht dann eine eigene Zeile für jedes Ziel-Objekt der Mehrfachbeziehung.

Das folgende Beispiel zeigt diesen Fall anhand einer Excel-Datei. Diese Datei wurde aus dem Business Entity „Partner“ exportiert, wobei nur die dargestellten Attribute im Filter aktiviert waren. Das Objekt „Partner“ enthält die Mehrfachbeziehung „CommunicationData“.

Für jedes Ziel-Objekt der Beziehung, also für jede Instanz von CommunicationData, ist eine eigene Zeile enthalten, auch wenn die Instanzen zur selben Instanz von „Partner“ gehören. Alle vier dargestellten Zeilen gehören zur selben Instanz von Partner mit dem Business Key „10010“.

Für jede Instanz einer Mehrfachbeziehung wird ein Tabelleneintrag erzeugt.

Erweitert man das Beispiel um weitere Attribute aus dem Hauptobjekt, würden auch diese Attribute, wie „number“, in jeder Zeile wiederholt werden.

6.2.2.3      Mehrere parallele Mehrfachbeziehungen

Parallele Beziehungen sind Beziehungen, die vom selben Business Object ausgehen. Auch eine Mehrfachbeziehung unterhalb eines Array-Attributes mit mehr als einem Element gilt als parallele Beziehung. In jeder Datei kann maximal eine parallele Mehrfachbeziehung enthalten sein. Im Beispiel des Business Entitys „Partner“ aus dem vorigen Abschnitt bestehen neben CommunicationData noch weitere Mehrfachbeziehungen. Damit kann das Business Entity „Partner“ in einer einzigen Datei nicht vollständig enthalten sein.

Für den Export bedeutet dies, dass ein Export nur möglich ist, wenn der Filter keine parallelen Mehrfachbeziehungen enthält. Damit dürfen pro Objekt nur Attribute aus einer Mehrfachbeziehung aktiviert sein. Alle Attribute aus weiteren Mehrfachbeziehungen müssen deaktiviert sein. Anderenfalls erscheint eine Fehlermeldung. Möchten Sie für ein Business Entity mehrere parallele Mehrfachbeziehungen exportieren, dann müssen Sie dies in mehreren Exportvorgängen mit jeweils angepassten Filtern tun.

Der Import mehrerer paralleler Mehrfachbeziehungen ist in einem Importvorgang nur möglich, wenn mit verknüpften Dateien gearbeitet wird. Dabei werden in einem Vorgang mehrere Dateien für ein Business Entity importiert. Näheres über den Import verknüpfter Dateien entnehmen Sie bitte dem Abschnitt 7.2.1.

6.2.2.4      Mehrfachbeziehungen ohne Inhalt

Wie oben beschrieben, kann pro Datei höchstens eine Mehrfachbeziehung verwendet werden. Für diese Mehrfachbeziehung ist beschrieben, wie auch mehrere Ziel-Objekte angegeben werden können.

Eine Besonderheit besteht jedoch, wenn für diese Mehrfachbeziehung kein Ziel-Objekt angegeben wird, die Mehrfachbeziehung jedoch im Filter aktiviert ist. Ein Beispiel für diesen Fall ist eine Auftrag ohne Positionen, oder aber ein Partner ohne Kommunikationsverbindungen.

Trifft dies für eine Import-Datei zu, kann der Import zu Fehlern führen, ggf. auch abhängig vom Business Entity des Imports. Auftretende Fehlermeldungen zeigen ggf. keinen Bezug zu der aufgetretenen Situation.

Folgende Lösungsmöglichkeiten bestehen:

• Deaktivieren Sie die Attribute aus dem Zielobjekt vollständig, sofern die gesamte Import-Datei keine Ziel-Objekte für die Mehrfachbeziehung enthält.
• Verwenden Sie den Dateityp XML.

6.2.2.5      Bearbeiten von Dateien in Microsoft Excel

Folgendes ist bei der Bearbeitung zu beachten:

• Festlegen von Spaltenformatierungen beim Öffnen
• Zeilenumbrüche in einer Zelle
• Speichern von Dateien
• Speichern von Dateien mit Zeitattributen

Festlegen von Spaltenformatierungen beim Öffnen

Wenn beim Öffnen einer Datei des Dateityps „Text“ oder „Unicode-Text“ in Microsoft Excel einzelne Spalten nicht richtig dargestellt werden, etwa weil Excel einen Text, der nur aus Ziffern besteht, fälschlicherweise als Zahl darstellt, gehen Sie wie folgt vor:

1. Öffnen Sie Excel. Wählen Sie den Menüpunkt „Datei/Öffnen“.
   • Ein Dateiauswahl-Dialog wird angezeigt.
2. Wählen Sie die zu öffnende Datei aus.
   • Der Dialog „Textkonvertierungs-Assistent“ wird angezeigt.
3. Wählen Sie auf der ersten Seite des Dialogs die Optionen
   „Ursprünglicher Datentyp: Getrennt“ und „Import beginnen in Zeile: 1“. Wechseln Sie mit „Weiter“ auf die zweite Seite.
4. Auf der zweiten Seite lassen Sie die Option „Aufeinanderfolgende Trennzeichen als ein Zeichen behandeln“ ausgeschaltet und wählen Sie, falls nötig, das richtige Trennzeichen aus. Wechseln Sie mit „Weiter“ auf die dritte Seite.
5. Auf der dritten Seite können Sie für einzelne Spalten die Formatierung festlegen. Markieren Sie dazu die Spalte und wählen Sie in der Rubrik „Datenformat der Spalten“ das richtige Datenformat aus. Verwenden Sie das Datenformat „Text“, wenn der Inhalt der Spalte nicht als Zahl oder Datumsangabe behandelt werden sollen.
6. Wählen Sie „Fertig stellen“, um die Datei zu öffnen.

Zeilenumbrüche in einer Zelle

Zeilenumbrüche in einer Zelle können zwar mit der der Tastenkombination Alt + Return erzeugt werden, jedoch standardmäßig nicht importiert werden. Beachten Sie ggf. die Hinweise in Abschnitt 6.3.2.

Speichern von Dateien

Beim Speichern von Dateien in den Formaten Text und Unicode-Text müssen Sie ggf. eine Abfrage bestätigen, die Sie darauf hinweist, dass bestimmte Merkmale der geöffneten Datei nicht gespeichert werden können.

Speichern von Dateien mit Zeitattributen

Zeitstempel-Werte werden von Excel als Zeit-/Datumsangaben erkannt, wenn Sie nicht, wie oben beschrieben, im Textkonvertierungsassistent ein abweichendes Datenformat angegeben haben.

Beim Speichern der Datei kann es vorkommen, dass der Zeitstempel nicht im vom System beim Import erwarteten und in diesem Dokument dokumentierten Serialisierungsformat für Zeitstempel geschrieben wird. Dies kann ggf. auch von verwendeten Zellenformaten abhängig sein. Wählen Sie im Textkonvertierungsassistenten das Datenformat „Text“ aus, um das Problem zu beheben.

In Dateien im Zeitformat „Normalisiert“ wird die Spalte „date“ beim Öffnen in Excel in eine landessprachliche Schreibweise umgewandelt. Um dies zu vermeiden, können Sie entweder wie oben beschrieben verfahren, oder nach dem Öffnen in Excel die Spalten mit einem benutzerdefinierten Datenformat „YYYY-MM-DD“ formatieren.

6.3               Serialisierungsformat der Datentypen

6.3.1          Übersicht

Um Attributwerte in den Dateien anzugeben, wird in Abhängigkeit des Attribut-Datentyps eine bestimmte Serialisierung verwendet. Zur Übersicht sind die Datentypen mit ihren Serialisierungsformaten in folgender Tabelle dargestellt.

Zusätzlich ist angegeben, ob ein Leer-Wert für den Datentyp ein gültiger Wert ist. Erläuterungen zu Leer-Werten sind im Abschnitt 6.3.6 enthalten.

Attribut-Datentyp	Anzeige im Filter	Format
String	str	Zeichenkette mit angegebener Maximallänge. Besonderheiten bzgl. der Behandlung von Zeilenumbrüchen und mehrsprachigen Attributen sind in den folgenden Abschnitten ausgeführt. Der Leer-Wert ist ein gültiger Wert und entspricht der leeren Zeichenkette.
Valueset	vset	Konstantenname des Valueset-Eintrags. Für Valuesets ist zusätzlich der Leer-Wert ein gültiger Wert. Er entspricht der Valueset-ID „0“.
boolean	bool	„true“, „false“
byte, short, int, long	byte, short, int, long	Zahl in Dezimaldarstellung, s.u.
Dezimalzahl	dec	Zahl in Dezimaldarstellung, s.u.
Zeit/Datum	Date, TimeStamp	Datumsangabe mit Genauigkeit 1 Tag (Anzeige „Date“), oder Zeitstempel mit der Genauigkeit  1 Millisekunde (Anzeige „TimeStamp“), jeweils in einer bestimmten Zeitzone. Die Serialisierung ist vom Zeitformat des Filters abhängig und wird in einem folgenden Abschnitt ausführlich erläutert.
GUID	guid	GUID-String, Hexadezimalziffern als Großbuchstaben. Der Leer-Wert und „xsi:nil“ beim Dateityp XML sind gültige Werte und entsprechen dem Wert „null“ für eine GUID.
BLOB	blob	Inhalt des BLOB in separater Datei; der Pfad dieser Datei ist in der Quell- bzw. Ziel-Datei enthalten.
Komplexes Attribut (Part)	(Keine)	Die im Part enthaltenen Attribute sind in XML als untergeordnete Elemente und in Text/Unicode-Text als Spalten enthalten. Hat ein Part auf der Datenbank den Wert „null“, wird es im Dateityp XML als „xsi:nil“ und im Dateityp Text/Unicode-Text als leere Spalten dargestellt.

Das Format für Zahlen, Datumsangaben und Zeitstempel ist vom Dateityp und teilweise von der Inhaltssprache des Benutzers abhängig, wie in den folgenden Abschnitten beschrieben ist.

6.3.2          Zeilenumbrüche in Strings

In Werten von String-Attributen können grundsätzlich Zeilenumbrüche vorkommen. Zeilenumbrüche sind allerdings nur in String-Attributen sinnvoll, die in der System-Oberfläche in einem mehrzeiligen Feld dargestellt werden. Wenn Werte mit Zeilenumbrüchen importiert werden, die in Dialog-Anwendungen in einem einzeiligen Textfeld dargestellt oder bearbeitet werden, so werden dabei automatisch die vorhandenen Zeilenumbrüche entfernt.

Zeilenumbrüche können mit Dateityp XML verwendet werden, nicht jedoch in den Dateitypen Unicode-Text[1] und Text.

Im Dateityp XML werden für Zeilenumbrüche teilweise Windows- als auch Unix-Zeilenumbrüche verwendet. Beim Export werden die Zeilenumbrüche abhängig vom Betriebssystem des Application-Servers umgewandelt. Der Import funktioniert unabhängig davon, welche Zeilenumbrüche verwendet werden.

Beachten Sie für das Einlesen von XML-Dateien in Fremdsoftware, dass standardkonforme XML-Parser beide Arten von Zeilenumbrüchen gleich behandeln und sie intern in Unix-Zeilenumbrüche umwandeln.

Im Dateityp Text und Unicode-Text werden Zeilenumbrüche als Leerzeichen exportiert. Beim Import werden in der Quell-Datei vorhandene Zeilenumbrüche in Leerzeichen importiert.

6.3.3          Mehrsprachige Attribute

Mehrsprachige Attribute sind immer vom Typ „String“ und werden beim Datenaustausch in Abhängigkeit von der Spracheinstellung des Filters behandelt.

In der Spracheinstellung „Einsprachig“ ist nur der Wert einer Sprache Inhalt der Datei. Die Serialisierung entspricht in diesem Fall der von Nicht-mehrsprachigen String-Attributen.

Die Spracheinstellung „Mehrsprachig“ ist nur mit dem Dateityp XML möglich. Hierbei enthält die Datei die Werte in allen Datenbanksprachen, und jeder Wert ist durch seine Sprache gekennzeichnet. Alle Werte zu einem mehrsprachigen Attribut stehen in derselben XML-Datei. Die genaue Serialisierung entnehmen Sie dem XML-Schema oder einer mehrsprachig exportierten XML-Datei.

6.3.4          Zahlen

Für den Dateityp XML werden Zahlen in den Zahlenformaten aus der XML-Schema-Spezifikation dargestellt. Gruppen- bzw. Tausendertrennzeichen werden nicht verwendet und das Dezimalzeichen für Dezimalzahlen ist der Punkt.

Für die Dateitypen Text und Unicode-Text wird ein sprachabhängiges Zahlenformat verwendet, das die Gebietsschemata des auf dem jeweiligen Application-Server installierten JDKs verwendet. Das Format hängt dabei von der Inhaltssprache der Session ab, in der der Import bzw. Export durchgeführt wird. Zahlen werden dadurch automatisch von Microsoft Excel in der jeweiligen Sprachversion erkannt. Tausendertrennzeichen und Dezimalzeichen sind von der Inhaltssprache der aktuellen Anmeldung abhängig. Beim Import ist die Verwendung des Tausendertrennzeichens optional.

Die nachfolgende Tabelle zeigt Beispiele für Zahlen:

Datentyp	XML	Text, Unicode-Text Gültig für die Sprache Deutsch.
byte, short, int, long	1000	1.000
Dezimalzahl	1000.12	1.000,12

Die einzelnen Datentypen haben folgende Wertebereiche:

Datentyp	Wertebereich
byte	-128 bis 127
short	-32768 bis 32767
int	-2147483648 bis 2147483647
long	-9223372036854775808 bis 9223372036854775807
Dezimalzahl	Die maximale Anzahl der gesamten Dezimalstellen und der Nachkommastellen wird am Filter angezeigt.

6.3.5          Datumsangaben und Zeitstempel

Die Serialisierung von Zeitattributen, d.h. Attributen die die Datumsangaben oder Zeitstempel darstellen, erfolgt in Abhängigkeit vom Zeitformat des Filters und dem Datentyp des Zeitattributs. Für Zeitattribute gibt es folgende Varianten:

Variante	Genauigkeit, Anzeige	Zeitzone
TimeStamp	1 Millisekunde „TimeStamp“	Kein Bezug zu einer Zeitzone.
CisObjectDate CisObjectDateUntil	1 Tag „Date“	Zeitzone existiert 1x pro Objekt für alle Attribute dieser Varianten.
CisObjectTimeStamp	1 Millisekunde „TimeStamp“
CisAttributeDate CisAttributeDateUntil	1 Tag „Date“	Eine Zeitzone ist Teil des Attributs und gilt nur für das jeweilige Attribut.
CisAttributeTimeStamp	1 Millisekunde „TimeStamp“

Zeitattribute werden ab Release 4.2 im der Anzeige des Filters als immer als einfaches Attribut angezeigt. Die Serialisierung ist jedoch Abhängigkeit von der Variante und vom Zeitformat einfach oder komplex.

Im den folgenden Abschnitten ist die Serialisierung in den beiden Zeitformaten beschrieben. Beachten Sie die Unterschiede in der Serialisierung in Bezug auf die Zeitzone, die der Serialisierung des Datums-/Zeitanteils zugrunde liegt.

Zeitformat „Kompakt“

Die Serialisierung ist, abhängig von der Variante des Zeitattributs, einfach oder komplex:

Variante	Serialisierung Beispiel eines Zeitattributs „attr“
TimeStamp	Einfache Serialisierung mit Zeitstempel-Wert. Beispiel in XML: <attr>2005-03-29T09:43:39.634Z</attr> In den Dateitypen Text und Unicode-Text gibt es eine Spalte „attr“. Bei „CisObjectDate“, „CisObjectDateUntil“ und „CisObjectTimeStamp“ ist die Zeitzone gesondert im Attribut „_timeZone“ enthalten und in Abschnitt 10.1 beschrieben.
CisObjectDate CisObjectDateUntil
CisObjectTimeStamp
CisAttributeDate CisAttributeDateUntil	Komplexe Serialisierung aus Zeitstempel-Wert und Zeitzone. Beispiel in XML: <attr> <timeStamp>2005-03-29T09:43:39.634Z</timeStamp> <timeZone>CET</timeZone> </attr> In den Dateitypen Text und Unicode-Text gibt die beidenSpalten „attr.timeStamp“ und „attr.timeZone“.
CisAttributeTimeStamp

Die Serialisierung eines Zeitstempel-Wertes ist abhängig vom Dateityp:

Für den Dateityp XML wird eine Datums- und Zeitangabe im Format ISO 8601 in der Zeitzone UTC verwendet. Die Zeitzone UTC ist durch den Buchstaben „Z“ am Ende der Datumsangabe bestimmt. Dies entspricht dem XML-Schema-Datentyp „xsd:dateTime“.

Für die Dateitypen Text und Unicode-Text werden Datum und Uhrzeit in einem sprachabhängigen Format angegeben. Das Format hängt von der Inhaltssprache der Session ab, in der der Import bzw. Export durchgeführt wird. Datumsangaben werden dadurch von Microsoft Excel in der jeweiligen Sprachversion automatisch als Zeitstempel erkannt. Die Datumsangabe beschreibt einen Zeitstempel in der Zeitzone des Application-Servers, auf dem der Export bzw. Import durchgeführt wird.

Die nachfolgende Tabelle gibt Beispiele zu den Dateitypen an, sowie die Werte der drei speziellen Zeitstempel Undefinierter (nicht angegebener), Minimaler und Maximaler Zeitstempel.

	XML	Text, Unicode-Text Gültig für die Sprache Deutsch in Deutschland.
Beispiel	2005-03-29T09:43:39.634Z	29.03.2005 11:43:39.634
Undefinierter Zeitstempel	0001-12-31T23:00:01.000Z	01.01.0002 00:00:01.000
Minimaler Zeitstempel	0001-12-31T23:00:02.000Z	01.01.0002 00:00:02.000
Maximaler Zeitstempel	4712-12-31T00:00:00.000Z	31.12.4712 01:00:00.000

Beachten Sie, dass Zeitstempel-Werte in allen Dateitypen vollständig angegeben werden müssen. Die Uhrzeit, Sekunden oder Millisekunden sind nicht optional. Zusätzlich gilt, dass ihre Serialisierung für den Dateityp XML immer in der Zeitzone UTC und für die Dateitypen Text bzw. Unicode-Text immer in Application-Server-Zeitzone erfolgt, und nicht in der Zeitzone des Zeitattributs, die im Falle der Varianten „CisObjectDate“, „CisObjectDateUntil“ und „CisObjectTimeStamp“ als Attribut „_timeZone“ bzw. im Falle der Varianten „CisAttributeDate“, „CisAttributeDateUntil“ und und „CisAttributeTimeStamp“ als Attribut „timeZone“ enthalten ist.

Zeitformat „Normalisiert“

Im Zeitformat „Normalisiert“ ist ein Zeitattribut immer mit einer Zeitzone versehen, und die Datums- und Uhrzeitangabe des Zeitattributs ist immer in dieser Zeitzone notiert.

Zeitattribute werden in diesem Zeitformat immer komplex serialisiert, d.h. die Serialisierung besteht aus mehreren Unterattributen. Die Serialisierung ist unabhängig vom Dateityp, aber abhängig von der Genauigkeit. Bei Attributen der Genauigkeit „Tag“ entfallen die Unterattribute „time“ und „dst“.

Die komplexe Serialisierung hat folgende Struktur:

Unterattribut mit Comarch-ERP-Enterprise- und XML-Schema-Datentyp	Bedeutung/Verhalten
specialValue: vset	Besonderer symbolischer Wert, Valueset (NONE, UNDEFINED_TIME_STAMP, MIN_TIME_STAMP, MAX_TIME_STAMP). Dieses Attribut hat den Wert NONE, wenn das komplexe Zeit-/Datumsattribut keinen symbolischen Wert annimmt. Anderenfalls hat dieses Attribut einen anderen Wert als NONE, und die Attribute „date“ und „time“ sind leer. Die symbolischen Werte bedeuten: UNDEFINED_TIME_STAMP: Undefinierter Zeitstempel, MIN_TIME_STAMP: Minimaler Zeitstempel, MAX_TIME_STAMP: Maximaler Zeitstempel. Import: Das Attribut ist ein Pflichtfeld und wird regulär importiert. Ein Importfehler liegt vor, falls dieses Attribut nicht zu den Attributen „date“ und „time“ passt.
date: str/xsd:date	Datum, angegeben in der Zeitzone aus dem Attribut timeZone Format: 2005-11-28, wie in ISO 8601. Import: Das Attribut ist ein Pflichtfeld. Falls „specialValue“ nicht den Wert NONE hat, muss dieses Attribut leer angegeben werden.
time: str/xsd:time	Tageszeit, angegeben in der Zeitzone aus dem Attribut timeZone, und der Sommerzeit-Einstellung aus dem Attribut dst. Format: 19:24:00, wie in ISO 8601. Nicht vorhanden bei Datumsattributen. Import: Das Attribut ist ein Pflichtfeld. Falls „specialValue“ nicht den Wert NONE hat, muss dieses Attribut leer angegeben werden.
dst: boolean/xsd:boolean	Gibt an, ob für das Attribut „time“ eine Sommerzeit-Zeitverschiebung aktiv ist. Nicht vorhanden bei Zeitattributen mit der Genauigkeit „Datum“, d.h. bei den Varianten „CisObjectDate/Until“ und „CisAttributeDate/Until“. Beim Import wird das Attribut ignoriert.
timeZone: str(10)/xsd:string	Identifikation der Zeitzone. Bei der Variante „TimeStamp“ ist dies die Kontext-Zeitzone. Bei den Varianten „CisObjectDate/-TimeStamp“ ist dies die Zeitzone des Objekts. Bei den Varianten „CisAttributeDate/-TimeStamp „ist dies die Zeitzone des komplexen Zeitattributs. Import: Optional. Vorgabewert: Bei Neuanlage durch Controller intialisiert bzw. Kontext-Zeitzone. Bei Aktualisierung der vorhandene Wert bzw. Kontext-Zeitzone. Bei der Variante „TimeStamp“ ist der Vorgabenwert immer die Kontext-Zeitzone. Er wird nur für das Parsen verwendet und nicht explizit in die Datenbank geschrieben. Beim Import der Varianten „CisObjectDate/-TimeStamp“ kann die Zeitzone durch den Import nicht geändert werden, sondern muss mit der vorhandenen bzw. vom Controller initialisierten Zeitzone übereinstimmen; anderenfalls liegt ein Importfehler vor. Beim Import der Varianten „CisAttributeDate/-TimeStamp“ kann die Zeitzone geändert werden.

Beispiele in XML:

Attribut mit Genauigkeit Tag:

<cisObjectDateField>

<specialValue>NONE</specialValue>

<date>2005-03-29</date>

<timeZone>CET</timeZone>

</cisObjectDateField>

Attribut mit Genauigkeit Millisekunde:

<cisObjectTimeStampField>

<specialValue>NONE</specialValue>

<date>2005-03-29</date>

<time>11:43:39.634</time>

<dst>true</dst>

<timeZone>CET</timeZone>

</cisObjectTimeStampField>

6.3.6          Leer-Werte beim Import

Werte, die in einer Ziel- oder Quell-Datei als leere Zeichenkette oder als eine Zeichenkette die nur Leerzeichen enthält angegeben sind, werden als Leer-Werte bezeichnet. Leer-Werte sind für einige Datentypen gültige Werte, die auch importiert werden können. Der BIS besitzt ein definiertes Verhalten, wie er mit Leer-Werten beim Import umgeht.

In den Dateitypen Text und Unicode-Text ist für einen Leer-Wert für einen Datensatz in der jeweiligen Spalte kein Wert angegeben. Im Dateityp XML ist für einen Leer-Wert das XML-Element ohne Wert angegeben.

Im Dateityp XML werden für bestimmte Datentypen die Leer-Werte zusätzlich als xsi:nil=”true” gekennzeichnet. Dies ist notwendig, um die Validierung von XML gegen ein XML-Schema zu ermöglichen. Wenn nichts Abweichendes dokumentiert ist, hat diese Angabe beim Import jedoch keine besondere Auswirkung und ist daher optional.

Aufgrund von Besonderheiten der Dateitypen Text und Unicode-Text akzeptiert (bzw. ignoriert) der BIS Leer-Werte auch dann, wenn sie keine gültigen Werte für den jeweiligen Datentyp darstellen. Beispielsweise werden Parts, die auf der Datenbank den Wert „null“ besitzen, beim Export als leere Spalten exportiert, auch wenn für diese Spalten aufgrund ihrer Datentypen Leer-Werte nicht zugelassen sind. Durch das Akzeptieren (bzw. Ignorieren) dieser Leer-Werte führen die leeren Spalten nicht zu Fehlern, wenn eine solche Datei wieder importiert wird.

In der folgenden Tabelle ist beschrieben, wie Leer-Werte für die einzelnen Datentypen beim Import behandelt werden.

Hinweis:

Für Importe mit Dateityp XML wird empfohlen, Attribute, die man gar nicht importieren möchte, auch nicht in der XML-Datei anzugeben. Das bedeutet, dass auch das XML-Element für das Attribut weglassen wird.

Attribut-Datentyp	Bedeutung und Behandlung von Leer-Werten
String	Der Leer-Wert ist ein gültiger Wert. Es wird die leere Zeichenkette importiert.
Valueset	Der Leer-Wert ist ein gültiger Wert. Es wird der Wert „0“ importiert.
boolean	Der Leer-Wert ist kein gültiger Wert und wird beim Import ignoriert.
byte, short, int, long	Der Leer-Wert ist kein gültiger Wert und wird beim Import ignoriert.
Dezimalzahl	Der Leer-Wert ist kein gültiger Wert und wird beim Import ignoriert.
Zeit/Datum	Der Leer-Wert ist kein gültiger Wert. Kompaktes Zeitformat, Varianten TimeStamp, CisObjectDate, CisObjectDateUntil, CisObjectTimeStamp: Es wird der Wert „UNDEFINED_TIME_STAMP“ importiert. Kompaktes Zeitformat, Varianten CisAttributeDate, CisAttributeDateUntil, CisAttributeTimeStamp: Für einen leeren Zeitstempel wird „UNDEFINED_TIME_STAMP“, und für eine leere Zeitzone die Zeitzone „GMT“ importiert. Normalisiertes Zeitformat: Behandlung wie in der Beschreibung oben.
GUID	Der Leer-Wert ist ein gültiger Wert. Es wird der Wert „null“ importiert.
BLOB	Der Leer-Wer ist ein gültiger Wert für den Pfad zur Datei mit den eigentlichen Inhalten. Ist keine Datei angegeben, so wird dies ignoriert. Ist eine Datei angegeben, die aber nicht existiert, führt dies beim Import zu einer Fehlermeldung.
Komplexes Attribut (Part)	Der Leer-Wert ist nur im Dateityp XML ein gültiger Wert, wenn xsi:nil=”true” angegeben wurde. In diesem Fall wird der Wert „null“  für den Part importiert. In den Dateitypen Text und Unicode-Text kann ein Part durch den Import nicht auf den Wert „null“ gesetzt werden.

Wenn in der Tabelle vermerkt ist, dass ein Leer-Wert beim Import ignoriert wird, bedeutet dies, dass bei einer Aktualisierung des jeweiligen Objektes der auf der Datenbank vorhandene Wert beibehalten wird. Bei einer Neuanlage des Objektes wird ein durch den jeweiligen Controller vorgegebener Wert verwendet.

GUID-Leerwerte in Schlüsseln

GUID-Leerwerte sind in Schlüsseln (Primary Key, Business Key, Secondary unique key) nicht zulässig. Dies kann beim Import zu Fehlern führen, wenn in einer Datei Leerwerte für eine GUID, die in einem Schlüssel enthalten ist, angegeben sind, und dieses Attribut im Importfilter aktiviert ist. Fremdschlüssel sind nicht betroffen, sofern das Attribut nicht gleichzeitig Bestandteil eines der genannten Schlüssel ist.

Wenn Sie aus einer Importdatei GUID-Werte für die genannten Schlüssel entfernen, können Sie das GUID-Attribut insgesamt entfernen (Dateityp Text oder Unicode-Text: Entfernen Sie die Spalte aus der Datei), oder das Attribut im Filter deaktivieren.

6.4               Verkürzte Schreibweise von Attributen

Attribute aus Nicht-Dependent-Beziehungen können unter bestimmten Umständen in den Dateien in zwei verschiedenen Schreibweisen geschrieben werden. Beide Schreibweisen sind in ihrer Bedeutung für die Datei identisch. Sie unterscheiden sich nur in dem Elementpfad, mit dem das Attribut in der Datei gekennzeichnet wird.

Der Elementpfad eines Attributes gibt an, über welche Elemente des Datenmodells das Attribut vom Haupt-Objekt des Business Entitys erreicht werden kann. In den Dateitypen Text und Unicode-Text steht der Elementpfad als Spaltenüberschrift in der Datei. Im Dateityp XML ergibt sich der Elementpfad durch die Kette der XML-Elemente, von der das XML-Element des Attributs vom Haupt-Objekt aus erreichbar ist.

Bei der verkürzten Schreibweise endet der Elementpfad bereits mit dem Beziehungsnamen, während bei der nicht-verkürzten Schreibweise auf die Beziehung der Attributname folgt. Das folgende Beispiel zeigt beide Schreibweisen für ein Attribut „isoCode“ aus einer Beziehung „Language“, das den Business Entity „Partner“ entnommen ist. Das Attribut isoCode habe den Wert „de“.

	XML	Text, Unicode-Text Angegeben ist die Spaltenüberschrift und ein beispielhafter Wert.
Nicht-verkürzte Schreibweise	<Language> <isoCode>de</isoCode> </Language>	Language.isoCode de
Verkürzte Schreibweise	<Language>de</Language>	Language de

Die nicht-verkürzte Schreibweise ist der Normalfall in den Dateien, die vom BIS verarbeitet werden. Unter den folgenden Voraussetzungen kann für ein Attribut alternativ die verkürzte Schreibweise verwendet werden:

• die Beziehung keine Dependent-Beziehung ist,
• die Beziehung keine Mehrfachbeziehung ist,
• das Attribut ein einfaches Attribut ist,
• in der Beziehung kein anderes Attribut und keine enthaltene Beziehung in der Datei verwendet wird (das Attribut ist das einzige verwendete Element aus der Beziehung).

Beide Schreibweisen werden wie folgt verwendet:

• Beim Export wird seit Release 4.2 ausschließlich die nicht-verkürzte Schreibweise verwendet.
• Beim Import sind grundsätzlich beide Schreibweisen zulässig.
• Ein vom System erzeugtes XML-Schema berücksichtigt seit Release 4.2 nur die nicht-verkürzte Schreibweise.

Hinweis:
Beachten Sie, dass der Export sowie die XML-Schema-Erzeugung bis einschließlich Release 4.1 immer dann die verkürzte Schreibweise verwendet hat, sofern die Voraussetzungen dafür erfüllt waren. In Abhängigkeit vom verwendeten Filter können sich das XML-Schema sowie die Ziel-Datei beim Umstieg auf Release 4.2 unterscheiden. Beachten Sie dies insbesondere bei der Weiterverarbeitung von Ziel-Dateien in Fremdsystemen.

Dateien, die bis einschließlich Release 4.1 exportiert wurden, können in Hinsicht auf verkürzte Schreibweisen selbstverständlich in Release 4.2 importiert werden.

Validierung gegen das XML-Schema

Eine Quell-Datei des Dateityps XML, die erfolgreich gegen das XML-Schema des zu verwendenden Importfilters validiert wurde, lässt sich immer auch mit dem Filter importieren.

Eine Quell-Datei, die die verkürzte Schreibweise verwendet, lässt sich zwar nicht gegen das XML-Schema validieren, jedoch importieren.

7                     Import- und Exportvorgänge

Ein Importvorgang ist das Importieren von Business-Entity-Instanzen aus einer Datei (Quell-Datei) in einer Datenbank für ein bestimmtes Business Entity. Ein Exportvorgang ist das Exportieren von Business-Objekt-Instanzen eines Business Entitys in eine Datei.

Im Folgenden sind zunächst Themen beschrieben, die den Import und den Export betreffen. Danach folgt die Funktionsweise von Import- und Exportvorgängen.

7.1               Allgemeines

7.1.1          Protokollierung

Import- und Exportvorgänge können auf Wunsch des Benutzers protokolliert werden. Bei ausgeschalteter Protokollierung wird das Protokoll nicht geschrieben und das Verhalten des BIS entspricht dem aus Release 4.3.

Jeder protokollierte Import und Export erzeugt einen Eintrag ins Protokoll. Bestandteile des Protokolls sind:

• Ergebnis bzw. Status des Export- oder Importvorgangs
• Verarbeitete Dateien (Export-Datei, Import-Datei, Fehler-Datei)
• Liste der importierten bzw. exportierten Instanzen
• Bei Importfehlern instanzbezogene Fehlermeldungen
• Durchgeführte Korrekturen für fehlerhafte Importe

Das Protokoll wird sukzessiv während des Import- oder Exportvorgangs in die Datenbank geschrieben. Damit ist es möglich, den Fortschritt eines lang laufenden Datenimports bereits während des Vorgangs zu überwachen. Nach Abschluss des Vorgangs kann das Ergebnis abgerufen werden.

Korrekturen für fehlerhafte Importe sind eigene Importvorgänge, in denen eine Fehlerdatei als Quell-Datei verwendet wird. Sofern die Korrektur mithilfe des Protokolls aufgerufen wurde, sind diese Korrektur-Importvorgänge Bestandteil desselben Protokolleintrags wie der ursprüngliche Importvorgang.

7.1.1.1      Anwendungen und Korrekturmöglichkeiten

Die Anwendung „Datenaustausch-Protokolleinträge abfragen“ bietet einen Überblick über durchgeführte Importe und Exporte. Die anzuzeigenden Protokolleinträge können auf verschiedene Weise eingegrenzt werden, darunter auch nach Meldungstexten bei fehlerhaften Importen. Als anpassbares Cockpit kann die Anwendung zudem auf Bedürfnisse der Benutzer verändert werden.

Die Anwendung „Datenaustausch-Protokolleinträge“ zeigt Details über einen Protokolleintrag an. Die Details umfassen den zuletzt für den Protokolleintrag durchgeführten Vorgang mit den darin verarbeiteten Instanzen. Bei fehlerhaft importierten Instanzen können auch die Fehlermeldungen angezeigt werden.

Fehlerhafte Importe können mithilfe des Protokolls auf verschiedenen Arten korrigiert werden. Werden Korrekturen aus den genannten Anwendungen gestartet, werden sie als Teil des Protokolleintrags protokolliert. Die Anzeige des Vorgangs in den Anwendungen „Datenaustausch-Protokolleinträge abfragen“ und „Datenaustausch-Protokolleinträge“ bezieht sich beim Vorhandensein von Korrekturen immer auf die zuletzt gestartete Korrektur.

Die Export- bzw. Import-Datei, und ggf. die letzte Fehler-Datei kann mithilfe der Anwendung „Datenaustausch-Protokolleinträge“ im Knowledge Store oder Dateisystem abgelegt werden, um sie mit externen Anwendungen bearbeiten zu können.

7.1.1.2      Status

Der Gesamt-Status eines Datenaustausch-Protokolleintrags zeigt an, wie weit der Import, Export und ggf. Korrekturen fortgeschritten sind:

• „In Bearbeitung“, „In Bearbeitung (Korrektur)“ und „In Bearbeitung (Korrekturanwendung“:
  Für den Datenaustausch-Protokolleintrag wird zurzeit ein Vorgang bearbeitet.
• „Erfolgreich“:
  Alle Instanzen wurden erfolgreich exportiert, importiert bzw. korrigiert.
• „Fehlerhaft“:
  Es sind Fehler aufgetreten. Eine Unterscheidung verschiedener Fehlerfälle ergibt sich aus dem Status des letzten Vorgangs.
• „Manuell geschlossen“:
  Kennzeichnung von Datenaustausch-Vorgängen, die auf Anweisung eines Benutzers nicht weiter bearbeitet werden sollen.

Für den letzten Vorgang gibt es folgende Status:

• „In Bearbeitung“: Der Lauf wird zurzeit bearbeitet.
• „Erfolgreich beendet“: Alle Instanzen wurden erfolgreich exportiert, importiert bzw. korrigiert.
• „Fehlerhaft beendet“: Alle Instanzen wurden bearbeitet, jedoch sind Fehler aufgetreten.
• „Abgebrochen durch Anwendung“:
  Der Lauf wurde durch einen Programmfehler abgebrochen. Möglicherweise konnten nicht alle Instanzen bearbeitet werden.
• „Abgebrochen durch Benutzer“:
  Der Lauf wurde auf Anforderung eines Benutzers vorzeitig abgebrochen.
• „Abgebrochen durch System“:
  Die Bearbeitung konnte wegen Systemausfalls nicht zu Ende geführt werden. Dieser Zustand kann erst durch einen Abgleich des Datenaustausch-Protokolls festgestellt werden.

Da bei abgebrochenen Importvorgängen die Fehlerdatei nicht vorhanden oder unvollständig sein kann, ist in diesem Fall keine Korrektur mithilfe des Datenaustausch-Protokolls möglich.

7.1.1.3      Abgleich des Protokolls

Durch die Aktion kann festgestellt werden, ob Datenaustausch-Vorgänge aufgrund eines Systemausfalls abgebrochen sind.

7.1.1.4      Einschränkungen

Da bei eingeschalteter Protokollierung auch Dateiinhalte protokolliert werden, steigt der Platzbedarf des Protokolls in der OLTP-Datenbank entsprechend. Besonders bei Verwendung von großen Dateien sollte das Protokoll regelmäßig reorganisiert werden.

Die eingeschaltete Protokollierung erhöht die Anzahl der Schreibzugriffe auf die OLTP-Datenbank, während Datenaustausch-Vorgänge ablaufen. Dies kann bei stark belasteten Datenbanken zu einer Performanceeinbuße im Vergleich zu Datenaustausch-Vorgängen bei ausgeschalteter Protokollierung führen.

Bei der Protokollierung der Dateiinhalte ist nicht als Archivierung gedacht, da auch die Dateiinhalte im Rahmen der Reorganisation gelöscht werden.

Einige Business Entitys enthalten in ihrem BIS-Datenmodell Attribute des Datentyps BLOB. Ein Beispiel ist das Business Entity „Dokumente“ (com.cisag.app.general.docman.obj.Document). Die separaten Dateien, in denen die Inhalte der BLOBs abgelegt sind, werden nicht in das BIS-Protokoll aufgenommen. Wird ein solches Attribut verwendet, ist keine Korrektur unter Verwendung des BIS-Protokolls möglich.

7.1.1.5      Reorganisation

Das Datenaustausch-Protokoll wird in der OLTP-Datenbank gespeichert. Es sollte regelmäßig reorganisiert werden. Dazu steht die Reorganisationsanwendung „Datenaustausch-Protokolleinträge reorganisieren“ zur Verfügung. Weitere Informationen finden Sie in der Dokumentation „Datenaustausch-Protokolleinträge reorganisieren“.

7.1.2          Auswirkung und Festlegung der Session-Sprachen

Die in einer einen Import oder Export ausführenden Session eingestellten Sprachen wirken sich wie folgt auf den BIS aus:

• Die Serialisierung bestimmter Datentypen in den Dateitypen Text und Unicode-Text ist von der Session-Inhaltssprache abhängig und ist in Abschnitt 3 beschrieben.
• Die Serialisierung von mehrsprachigen Attributen in der Spracheinstellung „Einsprachig“ ist von der Standardsprache der Datenbank, aus der exportiert bzw. in die importiert wird, abhängig. Es wird in diesem Fall der Wert des Attributs in der Standardsprache für den Import bzw. Export berücksichtigt. Dies betrifft alle Dateitypen.
  Die Standardsprache der Datenbank ist bei Business Entitys auf der OLTP- oder OLAP-Datenbanken die Inhaltssprache der Session, und bei Business Entitys auf der Repository-Datenbank die Anzeigesprache der Session.

Die Inhalts- und Anzeigesprache einer Session wird je nach Kanal, über den eine Session angemeldet wird, wie folgt bestimmt:

• Für Dialoganmeldungen und entfernte Anmeldungen hängen beide Sprachen von den Benutzereinstellungen ab, die zum Zeitpunkt der Anmeldung für den Benutzer gelten, für den die Session angemeldet wird. Bei Dialoganmeldungen hat der Benutzer zusätzlich die Möglichkeit, die Einstellungen innerhalb der Session zu ändern.
• Für Verarbeitungsaufträge werden beide Sprachen von der Session übernommen, aus der der Verarbeitungsauftrag erfasst wurde. Für Importe in Verarbeitungsaufträgen, die aus den Anwendungen „Daten importieren“ oder „Daten automatisch importieren“ erfasst werden, werden daher die eingestellten Sprachen aus der Dialogsession übernommen. Alternativ können Sie die Inhaltssprache für den Verarbeitungsauftrag auf dem Hintergrund-Dialog-Fenster explizit angeben.

7.2               Import

In einem Importvorgang wird jede Business-Entity-Instanz aus der Quell-Datei eingelesen, geprüft und bei erfolgreicher Prüfung in die Datenbank geschrieben. Ist für eine Business-Entity-Instanz die Prüfung nicht erfolgreich, liegt ein Importfehler für diese Instanz vor und sie wird, wie weiter unten beschrieben, in die Fehler-Datei geschrieben. Beachten Sie, dass es möglich ist, dass einige Instanzen aus einer Quell-Datei importiert werden können, während andere Instanzen aus derselben Datei Importfehler aufweisen.

7.2.1          Umfang der importierten Daten

Die Auswahl der Attribute, die aus der Quell-Datei für den Import verwendet werden, hängen sowohl von der Quell-Datei als auch vom Filter ab.

• Attribute aus der Quell-Datei werden nur dann verwendet, wenn sie im Filter aktiviert sind.
• Attribute aus der Quell-Datei, die im Filter deaktiviert sind, werden ohne eine Warnung übergangen. Dies trifft auch auf Attribute zu, die im Datenmodell des Business Entitys nicht enthalten sind.

Stellen Sie beim Import sicher, dass im Filter alle Attribute aktiviert sind, die Sie importieren möchten.

In vielen Fällen können Sie einen Import auch mit dem Standard-Import-Filter, in dem alle Attribute aktiviert sind, durchführen. Wenn Sie jedoch, wie oben beschrieben, bestimmte Attribute aus der Quell-Datei nicht importieren möchten, müssen Sie einen entsprechend angepassten Filter verwenden. Beachten Sie für die Dateitypen „Text“ und „Unicode-Text“ auch die in Abschnitt 6.2.2 beschriebenen Besonderheiten.

Ein Import ist nur möglich, wenn die Spracheinstellung und das Zeitformat zwischen dem Filter und der Datei übereinstimmen.

Für ein mehrsprachiges Attribut gilt, dass in der Spracheinstellung „Einsprachig“ der in der Datei angegebene Wert als Wert in der Session-Inhaltssprache des Importvorganges verwendet wird. Beim Import in der Spracheinstellung „Mehrsprachig“ werden mehrsprachige Attribute wie folgt importiert:

• Werte zu einer Datenbanksprache werden aus der Quell-Datei übernommen.
• Werte zu Nicht-Datenbanksprachen oder unbekannten Sprachen werden ohne Warnung übergangen.

7.2.2          Importmodi

Standardmäßig wird beim Import ein Objekt neu erzeugt oder aktualisiert (Standard-Importmodus). Mit dem Dateityp XML stehen jedoch auch andere Importmodi zur Verfügung, die festlegen, was mit dem zu importierenden Objekt beim Import geschieht. Bei den Dateitypen Text und Unicode-Text steht nur der Standardmodus zur Verfügung.

Es gibt folgende Importmodi. In der Regel unterstützen die importierbaren Business Entitys alle Modi. Ausnahmen sind in den einzelnen Dokumentationen zum Importieren der jeweiligen Business Entitys beschrieben.

Modus	Bedeutung	mode=
Standardmodus	Neuerstellung oder Aktualisierung des Objekts.
Nur Neuerstellung	Das Objekt wird auf der Datenbank neu erzeugt. Falls es schon vorhanden ist, ergibt sich ein Importfehler.	create
Nur Aktualisierung	Das Objekt wird auf der Datenbank aktualisiert. Falls es nicht vorhanden ist, gibt es einen Importfehler.	update
Prüfen	Es werden nur die Prüfungen durchgeführt, das Objekt wird aber nicht in die Datenbank geschrieben. Falls die Prüfungen Fehler ergeben, wird das Objekt mit den Fehlermeldungen in der Fehler-Datei protokolliert.	validate
Löschen	Das Objekt wird gelöscht oder ein Löschkennzeichen wird gesetzt (in Abhängigkeit vom Controller). Für diesen Modus reicht es im Allgemeinen, wenn die Schlüsselattribute in der Quell-Datei enthalten sind.	delete

Der Importmodus wird in der Import-Datei als XML-Attribut „mode“ angegeben. Die Angabe erfolgt am XML-Element für das Hauptobjekt oder an einem Dependent. Beispiel für das Löschmarkieren eines Artikels:

<Item mode=“delete“>

<number>…..</number>

……

Das XML-Attribut muss, wenn gewünscht, an jedem Objekt in der Import-Datei angegeben werden. Somit lässt sich der Importmodus auch je nach Objekt verschieden setzen.

Um den Standardmodus zu verwenden, lassen Sie das XML-Attribut „mode“ weg oder setzen seinen Wert auf einen Leerstring.

7.2.3          Import verknüpfter Dateien

Bei Verwendung der Formate „Text durch Trennzeichen getrennt“ und „Unicode-Text durch Tabulator getrennt“ können Sie weitere Dateien zusammen mit der Haupt-Quell-Datei importieren.

Aus der verknüpften Datei werden die Daten für ein bestimmtes Objekt und evtl. vorhandener untergeordneter Objekte importiert. In folgenden Fällen können verknüpfte Dateien verwendet werden:

• Das Objekt ist Ziel-Objekt einer Mehrfachbeziehung vom Hauptobjekt des Business Entitys.
• Das Objekt ist über evtl. mehrere Einfachbeziehungen und zuletzt einer Mehrfachbeziehung vom Hauptobjekt des Business Entitys aus erreichbar.

Hingegen können in folgenden Fällen keine verknüpften Dateien verwendet werden:

• für Ziel-Objekte von Einfachbeziehungen,
• für Ziel-Objekte von Mehrfachbeziehungen, deren Quellobjekt bereits aus einer verknüpften Datei importiert wird,
• für das Hauptobjekt des Business Entitys.

Der Objektpfad für eine verknüpfte Datei gibt die Beziehungen an, über die das oberste Objekt in der verknüpften Datei vom Hauptobjekt des Business Entitys erreichbar ist. Beispiel für das Business Entity „Partner“:

• „CommunicationData“ für das Ziel-Objekt der Beziehung
  CommunicationData,
• „Employee.PartnerRelations“: Über die Einfachbeziehung „Employee“ ist die Mehrfachbeziehung „PartnerRelations“ erreichbar; dessen Ziel-Objekt wird hier für die Verknüpfung verwendet.

Beachten Sie, dass jeder angebotene Objektpfad in einem Importvorgang nur für eine verknüpfte Datei verwendet werden kann.

7.2.4          Automatische Umwandlung in XML

Bei Verwendung der Dateitypen „Text“ und „Unicode-Text“ wird die Quell-Datei zusammen mit evtl. verknüpft importierten weiteren Quell-Dateien zu Beginn des Importvorgangs in eine einzige Datei des Typs „XML“ umgewandelt. Diese umgewandelte Datei wird in dem Ordner erzeugt, in dem sich die Quell-Datei bzw. die Haupt-Quell-Datei befindet. Der Name dieser neuen Datei ergibt sich aus dem Namen der Quell-Datei, indem die Dateierweiterung der Quell-Datei durch „.converted.xml” ersetzt wird.

Die Quell-Datei und die umgewandelte Datei bleiben nach dem Importvorgang erhalten. Anhand der umgewandelten Datei können Sie erkennen, ob bei einem Importvorgang mit verknüpften Dateien alle Attribute richtig übernommen wurden. Wenn Sie den Importvorgang wiederholen möchten, können Sie dies dann auch wahlweise mit den ursprünglichen oder mit der konvertierten Datei tun.

7.2.5          Leistungsaspekte

Beim Import von Dateien des Dateityps „Text“ bzw. „Unicode-Text“ wird immer zuerst die im Abschnitt 7.2.4 beschriebene Umwandlung in eine „XML-„Datei durchgeführt. Daher sollte wenn immer möglich direkt eine „XML“-Datei als Quell-Datei verwendet werden, da in diesem Fall die Zeit für die zusätzliche Umwandlung entfällt.

Wenn die Daten zu einem Business Entity in Form von mehreren „Text“ oder „Unicode-Text“-Dateien vorliegen, sollten Sie in jedem Fall die Möglichkeit der Verknüpfung von Dateien nutzen und die Dateien nicht einzeln nacheinander importieren. Dadurch reduzieren Sie die Zahl der Datenbankzugriffe deutlich und sparen Zeit ein.

7.2.6          Benachrichtigung bei erfolgtem Import

Sie können Sich über den Erfolg oder Misserfolg von Importvorgängen durch das Workflow-Management benachrichtigen lassen. Sie können dabei selbst festlegen, wann und wie die Benachrichtigung erfolgen soll.

Es ist beispielsweise möglich, nach jedem erfolgten Datenimport eine Workflow-Aufgabe für den Benutzer zu erzeugen, der den Datenimport durchgeführt hat. Diese Workflow-Aufgabe erscheint im Navigationsbereich (Karteireiter „Aufgaben suchen“).

Aus einer Workflow-Aufgabe, die der Benutzer über einen erfolgten Datenimport erhält, lässt sich eine Anwendung im System öffnen, die Details über den Importvorgang anzeigt, und ggf. eine Korrektur aufzurufen. Für Importe ohne Protokollierung kann hierfür die Anwendung „Datenimporte“ verwendet werden; für Importe mit Protokollierung sollte dagegen die Anwendung „Datenaustausch-Protokolleinträge“ verwendet werden. Hierzu muss die zu verwendende Anwendung in die Aktivitätsdefinition als zu öffnende Anwendung eingetragen werden.

Voraussetzung für die Benachrichtigung ist, dass eine Aktivitätsdefinition für das Workflow-Management erfasst und aktiviert ist, die auf das Workflow-Ereignis „com.cisag.pgm.bi.ImportRunCompleted“ reagiert. Weitere Informationen finden Sie in der Dokumentation „Datenaustausch-Programmier­schnittstellen“ sowie in der Dokumentation zum Workflow-Management.

7.2.7          Behandlung von Fehlern beim Import

7.2.7.1      Fehler-Datei und Protokollierung

Business-Object-Instanzen, die in einem Importvorgang nicht erfolgreich geprüft werden konnten, werden in eine Fehler-Datei gespeichert. Die Fehler-Datei liegt im Dateityp  XML vor  und hat dasselbe Format wie eine für das Business Entity passende XML-Quell-Datei.

Zusätzlich werden die Fehlermeldungen, die bei der Prüfung entstanden sind, in die Fehler-Datei geschrieben. Sie erscheinen direkt unterhalb vom XML-Element der fehlerhaften Business-Entity-Instanz, wodurch auch bei einem Import mehrerer Instanzen die Zuordnung zwischen Fehlermeldungen und fehlerhafter Instanz gewährleistet wird.

Ist die Protokollierung aktiviert, wird im Protokoll eine Liste der verarbeiteten  Instanzen vermerkt. Bei fehlerhaften Instanzen werden auch die Fehlermeldungen gespeichert. Die Fehlerdatei wird ebenfalls im Protokoll gespeichert, und kann bei Bedarf im Knowledge Store oder ins Dateisystem abgelegt werden.

Ist die Protokollierung nicht aktiv, wird die Fehlerdatei als Datei im Knowledge Store oder ins Dateisystem abgelegt. Als Vorgabe wird für den Namen der Fehler-Datei der Name der Quell-Datei verwendet und die Endung durch „.error.xml“ ersetzt. Wurde die Quell-Datei in XML umgewandelt, endet die Fehler-Datei auf „.converted.error.xml“.

7.2.7.2      Abgebrochene Importvorgänge

In bestimmten Fällen, wie z.B. syntaktischen Fehlern in der Importdatei, bricht der Import ab. Hierbei ist nicht sichergestellt, dass alle Instanzen verarbeitet werden konnten.

Bei abgebrochenen Importvorgängen ist es möglich, dass keine Fehlerdatei, oder eine unvollständige Fehlerdatei entsteht. Eine unvollständige Fehlerdatei lässt sich möglicherweise nicht wieder importierten. Eine Fehleranalyse muss dann anhand der Fehler- und Import-Datei erfolgen, und ggf. anhand des Protokolls.

7.2.8          Korrigieren von Importfehlern

Folgende Möglichkeiten zur Korrektur von Importfehlern werden angeboten.

7.2.8.1      Korrigieren in der Korrektur-Anwendung

Das Korrigieren fehlerhafter Daten wird in dafür vorgesehenen Anwendungen (Korrektur-Anwendungen) angeboten. Typischerweise handelt es sich dabei um die jeweilige Dialog-Anwendung des Business Entitys. Anwendungen, die für die Fehlerkorrektur zur Verfügung stehen, sind gesondert für diesen Zweck registriert.

Das Korrigieren in einer Korrektur-Anwendung steht in den folgenden Fällen zur Verfügung:

• Der Importvorgang wurde, gleich aus welcher Anwendung, mit aktivierter Protokollierung gestartet.
• Der Importvorgang wird aus der Anwendung „Daten importieren“ mit der Einstellung „Korrigieren: Mit Korrektur-Anwendung“ und im Modus „Sofort“ gestartet.
• Der Importvorgang wird aus der Anwendung „Daten importieren“, mit der Hintergrund-Anwendung „Daten im Hintergrund importieren“ oder über den entfernten BIS, jeweils mit der Einstellung „Korrigieren: Mit Workflow“, gestartet und die Benachrichtigung durch den Workflow ist aktiv.
• Der Importvorgang wird aus der Anwendung „Daten automatisch importieren“ gestartet und die Benachrichtigung durch den Workflow ist aktiv.

Hinweis:
Falls bei einem Import Fehler aufgetreten sind, die so schwerwiegend sind, dass sie nicht in einer Korrektur-Anwendung behoben werden können, oder der Import abgebrochen ist, ist die Korrektur in der Korrekturanwendung nicht möglich.

Hinweise zur Bedienung von Korrektur-Anwendungen finden Sie in Abschnitt 9.

7.2.8.2      Korrektur in der Fehlerdatei

Anstelle der Korrektur in der Korrektur-Anwendung haben Sie immer die Möglichkeit, die Fehler-Datei manuell zu korrigieren. Nach erfolgter Korrektur können Sie die Fehler-Datei einfach anstatt der Quell-Datei erneut importieren.

• Bei eingeschalteter Protokollierung ist der Import einer vom Benutzer korrigierten Fehlerdatei mit den Anwendungen „Datenaustausch-Cockpit“ und „Datenaustausch-Vorgänge“ möglich. Import-Einstellungen werden automatisch vorgenommen.
• Ohne Protokollierung verwenden Sie die Anwendung „Daten importieren“ und wählen die korrigierte Fehlerdatei als Importdatei aus.

7.2.8.3      Korrektur abhängiger Daten

Manche Fehler haben ihre Ursache nicht in den Importdaten, sondern es müssen bestimmte Daten im System erfasst oder geändert werden, bevor die zu importierenden Daten erfolgreich importiert werden können.

• Bei eingeschalteter Protokollierung ist der Import der Fehlerdatei mit den Anwendungen „Datenaustausch-Cockpit“ und „Datenaustausch-Vorgänge“ möglich. Import-Einstellungen werden automatisch vorgenommen.
• Ohne Protokollierung verwenden Sie die Anwendung „Daten importieren“ und wählen die Fehlerdatei als Importdatei aus.

7.2.9          Verwendung von Filtern beim Import

In einem Import, der aus der Anwendung „Daten importieren“ gestartet wird, ist es möglich, einen bereits gespeicherten Filter, oder einen neu erfassten, nicht gespeicherten Filter zu verwenden.

In Korrekturen in einer Korrekturanwendung, und Korrekturen, die aus den Anwendungen „Datenaustausch-Protokolleinträge abfragen“, „Datenaustausch-Protokolleinträge“ aufgerufen werden, gilt folgendes für die Verwendung des Filters bei der Korrektur:

• Wird ein bereits existierender Filter unverändert verwendet, d.h. die Anwendung „Daten importieren“ ist im Anzeige-Modus, wird der Filter für den Import und jede Korrektur erneut von der Datenbank geladen. Eine nachträgliche Änderung am Filter wirkt sich also ggf. auf nachfolgende Korrekturen aus.
  Für automatisierte Importe, gleich auf welche Weise sie gestartet werden, gilt dies ebenfalls.
• Wird ein neu erfasster, noch nicht gespeicherter Filter verwendet, oder ist der geöffnete Filter verändert, aber nicht gespeichert worden, ist die Anwendung im Modus „Neu“ oder „Bearbeiten“. In diesem Fall wird dem Importvorgang eine Kopie des in der Anwendung angezeigten Zustandes des Filters übergeben. Nachträgliche Änderungen am Filter wirken sich auf Korrekturen daher nicht aus.

Automatisierte Importe sollten immer einen gesonderten Filter verwenden, um unbeabsichtigte Änderungen zu vermeiden. Bei automatisierten Importen wird der Filter auch für jeden Importvorgang erneut von der Datenbank gelesen.

7.2.10       Weitere Möglichkeiten beim Importvorgang

Speziell um Importe von großen Datenmengen und Tests von Importszenarien besser handhabbar zu machen, stehen folgende Funktionen zur Verfügung.

Hinweis:
Die in diesem Abschnitt vorgestellten Einstellungen gelten pro ERP-System-Application-Server und damit für alle Importvorgänge, die auf dem Application-Server laufen. Daher sollten Sie diese Funktionen auf einem gesonderten Application-Server nutzen, auf dem nur ein Importvorgang läuft und auf dem keine anderen Benutzer arbeiten. Außerdem benötigen die weiteren Ausgaben zusätzlich Zeit und CPU-Ressourcen.

7.2.10.1   Ausgabe nicht berücksichtigter Attribute

Mit dem Setzen einer Debugging-Stufe für die Klasse „ImportSupport“ lässt sich ein Importvorgang genauer verfolgen. Das Setzen erfolgt mit diesem Toolshell-Befehl:

dbgcls -class:com.cisag.pgm.bi.ImportSupport

Auf der Debugging-Stufe WARNING erfolgt eine Ausgabe auf der Konsole, wenn Attribute aus einer Quell-Datei nicht berücksichtigt werden. Die Attribute werden nicht berücksichtigt, weil entweder das Attribut im Filter deaktiviert wurde oder das Attribut mit dem Namen in dem Business Entity nicht vorhanden ist. Möglicherweise ist im letzteren Fall das Attribut in der Quell-Datei falsch geschrieben.

7.2.10.2   Ausgabe des Importfortschritts

Mit einer Debugging-Stufe per

dbgcls -class:com.cisag.pgm.bi.ImportSupport
(bis Release 4.3), bzw.

dbgcls -class:com.cisag.sys.tools.bi.log.process.ImportProcessor
(ab Release 4.4)

Auf der Debugging-Stufe INFO wird für jede Business-Entity-Instanz aus der Quell-Datei vor dem Importieren eine Ausgabe auf der Konsole erzeugt. Damit können Sie den Fortschritt eines lang laufenden Imports überwachen.

7.2.10.3   Ausgabe der Import-Fehlermeldungen

Möchten Sie Fehlermeldungen und Warnungen, die beim Import auftreten, zusätzlich zur Fehlerdatei auch auf der Konsole und in den Meldungsprotokollen sehen, dann benutzen Sie dafür folgenden Toolshell-Befehl. Fehler und Warnungen werden dann mit Stacktrace ausgegeben.

dbgmsgmgr –loglevel:15 –traceLevel:15

Dies ist besonders hilfreich, wenn Meldungen aus Logikklassen von Controllern aufgrund von geschachtelten Aufrufen zwar gesendet, aber nicht korrekt berücksichtigt werden und daher der Import ohne ersichtlichen Grund nicht erfolgreich verläuft, d. h. keine Fehlermeldungen in der Fehler-Datei stehen.

7.2.11       Automatischer Import

Es gibt unterschiedliche Möglichkeiten, Daten zu bestimmten Zeitpunkten bzw. beim Eintreten bestimmter Ereignisse zu importieren. Welche davon eingesetzt werden sollten, hängt vom dem konkreten Szenario ab:

• In der Anwendung „Daten importieren“ können Sie einen Verarbeitungsauftrag erfassen, der eine Datei sofort, zu einem gegeben Zeitpunkt oder periodisch, d.h. in Form einer Serie, importiert.
• In der Anwendung „Daten automatisch importieren“ können Sie einen Verarbeitungsauftrag erfassen, der periodisch alle XML-Dateien aus einem Ordner importiert. Dies eignet sich vor allem für EDI-Szenarien, bei denen das System Daten automatisiert aus vorgelagerten Systemen erhält.
• Über Aktivitätsdefinitionen können Sie die Hintergrund-Anwendung für den Import aufrufen. Die Beschreibung ist im Dokument „Programmier-Schnittstellen für den Datenaustausch“ enthalten.

7.3               Export

7.3.1          Umfang der exportierten Daten

Durch die Eingrenzung wird festgelegt, welche Instanzen des Business Entitys exportiert werden, und in welcher Reihenfolge sie in die Export-Datei geschrieben werden. Dies geschieht durch eine OQL-Suche oder ein Dynamic-OQL-Statement.

Hinweis:

Es ist über die Eingrenzung nicht möglich, den Umfang der zu exportierenden Dependents festzulegen. Export-Controller exportieren in der Regel alle vorhandenen Dependent-Instanzen, für die im Filter Attribute aktiviert sind. Mittels eines im Dynamic-OQL-Statement angegebenen JOIN auf ein Dependent kann der Umfang der Business-Entity-Instanzen verändert werden, aber nicht der Umfang der Dependent-Instanzen.

Durch den Filter wird festgelegt, welche Attribute die Ziel-Datei für jede zu exportierende Instanz enthalten soll. Es werden immer diejenigen Attribute exportiert, die im Filter aktiviert sind.

Durch die Spracheinstellung des Filters wird festgelegt, wie mehrsprachige Attribute exportiert werden. In der Spracheinstellung „Einsprachig“ wird nur der Wert in der Standardsprache der Datenbank in der ausführenden Session exportiert. In der Spracheinstellung „Mehrsprachig“ werden die Werte in allen Datenbanksprachen exportiert.

Um die Ziel-Dateien übersichtlich zu halten und die Größe der Dateien zu begrenzen, ist es empfehlenswert, einen Filter für den Export zu erfassen und dort nur die benötigten Attribute zu aktivieren.

7.3.2          Automatischer Export

Es gibt unterschiedliche Möglichkeiten, Daten zu bestimmten Zeitpunkten bzw. beim Eintreten bestimmter Ereignisse zu exportieren. Welche davon eingesetzt werden sollten, hängt vom dem konkreten Szenario ab:

• In der Anwendung „Daten exportieren“ können Sie einen Verarbeitungsauftrag erfassen, der eine Datei sofort, zu einem gegeben Zeitpunkt oder periodisch, d.h. in Form einer Serie, exportiert. Hierbei ist zu beachten, dass die evtl. bereits bestehende Datei jedes Mal überschrieben wird.
• In der Anwendung „Belegdokument-Vorlagen“ können Sie definieren, ob und zu welchen Zeitpunkten (Bei Erst-Ausgabe, Bei Erst- und Kopie-Ausgabe) und in welchem Umfang die Daten eines Beleges, z. B. einer Rechnung), auch als XML-Datei exportiert werden sollen. Hierbei ist für die Ordner- und die Dateinamen die Verwendung von Variablen möglich und für bestehende Dateien werden automatisch neue Dateinamen vergeben. Dies eignet sich vor allem für EDI-Szenarien, bei denen das System Daten automatisiert an nachgelagerte Systeme weitergibt.
• Über Aktivitätsdefinitionen können Sie die Hintergrund-Anwendung für den Export aufrufen. Die Beschreibung ist im Dokument „Programmier-Schnittstellen für den Datenaustausch“ enthalten.

8                     Berechtigungen im BIS

Über den BIS sind ein Großteil der Daten eines Systems zugreifbar. Beim Export von Daten über den BIS hat ein Benutzer ggf. Zugriff auf Datensätze, die er nach den eingestellten Berechtigungen nicht öffnen darf. Inwieweit beim Export von Daten die Berechtigungen beachtet werden, hängt vom jeweils exportierten Business Entity ab.

Daher sollten Sie bei der Administration des Systems folgende Maßnahmen treffen, um den Zugriff auf den BIS auf berechtigte Benutzer einzuschränken:

8.1               Anwendungsberechtigungen

Erlauben Sie das Öffnen der im Folgenden aufgeführten Anwendungen nur denjenigen Benutzern, die Datenimporte bzw. –exporte durchführen müssen.

Für die Verwendung des BIS aus Dialoganwendungen heraus können die folgenden Anwendungen mit Berechtigungen versehen werden:

• „Daten exportieren“ (com.cisag.sys.tools.bi.ui.ExportMaintenance)
• „Daten importieren“ (com.cisag.sys.tools.bi.ui.ImportMaintenance)
• „Daten automatisch importieren“ (com.cisag.sys.tools.bi.ui.AutomaticImportMaintenance)

Für das Ansehen des Datenaustausch-Protokolls und Starten von Korrekturen mithilfe des Datenaustausch-Protokolls:

• „Datenaustausch-Protokolleinträge abfragen“ (com.cisag.sys.tools.bi.ui.ProcessProtocolCockpit)
• „Datenaustausch-Protokolleinträge“ (com.cisag.sys.tools.bi.ui.ProcessRunMaintenance)
• „Datenaustausch-Protokolleinträge reorganisieren“ (com.cisag.sys.tools.bi.log.ProcessProtocolReorganization)

Zum Starten von Exporten und Importen  aus dem Workflow oder aus adaptierten Anwendungen heraus sind folgende Hintergrund-Anwendungen relevant:

• „Daten im Hintergrund exportieren“ (com.cisag.pgm.bi.Export)
• „Daten im Hintergrund importieren“ (com.cisag.pgm.bi.Import)

Für die Verwendung des entfernten BIS sind folgende Anwendungen relevant:

• „Daten entfernt exportieren“ (com.cisag.sys.tools.bi.log.RemoteExport)
• „Daten entfernt importieren“ (com.cisag.sys.tools.bi.log.RemoteImport)
• „Suche entfernt ausführen“ (com.cisag.sys.tools.bi.log.RemoteSearch)

8.2               Business-Entity-Berechtigungen

Diejenigen Benutzer, die Datenimporte und –exporte über den BIS durchführen, müssen Berechtigungen auf den jeweiligen zu importierenden und exportierenden Business Entitys besitzen.

Allgemeine Informationen über Berechtigungen finden Sie in der Dokumentation „Berechtigungen“.

9                     Bedienung von Korrektur-Anwendungen

Wenn bei einem Import Fehler aufgetreten sind und Sie für den Importvorgang die Einstellung Korrigieren „Mit Workflow“ oder „Mit Korrektur-Anwendung“ ausgewählt haben, können die fehlerhaften Daten im Allgemeinen direkt im System korrigiert werden. Beachten Sie jedoch, dass das Korrigieren in der Korrektur-Anwendung bei bestimmten, schweren Fehlern nicht möglich ist. Zu den Fehlerursachen für diese Fehler zählt beispielsweise eine syntaktisch ungültige Quell-Datei oder die Verwendung einer ungültigen Kodierung. In diesen Fällen muss die Quell-Datei manuell geöffnet und korrigiert werden.

Wenn die Korrektur-Anwendung geöffnet wird, dann wird die erste fehlerhafte Business-Entity-Instanz aus der Fehler-Datei angezeigt und Meldungen über fehlende bzw. fehlerhafte Angaben werden im Navigationsbereich, sowie als rote Ecken an den betreffenden Feldern angezeigt. Sie können nun die fehlerhaften Daten korrigieren und anschließend die Änderungen akzeptieren.

Für die Bedienung der Korrektur-Anwendung gibt es in der Standard-Symbolleiste folgende zusätzliche Buttons. Wenn diese verfügbar sind, sind einige der Standard-Buttons der Standard-Symbolleiste deaktiviert.

Button	Aktion
(Diesen Eintrag akzeptieren)	Wenn fehlerhafte bzw. fehlende Angaben korrigiert bzw. manuell erfasst wurden, dann wird mit Klick auf das Symbol die Business-Entity-Instanz gespeichert. Danach ist der Datensatz tatsächlich importiert. Anschließend wird der nächste Datensatz aus der Fehler-Datei geöffnet.
(Diesen Eintrag ausnehmen)	Der aktuelle Datensatz wird aus der Korrektur ausgenommen und der nächste Datensatz aus der Fehler-Datei wird geöffnet.
(Nächster Eintrag)	Wechselt zum nächsten fehlerhaften Datensatz. Die aktuelle Business-Entity-Instanz kann zu einem späteren Zeitpunkt korrigiert wird. Nach der letzten Instanz aus einer Fehler-Datei erscheint durch Auswählen dieses Buttons wieder die erste noch verfügbare Instanz.

Die Buttons wirken sich immer auf alle Daten der in der Korrektur-Anwendung geöffneten Business-Entity-Instanz aus. Beispielsweise gilt eine Aktion auf einem Vertriebsauftrag damit immer auch für alle Positionen.

Hinweis:
Eine Quell-Datei kann dieselbe Business-Entity-Instanz mehrfach enthalten, typischerweise jeweils mit anderen Änderungen, die zu importieren sind. In diesem Fall wird die Instanz während der Korrektur mehrfach geöffnet und muss entsprechend mehrfach korrigiert werden.

Wenn alle fehlerhaften Instanzen erfolgreich korrigiert wurden oder von der Korrektur ausgenommen wurden, beendet die Anwendung automatisch die Korrektur und blendet die zusätzlichen Buttons wieder aus. Die bearbeiten Instanzen werden aus der Fehler-Datei entfernt. Wenn alle fehlerhaften Instanzen bearbeitet wurden, wird die Fehler-Datei gelöscht.

Sie können die Korrektur auch selbst beenden, indem Sie die Anwendung schließen, auch wenn noch nicht alle Instanzen korrigiert oder von der Korrektur ausgenommen sind. Nach Beendigung der Korrektur werden die korrigierten und die von der Korrektur ausgenommenen Instanzen aus der Fehler-Datei entfernt. Wenn alle fehlerhaften Instanzen bearbeitet wurden, wird die Fehler-Datei gelöscht. Wenn noch fehlerhaften Instanzen in der Fehler-Datei verblieben sind und Sie die Korrektur-Anwendung über die Anwendung „Datenimporte“ geöffnet haben, können Sie über das Workflow-Ereignis bzw. die Anwendung „Datenimporte“ die Korrektur später fortsetzen.

10                Spezielle Bestandteile des BIS-Datenmodells

In diesem Kapitel sind einige häufig vorkommende Bestandteile der BIS-Datenmodelle beschrieben.

10.1          Objekt-Zeitzone

Alle Business Objects, die Datums-/Zeitattribute der Varianten „CisObjectDate“, „CisObjectDateUntil“ und „CisObjectTimeStamp“ enthalten, haben zusätzlich ein generiertes Attribut „_timeZone“ vom Typ String. Dieses Attribut ist die Identifikation der Zeitzone aller Attribute dieser Varianten aus dem Business Object.

Beim Import wird die Objekt-Zeitzone nicht mit importiert, sondern nur gegen das vorhandene Objekt geprüft. Bei durch den Import neu erzeugten Objekten wird die Objekt-Zeitzone im Allgemeinen durch den Controller aus der Organisation, die für das Objekt in der Quell-Datei angegeben ist, bestimmt. Stimmen die Zeitzone der Quell-Datei und die Objekt-Zeitzone nicht überein, wird der Import mit einer Fehlermeldung abgebrochen.

10.2          Datenbankkennung

Business Entitys enthalten das Attribut managingSystem vom Typ GUID, das beim Export die Datenbankkennung des Objekts enthält.

Beim Import kann dieses Attribut nicht verwendet werden. Importierte Objekte erhalten bei einer Neuanlage immer die Datenbankkennung der Datenbank, in die das Objekt importiert wird. Bei einer Aktualisierung eines vorhandenen Objekts durch einen Import behält das Objekt seine Datenbankkennung bei.

10.3          Hauswährung

Werte in Hauswährungen (Part „com.cisag.app.general.obj.DomesticAmount“) werden im BIS-Datenmodell durch einen Part repräsentiert, der folgende Attribute und Beziehungen besitzt:

Attributpfad	Datentyp	Fremdschlüssel- Beziehung	Bezeichnung/ Bedeutung
amount1	Dezimalzahl (21,6)		Betrag in Hauswährung 1
currency1	GUID	Currency1	Hauswährung 1
amount2	Dezimalzahl (21,6)		Betrag in Hauswährung 2
currency2	GUID	Currency2	Hauswährung 2
amount3	Dezimalzahl (21,6)		Betrag in Hauswährung 3
currency3	GUID	Currency3	Hauswährung 3
exact	Byte		Bit 0-1 = Wert von exactAmountIndex Bit 2-7 = Hauswährungskombination
exactAmountIn­dex	Byte		Gibt an, welcher Wert genau ist (d. h. nicht durch eine Währungsumrechnung entstanden ist): 1= amount1 2= amount2 3= amount3 0= Kein Wert ist genau

Die Attribute „currency1“ bis „currency3“ sind die GUIDs und die Beziehungen „Currency1“ bis „Currency3“ sind die Fremdschlüsselbeziehungen auf das Business Object „com.cisag.app.general.obj.Currency“.

Sie können die Attribute „amount1“, „amount2“, „amount3“ und „exactAmountIndex“ inklusive dessen Vorkommen im Attribut „exact“ importieren.

Hinweis:
Wenn Sie beim Import Beträge ändern, aber weder „exactAmountIndex“ noch „exact“ angeben, dann wird exactAmountIndex auf den Wert 0 gesetzt.

Die übrigen Attribute (die drei Hauswährungen und die Hauswährungskombination) werden beim Import analog zur Objekt-Zeitzone lediglich gegen das vorhandene Objekt geprüft. Stimmen sie nicht überein, dann wird der Import mit einer Fehlermeldung abgebrochen. Beachten Sie, dass diese Attribute beim Erzeugen eines Objekts durch eine betriebswirtschaftliche Logik gesetzt werden.
Das Attribut „exact“ sollte beim Import nicht verwendet werden. Verwenden Sie stattdessen „exactAmountIndex“ und „Currency1“ … „Currency3“, falls erforderlich.

Hinweis:
Aus Gründen der Abwärtskompatibilität wird bei einem Import mit der Hauswährungskombination 0 im Attribut „exact“ die vorhandene Hauswährungskombination nicht geändert.

10.4          Hauswährungs-Umrechnungszeitpunkt

Jedes Business Object, das Hauswährungen (Part „com.cisag.app.general.obj.Domestic­Amount“) enthält, umfasst zusätzlich das Attribut „_conversionDate“ vom Typ Zeitstempel. Dies ist der Umrechnungszeitpunkt für Hauswährungen, der gebraucht wird, damit Hauswährungsbeträge bei einer Änderung der Hauswährungskombination richtig umgerechnet werden können. Dieses Attribut kann regulär importiert und exportiert werden.

10.5          Termin (PointInTime)

Ein Termin (Part „com.cisag.app.general.obj.PointInTime“) ist – im Gegensatz zu einfachen Datums- und Zeitangaben – ein komplexer Datentyp, der eine Zeitspanne mit einer bestimmten Genauigkeit, z. B. „01.02.2005“ oder „KW17/2005“ abbilden kann. Die Genauigkeit, z. B. „Tag“ oder „Kalenderwoche“, ist im Attribut „accuracy“ gespeichert. Der Wert, z. B. „01.02.2005“ wird in einem normalisierten, technischen Format („01#02#2005“) im Attribut „value“ gespeichert. Ein Termin kann eine Verschiebung beinhalten. Diese ist ebenfalls in einem normalisierten, technischen Format im Attribut „offset“ gespeichert. Eine Verschiebung um einen Tag entspricht beispielsweise „+1[D]“, Der symbolische Wert im Attribut „value“ wird auf den Kalender im komplexen Attribut „calendar“ bezogen ausgewertet, um den Wert im Attribut „offset“ verschoben und der so entstehende Zeitstempel wird im Attribut „timeStamp“ gespeichert. Wenn nach Terminen gesucht wird, wird dieser Zeitstempel als repräsentativer Wert für den gesamten Termin betrachtet. Dessen Anfang ist durch einen Zeitstempel (Attribut timestamp) und dessen Länge durch eine Genauigkeit (Attribut accuracy) angegeben. Das Ende der Zeitspanne ergibt sich durch den Anfang und die Länge.

Im Termin ist zusätzlich die Benutzereingabe für den Anfangszeitpunkt enthalten. Aus ihr wird unter Berücksichtigung der Genauigkeit, des Offsets und des Kalenders der Anfangszeitpunkt berechnet. Genauigkeit und Offset ergeben sich aus der Terminart, die dem Termin zugrunde liegt.

Attributpfad	Datentyp	Fremdschlüssel- Beziehung	Bezeichnung/ Bedeutung
accuracy	Valueset		Genauigkeit des Termins. Mögliche Werte sind: TIME_STAMP (Zeitstempel) DATE (Datum) CALENDAR_WEEK (Kalenderwoche) MONTH (Monat) QUARTER (Quartal) YEAR (Jahr)
calendar	Part „Calendar“		Kalender, der der Berechnung des Anfangszeitpunktes zugrunde liegt.
value	String(30)		Wert, der den Termin im normalisierten technischen Format der OQL-Suchen in Abhängigkeit von der Genauigkeit repräsentiert (siehe unten).
offset	String(20)		Offset auf den Wert zur Errechnung des Wertes für das Attribut „timestamp“ (siehe unten).
timestamp	Zeitstempel		Zeitstempel, der den Termin bei OQL-Suchen repräsentiert.
precision		Precision	Terminart

Die Attribute accuracy, calendar, offset, timestamp und precision werden beim Import durch den Controller mit Werten initialisiert, die von der Organisation der importierten Instanz abhängen. Wenn für „calendar“ und „precision“ andere Daten angegeben werden, als in der Instanz nach der Initialisierung vorhanden sind, so werden diese Werte ignoriert

Beim Import wird der Wert des Attributes „timestamp“ aus dem beim Import angegebenen Attribut „value“ berechnet. Im Normalfall reicht für den Import die Angabe von „value“ aus. Beachten Sie dazu auch die betriebswirtschaftliche Dokumentation für den Datenaustausch des betreffenden Business Entitys.

Format für das Attribut „value“

Das Attribut kann in einem der folgenden Formate angegeben werden:

Genauigkeit	Format
Zeitstempel	dd#MM#yyyy hh#mm#ss#SSS
Datum	dd#MM#yyyy
Kalenderwoche	[$CALENDARWEEK]ww#yyyy
Monat	[$MONTH]MM#yyyy
Quartal	[$QUARTER]q#yyyy
Jahr	[$YEAR]yyyy

Die in der folgenden Tabelle aufgeführten Symbole haben dabei die entsprechende Bedeutung.

Symbol	Bedeutung
dd	Tag (01-31)
MM	Monat (01-12)
yyyy	Jahr (vierstellig)
ww	Kalenderwoche (01-53)
q	Quartal (1-4)
hh	Stunde (00-23)
mm	Minute (00-59)
ss	Sekunde (00-59)
SSS	Millisekunden (000-999)

Beispiele für value: 15#04#2005 und [$CALENDARWEEK]15#2005

Format für das Attribut „offset“

Für das Offset können relative Zeitangaben nach folgendem Muster gemacht werden:

<Vorzeichen><Zahl><Einheit>

Vorzeichen ist „+“ oder „-“. Diese Angabe kann beliebig oft wiederholt werden. (Beachten Sie die Maximallänge des Offsets.)

Einheiten-Symbol	Bedeutung
[ms]	Millisekunden
[s]	Sekunden
[m]	Minuten
[h]	Stunden
[D]	Tage
[M]	Monate
[W]	Wochen
[CW]	Kalenderwochen
[Q]	Quartale
[Y]	Jahre

Beispiele für das Offset sind:

Beispiel für Offset	Bedeutung
+2[D]	Zwei Tage später
-4[CW]+1[D]	Vier Kalenderwochen früher, 1 Tag nach Beginn der Kalenderwoche

10.6          Lagerort

In vielen Business Entitys gibt es komplexe Attribute mit der Bezeichnung „Lagerort…“, die aus zwei einfachen Attributen vom Typ String bestehen. Ein Beispiel hierfür ist das Attribut „CustomerInvoice.Details.storageArea“.

Ein solches komplexes Lagerort-Attribut kann im Allgemeinen einen Lagerort oder eine Lagerzone in einem Lagerort beschreiben. Abhängig hiervon werden die beiden enthaltenen einfachen Attribute wie folgt verwendet:

Attribut	Datentyp	Bedeutung
warehouse	str(4)	Identifikation des Lagerortes. Falls eine Lagerzone beschrieben wird, ist dieses der Lagerort, in der die Lagerzone enthalten ist.
zone	str(4)	Identifikation der Lagerzone, falls eine Lagerzone in dem Lagerort beschrieben wird. Dieses Attribut ist leer, falls nur ein Lagerort beschrieben wird.

Unabhängig davon, ob es zu dem komplexen Attribut noch eine gleichnamige Beziehung gibt, sollten Sie für den Import und Export immer das Attribut verwenden. Es enthält bereits die fachlichen Schlüssel. Über die Beziehung ist im Allgemeinen kein Import möglich.

Beachten Sie, dass Sie hierzu einen Filter gegebenenfalls manuell abändern müssen, damit das Attribut aktiviert und die Beziehung deaktiviert ist.

Beachten Sie ergänzend auch die Dokumentation für den Import des entsprechenden Business Entitys.

10.7          Einheit

In vielen Business Entitys gibt es Nicht-Dependent-Beziehungen zum Business Object „Einheit“ („com.cisag.app.general.obj.UnitOfMeasure“). Über diese Beziehungen stehen die verwendeten Einheiten mit ihrem betriebswirtschaftlichen Schlüssel zur Verfügung.

Der betriebswirtschaftliche Schlüssel einer Einheit ist der Einheitencode. Der Einheitencode wird beispielsweise in Dialoganwendungen verwendet. Um in EDI-Szenarien die Behandlung von Einheiten zu vereinfachen, werden zusätzlich Einheitenkodierungen angeboten. Einheitenkodierungen ermöglichen, für den Datenaustausch andere Identifikationen zu verwenden als den Einheitencode.

Einheitenkodierungen zu den vorhandenen Einheiten sind zu einer Kodierungsart zusammengefasst und werden in der Anwendung „Kodierungen“ erfasst. Ob und welche Kodierungsart verwendet wird, legen Sie in der Anwendung „Customizing“ in der Funktion „Basis/‌Datenaustausch“ fest. Die dort angegebene Kodierungsart hat für die gesamte OLTP-Datenbank Gültigkeit.

Einheitencodes liegen auf der Datenbank als mehrsprachiges Attribut vor, und werden vom BIS immer in der Inhaltssprache der den Import oder Export ausführenden Session verwendet. Demgegenüber sind Einheitenkodierungen nicht sprachabhängig und haben auch deshalb für EDI Vorteile.

Die Beziehung enthält folgendes Attribut als Identifikation. Dieses Attribut kann exportiert und importiert werden.

Attribut	Datentyp	Bedeutung
code	str(10)	Identifikation der Einheit. Falls Einheitenkodierungen für diese Beziehung zur Verfügung stehen, eine Kodierungsart im Customizing eingetragen ist und in dieser Kodierungsart eine Einheitenkodierung für die Einheit eingetragen ist, hat dieses Attribut den Wert dieser Einheitenkodierung. Die Einheitenkodierung ist unabhängig von der Inhaltssprache. Anderenfalls enthält dieses Attribut den Einheitencode der Einheit in der Inhaltssprache der Session, die den Import oder Export ausführt. Das Verhalten dieses Attributs ist unabhängig von der Spracheinstellung des verwendeten Filters.

Die weiteren Attribute aus dieser Beziehung sind die Attribute aus dem Business Object „com.cisag.app.general.obj.UnitOfMeasure“. Sie können bei Bedarf zusätzlich exportiert werden, haben für einen Import allerdings keine Bedeutung.

11                Weitere Dokumentation

Weitere Informationen zu speziellen Themen des BIS finden Sie in folgenden Dokumentationen:

• Die für den BIS unterstützten Business Entitys sind in der Dokumentation Export- und Import-Schnittstellen aufgeführt.
• Die manuelle Nutzung des BIS und das Bearbeiten von Filtern ist in den Dokumentation „Daten exportieren“ und „Daten importieren“ beschrieben.
• Dokumentationen für den automatisierten BIS:
• Zur Verwendung des Workflow-Managements siehe die Dokumentation zum Workflow-Management.
• Für den Import als zeitgesteuerte Serie siehe die Dokumentation „Daten importieren“ und den Bedienungsleitfaden.
• Für den periodischen Import aller Dateien in einen Ordner siehe die Dokumentation „Daten automatisch importieren“.
• Für den Export als zeitgesteuerte Serie siehe die Dokumentation „Daten exportieren“ und den Bedienungsleitfaden.
• Für den Export bei der Ausgabe von Belegdokumenten siehe Dokumentation „Belegdokument-Vorlagen“.
• Informationen über den automatisierten BIS über entfernte Aufrufe finden Sie in der Dokumentation „Entfernte BIS-Schnittstellen“.
• Informationen über die Vorgehensweise für den Import und Export bestimmter Business Entitys finden Sie in der Online-Hilfe im Ordner „Datenaustausch“.
• Informationen zu Schnittstellen, die der BIS zur Softwareentwicklung bereitstellt:
• Entwicklung von BIS-Controllern
• Nutzung des BIS im Anwendungscode und im Workflow-Management

[1]    Mit einer System-Property ist möglich, Zeilenumbrüche für den Dateityp Unicode-Text zu unterstützen. Wir empfehlen dies jedoch nicht, da Unicode-Text-Dateien mit Zeilenumbrüchen mit dem Textkonvertierungs-Assistent von MS Excel nicht vollständig kompatibel sind. Verwenden Sie die System-Property nur nach gründlicher Prüfung.

Zur Unterstützung der Zeilenumbrüche setzen Sie vor dem Start eines Application-Servers die System-Property com.cisag.sys.tools.bi.log.csv.CSVUtility.unicodeTextLinefeedSupport=true. Die System-Property gilt für alle Exporte und Importe auf den Application-Servern, auf denen die Property gesetzt ist. Zeilenumbrüche in Zellen, die in MS Excel eingegeben wurden, lassen sich hiermit importieren.