06-1_Anlage 1G _ Anlage 1 - VIS_6.3_VAPI-Konfiguration.pdf

[Seite 1]

VIS-VAPI

Konfiguration

Version: 6.3 Stand: 15. Dezember 2021

[Seite 2]

© Copyright by PDV GmbH Haarbergstraße 73 99097 Erfurt

Alle Rechte vorbehalten. Sämtliche Angaben vorbehaltlich technischer Änderungen. Trotz sorgfältiger Prüfung wird für den Inhalt keine Haftung übernommen. Alle aufgeführten Warennamen sind eingetragen und als solche zu behandeln.

Im Interesse der besseren Lesbarkeit des Textes wird auf geschlechterspezifische Formulierungen verzichtet. Die männliche Form wird als generisches Maskulinum und damit ausdrücklich als Sammelbezeichnung für beide Geschlechter verwendet.

Nachdruck und Vervielfältigung – auch auszugsweise – nur mit Genehmigung der PDV GmbH, Erfurt

[Seite 3]

Inhaltsverzeichnis

Inhaltsverzeichnis

Inhaltsverzeichnis ............................................................................................................ 3 1 Einleitung ................................................................................................................ 6 1.1 Begleitende Dokumente ........................................................................................ 6 2 VAPI im Überblick ................................................................................................... 7 2.1 XML als Datenaustauschformat ............................................................................ 9 2.2 Software Development Kits ................................................................................. 10 3 Die bereitgestellten Funktionen des VAPI-Webservices .................................... 13 3.1 Geschäftsobjekt-Funktionen ................................................................................ 13 3.2 Repository-Funktionen ........................................................................................ 13 4 Verbindungseinstellungen ................................................................................... 14 4.1 Proxy einstellen ................................................................................................... 14 4.2 Verbindungstimeout ............................................................................................ 14 5 VAPI-Schnittstelle ................................................................................................. 15 5.1 Stub-Generierung................................................................................................ 15 5.2 Sicherheit ............................................................................................................ 15 6 VAPI-spezifische Mandanten-Propertys.............................................................. 16 6.1 Mandanten-Property »VAPI_STORAGE_LIST_RIGHTS« ................................... 16 7 Erstes Programmierbeispiel ................................................................................ 17 7.1 VAPI-Client-Instanz erzeugen ............................................................................. 17 7.1.1 Authentifizierung gegenüber VIS ......................................................................... 17 7.1.2 Authentifizierung mit OAuth2 ............................................................................... 18 7.2 XML-Erzeugung .................................................................................................. 19 7.2.1 Übersichtliche Erzeugung ................................................................................... 20 7.3 Erstellen eines neuen Geschäftsobjekts .............................................................. 20 8 Weitere Einsatzmöglichkeiten ............................................................................. 22 8.1 Anlegen einer neuen Akte ................................................................................... 22 8.2 Erstellen eines Vorgangs .................................................................................... 22 8.3 Geschäftsobjekte suchen .................................................................................... 23 8.4 Geschäftsobjekte anhand einer Vorlage suchen ................................................. 24 8.5 Suche nach Unterablagen ................................................................................... 25 8.6 Exportieren eines Geschäftsobjekts .................................................................... 25 8.7 Geschäftsobjektteile exportieren ......................................................................... 26 8.8 Prüfen, ob ein Geschäftsobjekt abgeschlossen ist .............................................. 26

3

[Seite 4]

Inhaltsverzeichnis

8.9 Geschäftsobjektoperationen ................................................................................ 27 8.9.1 Objekte abschließen ........................................................................................... 27 8.9.2 Objekte aufschließen .......................................................................................... 28 8.9.3 Objekte archivieren ............................................................................................. 28 8.9.4 Geschäftsgangverfügung löschen ....................................................................... 28 8.9.5 Geschäftsgangverfügung bearbeiten................................................................... 29 8.9.6 Geschäftsgangverfügung erledigen ..................................................................... 29 8.9.7 Geschäftsgangverfügung abweisen .................................................................... 29 8.9.8 Geschäftsgangmuster einfügen ........................................................................... 29 8.9.9 Wiedervorlage löschen ........................................................................................ 30 8.9.10 Wiedervorlage bearbeiten ................................................................................... 30 8.9.11 Wiedervorlage erledigen ..................................................................................... 30 8.9.12 Bezug löschen .................................................................................................... 30 8.9.13 Bezug bearbeiten ................................................................................................ 31 8.9.14 Geschäftsobjekte einander zuordnen .................................................................. 31 8.9.15 Ändern der Ablage für Geschäftsobjekte ............................................................. 31 8.9.16 Geschäftsobjekt umprotokollieren ....................................................................... 32 8.9.17 Geschäftsobjekt löschen ..................................................................................... 32 8.9.18 Privates Objekt löschen....................................................................................... 32 8.10 Transfer- und Aufbewahrungsfrist ändern ........................................................... 32 8.11 Geschäftsobjekte ändern .................................................................................... 33 8.12 Import von Dateien .............................................................................................. 33 8.12.1 Übergabe innerhalb des XML .............................................................................. 34 8.12.2 Übergabe als Attachment .................................................................................... 35 9 Repository-Funktionen ......................................................................................... 37 9.1 Benutzerfunktionen ............................................................................................. 37 9.2 Abfrage der Spracheinstellung ............................................................................ 37 9.3 Auswahllisteninhalt zurückgeben ........................................................................ 38 9.4 Ablagen abfragen ................................................................................................ 38 10 Anhang .................................................................................................................. 39 10.1 EBoType ............................................................................................................. 39 10.2 Ablagen ............................................................................................................... 40 10.3 ESecurityType ..................................................................................................... 40 10.4 EBoAction ........................................................................................................... 41 10.5 EUser .................................................................................................................. 42

4

[Seite 5]

Inhaltsverzeichnis

10.6 EExportImport ..................................................................................................... 43 10.7 EBoSearch .......................................................................................................... 44 10.8 EFileAction .......................................................................................................... 45 10.9 ERights ............................................................................................................... 46 10.10 EState ................................................................................................................. 46 10.11 Sprachkonstanten ............................................................................................... 46 10.12 EVapiScheme ..................................................................................................... 47

5

[Seite 6]

Einleitung

Begleitende Dokumente

1 Einleitung

1.1 Begleitende Dokumente

Tabelle 1: Begleitende Dokumente

6

[Seite 7]

VAPI im Überblick

2 VAPI im Überblick

VAPI steht für Verwaltungs Application Programming Interface und stellt eine universelle Verwaltungs-API für die Fernsteuerung von VIS-Funktionalitäten bereit. Es handelt sich dabei um eine freigegebene Schnittstelle zur Automation und Integration. Sie kann verwendet werden, um komplexe Operationen auszuführen oder verwaltungsspezifische Fachapplikationen anzubinden. Das Abstraktionsniveau wird auf die Ebene der Anwendungsschicht gehoben, wo die geltenden VIS-Geschäftsregeln für die Einhaltung der VIS-Geschäftslogik sorgen. Somit wird sichergestellt, dass nur transaktionssichere Operationen ausgeführt werden.

