Administrationshandbuch (EVI-EASY)
Voraussetzungen
Das Modul EVI-Basis ist im System vorhanden und aktiv
Das Modul EVI-EASY ist im System vorhanden Modul-Lizenz eingespielt
Die Anbindung ausgehend aus EVI erfolgt via Content Webservice Rest-API (ab EASY Archive Version 6.2.SR12 (6.2.4268)). Die entsprechende Easy-Version 6.2. oder neuer wird daher vorausgesetzt.
Zur Installation und Konfiguration der Easy-Integration in EVI sind Zuarbeiten eines Easy-Implementierungspartners erforderlich. Sofern die EVI-Easy-Integration in einem Systemumfeld erfolgt, in dem die Billing-Umgebung Schleupen CS.VA zum Einsatz kommt, agiert i.d.R. Schleupen als Easy-Excellence-Partner. Folgende Punkte sind durch den Implementierungspartner zu Leisten:
Lizenzierung: für den Betrieb sind folgende Easy-Lizenzen erforderlich
Jeder CRM-Benutzer benötigt eine EASY Interface - Named User EBIS Lizenz (Nr. 10170088). Verfügt der Benutzer bereits über die höherwertige Weboberflächenlizenz, so ist die EASY Interface - Named User EBIS-Lizenz dennoch freizuschalten.
Der Zugriff auf den Webservcie erfolgt ausschließlich durch einen technischen Benutzer, und nicht im Kontext des CRM-Users, gleich wenn für diesen eine CWS-Lizenz freizuschalten ist.Für die Anbindung eines "Fremdsystems", hier EVI, muss eine EASY Interface - EBIS-Lizenz (Nr. M10170085) freigeschaltet werden
Konfiguration:
Benennen der Endpunkt-URL, über welche der Webservice aufgerufen werden kann
Bereitstellen eines techn. Benutzers, über welchen per Webservice auf den ContentWebservice zugegriffen werden soll.
Benennen des eingesetzten Archives auf welches zugegriffen werden soll, bspw. das von Schleupen bereitgestellte EEX-Archiv JVAD
Die EVI-Modulkonfiguration über die globalen Variablen (s.u.) muss erfolgt sein
Technische Dokumentation
Komponentenübersicht
Prozesse
Beim Einspielen des Moduls werden die Prozesse automatisch veröffentlicht, dennoch ist eine Prüfung des Veröffentlichungsstatus empfehlenswert. Entsprechende Hinweise werden auch beim Import des Moduls ausgegeben.
Skriptbibliothek
SC12EASYUtils
Globale Variablen
C12EASYBaseUrl
C12EASYWebserviceUserName
C12EASYWebserviceUserPassword
C12EASYArchives
Administrationsmöglichkeiten
Über die globalen Variablen können folgende Konfigurationen durchgeführt werden:
Globale Variable Name | Beschreibung | Default | Beispiel |
---|---|---|---|
C12EASYBaseUrl | URL zum EASY Content Webservice | - | |
C12EASYWebserviceUserName | Username für den EASY Content Webservice | - | - |
C12EASYWebserviceUserPassword | Passwort für den EASY Content Webservice | - | - |
C12EASYArchives | EASY-Archive bzw. Schemata, die von EVI aus befüllt werden sollen. Die Werte können als Liste angegeben werden | - | JVAD |
Innerhalb der Skriptbibliothek SC12EASYUtils wird das Archiv mit der jeweiligen Dokumentenindizierung zusammengeführt. Anpassungen an der Indizierung können dort entsprechend übersteuert werden. Ebenfalls können die Mappings von Archiv zu Indizierung vorgenommen werden.
Technischer Ablauf
Nutzung Easy Content Webservice Rest-API
In EASY Archive 6.2 steht der EASY Content Web Service standardmäßig hier zur Verfügung: http://localhost:9090/api/content
In EASY Archive 7 hingegen läuft dieser Webservice standardmäßig über HTTPS und Port 9443: https://localhost:9443/api/content
Die URL des Endpunktes wird in der globalen Variablen C12EASYBaseUrl konfiguriert.
Dokumentation der REST-API: https://myeasy.me/docs/cws/1.3/de/Allgemeine_Verwendung.html
Authentifizierung
Die Authentifizierung erfolgt als Basic-Authentifizierung mittels Benutzername und Passwort. Diese werden in EVI in entsprechenden globalen Variablen verwaltet.
User zur Anmeldung am Webservice: globale Variable: C12EASYWebserviceUserName
Passwort zur Anmeldung am Webservice: globale Variable: C12EASYWebserviceUserPassword
Der Zugriff auf den Webservcie erfolgt ausschließlich durch einen technishcen Benutzer, und nicht im Kontext des Users, gleich wenn für diesen eine CWS-Lizenz freizuschalten ist.
Sitzungsverwaltung
Bei CWS-Aufrufen wird genau eine EBIS-Client-Lizenz für den aufrufenden technischen Benutzer auf der Serverseite belegt, die für weitere Aufrufe vom selben technischen Benutzer wiederverwendet wird, wenn nicht ein Abfrageparameter logout=true übertragen wird. Die Session bleibt dann gültig bis zum Timeout.
Daher ist bei jedem Webservcieaufruf die Session entsprechend zu beenden, um den Benutzer, bzw. die Session nicht zu sperren
Die Sessionabfrage erfolgt dabei Prozessual
Archivierung
Mit Aufruf DocumentUpload wird das Sessiontoken geöffnet
Mit Aufruf CreateDocument wird das Sessiontoken abgemeldet
Suche
Mit Aufruf der Suche wird das Sessiontoken geöffnet
Nach Abruf der Ergebnisse der letzten Page wird die Session geschlossen
Dokument öffnen
Mit Aufruf Get Document wird das Sessiontoken geöffnet und geschlossen
Jede Sessionabfrage muss beendet werden, auch im Fehlerfall. Hierzu kann ein beliebiger Service mit dem Parameter logout übergeben werden.
Sofern die Session aus dem gleichen Serverkontext ausgeführt wird erfolgt keine Sperrung
wird eine Abfrage vom Server und über eine Kachel aus dem Client Kontext aufgebaut, könnte es zu Sperrungen kommen.
Eine Sperrung, die nicht über den umgesetzten Funktionsumfang aufgehoben werden kann, muss innerhalb der easyarchive-Konsole erfolgen.
Archivieren von im CRM erzeugten Dokumenten in das Archiv
Kennzeichnen eines Dokumentes zur Übertragung an das Archiv
Ein in EVI erzeugte Dokument wird über die Basisfunktion aus DMS-Basis zur Archivierung an das DMS System easyarchive übermittelt
Hierzu stehen folgende Prozesse zur Verfügung, über welche ein Dokument manuell durch den Anwender oder automatisiert bei Dokumentenerstellung, bspw. aus dem Angebotsprozess heraus in easyarchive archiviert werden kann
durch manuelles Setzen des DMS-Status = 10 - Bereit für Übertragung auf dem Dokumentendatensatz
manueller Start via Aktionsbox am Dokument
Schalter "Archivieren" in Aktionsbox am Dokument.
Schalter und Ordner sind nur dann sichtbar, wenn das Modul EVI-EASY eingespielt ist.
Der Schalter ist in der Maske aktiv, solange das Feld DMS-Status leer ist. Andernfalls ist der Schalter deaktiviert
Der Schalter ist in der Liste aktiv. Beim Ausführen des Prozesses ist je Datensatz zu prüfen, ob er den Kriterien "DMS-Status = leer" entspricht. Der Prozess wird nur für die Datensätze ausgelöst, welche den Kriterien entsprechen.
Entspricht keiner der Datensätze den Kriterien zum Auslösen des Prozesses, so folgt eine sprechende Meldung an den Anwender
Durch Ausführen des Schalters wird der Dokumentendatensatz mit "DMS-Status = 10 - BEREIT ZUR ÜBERTRAGUNG" und "System-ID = EASY" gekennzeichnet
Der BPM-Prozess "C12DMS_TRANSFER_EVI2DMS" startet automatisch nach dem Speichern eines Dokumentes. Im Startereignis wird über die Methode "isReadyForTransfer" geprüft, ob das Dokument bereit für die Übertragung ist (C12DMSStatus ist gleich "BEREIT ZUR ÜBERTRAGUNG"). Im darauf folgenden Skripttask wird die Methode "transfer2DMS" aufgerufen. Diese Methode startet das Logging für die DMS-Schnittstelle "DOCUMENT_TRANSFER_DMS" und setzt den Status des Dokumentes auf C12DMSStatus = "IN ÜBERTRAGUNG". Anschließend wird ein C12Event "DOCUMENT_TRANSFER_DMS" angelegt und das Logging beendet. Das erzeugte Event ist der Einstiegspunkt für DMS-spezifische Logiken.
→ Durch das Kennzeichnen eines Dokumentes mit DMS-Status = 10 direkt bei der Erstellung, wird dieses automatisch dem Archivierungsprozess zugeführt.
Übertragung des Dokuments an das Archiv
Die konkrete DMS-Implementierung easyarchive reagiert auf das Event "DOCUMENT_TRANSFER_DMS"
Der Status (C12DMSSTATUS.DOCUMENT) wird auf "IN ÜBERTRAGUNG" gesetzt.
Das Dokument wird an das DMS übertragen.
Dies erfolgt idealerweise asynchron, damit der Anwender nicht blockiert wird.
Die Übertragung selbst wird in einem Schnittstellendetail-Datensatz dokumentiert.
Zur Übertragung eines Dokumentes und dessen Metadaten nach easyarchive sind folgende Schritte notwendig:
FileUpload - Überträgt das zu archivierende Dokument als Binary Stream an das Archiv. Als Rückmeldung wird eine eindeutige UploadID übermittelt
Dokumentation: https://myeasy.me/docs/cws/1.3/de/FileUpload.html#src-40476802_id-.FileUploadv1.0-Uploadsanattachment
Webservcie Endpunkt: POST /api/content/files/upload
Überträgt das zu archivierende Dokument als Binary Stream an das Archiv
Die uploadID aus der Response wird zwischengespeichert und für den Aufruf Create a document verwendet.
Creates a document - Erzeugt einen Metadatensatz in Easy und verknüpft diesen mit dem zuvor hochgeladenen Datensatz.
Dokumentation: https://myeasy.me/docs/cws/1.3/de/Document.html#src-95842689_id-.Documentv1.3-Createsadocument
Webservcie Endpunkt: POST /api/content/docs
Erzeugt einen Metadatensatz in Easy und verknüpft diesen mit dem zuvor hochgeladenen Datensatz.
Der Aufruf erfolgt nur, wenn aus FileUpload eine uploadID vorliegt.
In der Stufe 1 der Ausbringung wird zunächst das von Schleupen ausgelieferte EEX-Archiv JVAD und die dafür definierte Dokumentindizierung berücksichtigt. Für weitere Archivanbindungen ist in der Skriptbibliothek SC12EASYUtils vorgesehen, um weitere Archive und deren Indizierung zu hinterlegen. Bislang noch nicht berücksichtigt ist, wie die Auswahl des zu verwendenden Archiv/Dokumentenschemas verwendet werden soll.
Zur Übertragung eines Dokumentes in das Archiv JVAD wird folgende Dokumentenindizierung (Feldzuweisung) verwendet
Easy | EVI | |||||||
Bezeichnung | Index-Feld / Standardfeld | Type | Required | Beschreibung | Alias | Feldname fachlich | Feldname technisch | Beschreibung |
---|---|---|---|---|---|---|---|---|
Store | store | x | The document's store name or unique store ID. | Wert aus Variable C12EASYArchiv bspw. JVAD | ||||
Dokumentenschema | Schema | Wert aus Feldmapping in Skriptbibliothek hinter welchem dann das Feldmapping organisiert ist. | ||||||
Status | status | x | This property indicates whether the document has been archived or saved as a living document. If a document has already been archived but should be updated (document update), | fixer Wert: archived Wenn ein Dokument nicht als Archived übergeben wird, wird es an einem anderen Speicherort gespeichert. Es müsste hinterher noch als archived gespeichert werden. | ||||
UploadId | uploadId | x | The attachment's ID, which is returned by binary stream upload via /files/upload. | uploadId | aus Response von FileUpload | |||
Dateiname | name | The attachment's name. | fileName | DocumentName.Document | ||||
EXTERNAL_KEY | Text | docPk | Primärschlüssel | Pk.Document | ||||
Bereich | 1001 | Text | Verbrauchsabrechnung | fixer Wert Verbrauchsabrechnung | ||||
Ordner | 1002 | Text | VA-Abrechnung/ Öffentlich* | fixer Wert VA-Abrechnung | ||||
Fach | 1003 | Text | Kundenbriefe | fixer Wert Kundenbriefe | ||||
Register | 1004 | Text | Kundenbriefe/Schriftwechsel | fixer Wert Schriftwechsel | ||||
Dokumentenart | 1005 | Text | bspw. Druck CS.VA | fixer Wert EVI-Dokument | ||||
Dokumentenname | 1006 | Text | docTitel | Betreff | ShortAbstract.Document | |||
Listenbezeichnung | 1007 | Text | bspw. Rechnung (Welche Listenbezeichnungen gibt es?) | DocumentType.Document | Wert aus Dokumententyp, Schlüsselbeschreibung verwenden.
| |||
Geschäftsbereich | 1010 | bspw. SVERTRIEB SNETZ | - | - | - | - | ||
MandantenNummer | 1011 | Text | Schleupen-Mandatennummer aus globaler Variable C12SchleupenMandant beziehen | |||||
Name 1 | 1012 | - | - | - | - | |||
Straße | 1013 | - | - | - | - | |||
PLZ | 1014 | - | - | - | - | |||
Ort | 1015 | - | - | - | - | |||
Kunden-Nr. | 1019 | Text | gpPin | CustomerNo2.Customer | Setzt voraus, dass das Dokument mit einem GP über die Relation rCuDo verknüpft ist. | |||
Kundenname | 1020 | Text | gpName | Name | Name1.Customer | - | ||
Erzeugungsdatum | 1027 | DateTime | fileCreateDate | Erstellungsdatum | FileSystemCreation.Document | - | ||
Stichwort | 1028 | Text | fileHeadword | Stichwort | Headword.Document | - | ||
Verbraucherstelle | 1029 | - | - | - | - | |||
Verbraucher | 1030 | - | - | - | - | |||
RechnungseinheitsId | 1031 | Text | ContAccountNo.ContractAccount | Wenn ein Vertragskonto mit dem Dokument über rCnAcDo verknüpft ist, dann übernehmen. | ||||
Belegdatum | 1032 | DateTime | fileCreateDate | Erstellungsdatum | FileSystemCreation.Document | Dokumente können vordatiert werden. Aus EVI wird hier das Erstellungsdatum nochmals mitgeben. Diese Spalte ist ebenfalls in der Rechercheliste (Schleupen VA) enthalten und sollte daher gefüllt werden. | ||
Zählernummer | 1033 | - | - | - | - | |||
Rg Empf. Straße | 1034 | Text | Street | Straße | Street.Address + StreetNumber.Adress + StreetNumberAddition.Address | Werte aus Postadresse des Geschäftspartners | ||
Rg Empf. Ort | 1035 | Text | City | Ort | ZIP.Address + | Werte aus Postadresse des Geschäftspartners |
Beispiel Dokumentenschema JVAD Schleupen
Response
Innerhalb von easyarchive können zu einem Dokument mehrere Attachments abgelegt sein. In EVI sind Dokumentendatensatz und Attachment immer 1:1. Daher ist bei Entgegennahme von Dokumenten Easy2EVI je Attachment ein Dokumentendatensatz zu mit den jeweiligen Metadaten des Dokument zu erzeugen.
Im Feld DMS-ID (C12DMSID.Document) ist die ID wie folgt aufzubauen "DocumentReference (ID)"+Attachment(Reference(ID).
Im Feld System-ID (C12DMSSystemID.Document
Delete Document
Dokumentation: https://myeasy.me/docs/cws/1.3/de/FileUpload.html#src-40476802_id-.FileUploadv1.0-Deletesasingleattachment
Webservcie Endpunkt: DELETE /api/content/files/{uploadId}
Konnten die Metadaten zu einem Dokument über Create Document nicht übertragen werden ist das zuvor via File upload übertragenen Dokument via DELETE uploadID zu löschen
Anzeige und Aufruf von bereits archivierten Dokumenten im Archiv
Auf bereits in easyarchive archiviert Dokumente soll ausgehend vom einem Geschäftspartner zugegriffen werden, um diese zu selektieren und aus dem Archiv aufzurufen.
Die Bedienung zur Filterung und dem Abruf erfolgt dabei über eine Kachel Kundendokumente auf dem Infoboard Dokumente auf der Geschäftspartnermaske
Die Umsetzung basiert dabei auf der Standard-Kachel CompactList
Ist das Modul EVI-EASY deaktiviert, oder ist das Modul EVI-EASY aktiviert, aber die ERP-GP-Nr. (die ERP-GP-NR. ist das Identifizierungsmerkmal für Dokumente zu einem Geschäftspartner im Archiv) nicht gefüllt
werden auf der Kachel CompactList die zum Geschäftspartner abhängigen CRM-Dokumente (die aktuellsten zehn Dokumente) anzeigen
Ist das Modul EVI-EASY aktiviert, und die ERP-GP-Nr. gefüllt,
wird über die Kachel auf die Inhalte aus easyarchiv zugegriffen und die verfügbaren Dokumente per Webservice abgefragt.
der Dokumentenabruf erfolgt dabei über den Webservice Abruf der Dokumente via "Search in store(s)"
Parameter
Kundennummer des Geschäftspartners (CustomerNo2.Customer)
maxhits = 100 (Wert wird in der ScriptClass definiert)
pageSize = maxhits (hierdurch wäre nur ein Webserviceaufruf, der der ersten Seite notwendig)
Colums
Dokumentenname
Dateiname
Erstellungsdatum absteigend sortiert (The sort direction can be determined by prefixing the field name with a "+" (ascending) or a "-" (descending).
Die Dokumentenliste beinhaltet den Dokumentennamen. Dieser soll dem User als Auswahlkriterium angeboten werden.
Über den Dateiname wird der Dateityp ausgelesen und das entsprechende Dateitypen-Icon vor dem Dokumentenname ausgegeben
Filtermöglichkeiten
Innerhalb der Navigation der Kachel stehen dem Anwender weitere Filterkriterien zur Verfügung, um die Ergebnismenge einzugrenzen.
Archiv: Sofern vorhanden und konfiguriert kann innerhlab der Kachel auf die jeweiligen Archive gefiltert werden.
Vertragskonto: Filtern von Dokumenten nach Vertragskonten (Schleupen Rechnungseinheiten) des Geschäftspartners. Der Anwender erhält in der Liste alle zum Geschäftspartner hinterlegte Vertragskonten zur Auswahl angeboten. Wählt man eines der Vertragskonten aus, so wird die Ergebnisliste auf Dokumente zum Vertragskonto eingegrenzt.
Zeitraum von Bis bezieht sich auf Erstellungsdatum
mittels der Filterkriterien wird erneut die Suchanfrage über den Webservice ausgelöst, nun aber ergänzt um die Filterkriterien
Mit Auswahl eines Dokumentes erfolgt der Absprung via "Gets an attachment as stream" anhand der documentReference + Id
Es erfolgt der Aufruf über Browserfunktionalität, entweder als Download oder je nach Dateityp Aufruf im Browser (PDFs können im Browser direkt angezeigt werden)
Aufruf von bereits archivierten Dokumenten im Archiv
Beim Aufruf wird unterschieden zwischen Dokumenten, die über CRM an Easy übermittelt wurden und Dokumente die über die Kachel abgerufen werden.
Über CRM archivierte Dokumente erhalten durch die Archivierung eine Easy-ID und können über den Lese-Schalter auf dem Dokument direkt aus dem Archiv aufgerufen werden.
Zum Aufruf eines bereits archivierten Dokuments wird die Funktionalität aus der Umsetzung DMS Basis verwendet.
"Im Maskenskript des Dokumentes (Modul: C12EVI_BASIS) wurde die Methode "openArchiveDocument" implementiert. Diese prüft, ob das geöffnete Dokument eine DMS-ID besitzt (C12DMSID ist nicht leer). Anschließend wird der Wert aus C12DMSSystemID ausgelesen und wie folgt zu einem Klassennamen zusammengesetzt: "SC12" + C12DMSSystemID + "Utils". Hiermit wird nun geprüft, ob es eine Methode "openDocument" in dieser Klasse gibt. Falls ja, wird sie aufgerufen und das aktuelle Dokument als IContainer übergeben. Existiert die Methode nicht, wird nichts ausgeführt. Kann das Dokument nicht geöffnet werden, weil keine DMS-ID, keine SystemID oder aufzurufende Methode vorhanden ist, wird eine Meldung (Sprachvariable C12DMSOpenDocumentError) angezeigt."
Über die Kachel erfolgt der Aufruf immer direkt aus dem Kontext der Kachel.
Die Methode rufen das Dokument per Webservice in easyarchiv über den Webservice: Gets an attachment as stream: GET /api/content/docs/{documentReference}/attachments/{id} auf
Reads a single document from the system, which is specified by its URL encoded reference.
documentReference has to be the full qualified and url encoded document reference.