COM-Aktiv-Schnittstelle

Was ist die COM-Aktiv-Schnittstelle?

Die COM-Aktiv-Schnittstelle ermöglicht den programmatischen Zugriff auf Datenbestände sowie die Geschäftslogik der microtech Software. Über Microsoft COM (Component Object Model) können externe Anwendungen Datensätze lesen, anlegen und bearbeiten, Vorgänge erstellen und wandeln, Lagerbewegungen durchführen, Druckausgaben erzeugen und vieles mehr.

Die Schnittstelle richtet sich an Entwickler, die Integrationen, Automatisierungen oder Datenmigrationsprozesse für die microtech Software umsetzen. Sie ist aus jeder Programmiersprache nutzbar, die COM-Automatisierung unterstützt - darunter VBScript, Delphi, C#, VB.NET und VBA.

Diese Dokumentation beschreibt die Konzepte, Workflows und Interfaces der COM-Aktiv-Schnittstelle. Sie ist in folgende Bereiche gegliedert:

• Verbindung und Datenzugriff - Verbindungsaufbau, DataSets, Felder und Indizes
• Vorgänge und Wandeln - Vorgangserstellung, Positionen und Belegwandlung
• Lagerverwaltung - Ein-, Um- und Ausbuchungen, Seriennummern
• Drucken und Import/Export - Druckgenerierung, Layoutgruppen und Daten-Im/Export
• Weitere SpecialObjects - Dokumente, Banking, Offene Posten, Projekte u. a.
• mDL - microtech Data Language für Abfragen und .NET Data Provider
• Tipps, Tricks und Beispiele - Praxisbeispiele und häufige Muster
• Interface-Referenz - Vollständige IDL-Signaturen und Parametertabellen
• Aufzählungen und Datentypen - Enumerationen und Strukturen

Voraussetzungen

Lizenzierung

Zugriffe auf den Datenbestand über die COM-Aktiv-Schnittstelle sind in der jeweils aktuellen Jahresversion der microtech Software möglich. Erforderlich ist ein eingetragener COM-Aktiv Aktivierungsschlüssel für den aktuellen Jahresvertrag des Aktualitäts-Service.

Support-Unterstützung zur COM-Aktiv-Schnittstelle wird ausschließlich Solution Partnern und Entwicklern gewährt; der Support erfolgt ausschließlich schriftlich über das Service-Portal. Es besteht kein Rechtsanspruch auf Support-Unterstützung.

Die Bedingungen und Preise für den Solution Partner Vertrag erfragen Sie bei der microtech GmbH:

microtech GmbH - optionale Schnittstellen
55595 Hargesheim Mail: vertrieb@microtech.de
Fon: +49 (0)671 / 79 616-0

Haftungsausschluss

Die microtech GmbH gibt keine Garantien irgendeiner Art, weder ausdrücklich noch implizit, einschließlich aller Garantien der Verwendbarkeit dieser Schnittstelle für einen bezeichneten oder nicht bezeichneten Zweck. Unter keinen Umständen ist die microtech GmbH haftbar für jedwede Folgeschäden (einschließlich Schäden aus entgangenem Gewinn, Betriebsunterbrechung, Verlust von Informationen oder Daten oder aus anderem finanziellen Verlust), die aufgrund der Benutzung dieser Schnittstelle entstehen. Sie handeln auf eigene Gefahr.

Technische Voraussetzungen

Für die Nutzung der COM-Aktiv-Schnittstelle benötigen Sie:

• Die aktuelle Jahresversion der microtech Software
• Ein Windows-Betriebssystem auf aktuellem Stand
• Eine Entwicklungsumgebung oder einen Texteditor (z. B. Notepad, Visual Studio) mit COM-Automatisierungsfunktionen

Aktivierungsschlüssel-Logik: Damit die COM-Schnittstelle genutzt werden kann, muss ein namens- und laufzeitgebundener Aktivierungsschlüssel in den Aktivierungen hinterlegt sein. Ist dieser abgelaufen, kann das Programm mit einem vorläufigen Schlüssel des aktuellen Revisionsjahres vorläufig aktiviert werden - die COM-Schnittstelle funktioniert dann weiterhin, sofern zuvor bereits ein namensgebundener Schlüssel eingetragen war. Ein Zugriff ausschließlich mit vorläufigen Schlüsseln (ohne jemals einen namensgebundenen Schlüssel eingetragen zu haben) ist nicht möglich.

