MOXIS API Dokumentation
German English

MOXIS API: Datenmodell-Referenz

Inhalt

Dieses Kapitel beschreibt die zentralen MOXIS-API-Objekte zur Erstellung, Konfiguration und Nachverfolgung von Signierjobs: von Auftraggeber, jobDescription und Metadaten über Iterationen, Invitees, Formularfelder und zusätzliche Empfänger bis zur Job-Status-Antwort. Es erklärt die wichtigsten Felder, Klassen, Statuswerte und Beispielstrukturen, damit Integrationen Signaturprozesse korrekt modellieren, starten und überwachen können.


1. Constituent

Das Feld constituent identifiziert den MOXIS-Benutzer, dem der Job oder Entwurf gehört (der Auftraggeber). Durch die Angabe des Auftraggebers wird der Job in dessen Namen erstellt. Der Job erscheint im MOXIS-Dashboard dieses Benutzers, er erhält die zum Job gehörenden E-Mail-Benachrichtigungen, und sämtliche für den Prozess konfigurierten Rechte oder Berechtigungen gelten für ihn.

Der Auftraggeber ist immer ein interner MOXIS-User. Externe Signierende können keine Jobs “besitzen”. Die @class ist immer com.xitrust.moxispe.api.User.

1.1. Felder

Feld

Typ

Erforderlich

Beschreibung

@class

String

Ja

Immer com.xitrust.moxispe.api.User.

classifier

String

Ja

Legt fest, wie der Benutzer identifiziert wird. Siehe Classifier-Werte unten.

name

String

Ja

Der Identifikationswert, der dem gewählten Classifier entspricht.

Classifier-Werte

Classifier

Beschreibung

Hinweise

EMAIL

E-Mail-Adresse des Benutzers

Funktioniert sowohl für interne als auch für externe Benutzer. Maximal ein EMAIL-Classifier pro Benutzerobjekt.

ID

Interne MOXIS-Benutzer-ID

Nur für interne Benutzer.

UPN

User Principal Name

Nur für interne Benutzer. Wird typischerweise von einem Identity Provider wie Microsoft Entra (ehemals Azure AD) bereitgestellt.

1.2. Beispiele

Verwendung von EMAIL

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "EMAIL",
    "name": "max.mustermann@example.com"
  }
}

Verwendung von UPN

UPN ist der bevorzugte Classifier in Unternehmensumgebungen, in denen Benutzer über einen externen Identity Provider verwaltet werden.

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "UPN",
    "name": "max.mustermann@example.com"
  }
}

1.3. Verwandte Seiten

  • jobDescription: übergeordnetes Objekt

  • Benutzerklassen: @class-Werte für Invitee (Signer/Genehmiger)

2. jobDescription

jobDescription ist ein JSON-Objekt, das als jobDescription-Teil eines Multipart-Formularbodys in den API-Aufrufen POST createDraft und POST startProcess (createJob) übergeben wird. Es teilt MOXIS mit, wem der Job gehört, wer ihn unterzeichnen soll, in welcher Reihenfolge und wie die Signaturen visualisiert werden sollen.

Ein minimaler Entwurf benötigt nur Constituent. Ein vollständiger Signierauftrag erfordert zusätzlich iterationData mit mindestens einer Iteration und deren Invitees.

2.1. Felder der obersten Ebene

Feld

Typ

Erforderlich

Beschreibung

constituent

Object

Ja

Der MOXIS-Benutzer, dem der Job gehört (der Auftraggeber). Siehe Constituent.

positionType

String

Nein

Steuert die Signaturvisualisierung. Standard: ON_PLACEHOLDER. Siehe Werte unten.

metaData

Object

Nein

Job-Metadaten: Beschreibung, Referenz-ID, Ablaufdatum, benutzerdefinierte Daten. Siehe Job-Metadaten.

iterationData

Array

Für Aufträge erforderlich, für Entwürfe optional

Geordnetes Array der Signierrunden. Siehe Iterationsdaten.

additionalRecipients

Array

Nein

Benutzer, die Benachrichtigungen/Dokumente erhalten, aber nicht unterzeichnen. Siehe Zusätzliche Empfänger.

Werte für positionType

Wert

Beschreibung

ON_PLACEHOLDER

Standard. Die Signatur wird auf einem vorab positionierten Platzhalterbild im PDF platziert.