7

[Seite 8]

VAPI im Überblick

Der Zugriff auf die Funktionen der Schnittstelle erfolgt mit Hilfe des SOAP-Protokolls über den VAPI-Webservice. Dadurch wird ein hoher Grad an Plattformunabhängigkeit garantiert. Die Authentizität und Integrität der VAPI-Aufrufe wird durch den Einsatz von WS-Security sichergestellt.

Abbildung 1: Schematische Darstellung von VAPI

8

[Seite 9]

VAPI im Überblick

XML als Datenaustauschformat

Die folgende Abbildung zeigt die Verknüpfungen zwischen den VAPI-Clients, den Methoden und Endpoints.

Abbildung 2: Schematische Abbildung der VAPI-Clients, Methoden und Endpoints

2.1 XML als Datenaustauschformat

Der Datenaustausch zwischen VAPI und der externen Applikation erfolgt im XML-Format, wobei die gleiche Grammatik wie bei Im- und Export Verwendung findet. Der Aufbau soll im Folgenden an einigen konkreten Beispielen gezeigt werden:

Übergabe eines Betreffs

Übergabe eines Betreffs und des Aktenplanschlüssels

9

[Seite 10]

VAPI im Überblick

Software Development Kits

Hinzufügen von Primärdaten zu einem Dokument

2.2 Software Development Kits

Für eine einfache Nutzung des VAPI-Webservice stellt die PDV GmbH clientseitige Software Development Kits (SDK) bereit. Diese stellen eine Sammlung von Programmierwerkzeugen und Programmbibliotheken dar, welche die Arbeit mit VAPI erleichtern.

Für Java steht Ihnen der »vapiclient-cxf--dist.zip« zur Verfügung, welcher das WebService-Framework »CXF« nutzt. Zusätzlich kann projektspezifisch ein Client auf Basis des Glassfish Metro Frameworks mit leicht eingeschränkten Funktionsumfang bereitgestellt werden.

10

[Seite 11]

VAPI im Überblick

Software Development Kits

Neben den Java SDKs, gibt es auch das ».NET VAPI SDK«, welches die Windows Communication Foundation (WCF) nutzt. Aufgrund konfigurativer Besonderheiten dieser Kommunikationsplattform sind in der VAPI-Konfiguration (VAPI.dll.config) bereits Vorbereitungen getroffen worden, um einfach zwischen unverschlüsselter und verschlüsselter Verbindung wechseln zu können. Hierfür existieren zwei CustomBindings, die zwischen den Transportprotokollen »httpTransport« und »httpsTransport« unterscheiden:

11

[Seite 12]

VAPI im Überblick

Software Development Kits

Die Verwendung des jeweiligen Bindings wird ebenso in der »VAPI.dll.config« konfiguriert:

Vorbelegt ist hier die unverschlüsselte Variante »vapiWSPortMTOM«. Für die verschlüsselte Kommunikation ist der Wert des Attributes »name« entsprechend mit »vapiWSPortMTOMBindingSecure« zu belegen.

Zusätzlich existiert eine Möglichkeit das Binding in der jeweiligen VAPI Anwendung zu setzen. Die zuvor genannte Einstellungsmöglichkeit wird dabei überschrieben. Hierfür ist der Schlüssel »bindingName« entsprechend des folgenden Beispiels den Anwendungseinstellungen hinzuzufügen:

Diese Anwendungseinstellung kann ebenso dynamisch zur Laufzeit verändert werden. Nützlich ist diese Funktion, wenn innerhalb einer Anwendung Verbindungen zu Servern mit unterschiedlichen Konfigurationen (unverschlüsselt vs. verschlüsselt) aufgebaut werden müssen.

12

[Seite 13]

Die bereitgestellten Funktionen des VAPI-Webservices

Geschäftsobjekt-Funktionen

3 Die bereitgestellten Funktionen des VAPI-Webservices

Der VAPI-Webservice stellt Funktionen zum • Erzeugen, Suchen und Modifizieren von Geschäftsobjekten, • Ermitteln von Repository-Konfigurationen (Spracheinstellungen etc.) bereit.

3.1 Geschäftsobjekt-Funktionen

Tabelle 2: Funktionen zu Geschäftsobjekten

3.2 Repository-Funktionen

Tabelle 3: Funktionen zum Repository

13

[Seite 14]

Verbindungseinstellungen

Proxy einstellen

4 Verbindungseinstellungen

Zusätzlich zu dem Standard kann VAPI auch mit zusätzlichen Verbindungseinstellungen umgehen.

4.1 Proxy einstellen

VAPI kann auch hinter einem Proxy betrieben werden. Hierfür muss die Methode »setProxy()« auf der VAPI-Client-Instanz aufgerufen werden.

client.setProxy("string proxyServer", "string proxyExcludes");

Der Parameter »Excludes« ist eine Liste, deren einzelne Elemente durch ein Semikolon »;« getrennt werden.

Beispiel: client.setProxy("http://Beispiel", ".Beispiel.de;.Beispiel.com")

4.2 Verbindungstimeout

Um bei fehlerhaften Verbindungen nicht zu lange zu warten, kann abweichend vom Standard ein Verbindungstimeout in Millisekunden eingestellt werden.

client.setTimeout(10000);

14

[Seite 15]

VAPI-Schnittstelle

Stub-Generierung

5 VAPI-Schnittstelle

Um komfortabel aus Fremdanwendungen über die VAPI-Schnittstelle auf VIS- Funktionalitäten zugreifen zu können, sollten die mitgelieferten Clientbibliotheken verwendet werden. Steht für die gewünschte Umgebung keine geeignete Clientbibliothek zur Verfügung, so kann mit Hilfe der mitgelieferten WSDL (Web Service Description Language) selbst ein Stub erzeugt werden. Das Vorgehen hierfür soll im Folgenden exemplarisch beschrieben werden.

5.1 Stub-Generierung

Der VAPI-Webservice wird durch die mitgelieferte WSDL vollständig beschrieben. Auf Grundlage dieser Beschreibung ist das automatische Generieren eines sogenannten Stubs oder auch Proxys in nahezu jeder modernen Entwicklungsumgebung möglich.

Beim Einsatz des Visual Studio 2003 würde zum Beispiel das Generieren eines C#-Stubs mit Hilfe des Tools »wsdl.exe« erfolgen.

hwsdl /language:cs http://<>:<>/vis/<>/services/VapiWS?wsdl?WSDL

Das genaue Vorgehen innerhalb einer anderen IDE ist der jeweiligen Dokumentation zu entnehmen.

5.2 Sicherheit

Das Verschlüsseln und Signieren der Nachricht erfolgt durch die Verwendung von WS- Security nach OASIS Standard 2004011. Es werden Kerberos-, x509-Zertifikate und das Basic-Verfahren zur Authentifizierung unterstützt. Zur Erstellung eines Clients kann auf eine Bibliothek eines Drittherstellers zurückgegriffen werden.

Empfehlung: • AXIS + WSS4J 2 für Java • alternativ: xFire • Windows Communication Foundation (WCF)