Der COM-Zugriff benötigt kein aktives Echtheitszertifikat. Das Vorhandensein eines solchen für die aktuelle Jahresversion ist jedoch ein Indiz dafür, dass ein gültiger namensgebundener Schlüssel hinterlegt ist.

Mandanteneinrichtung

Bevor eine COM-Verbindung auf einen Mandanten zugreifen kann, müssen zwei Einstellungen in der microtech Software vorgenommen werden:

1. Mandant freigeben: Unter DATEI → INFORMATIONEN → AKTUELLE FIRMA / FILIALE / MANDANT → MANDANT BEARBEITEN auf der Karteiseite „Weitere Angaben" muss die Option „COM Schnittstelle für registrierte Anwendungen verfügbar" aktiviert sein.

2. Benutzerrecht setzen: Der verwendete Benutzer benötigt das Recht, über die COM-Schnittstelle zuzugreifen. Sie finden es unter DATEI → EINSTELLUNGEN → BERECHTIGUNGSSTRUKTUREN → GLOBAL → DATEI → „Fremdanwendungen dürfen über registrierte COM-Schnittstelle auf Daten zugreifen".

Außerdem muss die verwendete Programminstallation im normalen Modus (auch nach jedem Update) mindestens einmal gestartet worden sein, sodass keine Meldungen im Zusammenhang mit der Datenwartung auftreten.

Erste Schritte

Verbindung herstellen (Init / SelectMand)

Der Einstiegspunkt in die COM-Schnittstelle ist das Objekt BpNT.Application. Es wird über die Standard-COM-Erzeugungsmechanismen instanziiert:

• VBScript: Set BpApp = WScript.CreateObject("BpNT.Application")
• Delphi: BpApp := CreateOleObject('BpNT.Application');
• C#: BpNT.Application BpApp = new BpNT.Application();

Nach der Instanziierung sind zwei Aufrufe erforderlich, bevor auf Daten zugegriffen werden kann:

1. Init - Authentifiziert die COM-Instanz gegenüber der microtech Software.
2. SelectMand - Wählt den zu verwendenden Mandanten aus.

Der Init-Aufruf erwartet vier Parameter:

BpApp.Init("Firmenname", "", "Anmeldename", "Passwort")

Der „Firmenname" entspricht dem Firmennamen, der in der microtech Software unter DATEI → HILFE → SUPPORT & HOTLINE im Bereich „Ihre Kundendaten bei microtech" angezeigt wird. Groß-/Kleinschreibung und Leerzeichen müssen exakt übereinstimmen. „Anmeldename" und „Passwort" sind die Zugangsdaten eines Benutzers mit entsprechender COM-Berechtigung.

Der zweite Parameter bleibt für die reguläre Nutzung leer. Bei einer Solution-Partner-Anbindung ändert sich der Aufruf:

BpApp.Init("Connection String", "Connection Key", "Anmeldename", "Passwort")

Connection String und Connection Key werden von der microtech GmbH bereitgestellt.

SelectMand erwartet die Mandantennummer als String:

BpApp.SelectMand("1")

Die Vorgabe ist numerisch, allerdings können Mandantennummern auch alphanumerisch sein.

Ein erstes Beispiel (VBS)

Das folgende VBScript legt einen Artikel in der microtech Software an. Kopieren Sie die Zeilen in einen Texteditor und speichern Sie die Datei mit der Endung .vbs. Per Doppelklick wird das Script ausgeführt.

Beispiel: Artikel anlegen (VBScript)

Option Explicit
Dim BpNT
Set BpNT = WScript.CreateObject("BpNT.Application")
Call BpNT.Init("Firmenname", "", "Anmeldename", "Passwort")
Call BpNT.SelectMand("Mandanten Nummer")

Dim DataSet
Set DataSet = BpNT.DataSetInfos("Artikel").CreateDataSet
DataSet.Append
DataSet.Fields("ArtNr").Text = "Meine_Artikelnummer"
DataSet.Fields("Bez1").Text  = "Meine Artikel Bezeichnung"
DataSet.Post

Set BpNT = Nothing
MsgBox("Hallo Welt, mein erstes Script ist: Fertig!")