INVISIBLE

Keine visuelle Kennzeichnung im Dokument. Die Signatur ist kryptografisch vorhanden und überprüfbar. Für die erste Integration und zum Testen empfohlen.

SIGNATURE_PAGE

MOXIS fügt als letzte Seite des signierten Dokuments eine eigene Signaturseite an.

SIGNATURE_FIELD

Die Signatur wird in einem eingebetteten Adobe-Acrobat-Formularfeld platziert. Erfordert die Klasse UserForSignatureField. (siehe Formularfelder).

DIRECT_POSITION

Die Koordinaten sind ein Pflichtfeld für interne UserInnen. Ohne Koordinaten wird die Visualisierung von den externen EmpfängerInnen selbst platziert

2.3. Beispiel

Das folgende Beispiel zeigt eine vollständige jobDescription mit allen befüllten Feldern der obersten Ebene — einem internen QES-Signer in Iteration 0, einem externen Genehmigungs-Signer in Iteration 1, Job-Metadaten mit einer Referenz-ID und einem zusätzlichen Empfänger.

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "UPN",
    "name": "max.mustermann@example.com"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Q1 Contract Review",
    "referenceId": "ERP-ORDER-98765",
    "expirationDate": "2026-12-31T23:59:59+00:00",
    "customMap": {
      "department": "legal",
      "contractType": "vendor"
    }
  },
  "iterationData": [
    {
      "iterationNumber": 0,
      "category": "QSIG",
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "UPN",
          "name": "max.mustermann@example.com",
          "roleName": "moxisSigner"
        }
      ]
    },
    {
      "iterationNumber": 1,
      "category": "EXTERNAL_APPROVAL",
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "partner@external.com",
          "externalUserName": "Partner Contact",
          "roleName": "Extern",
          "locale": "en",
          "phoneNumber": "+43123456789"
        }
      ]
    }
  ],
  "additionalRecipients": [
    {
      "@class": "com.xitrust.moxispe.api.Recipient",
      "addressBookEntry": {
        "@class": "com.xitrust.moxispe.api.AddressBookEntry",
        "name": "Roland Referent",
        "email": "roland.referent@example.com",
        "phoneNumber": "+436641234567",
        "locale": "de"
      }
    }
  ]
}

2.4.Verwandte Seiten

  • Constituent: Das Objekt des Job-Auftraggebers

  • Iterationsdaten: Signierrunden und Eingeladene

  • Job-Metadaten: Beschreibung, Referenz-ID, benutzerdefinierte Daten

  • Benutzerklassen: Alle @class-Werte für Eingeladene

  • Zusätzliche Empfänger: Nicht signierende Empfänger

  • Formularfelder: Unterstützung für Adobe-Acrobat-Formularfelder

3. Job-Metadaten

Das Objekt metaData ist ein optionales Feld der obersten Ebene in der jobDescription. Es enthält beschreibende und operative Informationen zum Job (sichtbare Beschriftungen, Integrationsreferenzen, Ablaufdatum und Zugriffskontrollen) für externe Signierende.

3.1. Felder

Feld

Typ

Beschreibung

description

String

Lesbare Beschriftung des Jobs. Sichtbar im MOXIS-Dashboard.

category

String

Vom Prozess vorgegebene Kategoriebezeichnung. Die Werte werden vom MOXIS-Administrator vorkonfiguriert und können je nach Prozess erforderlich sein.

expirationDate

String

ISO-8601-Zeitstempel im Format yyyy-MM-ddTHH:mm:ssTZD. Bestimmt, wie lange der Job in MOXIS aktiv bleibt, bevor er automatisch geschlossen wird. Beispiel: 2026-12-31T23:59:59+00:00.

referenceId

String

Ihre eigene Kennung aus einem Drittsystem (z. B. eine ERP-Bestellnummer). Wird in der MOXIS-Benutzeroberfläche nicht angezeigt, ist aber über die *ByReferenceId-API-Methoden für Abfragen verfügbar. Sollte eindeutig sein; die Eindeutigkeit wird von MOXIS bei der Erstellung nicht erzwungen.

externalPassword

String

Einmalpasswort für externe Signer, die über MOXIS Guest (MOGU) auf den Job zugreifen, wenn keine Telefonnummer für die SMS-TAN-Authentifizierung verfügbar ist.