Weiterführende Informationen und konkrete Beispiele zum Einsatz der Bibliotheken können der Dokumentation der jeweiligen Umsetzung entnommen werden.

1 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf 2 http://ws.apache.org/wss4j/

15

[Seite 16]

VAPI-spezifische Mandanten-Propertys

Mandanten-Property »VAPI_STORAGE_LIST_RIGHTS«

6 VAPI-spezifische Mandanten-Propertys

In diesem Kapitel werden Mandanten-Propertys für VAPI vorgestellt.

6.1 Mandanten-Property »VAPI_STORAGE_LIST_RIGHTS«

Über das Mandanten-Property »VAPI_STORAGE_LIST_RIGHTS« kann gesteuert werden, welche Rechte (Lese- oder Schreibrecht) der VAPI-Nutzer an der Ablage haben muss, um den Inhalt auslesen zu können.

Mögliche Werte sind »read« und »write«. • Wert = »read«: Hierbei kann der Inhalt von Ablagen ausgelesen werden, auf die der VAPI-Nutzer Leserechte hat. • Wert = »write«: Der VAPI-Nutzer kann nur den Inhalt von Ablagen auslesen, auf die er Schreibrechte hat. Standardwert ist »write«.

16

[Seite 17]

Erstes Programmierbeispiel

VAPI-Client-Instanz erzeugen

7 Erstes Programmierbeispiel

Ist die Clientbibliothek erst einmal in das Projekt eingebunden, kann mit der eigentlichen Programmierung der Schnittstelle begonnen werden. Im folgenden Kapitel werden die Funktionalitäten der Clientbibliothek anhand von Beispielen in C# näher erläutert.

7.1 VAPI-Client-Instanz erzeugen

Um eine Client-Instanz zu erzeugen, muss Folgendes bekannt sein: • VIS-Endpoint • VIS-Mandant

String endpoint="http://srv-app1.dom.lan:8080/vis/238FFF46-F2C1-34F7- 3AD9-9A0C1DB0E8D9/service/VapiWSMTOM";

String mandant = "{238FFF46-F2C1-34F7-3AD9-9A0C1DB0E8D9}";

// 1. Schritt: VAPI-Objekt erzeugen (z.B. VapiVSMTOMClient) VapiWSMTOMClient client = new VapiWSMTOMClient(mandant, endpoint);

7.1.1 Authentifizierung gegenüber VIS

Damit die Anfragen der Clientanwendung vom VIS-Server akzeptiert werden, muss sich die eben erzeugte VAPI-Client-Instanz gegenüber VIS authentifizieren.

Hierfür gibt es vier Möglichkeiten:

1 - Ausführung im Windows-Benutzerkontext

client.setSecurityType((int)EsecurityType.SECURTYPE_WINDOWS_AUTHENT);

2 - Authentifizierung über Kerberoszertifikate

client.setSecurityType((int)ESecurityType.SECURTYPE_KERBEROS_AUTHENT);

3 - Authentifizierung mit dem OAuth2-Verfahren

4 - Ausführung mittels Basic-Authentifizierung

client.setSecurityType((int)ESecurityType.SECURTYPE_BASIC);

client.setBasicCredentials("<>","<>");

Die Authentifizierung über die Beispiele 1 und 2 erfolgt unmittelbar. Bei der Basic- Authentifizierung sind die Platzhalter <> und <> durch den

17

[Seite 18]

Erstes Programmierbeispiel

VAPI-Client-Instanz erzeugen

entsprechenden Nutzernamen bzw. Passwort als String im Klartext zu ersetzen. Die Authentifizierung mittels OAuth2 wird im nächsten Kapitel ausführlich beschrieben.

Anstelle der Enum-Typen ESecurityType können alternativ auch die Kennungen aus Anhang »10.3 ESecurityType« verwendet werden.

7.1.2 Authentifizierung mit OAuth2

Die OAuth-Authentifizierung wird nur für den VAPI-Java-Client auf Basis des CXF- Frameworks bereitgestellt und setzt auf das OAuth2-Verfahren »password grant type«.

Ähnlich wie bei der Basic-Authentifizierung ist das Verfahren im Rahmen von VAPI auf die Authentifizierung eines einzelnen Service-Nutzers ausgerichtet.

Um die OAuth-Authentifizierung zu nutzen, muss mit der nachfolgenden Klasse »VapiWSOauth« gearbeitet werden:

VapiWS vapiClient = new VapiWSOauth(mandantGuid, endpointURL);

Zusätzlich muss gegen den VAPI-Endpoint im oauth2-Securitykontext gearbeitet werden:

http://server:port/vis/MANDANTGUID/oauth/service/VapiWSMTOM

Die benötigten OAuth2-Authentifizierungs-Daten müssen im Classpath in einer Konfigurationsdatei »oauth2.properties« bereitgestellt werden.

Beispiel:

accessToken=0a232e3c-410d-4922-8c99-9ffdaa418699

refreshToken=dafa34d2-8855-48c0-b9d8-25bf2f829fd3

tokenEndpoint=http://srv-dev-virtual.pdv.lan:8088/visj-web- app/A8202BBD-CF74-62E7-F9B6-C5F46E3C0393/mvc/oauth/token

clientId=vapi

clientPassw0rd=password123

Mit dem tokenEndpoint ist ein TokenService zur Generierung von »accessToken« und »refreshToken« bereitgestellt. Dadurch wird sichergestellt, dass nur berechtigte Client- Anwendungen Token generieren können.

Username und Password eines Nutzers werden nur bei der initialen Token-Generierung (in gesicherter Umgebung, z. B. localhost) im Post-Body übergeben. Bei späteren Aktualisierungen des »accessToken« wird statt der Nutzerinfos, der »refreshToken« übergeben. Mittels dieser Authentifizierung durch die Anwendung selbst, lassen sich DoS- Angriffe effektiv vermeiden.

18

[Seite 19]

Erstes Programmierbeispiel

XML-Erzeugung

So authentifizieren Sie sich mit OAuth2:

1 - Generieren Sie manuell das accessToken, sowie das refreshToken und übertragen Sie diese in die properties-Datei:

curl -v vapi:password123@localhost:PORT/vis/MANDANTGUID/mvc/oauth/token -d grant_type=password -d username=UPN -d password=PWD

2 - Der VAPI-Client nutzt das accessToken für die Authentifizierung. Anschließend können Sie den VAPI-Client nutzen, bis das accessToken seine Gültigkeit verliert.

3 - Hat das accessToken keine Gültigkeit mehr, generiert der VAPI-Client mithilfe des refreshTokens ein neues accessToken und schreibt dieses in die »oauth2.properties«.

Die Authentifizierung mit OAuth2 bietet folgende Sicherheitsmerkmale: • Die einmalige Nutzung von Benutzername und Passwort in einer gesicherten Umgebung. • Die Nutzung eines accessTokens mit zeitlich begrenzter Gültigkeit. • Die seltene Nutzung eines refreshTokens mit zeitlich unbegrenzter Gültigkeit. • Einen eingeschränkten Bereich, in der die Tokens nutzbar sind, in diesem Fall VAPI.