Passen Sie die Parameter von Init und SelectMand an Ihre Umgebung an (siehe Abschnitt oben). Beachten Sie, dass das Feld ArtNr eindeutig sein muss - bei erneutem Ausführen muss ein neuer Wert vergeben werden.

Wie geht es weiter?

Um herauszufinden, welche Tabellen und Felder verfügbar sind, können Sie eine vollständige Feldliste generieren. Das entsprechende Script und eine Erläuterung finden Sie unter Verbindung und Datenzugriff - Feldliste. Weitere Praxisbeispiele und Codevorlagen stehen unter Tipps, Tricks und Beispiele bereit.

Architekturübersicht

BpNT-Bibliothek und Interface-Hierarchie

Die gesamte COM-Schnittstelle ist in der Type Library BpNT Bibliothek definiert, die in der Programmdatei BpNexT.exe eingebettet ist. Die Type Library enthält Funktionsaufrufe, Interfaces und Aufzählungstypen.

Alle COM-Objekte der microtech Software erben von IAutoBase, das zwei grundlegende Eigenschaften bereitstellt: Application (Zugriff auf das Wurzelobjekt) und Parent (Zugriff auf das übergeordnete Interface). Von IAutoBase leiten sich alle weiteren Interfaces ab.

Das zentrale Objekt ist IAutoApplication - es wird als einziges Objekt direkt über CreateOleObject bzw. CreateObject erzeugt. Alle weiteren Interfaces und Objekte werden über Methoden von IAutoApplication (und dessen Nachfolge-Interfaces IAutoApplication2 bis IAutoApplication18) erstellt. Die wichtigsten Zugangspunkte sind:

• Init / SelectMand - Authentifizierung und Mandantenauswahl
• DataSetInfos - Zugriff auf Metadaten und Erstellung von DataSets für alle Tabellen
• GetSpecialObject - Erzeugung spezialisierter Objekte (SpecialObjects) für Geschäftslogik
• OpenLayoutGroup - Zugriff auf Druck- und Import/Export-Layouts

Die Interface-Hierarchie der Application-Kette (IAutoApplication → IAutoApplication2 → … → IAutoApplication18) erweitert mit jeder Version den Funktionsumfang, ohne bestehende Methoden zu ändern. So bleibt die Abwärtskompatibilität gewahrt.

Die vollständige Interface-Referenz mit IDL-Signaturen und Parametertabellen finden Sie in der Interface-Referenz.

Type Library einsehen: Sie können die BpNT-Bibliothek mit einem Type Library Viewer inspizieren. Die BpNexT.exe im Installationsverzeichnis der microtech Software enthält die eingebettete Type Library. Alternativ können Sie den Visual-Basic-Editor in Microsoft Word verwenden: Unter Extras → Verweise aktivieren Sie den Eintrag „BpNT Bibliothek" und können dann unter Ansicht → Objektkatalog alle Interfaces und Enumeratoren durchsuchen.

SpecialObjects im Überblick

Neben dem reinen Datenzugriff über DataSets stellt die COM-Schnittstelle SpecialObjects bereit. Diese Objekte kapseln Geschäftslogik - etwa das Erstellen von Vorgängen mit automatischer Parameterabarbeitung oder das Durchführen von Lagerbuchungen. Sie werden über GetSpecialObject mit der entsprechenden Aufzählung angefordert:

Set Vorgang = BpApp.GetSpecialObject(soVorgang)

Die verfügbaren SpecialObjects sind:

Aufzählung	Wert	Objekt	Beschreibung
soLager	0	AutoLager	Lagerbearbeitung
soVorgang	1	AutoVorgang	Vorgangsbearbeitung
soDokumente	2	AutoDokument	Dokumentenverwaltung
soKontenAnalyse	3	AutoKontenAnalyse	Kontenanalyse
soAppObject	4	AutoAppObject	COM-Instanz-Eigenschaften
soWandeln	5	AutoWandeln	Belegwandlung
soDoublette	6	AutoDoublette	Doublettensuche
soEvents	7	AutoEvents	Event-Benachrichtigungen
soNachricht	8	AutoNachricht	Benutzernachrichten
soVariablen	9	AutoSpecialVariablen	Einstellungszugriff
soDrucken	10	AutoSpecialDrucken	Druckgenerierung
soBanking	11	AutoSpecialBanking	Bankverkehr
soEBilanz	13	AutoSpecialEBilanz	E-Bilanz
soOffenePosten	14	AutoSpecialOffenePosten	Offene Posten
soZahlungsverkehr	15	AutoSpecialZahlungsverkehr	Zahlungsverkehr
soAusgabeVerzeichnis	16	AutoSpecialAusgabeVerzeichnis	Ausgabeverzeichnis
soTableDefinition	17	AutoSpecialTableDefinition	Erweiterte Metainformationen
soAdrSpezPr	18	AutoSpecialAdrSpezPr	Adressspezifische Preise
soModificationMonitor	19	AutoModificationMonitor	Änderungsüberwachung
soProjekte	20	AutoSpecialProjekte	Projektverwaltung

