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 |
|
|
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. |
|
|
String |
Ja |
E-Mail-Adresse, an die Benachrichtigungen gesendet werden. |
|
phoneNumber |
String |
Nein |
Telefonnummer im internationalen Format
|
|
locale |
String |
Nein |
Sprachcode für Benachrichtigungs-E-Mails
|
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)