7.2 XML-Erzeugung

Im folgenden Abschnitt wird auf die Erzeugung von XML-Objekten mittels C# eingegangen.

19

[Seite 20]

Erstes Programmierbeispiel

Erstellen eines neuen Geschäftsobjekts

7.2.1 Übersichtliche Erzeugung

Um ein neues Geschäftsobjekt zu erstellen, muss ein valider XML-String erstellt und der VAPI-Client-Instanz übergeben werden.

Die Erzeugung des Strings kann zum Beispiel wie folgt geschehen:

string inhalt ="Test VAPI";

Dies ist durchaus ein Vorgehen, welches funktioniert. Jedoch werden die Strings, welche im Arbeitsalltag erstellt werden, üblicherweise sehr viel länger und generischer. Wir empfehlen daher ein anderes Vorgehen.

Die Strings sollten nicht komplett im Programmcode erstellt werden, sondern sollten mit Platzhaltern vordefiniert in Dateien gehalten werden.

Im Beispiel die Datei »createBusinessObject.xml«:

Die XML-Struktur kann mit den vorgegebenen Platzhaltern als Datei gespeichert werden. Zur Laufzeit werden die »%%platzhalter%%« dann entfernt und durch reale Werte ersetzt.

Die Platzhalter können wie folgt in C# ersetzt werden:

//pathXml gibt den Pfad an, unter dem die Datei createBusinessObject.xml zu finden ist

string path = pathXml + @"createBusinessObject.xml"; string inhalt = File.ReadAllText(path).Replace("%%betreff%%", "Test VAPI");

Der XML-Inhalt des Strings »inhalt« ist in beiden Fällen identisch.

Für eine Stapelverarbeitung empfiehlt es sich, die Datei einmalig einzulesen und im Arbeitsspeicher vorzuhalten.

Um die passenden XML-Tag-Namen zu ermitteln, empfiehlt es sich, ein passendes Geschäftsobjekt zu exportieren und das Ergebnis als Kopiervorlage zu nutzen.

7.3 Erstellen eines neuen Geschäftsobjekts

Nachdem nun eine VAPI-Client-Instanz (siehe Kapitel »7.1 VAPI-Client-Instanz erzeugen«) und ein gültiges XML-Dokument (siehe Kapitel »7.2 XML-Erzeugung«) erstellt wurden, müssen sie im VIS-Server gespeichert werden.

Nun wird ein neues internes Schreiben mit dem Betreff »Test VAPI« und mit dem im Abschnitt »7.2 XML-Erzeugung« erstellten XML erzeugt.

20

[Seite 21]

Erstes Programmierbeispiel

Erstellen eines neuen Geschäftsobjekts

Hierfür wird die Methode »createBo()« auf der VAPI-Client-Instanz aufgerufen:

int boType = 14; //gibt den Geschäftsobjekttyp an (14 = internes Schreiben)

int vaterID = 1234; // VIS-ID der Akte, in der das Dokument anzulegen ist

int poolId = -1; // VIS-ID der Ablage (-1 = Standardablage)

int dokumentBOID = client.createBo(boType, inhalt, vaterID, poolId, (int)(EExportImport.DEFAULT));

Die Parameter der Methode »createBo()« im Detail: • »boType«: der Typ des anzulegenden Geschäftsobjekts (siehe Anhang »10.1 EBoType«) • »inhalt«: der Inhalt des Geschäftsobjekts im XML-Format • »vaterID«: die ID der Akte, in der das Dokument angelegt wird • »poolId«: die ID der Ablage, in der das Dokument angelegt wird (siehe Anhang »10.2 Ablagen«) • Verarbeitungsoptionen

Der Rückgabewert der Methode ist die VIS-ID des neu erstellten Dokuments.

21

[Seite 22]

Weitere Einsatzmöglichkeiten

Anlegen einer neuen Akte

8 Weitere Einsatzmöglichkeiten

Nachdem nun die Grundlagen der VAPI-Schnittstelle aufgezeigt wurden, geht es im folgenden Kapitel um die weiteren Einsatzmöglichkeiten von VAPI. Es werden Grundkenntnisse der VAPI-Schnittstelle vorausgesetzt, welche in den Kapiteln »4 Verbindungseinstellungen« und »5 VAPI-Schnittstelle« thematisiert wurden.

In den Beispielen wird zuerst eine XML-Datei gezeigt, welche mit Platzhaltern versehen ist. Das Vorgehen zum Setzen der Platzhalter in den Dateien ist im Abschnitt 7.2.1 Übersichtliche Erzeugung beschrieben.

Zu beachten ist, dass beim Anlegen von Geschäftsobjekten immer alle Pflichtfelder innerhalb der XML-Datei vorhanden sein müssen.

8.1 Anlegen einer neuen Akte

Inhalt der Datei »createAkte.xml«:

Die im Beispiel gezeigte Datei kann beliebig um Werte ergänzt werden.

Sind alle Platzhalter durch Werte ersetzt worden, kann die Akte mit der Methode »createBo()« angelegt werden:

int boType = 1; //gibt den Geschäftsobjekttyp an (1 = Akte)

int vaterID = -1; // VIS-ID der Ablage

int poolId = -1; // VIS-ID der Ablage (-1 = Standardablage, dem VAPI- Benutzer muss eine Standardablage zugeordnet sein)

int akteBOID = client.createBo(boType, inhalt, vaterID, poolId, (int)(EExportImport.DEFAULT));

Der Rückgabewert der Methode ist die VIS-ID der neu erstellten Akte. Innerhalb der neu erstellten Akte können nun weitere Geschäftsobjekte erstellt werden.

8.2 Erstellen eines Vorgangs

Prinzipiell funktioniert das Erstellen eines Vorgangs genauso wie das Erstellen eines Dokuments in Abschnitt »7.3 Erstellen eines neuen Geschäftsobjekts«. Für den Vorgang muss lediglich ein anderes XML-Dokument erzeugt und der »boType« angepasst werden.

22

[Seite 23]

Weitere Einsatzmöglichkeiten

Geschäftsobjekte suchen

Inhalt der Datei »createVorgang.xml«:

Der Aufruf der VAPI-Client-Instanz sieht dann folgendermaßen aus:

int boType = 3; //gibt den Geschäftsobjekttyp an (3 = Vorgang)

int vaterID = 1234; // VIS-ID der Akte, in der das Dokument anzulegen ist

int poolId = -1; // VIS-ID der Ablage (-1 = Standardablage)

int vorgangsBOID = client.createBo(boType, inhalt, vaterID, poolId, (int)(EExportImport.DEFAULT));

Der Unterschied zum Aufruf in Abschnitt »7.3 Erstellen eines neuen Geschäftsobjekts« besteht lediglich in dem geänderten »boType« und einem anderen Inhalts-String.

8.3 Geschäftsobjekte suchen

VAPI unterstützt die Suche nach Geschäftsobjekten innerhalb des VIS-Servers. Hierfür wird im folgenden Beispiel die Methode »searchBO()« verwendet.