Jedes SpecialObject wird in den jeweiligen thematischen Abschnitten dieser Dokumentation behandelt: Vorgänge und Wandeln, Lagerverwaltung, Drucken und Import/Export sowie Weitere SpecialObjects.

Support und Fehlerdiagnose

Anfragen an den Support

Im Basis-Support der microtech Software ist der Support für die COM-Aktiv-Schnittstelle nicht enthalten. Wenn Sie eine Entwicklerversion gemietet haben, können Sie sich per Support-Ticket im Service-Portal an den COM-Aktiv-Support wenden. Ein telefonischer Support wird nicht angeboten.

Bitte haben Sie Verständnis dafür, dass kein Review Ihres Programms durchgeführt wird. In vielen Fällen lässt sich die Ursache durch das Erstellen eines minimalen Beispielprogramms eingrenzen.

Bei einer Support-Anfrage sollten Sie folgende Informationen bereitstellen:

• Ihre microtech Kundennummer
• Programm-Build-Nummer
• Ausbaustufe (z. B. Gen. 24 Entersprise, genutzte Module, etc.)
• Kurze Beschreibung des Sachverhaltes
• Kurze Beschreibung der Zielsetzung (optional)
• Pseudo-Quelltext oder Script, mit dem die Problematik nachstellbar ist
• Callstack (optional)

Wenn spezielle Datenbestände zur Reproduktion benötigt werden, weisen Sie darauf hin, dass eine Datensicherung angefordert werden kann.

Häufigste Fehler

Die folgenden Fehler treten im Umgang mit der COM-Schnittstelle am häufigsten auf:

• Post ohne Edit: Ein Post wurde aufgerufen, ohne zuvor Edit oder Append auf dem DataSet ausgeführt zu haben.
• Key Violations: Key Violation. [$xxxx/xxxx] <Tabelle: Name> - Felder, die in Indizes verwendet werden, müssen in ihren Kombinationen eindeutig sein. Tragen Sie nie denselben Wert doppelt in einen Index ein.
• Fehlende Berechtigungen: Der verwendete Benutzer hat nicht das Recht, über die COM-Schnittstelle auf Daten zuzugreifen (siehe Abschnitt Mandanteneinrichtung).
• Kein endgültiger Schlüssel eingetragen: Betrifft die COM-Schnittstelle ohne Solution-Partner-Zugang. Ohne gültigen namensgebundenen Aktivierungsschlüssel ist kein Zugriff möglich.

Erweiterte Fehlerprotokollierung

Wenn Sie Fehlermeldungen erhalten und die Ursache nicht sofort ersichtlich ist, aktivieren Sie die erweiterte Fehlerprotokollierung in der microtech Software. In vielen Fällen wird dann eine detailliertere Meldung über die COM-Schnittstelle nach außen gegeben.

Nächste Schritte

Thema	Beschreibung
Verbindung und Datenzugriff	DataSets, Felder, Indizes, Ranges, Feldliste
Vorgänge und Wandeln	Vorgänge erstellen, bearbeiten, Positionen und Belegwandlung
Lagerverwaltung	Lagerein- und -ausbuchungen, Umbuchungen, Seriennummern
Drucken und Import/Export	Druckgenerierung, Layoutgruppen, Daten-Im/Export
Weitere SpecialObjects	Dokumente, Banking, Offene Posten, Projekte u. a.
mDL	microtech Data Language, Abfragen, .NET Data Provider
Tipps, Tricks und Beispiele	Praxisbeispiele, häufige Muster, Troubleshooting
Interface-Referenz	Vollständige IDL-Signaturen und Parametertabellen
Aufzählungen und Datentypen	Enumerationen und Strukturen