Das Plugin zur Anbindung der MOXIS Unterschriftenmappe von der Firma XiTrust ist ein kostenpflichtiges Plugin. Bei Fragen zur Lizenzierung können Sie sich an Ihren organisatorischen Ansprechpartner wenden.

Das MOXIS Plugin dient zur Anbindung der MOXIS eSignature Business Plattform der Firma XiTrust.

Es ermöglicht die Übermittlung von PDF Dokumenten an die MOXIS Unterschriften-Mappe für eine digitale Signierung in frei wählbaren Signaturqualitäten (QES, AES, SES)

INHALTSVERZEICHNIS

• Installation
  • Konfigurationsparameter für die Anbindung der MOXIS REST-API:
  • Konfigurationsparameter für den MOXIS Web-Hook:
• Workflow-Aktion: MOXIS Create Job
  • Grundeinstellungen
  • Zusätzlich zu übermittelnde Dateien
  • Serverkonfiguration übersteuern
  • Zurückgelieferte Werte der Workflow-Aktion
• Workflow-Ereignisse für Rückmeldung des Auftragsstatus aus MOXIS
  • Voraussetzungen für eine Rückmeldung des Auftragsstatus
  • Einbindung der Rückmeldungs-Ereignisse im Workflow
    • Beschreibung der am Ereignis bereitgestellten Parameter
• Workflow-Aktion: MOXIS Get Job State
  • Grundeinstellungen
  • Serverkonfiguration übersteuern
  • Zurückgelieferte Werte der Workflow-Aktion
• MOXIS-Signier-Platzhalter in Formularen

Installation

Die Installation bzw. Registrierung des Plugins kann als Mandant- oder System-Plugin erfolgen.

Konfigurationsparameter für die Anbindung der MOXIS REST-API:

moxis.rest.srv.url (Pflichtangabe)

Basis - URL zur MOXIS REST-Webservice. (Ohne Angabe einer spezifischen REST- Aktion)

moxis.rest.srv.action.create.job (Pflichtangabe)

Name der Standard-Aktion zum Erzeugen eines Signaturauftrages in MOXIS.

moxis.rest.srv.connection.timeout

Wert für Connection-Timeout in Millisekunden. (Standard-Wert: 10000)

moxis.rest.srv.read.timeout

Wert für Read-Timout in Millisekunden. (Standard-Wert: 30000)

basic.auth.name

Login-Name für eine Basic-Auth Authentifizierung an der MOXIS REST-API

basic.auth.password

Passwort für eine Basic-Auth Authentifizierung an der MOXIS REST-API

Konfigurationsparameter für den MOXIS Web-Hook:

(Der Web-Hook dient der Rückmeldung vom Signierstatus bzw. teil- / vollsignierten PDF-Dokumenten aus MOXIS an formcycle)

web.hook.basic.auth.name

Login-Name für eine Basic-Auth Authentifizierung die am Web-Hook auf Seiten von MOXIS hinterlegt werden kann.

web.hook.basic.auth.password

Login-Name für eine Basic-Auth Authentifizierung die am Web-Hook auf Seiten von MOXIS hinterlegt werden kann.

Bei Nutzung einer Basic-Auth Authentifizierung ist darauf zu achten, dass die Kommunikation zwischen MOXIS und formcycle über HTTPS stattfindet.

Workflow-Aktion: MOXIS Create Job

Dieses Plugin ermöglicht es ein PDF-Dokument aus einer datei-bereitstellenden Aktion an die MOXIS Signierplattform zu übermitteln. Die auf das Dokument anzuwendenden Signatur-Parameter (Iterations-Stufen, Signaturqualitäten etc.) können über die zu übermittelnde Job-Description variabel angepasst werden.

Grundeinstellungen

Zu signierendes Dokument

Verweis auf ein PDF-Dokument, welches als zu signierendes Dokument an MOXIS zu übermitteln ist.

MOXIS Prozess

Der zu benutzende MOXIS-Prozess. Die hier vorgenommen Angabe wird als Name für die anzusprechende REST Aktion interpretiert. Wenn keine Angabe erfolgt, wird der Wert aus dem globalen Konfigurationsparameter moxis.rest.srv.action.create.job verwendet.

MOXIS-Job Konfiguration

In diesem Bereich wird die anzuwendende Verarbeitung auf Seiten von MOXIS, in Form einer JSON Struktur, definiert. Diese Beschreibung enthält (unter anderem) Bestimmungen darüber, welche(r) Benutzer, in welcher Entscheidungsebene des Prozesses, das Dokument unterzeichnen oder freigeben soll(en).
Es können formcycle Platzhalter innerhalb der Job-Konfiguration verwendet werden.