customMap

Object

Beliebige Schlüssel-Wert-Paare, die dem Job zugeordnet werden. Verfügbar in der Job-Status-Antwort und nutzbar, um strukturierte Daten aus Ihrem System an MOXIS zu übergeben. Kann auch pro Iteration festgelegt werden - siehe Iterationsdaten.

3.2. Beispiel

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "EMAIL",
    "name": "user.name@example.com"
  },
  "metaData": {
    "description": "Demo CustomMap",
    "referenceId": "Ref123456",
    "expirationDate": "2026-12-31T23:59:59+00:00",
    "category": "vendor-contracts",
    "customMap": {
      "ID": "123",
      "key": "value",
      "status": "active",
      "changed": true
    }
  }
}

3.3. Hinweise zu referenceId

Sobald eine

referenceId 

festgelegt ist, können Sie die folgenden API-Methoden verwenden, um Jobdaten abzurufen, ohne die von MOXIS generierte

processInstanceId

zu benötigen:

GET getJobStateByReferenceId/{referenceId}/{nameClassifier}

GET getDocumentByReferenceId/{referenceId}

GET getAttachmentsByReferenceId/{referenceId}

GET getMultisignDocumentsByReferenceId/{referenceId}

GET lookupJobStates?referenceId={referenceId}

3.4. Verwandte Seiten

  • jobDescription: Übergeordnetes Objekt

  • Iterationsdaten: customMap je Iteration

  • Job-Status-Antwort: jobMetaData in der Antwort

4. Job-Status-Antwort

Die Job-Status-Antwort wird von

GET getJobState 

und

GET getJobStateByReferenceId 

zurückgegeben. Dieselbe Struktur wird von Webhooks übermittelt, wenn ein Job-Status-Ereignis ausgelöst wird. Sie liefert eine vollständige Momentaufnahme des Jobs zu diesem Zeitpunkt, einschließlich des aktuellen Signaturstatus, aller Iterationsdetails und der URLs für Signer.

4.1. Felder der obersten Ebene

Feld

Typ

Beschreibung

state

String

Aktueller Status des Jobs. Siehe Job-Status unten.

processId

String

ID der Prozessvorlage, die zur Erstellung des Jobs verwendet wurde.

processInstanceId

String

Eindeutige ID für diese spezifische Job-Instanz. Verwenden Sie diese ID in nachfolgenden API-Aufrufen.

jobMetaData

Object

Bei der Job-Erstellung festgelegte Metadaten: description, category, expirationDate, referenceId, customMap, externalPassword.

creationDate

String

ISO-8601-Zeitstempel der Job-Erstellung.

endDate

String

ISO-8601-Zeitstempel, zu dem der Job einen finalen Status erreicht hat. null, solange der Job noch aktiv ist.

currentIteration

Integer

Nullbasierter Index der Iteration, die aktuell auf eine Aktion wartet.

iterations

Array

Alle Iterationen des Jobs, einschließlich der Aktionsdaten je Eingeladenem und der Signierenden-URLs.

additionalRecipients

Array

Für den Job konfigurierte Empfänger. Siehe Zusätzliche Empfänger.

owner

String

E-Mail-Adresse des Auftraggebers (Job-Besitzer).

customMap

Object

Benutzerdefinierte Schlüssel-Wert-Daten der obersten Ebene, die dem Job zugeordnet sind.

eventTimestamp

String

Nur bei Webhooks. ISO-8601-Zeitstempel, zu dem das Ereignis ausgelöst wurde.

eventType

String

Nur bei Webhooks. Der Typ des Ereignisses, das den Webhook ausgelöst hat.

4.2. Felder je Eingeladenen innerhalb von iterations[].invitees[]

Diese Felder werden auf den Invitee-Objekten innerhalb des Arrays iterations befüllt und sind der wichtigste Integrationspunkt für die Nachverfolgung des Signer-Fortschritts und die Bereitstellung von Signaturlinks.

Feld

Typ

Beschreibung

action

String

Die vom Signer ausgeführte Aktion, z. B. SIGNED, DECLINED. null, solange die Aktion ausständig ist.

actionDate

String

ISO-8601-Zeitstempel, zu dem die Aktion ausgeführt wurde. null, solange die Aktion ausständig ist.

comments

String