Als erster Schritt muss wieder ein XML-Dokument als Suchmuster erstellt werden.

Inhalt der Datei »discoverVorgang.xml«:

Das XML sagt dem VIS-Server, er soll Vorgänge suchen, welche im Betreff das Pattern enthalten, welches durch den Platzhalter »%%betreff%%« ersetzt wurde. Die Methode »searchBo()« wird dann wie folgt aufgerufen:

int type = 1; //gibt den Geschäftsobjekttyp an (1 = Akte)

int[] ids = client.searchBo(typ, searchParamsDoc);

Der erste Parameter gibt an, nach welcher Art von Geschäftsobjekten gesucht werden soll. Der zweite Parameter enthält das Suchmuster als XML-Fragment.

Im Beispiel wird folglich nach Akten gesucht, die einen Vorgang mit dem gesuchten Betreff haben.

Die Rückgabe besteht aus einem Integer-Array, welches alle IDs beinhaltet, auf die die angewendete Suche zutrifft.

23

[Seite 24]

Weitere Einsatzmöglichkeiten

Geschäftsobjekte anhand einer Vorlage suchen

Für komplexe Suchbedingungen kann die VIS-Datenbank genutzt werden. Dazu erstellen Sie in VIS ein Suchmuster und fragen dieses dann in der Datenbank ab. Die Spalte »stream« der Tabelle »vset_suchmuster« beinhaltet die Suchbedingung als XML. Die Daten sind als BLOB abgelegt, was das Lesen erschwert.

Bei der Oracle-DB nutzt man am besten die Funktionalität des SQLDevelopers: Zelle anklicken → Anzeigen als: Text.

Beim SQL Server kann die folgende Select-Anweisung genutzt werden:

select convert(varchar(max),convert(varbinary(max),stream)) from vset_suchmuster where suchmuster_id = 2222

8.4 Geschäftsobjekte anhand einer Vorlage suchen

Im folgenden Abschnitt wird gezeigt, wie Geschäftsobjekte anhand einer Vorlage gesucht werden und wie die Rückgabe eingeschränkt werden kann.

Im Beispiel ist das Suchschema in der Datei »erweiterteSuche.xml« dargestellt:

int type = 14; //gibt den Geschäftsobjekttyp an (14 = internes Schreiben)

string fields = "";

string[] ids = client.searchBoEx(typ, searchParamsDoc, fields);

Im Beispiel wird die Datei »erweiterteSuche.xml« geladen und auf die Suche angepasst. Der Methode »searchBoEx()« wird dieses XML-Element dann als Parameter »searchParamsDoc« übergeben. Der Parameter »fields« gibt an, dass von allen gefundenen internen Schreiben der Inhalt von »Betreff« zurückgegeben werden soll.

Angenommen, der Platzhalter im Beispiel oben wird durch »test*« ersetzt, so wird nach allen internen Schreiben gesucht, die mit »test« beginnen. Anschließend wird der Betreff von allen internen Schreiben zurückgegeben, die der Suche entsprechen.

24

[Seite 25]

Weitere Einsatzmöglichkeiten

Suche nach Unterablagen

Sollen mehrere Felder auf einmal zurückgegeben werden, empfiehlt sich eine generische Erstellung des Parameters »fields«, um eine bessere Lesbarkeit des Quellcodes zu erreichen:

int type = 14; //gibt den Geschäftsobjekttyp an (14 = internes Schreiben)

string[] columns = {

"Geschäftszeichen", "Fremd-GZ", "Kurzbez-Dok", "Betreff", "Adresse", "Vorgangstyp", "Laufzeit von"};

StringBuilder sb = new StringBuilder("");

foreach (string col in columns){

sb.Append("<").Append(replaceSpecialCharacters(col)).Append("/>"); }

sb.Append("");

string fields = sb.ToString();

string[] ids = client.searchBoEx(typ, searchParamsDoc, fields);

Im Beispiel wird ein Array mit allen gesuchten Feldern angelegt. Ein StringBuilder wandelt diese Namen dann in eine XML-Struktur um, die der Methode »searchBoEx()« übergeben wird.

8.5 Suche nach Unterablagen

Die Suche nach Unterablagen lässt sich mit der Methode »searchBoEx()« realisieren.

client.searchBoEx(EBoSearch.SEARCH_SUB_POOL, "", "");

Im Beispiel werden alle Unterablagen mit Name und Bemerkung zurückgegeben.

8.6 Exportieren eines Geschäftsobjekts

Die VAPI-Client-Instanz ist nicht nur in der Lage, Objekte zu schreiben, sondern auch Objekte zu lesen. Für den Export eines Geschäftsobjekts muss mindestens eine Geschäftsobjekt-ID bekannt sein. Entweder ist die zu exportierende ID bekannt oder sie muss mit Hilfe der Methode »searchBo()« abgefragt werden (siehe Abschnitt »8.3 Geschäftsobjekte suchen«).

Für den Export wird folgender Aufruf benötigt:

int[] objekteInts = new[] {1234};

string bo = client.exportBo( ref objekteInts,(int)EBoType.BO_TYPE_FILE);

25

[Seite 26]

Weitere Einsatzmöglichkeiten

Geschäftsobjektteile exportieren

Zuerst wird ein Array mit Geschäftsobjekt-IDs angelegt, welche exportiert werden sollen. Im Beispiel wird nur eine Akte mit der ID 1234 exportiert. Es können aber auch mehrere IDs angegeben werden. Über das zweite Argument der Methode »searchBo()« wird definiert, von welchem Typ die exportierten Objekte sind.

Die Rückgabe der Methode ist ein XML-Objekt, welches als String geliefert wird. Dieser String kann dann entsprechend weiterverarbeitet werden.

Für aufwendigere Arbeiten empfiehlt es sich, den String als C#-XmlDocument weiter zu verarbeiten:

XmlDocument document = new XmlDocument();

document.LoadXml(bo);

Im Beispiel wird das vom VAPI-Client zurückgelieferte XML als »XmlDocument« geladen, um es anschließend weiter zu verarbeiten.

8.7 Geschäftsobjektteile exportieren

Im Abschnitt »8.6 Exportieren eines Geschäftsobjekts« wurde gezeigt, wie ganze Geschäftsobjekte exportiert werden können. Mit VAPI ist es aber auch möglich, nur einen Teil eines Geschäftsobjektes zu exportieren.

Dies wird mit der Methode »getBoData()« realisiert.

int[] objekteInts = new[] {1234};

string vorlage = "";

string bo = client.exportBo(ref objekteInts, vorlage, (int)EExportImport.DEFAULT);

Im Beispiel wird der Betreff des Geschäftsobjektes mit der ID 1234 exportiert. Es können aber auch, mehrere Attribute eines Geschäftsobjektes auf einmal abgefragt werden.

8.8 Prüfen, ob ein Geschäftsobjekt abgeschlossen ist

In diesem Kapitel wird gezeigt, wie geprüft werden kann, ob eine exportierte Akte abgeschlossen ist.

