MOXIS API Dokumentation
German English

MOXIS API: Kernkonzepte, Job-Management und Benutzerrollen

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.
Anfrage erfolgreich.

201

Created.
Der Job oder Entwurf wurde erfolgreich erstellt. Dies ist die Standard-Erfolgsantwort für startProcess und createDraft.

302

Redirect.

400

Bad Request.
Die Struktur des API-Aufrufs ist fehlerhaft, oder der referenzierte Dienst bzw. Prozess ist inaktiv.

404

Not Found.
Die angegebene processInstanceId, referenceId oder processId existiert in MOXIS nicht.

500

Server Error.
Ein Objekt konnte während der Verarbeitung nicht gefunden werden oder wurde mit einem falschen Klassentyp referenziert. Häufige Ursachen: falscher @class-Wert im JSON-Body, fehlende Rollen bei einem Benutzer, oder Verweis auf einen nicht existierenden Signer.

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 (getJobState)

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

basicNow

Dokument(e) signieren

Sign document(s)

eIDAS

moxisStdMultiEidas

Dokument(e) signieren

Sign document(s)

eIDAS

containerNow

Dokument mit Anhängen signieren

Sign document with attachments

eIDAS

moxisContainerEidas

Dokument mit Anhängen mitsignieren

Sign documents with attachments

eIDAS

biometry

Dokument(e) mit biometrischen Merkmalen signieren

Sign document(s) with biometric characteristics

eIDAS

extAttachNow

Dokument(e) mit externen Anhängen signieren

Sign document(s) with external attachements

eIDAS

extAttachEidas

Dokument(e) mit externen Anhängen signieren

Sign document(s) with external attachements

eIDAS

accProtNow

Dokument(e) mit fortgeschrittener Signatur signieren

Sign document(s) with an advanced signature

eIDAS

accProtEidas

Dokument(e) mit fortgeschrittener Signatur signieren

Sign document(s) with an advanced signature

eIDAS

smsLinkNow

Dokument(e) über SMS-Link signieren

Sign document(s) via SMS link

eIDAS

smsLinkEidas

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

moxisStdMultiZertes

Standardprozess  (ZertES)

Standard process  (ZertES)

ZertES

moxisContainerZertes

Anhänge mitsignieren (ZertES)

Sign attachments (ZertES)

ZertES

biometryZertes

Dokument(e) mit biometrischen Merkmalen signieren (ZertES)

Sign document(s) with biometric characteristics (ZertES)

ZertES

extAttachZertes

Dokument(e) mit externen Anhängen signieren (ZertES)

Sign document(s) with external attachements (ZertES)

ZertES

accProtZertes

Dokument(e) mit fortgeschrittener Signatur signieren (ZertES)

Sign document(s) with an advanced signature (ZertES)

ZertES

smsLinkZertes

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.