Ein vom Signierenden hinterlassener Kommentar.

instantSignUrl

String

URL zur InstantSign-Ansicht für interne Signierende. In ein iframe einbettbar. null bei externen Signierenden.

externalSignerUrl

String

MOXIS-Guest-URL für externe Signierende. Teilen Sie diesen Link mit dem externen Signierenden.

externalDownloadUrl

String

Externer Download-Link für das Dokument.

externalSignerName

String

Anzeigename des externen Signierenden.

externalSignerEmail

String

E-Mail-Adresse des externen Signierenden.

4.3. Job-Status

Status

Aktiv / Final

Beschreibung

DRAFTING

Aktiv

Der Job wurde als Entwurf erstellt und noch nicht gestartet.

ACTIVE

Aktiv

Der Job ist in Bearbeitung und wartet auf eine Aktion des Signers.

POST_PROCESSING

Aktiv

Alle Signaturen wurden eingeholt; MOXIS finalisiert das Dokument.

FINISHED_SUCCESS

Final

Alle erforderlichen Signaturen wurden erfolgreich eingeholt.

FINISHED_FAILED

Final

Der Job wurde aufgrund eines Fehlers beendet.

FINISHED_TIMEOUT

Final

Der Job ist abgelaufen, bevor alle Signaturen eingeholt werden konnten.

FINISHED_WF_CANCELLED

Final

Der Job wurde über den Workflow abgebrochen (z. B. PUT cancelJob).

FINISHED_SIGNATURE_DENIED

Final

Ein Signer hat die Signatur abgelehnt.

DRAFT_DISMISSED

Final

Der Entwurf wurde verworfen, bevor er gestartet wurde.

4.4. Vollständiges Beispiel einer Antwort

Das folgende Beispiel stammt aus einem realen Job mit zwei Iterationen. Iteration 0 enthält einen internen Signer mit einer instantSignUrl; Iteration 1 enthält einen externen Signer mit einer externalSignerUrl.

{
  "state": "ACTIVE",
  "processId": "customer100",
  "processInstanceId": "277764",
  "jobMetaData": {
    "description": "Jobstate example",
    "category": null,
    "expirationDate": "2024-08-17T21:59:59.849+00:00",
    "referenceId": null,
    "customMap": {
      "key": "value"
    },
    "externalPassword": null
  },
  "creationDate": "2024-06-18T11:54:48.471+00:00",
  "endDate": null,
  "currentIteration": 0,
  "iterations": [
    {
      "numberOfSignatures": 1,
      "category": "APPROVAL",
      "iterationNumber": 0,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.Signer",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": "https://moxis.example.com/instant-sign/task/277764/f3eba906-9879-42ce-a331-0224b32e8954"
        }
      ]
    },
    {
      "numberOfSignatures": 1,
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 1,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalSigner",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": null,
          "externalSignerName": "User Name",
          "externalSignerEmail": "user.name@domain.com",
          "externalSignerUrl": "https://moxis.example.com/guest/job/b6655956-f433-46d1-9498-57283b4c86ca",
          "externalDownloadUrl": "https://moxis.example.com/guest/job/b6655956-f433-46d1-9498-57283b4c86ca"
        }
      ]
    }
  ],
  "additionalRecipients": [],
  "owner": "user.name@domain.com",
  "customMap": {}
}

4.5. Verwandte Seiten

  • jobDescription: Der zur Erstellung eines Jobs verwendete Anfrage-Body

  • Iterationsdaten: Wie Iterationen in der Anfrage strukturiert sind

  • Zusätzliche Empfänger: Empfängerobjekte

  • Job-Metadaten: Felder von jobMetaData

5. Formularfelder

MOXIS kann in ein PDF eingebettete Adobe-Acrobat-Formularfelder erkennen und zuweisen. Wenn ein PDF mit Formularfeldern übermittelt wird, ordnet MOXIS diese Felder bestimmten Signern zu, sodass Signaturen und Daten exakt an der vorgesehenen Stelle erfasst werden können, ohne auf Platzhalterbilder angewiesen zu sein.

5.1. Voraussetzungen

Zwei Einstellungen müssen sowohl auf Ebene der jobDescription als auch am Invitee-Objekt vorhanden sein:

  • positionType muss in der jobDescription auf

SIGNATURE_FIELD 