XmlNodeList tagAbgeschlossen= document.SelectNodes("/TrefferElemente/Akte/Abgeschlossen");

string isClosed = tagAbgeschlossen[0].InnerText;

Im Beispiel werden innerhalb des exportierten XML alle Knoten »TrefferElemente/Akte/Abgeschlossen« selektiert. Da wir im Beispiel nur eine Akte haben, wird aus dem ersten zutreffenden Knoten der Text geholt.

Ist der Wert »0«, so ist das Objekt nicht abgeschlossen. Ist er »1«, so ist das Objekt abgeschlossen.

26

[Seite 27]

Weitere Einsatzmöglichkeiten

Geschäftsobjektoperationen

Bei Geschäftsobjekten eines anderen Typs muss der String innerhalb von »SelectNodes« angepasst werden. Mit Hilfe dieses Vorgehens können auch andere Werte des Geschäftsobjekts abgefragt werden.

8.9 Geschäftsobjektoperationen

Auf Geschäftsobjekten können mithilfe der Methode »doBoAction()« verschiedenste Aktionen durchgeführt werden.

Für einen Überblick der möglichen Operationen empfehlt sich der Anhang »10.4 EBoAction«.

8.9.1 Objekte abschließen

Im folgenden Beispiel wird gezeigt, wie ein Objekt abgeschlossen werden kann:

int[] objekteInts = new[] {1234};

client.doBoAction(ref objekteInts, (int)EBoAction.BO_ACTION_FINALIZE, "<dummy kommentar="Objekt abgeschlossen"/>");

Im Beispiel wird das Geschäftsobjekt mit der ID 1234 abgeschlossen. Als Erstes wird der Methode ein Array mit den abzuschließenden Objekt-IDs gegeben. Die Aktion »EBoAction.BO_ACTION_FINALIZE« gibt an, dass die entsprechenden Objekte abgeschlossen werden sollen. Als Letztes wird ein kurzes Dummy-XML überreicht, welches ein Attribut »kommentar« enthalten muss, in dem der Kommentar angegeben ist.

27

[Seite 28]

Weitere Einsatzmöglichkeiten

Geschäftsobjektoperationen

8.9.2 Objekte aufschließen

Auf abgeschlossenen Objekten können keine Operationen ausgeführt werden. Es besteht aber die Möglichkeit, diese wieder aufzuschließen. Dies geschieht genau wie vorangegangenen Beispiel, lediglich die Aktion »EBoAction.BO_ACTION_REOPEN« muss verwendet werden:

int[] objekteInts = new[] {1234};

client.doBoAction(ref objekteInts, (int)EBoAction.BO_ACTION_REOPEN, "<dummy kommentar="Objekt aufgeschlossen"/>");

Im Beispiel wird das Geschäftsobjekt mit der ID 1234 wieder aufgeschlossen.

8.9.3 Objekte archivieren

Aktion »EboAction.BO_ACTION_ARCHIVE_OBJECT«

client.doBoAction(new int[] {1234},EBoAction.BO_ACTION_ARCHIVE_OBJECT, "");

Im Beispiel wird die Geschäftsgangverfügung mit der Objekt-ID 1234 archiviert.

8.9.4 Geschäftsgangverfügung löschen

Aktion »EboAction.BO_ACTION_REMOVE_GGV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_REMOVE_GGV, "<Geschaeftsgangverfuegungen id="19359"/>");

Im Beispiel wird die Geschäftsgangverfügung mit der ID 19359 der Akte 1234 gelöscht.

28

[Seite 29]

Weitere Einsatzmöglichkeiten

Geschäftsobjektoperationen

8.9.5 Geschäftsgangverfügung bearbeiten

Aktion »EboAction.BO_ACTION_UPDATE_GGV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_UPDATE_GGV, "<Geschaeftsgangverfuegungen id="19359"> A A ");

Im Beispiel werden die Aufgabenbeschreibung und Vermerk der Geschäftsgangverfügung mit der ID 19359 der Akte 1234 aktualisiert.

8.9.6 Geschäftsgangverfügung erledigen

Aktion »EBoAction.BO_ACTION_DONE_GGV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_DONE_GGV, "<Geschaeftsgangverfuegungen id="19359"/>");

Im Beispiel wird die Geschäftsgangverfügung mit der ID 19359 der Akte 1234 erledigt.

8.9.7 Geschäftsgangverfügung abweisen

Aktion »EBoAction.BO_ACTION_ REJECT_GGV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_REJECT_GGV, "<Geschaeftsgangverfuegungen id="19359"/>");

Im Beispiel wird die Geschäftsgangverfügung mit der ID 19359 der Akte 1234 abgewiesen.

8.9.8 Geschäftsgangmuster einfügen

Aktion »EBoAction.BO_ACTION_INSERT_GGV_TEMPLATE«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_INSERT_GGV_TEMPLATE, "<Muster name="test"/>");

Im Beispiel wird ein Geschäftsgangmuster verwendet.

29

[Seite 30]

Weitere Einsatzmöglichkeiten

Geschäftsobjektoperationen

8.9.9 Wiedervorlage löschen

Aktion »EBoAction.BO_ACTION_REMOVE_WM«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_REMOVE_WV, "<Wiedervorlagen id="738"/>");

Im Beispiel wird die Wiedervorlage mit der ID 738 der Akte 1234 gelöscht.

8.9.10 Wiedervorlage bearbeiten

Aktion »EBoAction.BO_ACTION_UPDATE_WV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_UPDATE_WV, "<Wiedervorlagen id="739"> A ");

Im Beispiel wird der Vermerk der Wiedervorlage mit der ID 739 der Akte 1234 aktualisiert.

8.9.11 Wiedervorlage erledigen

Aktion »EBoAction.BO_ACTION_DONE_WV«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_DONE_WV, "<Wiedervorlagen id="740"> A A ");

Im Beispiel wird die Wiedervorlage mit der ID 740 der Akte 1234 erledigt. Dabei werden die Aufgabenbeschreibung und der Vermerk aktualisiert.

8.9.12 Bezug löschen

Aktion »EBoAction.BO_ACTION_REMOVE_BEZUG«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_REMOVE_BEZUG, "<Bezuege id="740">;

Im Beispiel wird der Bezug mit der ID 740 der Akte 1234 gelöscht.

30

[Seite 31]

Weitere Einsatzmöglichkeiten

Geschäftsobjektoperationen

8.9.13 Bezug bearbeiten

Aktion »EBoAction.BO_ACTION_UPDATE_BEZUG«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_UPDATE_BEZUG, "<Bezuege id="3202"> Test1 new <Bezugstyp_id>Antwort</Bezugstyp_id> ");

Im Beispiel wird die Bemerkung und der Bezugstyp des Bezugs mit der ID 3202 der Akte 1234 aktualisiert.

8.9.14 Geschäftsobjekte einander zuordnen

Aktion »EBoAction.BO_ACTION_ZUORDNEN«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_ZUORDNEN, "<dummy id="81124"/>");

Im Beispiel wird die Akte 1234 dem Geschäftsobjekt mit der ID 81124 zugeordnet.

