Skip to main content
Skip table of contents

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

-

http://localhost:9090/api/content

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

  • 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
Bei VWEW wäre es VWEW_V_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.
This property can only contain the value "archived"; this allows archiving the document.
If it is completely missing, the document will be saved as a living document.

If a document has already been archived but should be updated (document update),
a new document version will be generated instead and that version will also be archived.




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.

  • Angebot

  • Vertrag

  • Einzelbrief

  • ...

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 +
City.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

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.