gesetzt sein.

  • Die @class des Invitees muss

com.xitrust.moxispe.api.UserForSignatureField

sein.

5.2. Zuweisungsmodi

Es gibt zwei Möglichkeiten, einem Benutzer Formularfelder zuzuweisen. Wählen Sie eine Variante pro Invitee:

Feld

Typ

Beschreibung

assignAllFormFields

Boolean

Wenn true, werden alle Formularfelder im Dokument diesem Benutzer zugewiesen.

assignFormFields

Array of Strings

Weist bestimmte Formularfelder anhand ihrer exakten Feld-ID zu (z. B. ["Check3", "Text1", "Text2"]). Sie müssen die im PDF definierte Feld-ID kennen.

signatureFieldName

String

Der Name des Adobe-Signaturfelds, in dem die Signatur dieses Benutzers platziert werden soll (z. B. "Signaturfeld0").

5.3. Beispiel

Das folgende Beispiel weist einem bestimmten externen Signer ein benanntes Signaturfeld zu. signatureFieldName referenziert die exakte, im PDF eingebettete Feld-ID.

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "EMAIL",
    "name": "test.testmasser@example.com"
  },
  "positionType": "SIGNATURE_FIELD",
  "metaData": {
    "description": "Signature field demo",
    "referenceId": "MultisignID"
  },
  "iterationData": [
    {
      "iterationNumber": 0,
      "category": "EXTERNAL_APPROVAL",
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForSignatureField",
          "classifier": "EMAIL",
          "name": "test.testmasser@example.com",
          "externalUserName": "Test Testmasser",
          "locale": "de",
          "roleName": "Extern",
          "signatureFieldName": "Signaturfeld0"
        }
      ]
    }
  ]
}

Zuweisung aller Formularfelder

Um jedem Formularfeld im Dokument einen einzelnen Benutzer zuzuweisen, verwenden Sie

assignAllFormFields: true

anstelle von signatureFieldName.

{
  "@class": "com.xitrust.moxispe.api.UserForSignatureField",
  "classifier": "EMAIL",
  "name": "user.name@example.com",
  "externalUserName": "User Name Test",
  "roleName": "Extern",
  "assignAllFormFields": true
}

Zuweisung einzelner Felder anhand der ID

Um einzelne Felder zuzuweisen, geben Sie deren Namen im Array assignFormFields an.

{
  "@class": "com.xitrust.moxispe.api.UserForSignatureField",
  "classifier": "EMAIL",
  "name": "user.name@example.com",
  "externalUserName": "User Name Test",
  "roleName": "Extern",
  "assignFormFields": ["Check3", "Text1", "Text2"]
}

5.4. Verwandte Seiten

  • Benutzerklassen: Details zur Klasse UserForSignatureField

  • jobDescription: Feld positionType

  • Iterationsdaten: Struktur der Invitee

6. Zusätzliche Empfänger

Das Array additionalRecipients ist ein optionales Feld der obersten Ebene in der jobDescription. Empfänger, die hier aufgeführt sind, erhalten das signierte Dokument und Job-Benachrichtigungen, unterzeichnen oder genehmigen das Dokument jedoch nicht.

6.1. Klassen

Innerhalb dieses Arrays werden zwei Klassen verwendet:

@class

Beschreibung

com.xitrust.moxispe.api.Recipient

Umschließt einen AddressBookEntry. Verwenden Sie diese Klasse als äußeren Container im Array additionalRecipients.

com.xitrust.moxispe.api.AddressBookEntry

Enthält die Kontaktdaten. Über das Feld addressBookEntry in ein Recipient-Objekt verschachtelt.

6.2. Felder von AddressBookEntry

Feld

Typ

Erforderlich

Beschreibung

@class

String

Ja

Immer com.xitrust.moxispe.api.AddressBookEntry.

name

String

Ja

Anzeigename des Empfängers.

email

String

Ja

E-Mail-Adresse, an die Benachrichtigungen gesendet werden.

phoneNumber

String

Nein

Telefonnummer im internationalen Format
(z. B. "+436641234567"). Wird verwendet, wenn SMS-Benachrichtigungen konfiguriert sind.

locale

String

Nein

Sprachcode für Benachrichtigungs-E-Mails
(z. B. "de", "en").

6.3. Beispiel