8.9.15 Ändern der Ablage für Geschäftsobjekte

Aktion »EBoAction.BO_ACTION_CHANGE_POOL«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_CHANGE_POOL, "ReferatA");

Im Beispiel wird das Objekt mit der Objekt-ID 1234 in die Ablage ReferatA eingeordnet.

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_CHANGE_POOL, "Allgemein<uablage_id>269300</uablage_id> ");

Im Beispiel wird das Objekt mit der Objekt-ID 1234 in die Ablage Allgemein und dort in die Unterablage mit der ID 269300 eingeordnet.

31

[Seite 32]

Weitere Einsatzmöglichkeiten

Transfer- und Aufbewahrungsfrist ändern

8.9.16 Geschäftsobjekt umprotokollieren

Aktion »EBoAction.BO_ACTION_RE_REGISTER«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_RE_REGISTER, "1111 ");

Im Beispiel wird der Aktenplanschlüssel des Objekts mit der Objekt-ID 1234 geändert.

8.9.17 Geschäftsobjekt löschen

Aktion »EBoAction.BO_ACTION_DELETE_OBJECT«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_DELETE_OBJECT, "");

Im Beispiel wird die Akte mit der Objekt-ID 1234 gelöscht.

8.9.18 Privates Objekt löschen

Aktion »EboAction.BO_ACTION_DELETE_PRIVAT_OBJECT«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_DELETE_PRIVAT_OBJECT, "");

Im Beispiel wird das Objekt mit der Objekt-ID 1234 aus der privaten Ablage gelöscht.

8.10 Transfer- und Aufbewahrungsfrist ändern

Aktion »EBoAction.BO_ACTION_UPDATE_FUB«

client.doBoAction(new int[] {1234}, EBoAction.BO_ACTION_UPDATE_FUB, "<Akte Art="1"> 5 3 ");

Im Beispiel wird an der Akte mit der Objekt-ID 1234 die Transferfrist auf 3 Jahre und die Aufbewahrungsfrist auf 5 Jahre gesetzt.

32

[Seite 33]

Weitere Einsatzmöglichkeiten

Geschäftsobjekte ändern

8.11 Geschäftsobjekte ändern

Um einzelne oder mehrere Werte von Geschäftsobjekten zu ändern, gibt es die Methode »updateBo()«.

Innerhalb eines XML-Elements wird das Attribut des Geschäftsobjekts, welches geändert werden soll, angegeben.

Im Falle des Beispiels soll ein Vorgang einen neuen Betreff erhalten. Hierfür kann dieselbe XML-Datei wie in Abschnitt »7.2 XML-Erzeugung« verwendet werden.

client.updateBo(12345, umschlag, (int)(EExportImport.EXPORT_IMPORT_DEFAULT));

Im Beispiel wird der Vorgang mit der ID 12345 geändert (erster Parameter der Methode »updateBo()«). Die Änderung ist im String »umschlag« enthalten, welcher das eingelesene XML mit dem ausgetauschten Platzhalter entfernt. Im letzten Parameter ist angegeben, dass die Änderung im Default-Modus durchgeführt werden soll.

Einfache Attribute der Geschäftsobjekte lassen sich unkompliziert ändern. Manche jedoch entziehen sich zur Wahrung der Geschäftsregeln einem solchen Eingriff. Bei Attributen, die eine Auflistung mehrerer Objekte beinhalten, sogenannten komplexen Attributen, bedarf es eines differenzierten Vorgehens. Geschäftsgangverfügungen, Wiedervorlagen und Bezüge lassen sich über ein Update hinzufügen, zum Löschen oder Aktualisieren sind jedoch die in Kapitel »8.9 Geschäftsobjektoperationen« erläuterten Aktionen zu nutzen. Dateien lassen sich einfach hinzufügen. Zum Aktualisieren sind insbesondere die Optionen • »EXPORT_IMPORT_PRIMDOC_RENAME_IF_EXISTS« sowie • »EXPORT_IMPORT_CREATEVERSION« zu berücksichtigen. Das Löschen von Dateien wird nicht über die VAPI-Schnittstelle angeboten, wohl aber über die PoolWS-Soap-Schnittstelle oder noch einfacher per WebDAV. Allgemeine oder spezifische Informationen sind unproblematisch. Sie werden wie eine Map mit dem Namen als Schlüssel bearbeitet.

8.12 Import von Dateien

Um Dateien beim Schreiben von VIS-Dokumenten mit anzulegen (oder auch nachträglich hinzuzufügen), werden die Dateien als Inhaltselemente übergeben. Der Name, unter dem

33

[Seite 34]

Weitere Einsatzmöglichkeiten

Import von Dateien

die Datei im Dokument angelegt werden soll, wird stets im XML definiert. Für die Übergabe der Binärdaten bestehen zwei Möglichkeiten, die im Folgenden erläutert werden.

8.12.1 Übergabe innerhalb des XML

Die einfachste Möglichkeit der Übergabe besteht darin, die Binärdaten Base64-codiert XML-inline zu übergeben. Dies ist die bevorzugte Variante für kleine Dateien (bis ca. 30 MB).

Inhalt der Datei »DokumentMitDatei.xml«:

%%betreff%%

Im Beispiel wird das Rahmenwerk für den Upload einer Datei geschaffen. Alle Daten bezüglich der Datei sind innerhalb des Tags »Inhalt« zu finden. Verpflichtend ist die Angabe des Namens der Datei mit Dateiendung und natürlich der Binärdaten der Datei.

MemoryStream inMemoryCopy = new MemoryStream();

using (FileStream fs = File.OpenRead("....\Testdocument.pdf")){ fs.CopyTo(inMemoryCopy);}

byte[] byteArrPDF = inMemoryCopy.ToArray();

string content = Convert.ToBase64String(byteArrPDF);

string dokumentenString = File.ReadAllText(path).Replace("%%betreff%%", "Test VAPI") .Replace("%%dateiName%%", "Testdocument.pdf") .Replace("%%binaries%%", content);

int vaterID = 1234; // VIS-ID des Objekts, an welches das Dokument angehangen werden soll

int poolId = -1; // VIS-ID der Ablage (-1 = Standardablage)

client.createBo(14, dokumentenString, vaterID, poolID, (int)(EExportImport.EXPORT_IMPORT_DEFAULT));

34

[Seite 35]

Weitere Einsatzmöglichkeiten

Import von Dateien

Im Beispiel wird ein MemoryStream erstellt, welcher mit dem Inhalt der Datei im Filesystem gefüllt wurde. Danach wird der entsprechende Stream zu einem Byte-Array konvertiert, welches wiederum BASE64 kodiert wurde.

Alle gewonnenen Informationen werden anschließend in die XML-Vorlage kopiert und diese mit der Methode »createBO()« gesendet.

Die Argumente der Methode »createBO()«: • der Typ, des anzulegenden Dokuments (siehe Anhang »10.1 EBoType«) • der XML-String, welcher die Datei enthält • VIS-ID des Objekts, an welches das Dokument angehangen werden soll • VIS-ID der Ablage • die Default-Import-Optionen (siehe Anhang »10.6 EExportImport«)