(Alle Möglichkeiten zu den konfigurierbaren Einstellungen entnehmen Sie bitte ihrer jeweiligen MOXIS REST API Schnittstellenbeschreibung zum Thema JobDescription)

Adhoc Signierung starten?

Wenn diese Option aktiviert ist, wird versucht eine Adhoc Siginerung auszuführen. Dabei wird dem Unterschreiber sofort das Dokument zur Unterschrift vorgelegt. Damit die Adhoc Signierung gestartet werden kann, darf nur eine Iteration mit einem externen Unterschreiber konfiguriert sein.

Dokumentnamen-Präfix

Möglichkeit zur Definition eines Präfix für den Dokumentnamen, unter dem das unsignierte bzw. signierte Dokument abgespeichert wird. Der neu erstelle Dateinamen setzt sich folgendermaßen zusammen:
<Dokumentnamen-Präfix><original Dokumentname>_<MoxisId>_<Signierstatus>

Unsigniertes Dokument mit signierten Dokument ersetzen?

Diese Option bewirkt ein Ersetzen des unsignierten Dokumentes (welches als Sicherheitskopie automatisch am Vorgang hinterlegt wird) mit dem teil- bzw. vollständig-signierten Dokuments, sobald dies übermittelt wird.

Zusätzlich zu übermittelnde Dateien

In diesem können zusätzlich an MOXIS zu übertragende Dateien definiert werden. Weiterhin gibt es hier zusätzliche Optionen, welche auf der verarbeiteten Dateien angewendet werden können.

Dateien

Hier können zusätzliche Dateien ausgewählt werden, welche mit an MOXIS übermittelt werden sollen, um den Unterschriften-Prozess für die Entscheider zu unterstützen.

Dateinamen-Präfix bei Anhängen

Definition eines Präfix an den Dateinamen, unter dem die von MOXIS zusätzlich übermittelten Attachments am Vorgang abgelegt werden. Der neu erstelle Dateinamen setzt sich folgendermaßen zusammen:
<Präfix><original Dateiname>

Gleichnamige Anhänge überschreiben

Wenn diese Einstellung aktiviert ist, werden am Vorgang existente Dateianhänge überschrieben, wenn von MOXIS Dateien gleichen Namens übermittelt werden. 

Serverkonfiguration übersteuern

In diesem Bereich können die global definierten Daten zur Anbindung einer MOXIS Instanz übersteuert werden.

MOXIS REST-Service URL

URL zum MOXIS REST-Service, ohne Angabe einer konkrete REST-Aktion, diese wird separat definiert. Übersteuert den globalen Parameter moxis.rest.srv.url.

Basic Authentication Login

Login-Name für Basic-Auth Authentifikation, zum Zugriff auf die MOXIS REST-API. Übersteuert den globalen Parameter 

basic.auth.name

Basic Authentication Passwort

Passwort für Basic-Auth Authentifikation, zum Zugriff auf die MOXIS REST-API. Übersteuert den globalen Parameter basic.auth.password

Zurückgelieferte Werte der Workflow-Aktion

Die Workflow-Aktion liefert im Erfolgsfall folgende Werte zurück, auf die per Platzhalter in weiteren Workflow-Aktionen zugegriffen werden kann:

MoxisId

Die ID, welche MOXIS beim Anlegen des Signierauftrags erzeugt hat und die den Auftrag eindeutig in MOXIS kennzeichnet.

Workflow-Ereignisse für Rückmeldung des Auftragsstatus aus MOXIS

Für die Rückmeldung des aktuellen Auftragsstatus aus MOXIS stehen verschiedene Ereignisse im formcycle Workflow zur Verfügung.

• Signierung erfolgreich
• Teilweise signiert
• Signierauftrag wurde abgelehnt
• Signierauftrag wurde geschlossen
• Signierzeitraum abgelaufen
  
  

Voraussetzungen für eine Rückmeldung des Auftragsstatus

Damit die Ereignisse im formcycle Workflow ausgelöst werden können, muss auf Seiten von MOXIS ein sogenannter "Web Hook" für den MOXIS-Prozess eingerichtet werden. 

Die Basis-URL für den MOXIS Web Hook ergibt sich dabei aus folgendem Muster

http(s)://[webdomain]/[formcycle-webapp]/plugin/?name=MoxisJobAcceptance&client-id=[ID eines Mandanten]

Beachten Sie bei Verwendung einer HTTPS-Verbindung dass dem formcycle System gegebenenfalls die Zertifikate für den Aufbau einer TLS-Verbindung im Java-Truststore bereitgestellt werden müssen.