{
  "additionalRecipients": [
    {
      "@class": "com.xitrust.moxispe.api.Recipient",
      "addressBookEntry": {
        "@class": "com.xitrust.moxispe.api.AddressBookEntry",
        "name": "Roland Referent",
        "email": "roland.referent@example.com",
        "phoneNumber": "+436641234567",
        "locale": "de"
      }
    }
  ]
}

6.4. Verwandte Seiten

  • jobDescription: übergeordnetes Objekt

  • Job-Status-Antwort: additionalRecipients in der Antwort

7. Iterationsdaten

Das Array iterationData definiert die Signierrunden eines Jobs. Jedes Element steht für eine Runde; die Iterationen werden sequenziell ausgeführt — Iteration 0 muss abgeschlossen sein, bevor Iteration 1 beginnt, und so weiter. Sie können beliebig viele Iterationen anlegen.

Jede Iteration legt fest, wer die Signer oder Genehmiger sind (invitees), welche Art von Signatur erforderlich ist (category), sowie optionale Einstellungen wie Anmerkungstext oder Datenschutzoptionen.

7.1. Pflichtfelder je Iteration

Feld

Typ

Beschreibung

iterationNumber

Integer

Nullbasierter Index. Muss sequenziell bei 0 beginnen.

category

String

Signaturqualität für diese Iteration. Siehe Kategoriewerte unten.

invitees

Array

Ein oder mehrere Benutzerobjekte, die in dieser Iteration unterzeichnen oder genehmigen. Siehe Benutzerklassen.

Kategoriewerte

Wert

Beschreibung

QSIG

Qualifizierte elektronische Signatur (QES) für interne Signierende.

EXTERNAL_QSIG

Qualifizierte elektronische Signatur (QES) für externe Signierende.

APPROVAL

Einfache oder fortgeschrittene elektronische Signatur (SES/AES) für interne Signierende.

EXTERNAL_APPROVAL

Einfache oder fortgeschrittene elektronische Signatur (SES/AES) für externe Signierende.

APPROVAL_NOSIG

Nur Workflow-Schritt, es wird keine Signatur angebracht.

7.2. Optionale Felder je Iteration

Feld

Typ

Standard

Beschreibung

numberOfSignatures

Integer

1

Anzahl der von den Empfängern in dieser Iteration benötigten Signaturen.

remark

String

—

Freitext-Anmerkung, die den Signierenden für diese Iteration angezeigt wird.

privateIteration

Boolean

false

Wenn true, ist diese Iteration für Einsichtnehmer und Vertreter nicht sichtbar.

signerGroup

String

—

Referenziert eine in MOXIS konfigurierte Gruppenvisualisierung. Erforderlich bei Verwendung von Gruppen-Platzhaltern.

groupPosition

Array

—

Definiert explizite Platzierungskoordinaten für eine Gruppenvisualisierung.

customMap

Object

—

Schlüssel-Wert-Paare, die auf diese Iteration beschränkt sind. Wird mit dem customMap von metaData der obersten Ebene zu einem Gesamtkontext zusammengeführt.

7.3. Beispiel: Job mit zwei Iterationen

Iteration 0 holt eine qualifizierte Signatur von einem internen Benutzer ein. Iteration 1 holt eine externe Genehmigung ein, sobald die interne Signatur vorliegt.

{
  "constituent": {
    "@class": "com.xitrust.moxispe.api.User",
    "classifier": "EMAIL",
    "name": "user.name@example.com"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Some iterations",
    "referenceId": "referenceId"
  },
  "iterationData": [
    {
      "iterationNumber": 0,
      "category": "APPROVAL",
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@example.com",
          "roleName": "moxisApprover"
        }
      ]
    },
    {
      "iterationNumber": 1,
      "category": "EXTERNAL_APPROVAL",
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "external.user@email.com",
          "externalUserName": "Test UserName",
          "roleName": "Extern",
          "locale": "de",
          "phoneNumber": "+43123456789"
        }
      ],
      "remark": "Please review section 3 before approving.",
      "privateIteration": false,
      "customMap": {
        "approvalStage": "external-review"
      }
    }
  ]
}

7.4. Verwandte Seiten

  • Benutzerklassen: alle @class-Werte für Invitee

  • jobDescription: übergeordnetes Objekt

  • Job-Metadaten: customMap der obersten Ebene und weitere Metadatenfelder

