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:

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

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.