Die Verbindung zu formcycle lässt sich mittels einer Basic-Auth Authentifizierung absichern. Die dafür notwendigen Parameter können ebenfalls am MOXIS Web Hook hinterlegt werden. In formcycle sind diese im Vorfeld in den globalen Einstellungen am Plugin festzulegen.

Einbindung der Rückmeldungs-Ereignisse im Workflow

Hinweis:
Das teil- oder vollständig signierte PDF-Dokument wird automatisch am Vorgang hinterlegt, der über den MOXIS Web Hook angesprochen wird, sodass eine Bereitstellung am jeweiligen Rückleitungs-Ereignis entfällt.

Beschreibung der am Ereignis bereitgestellten Parameter

MoxisProcessId

Enthält die aktuelle MOXIS Process-Instance-ID

MoxisSignerEmail

Enthält die Email-Adresse des aktuellen Unterschreibers, wenn durch MOXIS zurück geliefert.

MoxisSignComment

Enthält den Kommentar des Unterschreibers, wenn durch MOXIS zurück geliefert.

MoxisSignDocumentId

Enthält die ID unter der das Dokument in MOXIS gespeichert ist.

MoxisSignDocumentName

Enthält den erzeugten Dateinamen, wenn eine Datei aus MOXIS übermittelt und im formcycle System abgespeichert werden konnte.

Workflow-Aktion: MOXIS Get Job State

Dieses Plugin ermöglicht es den Status eines Signaturauftrages bei MOXIS abzufragen.

Grundeinstellungen

MOXIS Prozess-ID 

Hier ist der abzufragende Moxis-Auftrag, durch Angabe der MOXIS-ID (aka MOXIS-ProcessInstanceId) zu hinterlegen.
Es können Platzhalter verwendet werden.

Name Classifier

Gibt an, wie ein MOXIS-Benutzer im resultierenden Statusbericht referenziert werden sollen.
Mögliche Werte sind: ID (MOXIS Nutzer ID), UPN (User-Principal-Name aus dem AD) oder EMAIL (E-Mail Adresse eines registrierten Nutzers)

MOXIS Dokument ermitteln?

Ermittelt das zu signierende Dokument in seinem aktuellen Status aus MOXIS und liefert es zurück.
Wenn diese Option deaktiviert ist, werden nur die Status-Informationen aus MOXIS erfragt.

Serverkonfiguration übersteuern

MOXIS REST-Service URL

URL zum MOXIS REST-Service, ohne Angabe einer konkrete REST-Aktion, diese wird separat definiert. Übersteuert den globalen Parameter moxis.rest.srv.url.

Basic Authentication Login

Login-Name für Basic-Auth Authentifikation, zum Zugriff auf die MOXIS REST-API. Übersteuert den globalen Parameter 

basic.auth.name

Basic Authentication Passwort

Passwort für Basic-Auth Authentifikation, zum Zugriff auf die MOXIS REST-API. Übersteuert den globalen Parameter 

basic.auth.password

Zurückgelieferte Werte der Workflow-Aktion

Die Workflow-Aktion liefert im Erfolgsfall folgende Werte zurück, auf die per Platzhalter in weiteren Workflow-Aktionen zugegriffen werden kann

Der Platzhalter ergibt sich dabei nach folgendem Schema:

[%$<Name der Workflow-Aktion>.RESULT.<Result-Parameter-Name>%]

MoxisDocumentName

Liefert den Dateinamen unter dem das Dokument in MOXIS gespeichert wurde.

MoxisJobCreationDate

Das Datum an dem der MOXIS Auftrag erzeugt wurde. (Format: dd.MM.yyyy hh:mm:ss)

MoxisJobCurrentIteration

Liefert die aktuelle Iteration in dem sich der MOXIS Auftrag gerade befindet.

MoxisJobEndDate

Das Datum an dem der MOXIS Auftrag beendet wurde. Ist nur gesetzt, wenn die der Auftrag im finalen Status befindet.

MoxisJobProcess

Name der Prozesses mit dem der Auftrag in MOXIS erzeugt wurde.

MoxisJobState

Aktueller Status des Dokuments in MOXIS. Kann einer der folgenden Werte sein:

• PROCESSING: aktiver Status
• POST_PROCESSING: aktiver Status
• FINISHED_SUCCESS: finaler Status
• FINISHED_SIGNATURE_DENIED: finaler Status
• FINISHED_WF_CANCELLED: finaler Status
• FINISHED_TIMEOUT: finaler Status

MoxisJsonData