8. Benutzerklassen

Benutzerklassen definieren den @class-Wert von Objekten im Array

iterationData[].invitees. 

Die gewählte Klasse bestimmt den Benutzertyp (intern vs. extern), ob für platzhalterbasiertes Signieren ein Rollen-/Gruppenkontext erforderlich ist, und welche zusätzlichen Felder anwendbar sind.

8.1. @class-Referenz

@class

Anwendungsfall

Hinweise

com.xitrust.moxispe.api.User

Interner Benutzer, direkte Referenz

Standard-Signer oder -Genehmiger intern. Kein Rollen-/Gruppenkontext.

com.xitrust.moxispe.api.ExternalUser

Externer Benutzer, direkte Referenz

Kein Gruppen- oder Rollenkontext.

com.xitrust.moxispe.api.ExternalApprover

Externer Genehmiger, direkte Referenz

Veraltet. Nicht für neue Integrationen verwenden.

com.xitrust.moxispe.api.UserForSignatureField

Interner Benutzer, Platzierung im Signaturfeld

Erfordert positionType: SIGNATURE_FIELD. Siehe Formularfelder.

com.xitrust.moxispe.api.UserForRole

Interner Benutzer mit Rollen- oder Gruppenkontext

Erforderlich bei platzhalterbasiertem Signieren für interne Benutzer. roleName identifiziert die Rolle oder Gruppe.

com.xitrust.moxispe.api.ExternalUserForRole

Externer Benutzer mit Rollen- oder Gruppenkontext

Die gängigste Klasse für externe Signer. roleName verweist auf eine in MOXIS konfigurierte Rolle.

com.xitrust.moxispe.api.ExternalApproverForRole

Externer Genehmiger mit Rollenkontext

Veraltet. Verwenden Sie statt dessen ExternalUserForRole.

8.2. Zusätzliche Felder je Klasse

Die folgenden Felder können abhängig von der verwendeten Klasse zusätzlich zu den Basisfeldern @class, classifier und name angegeben werden.

Feld

Typ

Anwendbare Klassen

Beschreibung

roleName

String

UserForRole, ExternalUserForRole

Der Name der MOXIS-Rolle oder -Gruppe, zu der dieser Benutzer gehört. Die Rolle oder Gruppe muss in MOXIS bereits existieren.

externalUserName

String

ExternalUser, ExternalUserForRole, UserForSignatureField

In MOXIS angezeigter Name des externen Benutzers.

locale

String

ExternalUser, ExternalUserForRole

Sprachcode für Benachrichtigungs-E-Mails (z. B. "de", "en").

phoneNumber

String

ExternalUser, ExternalUserForRole

Telefonnummer im internationalen Format für die SMS-TAN-Authentifizierung (z. B. "+43123456789").

signatureFieldName

String

UserForSignatureField

Name des spezifischen Adobe-Signaturformularfelds, in dem dieser Benutzer unterzeichnen soll.

directUserPosition

Object

User, ExternalUser

Explizite x/y/Seiten-Koordinaten für die Platzierung mit DIRECT_POSITION. Felder: x, y, width, height, pageNumber (jeweils als Float-Strings).

8.3. Beispiele

Interner Benutzer, identifiziert über UPN

Wird verwendet, wenn der Signer über einen Identity Provider verwaltet wird (z. B. Microsoft Entra).

{
  "@class": "com.xitrust.moxispe.api.UserForRole",
  "classifier": "UPN",
  "name": "max.mustermann@example.com",
  "roleName": "moxisSigner"
}

Externer Benutzer, identifiziert über EMAIL, mit SMS-TAN und locale

Das gängigste Muster für externe

Signer. roleName

muss mit einer im MOXIS-Prozess konfigurierten Rolle übereinstimmen.

{
  "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
  "classifier": "EMAIL",
  "name": "partner@external.com",
  "externalUserName": "Partner Contact",
  "roleName": "Extern",
  "locale": "de",
  "phoneNumber": "+43123456789"
}

8.4. Verwandte Seiten

  • Iterationsdaten: Wie Invitee innerhalb von Iterationen verwendet werden

  • Formularfelder: Verwendung von UserForSignatureField

  • Constituent: Das Objekt des Job-Auftraggebers (immer com.xitrust.moxispe.api.User)