Sind die Binärdaten zu umfangreich, kann es zu Problemen kommen: • beim serverseitigen Parsen des XML bzw. • bei der Auslastung des Arbeitsspeichers von Client und/oder Server. Diese Probleme bestehen nicht bei Verwendung der alternativen Übergabe-Option unter Verwendung von Attachments, die im nächsten Abschnitt erläutert wird.

8.12.2 Übergabe als Attachment

Eine zweite Möglichkeit der Übergabe besteht darin, die Binärdaten als Attachment zu übergeben, ähnlich wie dies bei E-Mails erfolgt. Dies ist die bevorzugte Variante für größere Dateien.

Inhalt der Datei »DokumentMitDatei.xml«:

%%betreff%%

Im Beispiel wird das Rahmenwerk für den Upload einer Datei geschaffen. Alle Daten bezüglich der Datei sind innerhalb des Tags »Inhalt« zu finden. Verpflichtend ist die Angabe des Namens der Datei mit Dateiendung. Die Binärdaten der Datei werden bei dieser Option mittels Referenzieren auf das erste (1-basierter Index!) Attachment spezifiziert.

35

[Seite 36]

Weitere Einsatzmöglichkeiten

Import von Dateien

string dokumentenString = File.ReadAllText(path) .Replace("%%betreff%%", "Test VAPI") .Replace("%%bytegroesse%%", byteArr.Length.ToString()) .Replace("%%dateiName%%", "Testdocument.pdf");

int vaterID = 1234; // VIS-ID des Objekts, an welches das Dokument angehangen werden soll

int poolID = -1; // VIS-ID der Ablage (-1 = Standardablage)

client.addRequestAttachment("....\Testdocument.pdf");

client.createBo(14, dokumentenString, vaterID, poolID, (int)(EExportImport.EXPORT_IMPORT_DEFAULT + EExportImport.EXPORT_IMPORT_PRIMDOC_ATTACHMENTS));

Dieses Beispiel unterscheidet sich in folgenden Punkten von dem Beispiel des vorherigen Kapitels: • Die Datei muss nicht in den Arbeitsspeicher gelesen werden. • Stattdessen wird das Einlesen der Datei mit der Methode »addRequestAttachment()« vorbereitet. • Die Importoption »EXPORT_IMPORT_PRIMDOC_ATTACHMENTS« zur Verwendung von Attachments muss hinzugefügt werden.

36

[Seite 37]

Repository-Funktionen

Benutzerfunktionen

9 Repository-Funktionen

Dieser Abschnitt gibt einen Überblick über Methoden zum Ermitteln von Repository- Einstellungen und -Daten.

9.1 Benutzerfunktionen

Über die Methode »getUserList()« ist es möglich, eine Liste von Nutzern oder Gruppen abzufragen:

client.getUserList((int)EUser.USER_ALL_USERS);

Als Parameter wird eine Benutzergruppen-Konstante übergeben, um zu definieren, was genau zurückgegeben wird. Im Beispiel werden alle Nutzer zurückgegeben. Weitere Konstanten sind im Anhang »10.5 EUser« zu finden.

Über die Methode »getUserListEx« ist es möglich, zusätzlich zu den Standardfeldern weitere Felder aus der Tabelle »vadm_benutzer_gruppen« abzufragen:

client.getUserListEx(EUser.USER_GROUP, " <vis_samaccountname/> <vis_userprincipalname/> ")

9.2 Abfrage der Spracheinstellung

Über die Methode »getLanguage()« kann die aktuelle Spracheinstellung des Nutzers abgefragt werden. Beim Aufruf wird die Sprachkonstante des Nutzerkontextes als Integerwert zurückgegeben.

client.getLanguage();

37

[Seite 38]

Repository-Funktionen

Auswahllisteninhalt zurückgeben

9.3 Auswahllisteninhalt zurückgeben

Über die Methode »getSelectionList()« ist es möglich, den Inhalt von Auswahllisten zu ermitteln. Somit kann in Erfahrung gebracht werden, welche Einträge dem VAPI-Nutzer unter Berücksichtigung seiner Berechtigungen zur Auswahl stehen.

client.getSelectionList("<>", true, (int)EState.SELECTION_STATE_SEARCH, (int)ERights.RIGHT_CREATE);

Die Parameter der Methode »getSelectionList()« im Detail: • »identifier«: Bezeichnung der Auswahlliste • »true«: inaktive Elemente werden ausgeblendet, »false«: inaktive Elemente werden nicht ausgeblendet • Zustand der Auswahlliste »EState« (siehe Anhang »10.10 EState«) • Zugriffsrechte »ERights« (siehe Anhang »10.9 ERights«)

9.4 Ablagen abfragen

Mit der Methode »getRepositoryList()« kann eine Anfrage nach allen Ablagen gestellt werden. Die Rückgabe enthält dann alle im Server vorhandenen Ablagen:

client.getRepositoryList();

38

[Seite 39]

Anhang

EBoType

10 Anhang

10.1 EBoType

Tabelle 4: Überblick über die BO-Typen

39

[Seite 40]

Anhang

Ablagen

10.2 Ablagen

Tabelle 5: Übersicht über Ablagen

Weitere Ablagen und Kennung sind installationsabhängig.

10.3 ESecurityType

Tabelle 6: Übersicht über die Authentifizierungsmöglichkeiten

40

[Seite 41]

Anhang

EBoAction

10.4 EBoAction

Tabelle 7: Übersicht über die Geschäftsobjektoperationen

41

[Seite 42]

Anhang

EUser

10.5 EUser

Tabelle 8: Übersicht über die Benutzergruppenkonstanten

42

[Seite 43]

Anhang

EExportImport

10.6 EExportImport

43

[Seite 44]

Anhang

EBoSearch

Tabelle 9: Übersicht über die Export- und Importoptionen

Die Optionen können mit Hilfe der logischen ODER-Operation miteinander verknüpft werden. Standardmäßig sollten die Optionen »EXPORT_IMPORT_META«, »EXPORT_IMPORT_PRIMAER« und »EXPORT_IMPORT_RECURSIVE« ausgewählt werden. Dies entspricht der Option »EXPORT_IMPORT_DEFAULT«.

10.7 EBoSearch

44

[Seite 45]

Anhang

EFileAction

Tabelle 10: Übersicht über die Rechercheoptionen

10.8 EFileAction

Tabelle 11: Übersicht über Aktionen an Dateien

45

[Seite 46]

Anhang

ERights

10.9 ERights

Tabelle 12: Übersicht über die Zugriffsrechte

10.10 EState

Tabelle 13: Übersicht über die Zustände von Auswahllisten

10.11 Sprachkonstanten

Tabelle 14: Übersicht über die Sprachkonstanten

Das Standardprodukt umfasst nur die deutsche Sprache.

46

[Seite 47]

Anhang

EVapiScheme

10.12 EVapiScheme

Tabelle 15: Übersicht über die VAPI-Schemata

47