Dieser Parameter enthält die vom MOXIS Service zurück gelieferten Roh-Daten im JSON-Format.
Auf die einzelnen Parameter kann per JSON-Path-Notation zugegriffen werden:

Um beispielsweise in der nachfolgend dargestellten Beispielstruktur auf den Parameter name innerhalb der invitees der 1. Iteration zuzugreifen, kann der folgende Platzhalter verwendet werden:

[%$<Name der Workflow-Aktion>.RESULT.MoxisJsonData.iterations[0].invitees[0].name%]

Beispiel für eine zurückgelieferte JSON-Struktur:

{
      "state": "FINISHED_SUCCESS",
      "processId": "moxisDefault",
      "processInstanceId": "17501",
      "jobMetaData": {
          "description": "Please sign this document",
          "category": null,
          "expirationDate": "2019-10-13T21:59:59.914+0000",
          "referenceId": "Some Id",
          "customMap": '{}'
      },
      "creationDate": "2019-10-03T12:48:12.156+0000",
      "endDate": "2019-10-03T12:51:09.977+0000",
      "currentIteration": 0,
      "iterations": [
          {
              "numberOfSignatures": 1,
              "invitees": [
                  {
                      "@class": "com.xitrust.moxispe.api.Signer",
                      "classifier": "UPN",
                      "name": "max@mustermann.com",
                      "action": "APPROVED",
                      "actionDate": "2019-10-03T12:51:09.636+0000",
                      "comments": []
                  }
              ],
              "category": "EXTERNAL_QSIG",
              "iterationNumber": 0,
              "remark": null,
              "signerGroup": null,
              "privateIteration": null,
              "additionalRecipients": [
                  {
                      "@class": "com.xitrust.moxispe.api.Recipient",
                      "addressBookEntry": {
                          "@class": "com.xitrust.moxispe.api.AddressBookEntry",
                          "name": "Test recipient",
                          "email": "testrecipient@xitrust.com",
                          "phoneNumber": "+436641234567",
                          "locale": "de"
                      },
                      "downloadURL":"https://yourMdsUrl/mds/files/download/8336d801-1efe-4d4d-a586-f72faba3be90"
                  }
              ],
              "customMap": {}
          }
      ]
  }

Zusätzlich kann die Workflow-Aktion das zu signierende bzw. signierte Dokument in der jeweils aktuellen Ausprägung zur Verfügung stellen. (Dies ist im Vorfeld durch die Konfiguration in den Grundeinstellungen festzulegen)

Da die Workflow-Aktion in diesem Fall als datei-bereitstellende Aktion interagiert, kann auf die Datei einfach mit einer datei-konsumierenden Aktion zugegriffen werden (z.B. über Datei ausliefern - Aktion)

MOXIS-Signier-Platzhalter in Formularen

MOXIS Signierplatzhalter lassen sich per JavaScript dynamisch in Formulare einfügen, wenn das Formular beispielsweise im Workflow in ein PDF umgewandelt und anschließend an MOXIS übermittelt werden soll.

Der nachfolgende Quellcode setzt ein Text-Eingabe-Element mit Name tfEmail und ein Container-Element mit Namen div im Formular voraus. Das Inhalt des Feldes tfEmail dient dabei als Identifikator der Person, für die der MOXIS-Platzhalter erstellt werden soll.
Im Container-Element mit Namen div wird anschließend der ermittelte MOXIS-Platzhalter eingebettet. Das Ausführen der Logik wird nach dem Verlassen ("blur"-Event) des Email-Eingabefeldes ausgeführt.

$('[data-name="tfEmail"]').on("blur", () => {
    // Konfigurations-Optionen zur Erstellung eines Platzhalters auf Seiten von MOXIS
    const options = {
            iteration: 0,
            classifier: "EMAIL",
            signerType: "PERSON",
            externalEmail: $('[name=tfEmail]').val(),
            placeHolderSize: "MEDIUM",
            placeHolderText: "",
            signatureType: "EXTERNAL_QSIG",
            signer: $('[name=tfEmail]').val(),
    }

    // Funktion ruft die MOXIS Platzhalter API mit den übergebenen Optionen auf und 
    // fügt das übermittelte JPEG mit dem QR-Platzhalter in die im ersten Parameter übergebene
    // HTML-Element-Referenz als Kind-Element ein.
    // @param elem ein HTML-Container-Element per JQuery referenziert
    // @param options die JSON-Objekt mit den Konfigurations-Parametern für die Platzhalter-Erzeugung 
    $.xutil.moxis.initMoxisPlaceholder($("[data-name=div]"), options);
});