Inhalt
MOXIS ist eine eSignature-Plattform. Sie bietet Signaturworkflows, prozessbasiertes Dokumentenrouting und unterstützt alle rechtlich anerkannten Arten elektronischer Signaturen nach eIDAS und ZertES. Die Plattform stellt für die Integration eine REST API bereit. Diese Dokumentation behandelt Layer 2 dieser API, die primäre Integrationsschnittstelle zum Erstellen und Verwalten von Signatur-Jobs.
1. Kernkonzepte
Job
Ein Job ist ein aktiver Signaturworkflow in MOXIS. Er verbindet ein Dokument, eine Gruppe von in Iterationen organisierten Signierenden und eine Prozesskonfiguration. Sobald ein Job über die API erstellt wurde, erscheint er in der MOXIS-Benutzeroberfläche, damit die zugewiesenen Signierenden tätig werden können. Der eigentliche Signaturschritt wird immer in der MOXIS-Web-Anwendung (bzw. in MOXIS Guest für externe Signierende) durchgeführt, jedoch nicht über die API.
Wenn Sie startProcess aufrufen, liefert MOXIS eine processInstanceId, die diesen Job eindeutig identifiziert. Verwenden Sie diese ID für alle nachfolgenden Operationen zu diesem Job (Statusabfrage, Abrufen des signierten Dokuments, Abbrechen).
Entwurf
Ein Entwurf ist ein unvollständiger Job der erstellt, aber noch nicht gestartet wurde. Verwenden Sie createDraft, wenn Sie einen Job vorab befüllen möchten und ein MOXIS-Benutzer die Zuweisung der Signierenden oder Dokumentdetails in der MOXIS-Benutzeroberfläche finalisieren soll, bevor der Workflow gestartet wird. Der createDraft-Aufruf erfordert weniger Angaben als startProcess. Lediglich der Constituent ist verpflichtend. Sobald ein Benutzer den Entwurf in der MOXIS-Benutzeroberfläche anwendet, wird er zu einem aktiven Job.
Prozess
Ein Prozess ist eine von einem Administrator in MOXIS konfigurierte Workflow-Vorlage. Sie legt fest, welche Signaturtypen zulässig sind, wer Zugriff hat, die Benachrichtigungseinstellungen, das Ablaufverhalten und die Webhook-Endpunkte. Jeder API-Aufruf, der einen Job oder Entwurf erstellt, benötigt eine processId, die angibt, welcher Prozess verwendet werden soll.
Die processId finden Sie im MOXIS-Prozessadministrationsbereich. Bei Business Cloud steht eine feste Menge an Process-IDs zur Verfügung.
processInstanceId
Die
processInstanceId
ist der eindeutige Bezeichner, der beim Erstellen eines Jobs oder Entwurfs zurückgegeben wird. Es handelt sich um eine Zeichenkette im UUID-Format, die als Pfadparameter für alle Operationen auf Job-Ebene erforderlich ist:
GET .../getJobState/<processInstanceId>/...
GET .../getDocument/<processInstanceId>
PUT .../cancelJob/<processInstanceId>
Wenn Sie in den Metadaten der Job-Beschreibung eine
referenceId
angeben, können Sie auch referenzbasierte Endpunkte verwenden, um die
processInstanceId
nicht direkt speichern zu müssen.
2. API-Basis-URL
basis-url/webservices/rest/api/layer2/v1.0
Ersetzen Sie
<basis-url>
durch den Hostnamen Ihrer MOXIS-Instanz. Alle in dieser Dokumentation beschriebenen Endpunkt-Pfade sind relativ zu dieser Basis-URL.
3. HTTP-Antwortcodes
|
Code |
Bedeutung |
|
200 |
OK.
|
|
201 |
Created.
|
|
302 |
Redirect. |
|
400 |
Bad Request.
|
|
404 |
Not Found.
|
|
500 |
Server Error.
|
4. Multipart Form Data
Alle POST-, PUT- und PATCH-Anfragen, die Aufträge erstellen oder ändern, verwenden Multipart Form Data (RFC 7578). Jede Anfrage enthält mindestens zwei Teile:
|
Teilname |
Typ |
Beschreibung |
|
documentToSign |
application/pdf (binär) |
Das zu signierende PDF-Dokument. IDEs und HTTP-Clients kodieren dies in der Regel automatisch Base64. |
|
jobDescription |
JSON-Zeichenkette |
Das Job-Konfigurationsobjekt. Das vollständige Schema finden Sie im Datenmodell. |
|
attachments |
application/pdf (binär, optional) |
Ein oder mehrere Anhang-PDFs. Wird von Endpunkten unterstützt, die Anhänge akzeptieren. |
5. Der typische Signaturablauf
Schritt 1 Job erstellen:
POST
an
startProcess
mit Dokument und Job-Beschreibung. MOXIS liefert eine
processInstanceId.
Schritt 2 Signer werden in MOXIS tätig:
Die zugewiesenen Signierenden erhalten Benachrichtigungen und leisten ihre Signatur in der MOXIS-Web-Anwendung. Externe Signer erhalten einen Link zu MOXIS Guest für externe Signierende. Die API ist am Signaturschritt selbst nicht beteiligt.
Schritt 3 Status abfragen oder Webhook empfangen:
Rufen Sie
getJobState
auf, um den Fortschritt zu prüfen, oder konfigurieren Sie einen Webhook für den Prozess (Enterprise Cloud), um Push-Benachrichtigungen bei Änderungen des Job-Status zu erhalten.
|
Methode |
Vorteile |
Einschränkungen |
|---|---|---|
|
Polling ( |
Einfach, funktioniert überall, keine zusätzliche Infrastruktur nötig |
Verzögerung abhängig vom Poll-Intervall |
|
Webhook |
Push-Benachrichtigung in Echtzeit bei Statusänderung, kein Polling nötig |
Nur Enterprise Cloud |
Schritt 4: Signiertes Dokument abrufen:
Sobald
getJobState
den Status
FINISHED_SUCCESS
meldet, rufen Sie
GET getDocument/<processInstanceId>
auf, um das signierte PDF herunterzuladen. Die Antwort enthält das Dokument als Binärdatei.
Die API führt keine Signaturen durch. Sie erstellt die Signaturanfrage, liefert Statusinformationen und stellt das Ergebnis bereit.
6. API Einschränkungen
Business Cloud und Now Cloud Instanzen verfügen nicht über Webhook-Unterstützung. OAuth 2.0 ist nur in Enterprise-Umgebungen verfügbar. Bei Business Cloud (eIDAS/ZertES) stehen folgende Process-IDs zur Verfügung:
Process-IDs für eIDAS
|
processId |
Name (DE) |
Name (EN) |
Legal basis |
|---|---|---|---|
|
|
Dokument(e) signieren |
Sign document(s) |
eIDAS |
|
|
Dokument(e) signieren |
Sign document(s) |
eIDAS |
|
|
Dokument mit Anhängen signieren |
Sign document with attachments |
eIDAS |
|
|
Dokument mit Anhängen mitsignieren |
Sign documents with attachments |
eIDAS |
|
|
Dokument(e) mit biometrischen Merkmalen signieren |
Sign document(s) with biometric characteristics |
eIDAS |
|
|
Dokument(e) mit externen Anhängen signieren |
Sign document(s) with external attachements |
eIDAS |
|
|
Dokument(e) mit externen Anhängen signieren |
Sign document(s) with external attachements |
eIDAS |
|
|
Dokument(e) mit fortgeschrittener Signatur signieren |
Sign document(s) with an advanced signature |
eIDAS |
|
|
Dokument(e) mit fortgeschrittener Signatur signieren |
Sign document(s) with an advanced signature |
eIDAS |
|
|
Dokument(e) über SMS-Link signieren |
Sign document(s) via SMS link |
eIDAS |
|
|
Dokument(e) über SMS-Link signieren |
Sign document(s) via SMS link |
eIDAS |
Process-IDs für ZertES
|
processId |
Name (DE) |
Name (EN) |
Legal basis |
|---|---|---|---|
|
|
Standardprozess (ZertES) |
Standard process (ZertES) |
ZertES |
|
|
Anhänge mitsignieren (ZertES) |
Sign attachments (ZertES) |
ZertES |
|
|
Dokument(e) mit biometrischen Merkmalen signieren (ZertES) |
Sign document(s) with biometric characteristics (ZertES) |
ZertES |
|
|
Dokument(e) mit externen Anhängen signieren (ZertES) |
Sign document(s) with external attachements (ZertES) |
ZertES |
|
|
Dokument(e) mit fortgeschrittener Signatur signieren (ZertES) |
Sign document(s) with an advanced signature (ZertES) |
ZertES |
|
|
Dokument(e) über SMS-Link signieren (ZertES) |
Sign document(s) via SMS link (ZertES) |
ZertES |
Für ZertES (Schweiz) enden die entsprechenden Prozesse auf ...Zertes. Bei Now Cloud verwenden Sie basicNow, biometry oder extAttachNow.
7. Benutzertypen
MOXIS unterscheidet zwischen zwei Benutzerkategorien: intern und extern. Diese Unterscheidung wirkt sich darauf aus, welche JSON-Klasse Sie in der Job-Beschreibung verwenden, wie sich der Benutzer authentifiziert und welche category-Werte für dessen Iterationen gültig sind. Dies korrekt zu handhaben ist eine der häufigsten Fehlerquellen bei der Integration.
7.1. Interne Benutzer
Interne Benutzer sind Mitarbeiter oder Mitglieder Ihrer Organisation mit regulären, bereitgestellten Konten in MOXIS. Sie werden in der Regel in einem Identitätsverzeichnis wie Microsoft Entra (früher Azure Active Directory) oder einer kompatiblen LDAP-/SAML-/SCIM-Quelle verwaltet.
Merkmale:
-
Zu finden in der MOXIS Administrationsoberfläche
-
Je nachdem, wie Sie die User verwalten, verfügen interne UserInnen über eine E-Mail-Adresse in der Unternehmensdomäne und authentifizieren sich über den Identity Provider (IDP) Ihrer Organisation.
-
Haben MOXIS-Rollen zugewiesen (siehe Rollen und Berechtigungen).
-
Signieren Dokumente in der MOXIS-Web-Anwendung, nachdem Sie sich authentifiziert haben.
Identifikatoren:
Interne Benutzer können über EMAIL, ID (MOXIS-Benutzer-ID) oder UPN (User Principal Name) identifiziert werden. Setzen Sie das Feld classifier entsprechend.
Der User Principal Name ist der Login-Name eines Benutzers in Azure AD / Microsoft Entra ID, meist im Format
vorname.nachname@domain.com
(Der Wert sieht oft wie die E-Mail-Adresse aus, muss es aber nicht zwingend sein. So ist in Entra der UPN in der Regel die ObjectID, also ein Hash-Wert. Datenbanknutzer:innen haben in der Regel als UPN die E-Mailadresse.).
JSON-Klasse:
com.xitrust.moxispe.api.User
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "jane.doe@example.com"
}
Für Gruppenplatzhalter verwenden Sie
com.xitrust.moxispe.api.UserForRole
{
"@class": "com.xitrust.moxispe.api.UserForRole",
"classifier": "UPN",
"name": "jane.doe@example.com",
"roleName": "teamLeader"
}
Für die Zuweisung von Adobe-PDF-Signaturfeldern verwenden Sie
com.xitrust.moxispe.api.UserForSignatureField.
7.2. Externe Benutzer
Externe Benutzer sind Gäste, Auftragnehmer, Kunden oder jede Person, die kein reguläres MOXIS-Konto besitzt. Sie werden eingeladen, ein bestimmtes Dokument zu signieren, und greifen nur zu diesem Zweck auf MOXIS zu.
Merkmale:
-
Kein bestehendes Konto in MOXIS oder im IDP Ihrer Organisation.
-
Optional: Authentifizieren sich über einen Einmalmechanismus: SMS-TAN oder OTP.
-
Greifen über einen eindeutigen Link (externalSignerUrl) auf das Dokument zu, der zu MOXIS Guest für externe Signierende führt, einer vereinfachten Signaturoberfläche.
-
Können in der Regel über EMAIL identifiziert werden. Die Classifier ID und UPN sind nicht anwendbar.
JSON-Klasse:
com.xitrust.moxispe.api.ExternalUser
{
"@class": "com.xitrust.moxispe.api.ExternalUser",
"classifier": "EMAIL",
"name": "contractor@external.com",
"roleName": "External",
"locale": "de",
"phoneNumber": "+43000123456",
"externalUserName": "Max Contractor"
}
|
Feld |
Erforderlich |
Beschreibung |
|
@class |
Ja |
Muss ExternalUserForRole oder ExternalUser sein |
|
classifier |
Ja |
Bei externen Benutzern immer EMAIL |
|
name |
Ja |
Die E-Mail-Adresse des externen Benutzers |
|
roleName |
Ja |
Die in MOXIS konfigurierte externe Gruppe/Rolle (z. B. "External") |
|
externalUserName |
Ja |
Der in der Signaturoberfläche angezeigte Anzeigename |
|
locale |
Nein |
Sprache für die Einladungs-E-Mail und die Signaturoberfläche (z. B. "de", "en") |
|
phoneNumber |
Nein |
Erforderlich für die SMS-TAN-Authentifizierung; inklusive Landesvorwahl |
Eine vollständige Liste der @class-Werte und deren Verwendung finden Sie unter Benutzerklassen.
7.4. Abrufen der externen Signer-URL
Sobald ein Auftrag mit einem externen Signierenden erstellt wurde, erhält dieser eine Einladungsmail. Sie können zusätzlich
getJobState
aufrufen, um die
externalSignerUrl
abzurufen und diese dann mit dem externen Benutzer zu teilen. Sie führt ihn zu MOXIS Guest für externe Signierende, wo er sich authentifizieren und seine Signatur abschließen kann.
{
"@class": "com.xitrust.moxispe.api.ExternalSigner",
"externalSignerUrl": "https://<moxis-base-url>/guest/job/de4f783c-99d0-4678-a513-b8e5eecfc11a",
"externalDownloadUrl": "https://<moxis-base-url>/guest/job/de4f783c-99d0-4678-a513-b8e5eecfc11a"
}
Die
externalSignerUrl
ist nur für die aktuelle Iteration gültig. Sobald diese Iteration abgeschlossen ist und der Auftrag fortschreitet, kann nicht mehr signiert werden. Der Link bleibt jedoch gültig. So können Signierende das Dokument aufrufen und herunterladen.
Zusammenfassung
|
|
Interner Benutzer |
Externer Benutzer |
|
Konto in MOXIS |
Ja |
Nein |
|
Authentifizierung |
IDP (Entra / SAML) |
SMS-TAN / OTP |
|
Signaturoberfläche |
MOXIS-Web-Anwendung |
MOXIS Guest für externe Signierende |
|
Identifikator-Classifier |
EMAIL, UPN oder ID |
EMAIL oder ID |
|
@class (Basis) |
com.xitrust.moxispe.api.User |
com.xitrust.moxispe.api.ExternalSigner |
|
Iterationskategorie |
APPROVAL, QSIG |
EXTERNAL_APPROVAL, EXTERNAL_QSIG |
8. Signaturqualitäten
MOXIS unterstützt zwei übergeordnete Signaturkategorien:
APPROVAL und QSIG.
Die im iterationData-Array angegebene Kategorie bestimmt die rechtliche Verbindlichkeit der Signatur, den verwendeten Authentifizierungsmechanismus und die für das Konto des Signers erforderlichen Rollen.
8.1. APPROVAL
Die Kategorie APPROVAL umfasst alle Signaturtypen, die einen persönlichen Bezug zu einem Signer aufweisen, aber keine qualifizierte digitale Identität erfordern:
-
Einfache elektronische Signatur (SES):
Eine einfache digitale Freigabe.
-
Fortgeschrittene elektronische Signatur (AES)
Eine erweiterte Signatur mit stärkerer Identifikation des Signierenden.
8.2. QSIG
Die Kategorie QSIG umfasst die persönliche qualifizierte elektronische Signatur (QES). Dies ist die höchste rechtlich anerkannte Form der elektronischen Signatur – sie ist einer handschriftlichen Unterschrift nach eIDAS vollständig gleichgestellt. Die Verwendung von QSIG setzt voraus, dass der Signierende über eine gültige digitale Identität verfügt (ein von einem Trust Center ausgestelltes qualifiziertes Zertifikat). Informationen zum Erwerb einer digitalen Identität finden Sie in den MOXIS-FAQ zu digitalen Identitäten.
Der Signierende muss in MOXIS mindestens die Rolle moxisSigner zugewiesen haben.
8.3. Weitere Typen
Qualifiziertes Firmensiegel (ZertES / Schweizer Recht)
Nach dem schweizerischen ZertES-Gesetz unterscheidet sich ein „geregeltes Siegel” vom eIDAS-Firmensiegel. MOXIS kann so konfiguriert werden, dass ein Token abgerufen und dieser Siegeltyp angebracht wird. Die Einrichtung erfordert jedoch eine Abstimmung mit MOXIS. Wenden Sie sich für Details an servicedesk@xitrust.com.
MOXIS eStamp
eStamp ist ein automatischer Signaturdienst, der eine Signatur ohne Bezug zu einer bestimmten Person anbringt. Typische Anwendungsfälle sind die Sicherstellung der Unveränderlichkeit eines Dokuments oder das Anbringen eines qualifizierten Zeitstempels zur Archivierung. MOXIS bietet dies als separaten Dienst an (den automatischen PDF-Signaturdienst); er ist nicht Teil dieser API.
8.4. Category-Werte in iterationData
Setzen Sie das Feld category jedes Iterationsobjekts auf einen der folgenden Werte:
|
Wert |
Beschreibung |
|
QSIG |
Qualifizierte elektronische Signatur, interner Signierender |
|
EXTERNAL_QSIG |
Qualifizierte elektronische Signatur, externer Signierender |
|
APPROVAL |
Einfache oder fortgeschrittene elektronische Signatur, interner Signierender |
|
EXTERNAL_APPROVAL |
Einfache oder fortgeschrittene elektronische Signatur, externer Signierender |
|
APPROVAL_NOSIG |
Nur Workflow-Freigabe: der Schritt wird geroutet und protokolliert, es wird jedoch keine Signatur auf dem Dokument angebracht. Bitte beachten Sie: Die Freigabe ist nur intern verfügbar. |
Die Unterscheidung zwischen
INTERNAL und EXTERNAL
entspricht direkt dem Benutzertyp des eingeladenen Signierenden in dieser Iteration. Verwenden Sie eine EXTERNAL_*-Kategorie, wenn ein beliebiger Eingeladener in der Iteration ein externer Signierender ist; verwenden Sie andernfalls die Kategorie ohne Präfix für interne Benutzer. Eine Iteration kann keine internen und externen Benutzertypen mischen. Sollten Sie beide benötigen, verwenden Sie separate Iterationen.
8.5. Beispiel — einzelne APPROVAL-Iteration
{
"constituent": {
"classifier": "UPN",
"name": "max.test@example.com",
"@class": "com.xitrust.moxispe.api.User"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "UPN",
"name": "max.test@example.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
9. Visualisierung
Die Visualisierung bestimmt, wie eine abgeschlossene Signatur auf dem signierten PDF erscheint. MOXIS unterstützt fünf Positionstypen, die von keinem sichtbaren Stempel bis hin zu präzise positionierten Stempeln mit vollständiger Koordinatenkontrolle reichen. Der Positionstyp wird über das Feld positionType in der JSON-Job-Beschreibung festgelegt. Er ist optional - wird er ausgelassen, wird standardmäßig
ON_PLACEHOLDER
verwendet.
9.1. Positionstypen
|
positionType |
Beschreibung |
Am besten geeignet für |
|
INVISIBLE |
Es wird kein sichtbarer Stempel auf dem Dokument angebracht. Die Signatur wird in den Metadaten des PDFs erfasst und ist durch PDF-Validierungstools erkennbar, es gibt jedoch keine sichtbare Markierung. |
QES-Compliance-Workflows, erste Integrationsversuche, Fälle, in denen keine visuelle Platzierung erforderlich ist |
|
SIGNATURE_PAGE |
MOXIS fügt dem signierten Dokument automatisch eine letzte Seite mit allen Signaturstempeln hinzu. Das Seitendesign ist in MOXIS vorkonfiguriert. |
Einfacher visueller Nachweis der Signatur, ohne dass Dokumentlayout oder Koordinaten bekannt sein müssen |
|
ON_PLACEHOLDER |
Vor dem Einreichen muss ein von MOXIS generiertes Platzhalterbild in das PDF eingebettet werden. MOXIS parst das Dokument, findet den Platzhalter und platziert dort den Signaturstempel. Dies ist die Standardeinstellung, wenn positionType nicht angegeben ist. |
Flexibles Dokumentdesign, bei dem Signierende oder Auftraggeber die Stempelplatzierung vorab bestimmen |
|
DIRECT_POSITION |
Die Koordinaten des Signaturstempels werden im API-Aufruf über das Objekt directUserPosition bei jedem Invitee angegeben. Auch haben externe Signierende die Möglichkeit, die Visualisierung selbst zu platzieren. |
Programmatische Platzierung, bei der Ihre Anwendung die genaue Position jedes Stempels steuert |
|
SIGNATURE_FIELD |
Der Signaturstempel wird in einem im Dokument bereits eingebetteten Adobe-Acrobat-PDF-Signaturfeld platziert. |
Strukturierte Formulare mit vordefinierten Signaturfeldern |
Wird positionType auf oberster Ebene der Job-Beschreibung gesetzt, gilt dies für alle Signer. Einzelne Signer können dies über directUserPosition mit benutzerspezifischen Koordinaten überschreiben.
9.2. Platzhalter
Platzhalter sind kleine, von MOXIS generierte Bilder (GET /getPlaceholder), die die Identität des Signers und die Iterationsdaten sowohl in EXIF-Metadaten als auch in einem QR-Code kodieren. Wird ein Dokument, das diese Bilder enthält, mit
ON_PLACEHOLDER
an MOXIS übermittelt, parst die Plattform sie automatisch und weist jede Signaturposition entsprechend zu.
Personalisierte Platzhalter
Ein personalisierter Platzhalter ist mit einem bestimmten Benutzer und einer bestimmten Iterationsnummer verknüpft. Ein Platzhalter für „Jane Doe, Iteration 0” kodiert beispielsweise Janes Identität und die Iteration. Wenn Jane signiert, erscheint ihr Stempel an der Position des Platzhalters.
Personalisierte Platzhalter erfordern keine zusätzlichen Angaben im iterationData-JSON - das Platzhalterbild selbst enthält die notwendigen Informationen.
Gruppenplatzhalter
Ein Gruppenplatzhalter ist mit einer MOXIS-Gruppe verknüpft und nicht mit einer bestimmten Person. Jedes berechtigte Mitglied der Gruppe kann den Platzhalter beanspruchen und signieren. Gruppenplatzhalter erfordern das Feld signerGroup in den Iterationsdaten, um anzugeben, zu welcher Gruppe der Platzhalter gehört.
Sind in derselben Iteration mehrere Gruppenplatzhalter vorhanden, wird jeder Platzhalter durch eine Signatur verbraucht. MOXIS verwendet eine Signatur pro Platzhalter. Erscheinen in derselben Iteration mehrere personalisierte Platzhalter für denselben Signierenden, wird die einzelne Signatur an jeder Platzhalterposition visualisiert.
Sie können personalisierte und Gruppenplatzhalter kombinieren, sie müssen sich jedoch in separaten Iterationen befinden.
9.3. DIRECT_POSITION-Koordinaten
Bei Verwendung von
DIRECT_POSITION
fügen Sie bei jedem eingeladenen Signierenden im
iterationData-Array ein Objekt directUserPosition
hinzu. Alle Koordinatenwerte sind Fließkommazahlen.
|
Feld |
Typ |
Beschreibung |
|
x |
int |
Horizontale Position des Stempels, gemessen vom linken Seitenrand in Punkten |
|
y |
int |
Vertikale Position des Stempels, gemessen vom unteren Seitenrand in Punkten |
|
width |
int |
Breite des Signaturstempels in Punkten |
|
height |
int |
Höhe des Signaturstempels in Punkten |
|
pageNumber |
int |
Seitenzahl (beginnend bei 1), auf der der Stempel platziert werden soll |
Beispiel
{
"positionType": "DIRECT_POSITION",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@example.com",
"directUserPosition": {
"x": "50",
"y": "100",
"width": "160",
"height": "100",
"pageNumber": 1
}
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
9.4. Auswahl eines Positionstyps
Wenn Sie zum ersten Mal integrieren, verwenden Sie
INVISIBLE.
Er erfordert keine Kenntnis des Dokumentlayouts und ist immer erfolgreich, solange der Job korrekt konfiguriert ist. Wechseln Sie zu
SIGNATURE_PAGE
oder
DIRECT_POSITION,
sobald Ihre grundlegende Integration funktioniert und Sie einen visuellen Nachweis der Signatur benötigen.
10. Iterationen
Eine Iteration ist eine Signaturrunde in einem MOXIS-Workflow. Iterationen sind geordnet: Iteration 0 muss vollständig abgeschlossen sein, bevor Iteration 1 beginnt, Iteration 1 vor Iteration 2, und so weiter. So können Sie sequenzielle Freigabeketten modellieren. So ist es denkbar, dass zunächst ein Manager seine Freigabe gibt, dann signiert eine Gegenpartei.
Mehrere Signierende innerhalb derselben Iteration signieren parallel. MOXIS benachrichtigt alle gleichzeitig und wartet, bis jeder Einzelne tätig geworden ist, bevor zur nächsten Iteration übergegangen wird.
10.1. Struktur
Jedes Objekt im iterationData-Array stellt eine Iteration dar. Drei Felder sind verpflichtend:
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
iterationNumber |
int |
Ja |
Nullbasierter Index. Die erste Iteration ist 0, die zweite 1 usw. |
|
category |
string |
Ja |
Signaturtyp für diese Iteration. Gültige Werte finden Sie unter Signaturqualitäten. |
|
invitees |
array |
Ja |
Ein oder mehrere Benutzerobjekte, die die Signer bzw. Freigebenden dieser Iteration darstellen. |
Die Iterationsnummerierung muss sequenziell sein und bei 0 beginnen. Lücken in der Sequenz werden nicht unterstützt.
10.2. Paralleles Signieren innerhalb einer Iteration
Enthält invitees mehr als einen Benutzer, werden alle gleichzeitig benachrichtigt. Alle müssen ihre Aktion abschließen, bevor MOXIS zur nächsten Iteration übergeht. Dies ist paralleles Signieren innerhalb einer einzelnen Iteration.
{
"iterationNumber": 0,
"category": "APPROVAL",
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer-a@example.com"
},
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer-b@example.com"
}
]
}
Sowohl signer-a als auch signer-b müssen signieren, bevor MOXIS fortfährt.
10.3. Optionale Iterationsfelder
|
Feld |
Typ |
Beschreibung |
|
numberOfSignatures |
int |
Für Gruppensignaturen: gibt an, wie viele Mitglieder der Gruppe signieren müssen. Hat eine Gruppe 5 Mitglieder und numberOfSignatures ist auf 2 gesetzt, ist die Iteration abgeschlossen, sobald 2 beliebige Mitglieder signiert haben. |
|
remark |
string |
Ein an diese Iteration angehängter Textvermerk, der für Signer in der MOXIS-Benutzeroberfläche sichtbar ist. |
|
privateIteration |
bool |
Ist dieser Wert true, wird diese Iteration vor Beobachtern und Vertretern verborgen. Nur die zugewiesenen Signer und der Job-Owner sehen sie. |
|
signerGroup |
string |
Referenziert eine MOXIS-Gruppe bei Verwendung der Gruppenplatzhalter-Visualisierung. Muss mit einem in MOXIS konfigurierten, bestehenden Gruppennamen übereinstimmen. |
|
groupPosition |
array |
Definiert die visuelle Position des Signaturstempels der Gruppe bei Verwendung der Gruppenvisualisierung. Enthält DirectSignaturePosition-Objekte. |
|
customMap |
object |
Beliebige Schlüssel-Wert-Paare, die dieser Iteration angehängt werden. Nützlich, um externe Referenzdaten durch den Workflow zu leiten. Format: {"key": "value"}. |
10.4. Beispiel: Workflow mit zwei Iterationen
Dieses Beispiel modelliert ein gängiges Unternehmensmuster: Ein interner Mitarbeiter signiert in der ersten Runde mit QES, gefolgt von einer externen Gegenpartei, die eine Freigabesignatur leistet.
{
"constituent": {
"classifier": "UPN",
"name": "employee@example.com",
"@class": "com.xitrust.moxispe.api.User"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"iterationNumber": 0,
"category": "QSIG",
"invitees": [
{
"@class": "com.xitrust.moxispe.api.UserForRole",
"classifier": "UPN",
"name": "employee@example.com",
"roleName": "moxisSigner"
}
]
},
{
"iterationNumber": 1,
"category": "EXTERNAL_APPROVAL",
"invitees": [
{
"@class": "com.xitrust.moxispe.api.ExternalUserForRole",
"classifier": "EMAIL",
"name": "contractor@external.com",
"roleName": "External",
"locale": "en",
"phoneNumber": "+43000123456",
"externalUserName": "Alex Contractor"
}
]
}
]
}
Iteration 0 ist abgeschlossen, sobald employee@example.com mit seiner qualifizierten Signatur signiert. Erst dann benachrichtigt MOXIS contractor@external.com und stellt das Dokument in MOXIS Guest für externe Signierende zur Freigabe bereit.
10.5. Gruppensignatur mit numberOfSignatures
Wenn Sie in invitees mithilfe von UserForRole mit einem Gruppen-roleName eine Gruppe konfigurieren, können Sie mit numberOfSignatures festlegen, wie viele Mitglieder signieren müssen. Wird das Feld ausgelassen, müssen alle Gruppenmitglieder signieren.
{
"iterationNumber": 0,
"category": "APPROVAL",
"numberOfSignatures": 2,
"signerGroup": "ManagementGroup",
"invitees": [
{
"@class": "com.xitrust.moxispe.api.UserForRole",
"classifier": "UPN",
"name": "manager@example.com",
"roleName": "ManagementGroup"
}
]
}
Wenn zwei Mitglieder von ManagementGroup in beliebiger Reihenfolge signieren, ist diese Iteration abgeschlossen.
11. Rollen und Berechtigungen
MOXIS verwendet ein rollenbasiertes Zugriffskontrollsystem. Jeder interne Benutzer, der an einem Signaturworkflow beteiligt ist (sei es als Owner, Freigebender oder Signierender) muss über die entsprechenden MOXIS-Rollen verfügen. Die API selbst erzwingt Rollen nicht auf HTTP-Ebene, doch falsche Rollenzuweisungen sind eine häufige Ursache für 500-Fehler, nachdem ein Job angenommen wurde.
11.1. Erforderliche MOXIS-Basisrollen
Diese Rollen sind systemweit angelegt und steuern, was ein Benutzer in MOXIS tun darf. Sie unterscheiden sich von benutzerdefinierten Gruppen, die den Zugriff auf bestimmte Prozesse steuern.
|
Rolle |
Erforderlich für |
|
moxisUser |
Anmeldung an der MOXIS-Weboberfläche. Alle internen Benutzer benötigen diese Rolle. |
|
moxisApprover |
Signieren von Dokumenten unter der Kategorie APPROVAL oder EXTERNAL_APPROVAL. |
|
moxisSigner |
Signieren von Dokumenten unter der Kategorie QSIG oder EXTERNAL_QSIG (qualifizierte elektronische Signaturen). |
|
moxisOwner |
Erstellen von Jobs über ein Benutzerkonto. Der in Ihren API-Aufrufen referenzierte Constituent (Job-Owner) muss über diese Rolle verfügen. |
Ist ein Benutzer als Invitee in einer QSIG-Iteration gelistet, verfügt aber nicht über die Rolle moxisSigner, führt dies zu einem Fehler bei der Erstellung.
Liefert ein API-Aufruf 500 und die Struktur der Anfrage ist korrekt, prüfen Sie, ob der Constituent und alle Invitees über die erforderlichen Basisrollen verfügen.
11.2. Benutzerdefinierte Rollen (Gruppen)
Über die Basisrollen hinaus unterstützt MOXIS benutzerdefinierte Rollen (oder Gruppen), die steuern, auf welche Prozesse und Funktionen bestimmte Benutzer zugreifen können. Ein Prozess kann beispielsweise so konfiguriert sein, dass nur Mitglieder einer bestimmten Gruppe Jobs innerhalb dieses Prozesses erstellen oder signieren dürfen.
Benutzerdefinierte Gruppen werden in der Job-Beschreibung über das Feld
roleName
bei Benutzerobjekten und das Feld
signerGroup
bei Iterationen referenziert.
11.2.1. Verwaltung benutzerdefinierter Rollen
Es gibt zwei Möglichkeiten, Gruppenzuweisungen zu verwalten:
Über ein externes Identity-Management-System (IDM)
Dies ist der Standardansatz in Unternehmensumgebungen. Unterstützte Protokolle sind LDAP, SAML und SCIM. Gruppen werden in Ihrem IDM (z. B. Microsoft Entra) verwaltet und automatisch mit MOXIS synchronisiert. Dies ist die empfohlene Methode für große Benutzerpopulationen.
Über die MOXIS-Administrationsoberfläche
Administratoren können benutzerdefinierte Gruppen direkt im MOXIS-Benutzerverwaltungsbereich anlegen und zuweisen. Dies eignet sich für kleinere Implementierungen oder zur Verwaltung von Gruppen, die in keinem externen IDM existieren.
Wichtige Unterschiede
-
Basisrollen (moxisUser, moxisApprover, moxisSigner, moxisOwner) sind für jede Benutzeraktion erforderlich. Ohne sie kann der Benutzer überhaupt nicht mit MOXIS interagieren.
-
Benutzerdefinierte Gruppen gewähren oder beschränken den Zugriff auf bestimmte Prozesse, Funktionen oder Signaturkontexte. Ein Benutzer kann über die Basisrollen verfügen und trotzdem von einem bestimmten Prozess ausgeschlossen sein, wenn ihm die erforderliche Gruppenmitgliedschaft fehlt.
-
Nur interne Benutzer können in der API über einen Gruppennamen referenziert werden. Externe Benutzer nehmen nicht an der gruppenbasierten Zugriffskontrolle von MOXIS teil.
Diagnose von Rollenfehlern
|
Symptom |
Wahrscheinliche Ursache |
|
500 bei getJobState oder während des Signierens |
Dem Signer oder Constituent fehlt eine erforderliche Basisrolle |
|
Invitee erhält nie eine Signaturbenachrichtigung |
Die E-Mail-Adresse des Invitees ist falsch |
Bei Fragen zur Rollenkonfiguration wenden Sie sich an servicedesk@xitrust.com.