Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core JavaScript-API

agorum core insign JavaScript-Bibliotheken

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins agorum core insign. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Das Plugin agorum core insign wird mit zwei Bibliotheken ausgeliefert:

  • agorum.insign/js/lib/settings: Diese Bibliothek dient zur Verwaltung und Konfiguration von Client-Einstellungen. Sie ermöglicht das Abrufen von Konfigurationsinformationen für Clients. Die Verbindungskonfiguration wird über die Administrationsoberfläche erstellt, siehe agorum core insign einrichten.

Verwendung

Sie können mit den agorum core insign-Bibliotheken einen eigenen Signaturprozess über den Signaturanbieter inSign erstellen. Die Voraussetzung dafür ist, dass Sie ein inSign-Konto mit API-Zugriff haben und eine inSign-Schnittstellenkonfiguration erstellt haben. Mit den agorum-Bibliotheken können Sie:

  • eine inSign-Sitzung mit den richtigen Benutzer- und Verbindungskonfigurationsinformationen erstellen
  • eine Signaturanfrage mit dem zu signierenden Dokument und weiteren Angaben wie den erforderlichen Unterzeichnern an inSign schicken
  • den Signaturstatus eines Dokuments in inSign überprüfen
  • signierte Dokumente aus inSign herunterladen
  • eine Signaturanfrage abbrechen

Binden Sie dazu die Bibliotheken stets am Anfang eines Skripts ein:

let settings = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

Beispiel für eine Signaturanfrage

Das folgende Beispiel zeigt, wie Sie eine Signaturanfrage für ein PDF-Dokument mit Anforderung von zwei Signaturen und Identifizierung der Signaturposition über eine Textsuche erstellen können.

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

// set user and client context 
let user = objects.find('715d9471-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);
let configUser = settings.getUserConfigByClientId(user, '1997ca25-e67a-47da-a2c3-009025ba5159');
configUser;
let config = settings.getUserConfig(user);
config;

// select document to be signed
let pdf = objects.find('c0d41e70-8713-11ef-9101-02420a0a0006');

// signature request with specification of two signatures by different persons (e-mail adresses)
insign.sign({
  user: user,
  displayName: 'Test Session Name DOC',
  parameter: {
    documents: [
      {
        scanSigTags: false,
        signatures: [
          {
            role: 'Role1',
            id: '1',
            displayname: 'userA@example.com',
            textsearch: 'Unterschrift Käufer',
            required: true,
          },
          {
            role: 'Role2',
            id: '2',
            displayname: 'userB@example.com',
            textsearch: 'Unterschrift Verkäufer',
            required: true,
          },
        ],
      },
    ],
  },
  documents: [pdf],
  recipients: {
    inOrder: true,
    externUsers: [
      {
        recipient: 'userA@example.com',
        sendEmails: true,
        roles: ['Role1'],
        orderNumber: 1,
      },
      {
        recipient: 'userB@example.com',
        sendEmails: true,
        roles: ['Role2'],
        orderNumber: 2,
      },
    ],
  },
});

Das Beispiel zeigt, wie eine Signaturanfrage für das über die UUID angegebene PDF-Dokument mit dem Kontext des angegebenen Benutzers erstellt wird.

Die Signaturanfrage erstellt eine REST-Anfrage an inSign. Die Angaben in den Abschnitten recipients und parameter sind flexibel und müssen der REST-Spezifikation von inSign entsprechen (siehe inSign REST-API-Dokumentation). In diesem Beispiel umfasst die Anfrage die Angabe der Empfänger (recipients) mit ihren E-Mail-Adressen und einer Reihenfolge, in der die elektronischen Signaturen erfolgen sollen (über inOrder und orderNumber). Außerdem enthält die Anfrage eine Angabe der Positionen (Signaturfelder), an denen die Signaturen aufgebracht werden sollen, im Abschnitt paramter/documents/signatures. In diesem Fall wird die Position der Unterschriften über eine Textsuche (textsearch) ermittelt.

In diesem Beispiel würden Sie eine Antwort nach dem folgenden Muster von inSign zurückerhalten:

{
  "link" : "https://connect.test.getinsign.show/index?sessionid=5be7184be43360f782fec00",
  "sessionId" : "5be7184be43360f782fec00"
}

Beispiel für eine Signaturanfrage mit Position des Signaturfelds

Das folgende Beispiel zeigt, wie Sie eine Signaturanfrage für ein PDF-Dokument mit Anforderung von einer Signatur und Identifizierung der Signaturposition über Positionsangaben erstellen können.

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('714614d0-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);
let configUser = settings.getUserConfigByClientId(user, '2a29157e-c459-414d-bba2-254406e24c38');
let config = settings.getUserConfig(user);

let pdf = objects.find('df000aa0-9139-11ef-a076-00007f000101');

insign.sign({
  user: user,
  displayName: 'Test Session Name',
  parameter: {
    documents: [
      {
        scanSigTags: false,
        signatures: [
          {
            role: 'Role1',
            id: '1',
            position: {
              h: '0.02',
              page: '0',
              w: '0.1',
              x0: '0.77',
              y0: '0.73',
            },
            required: true,
          },
        ],
      },
    ],
  },
  documents: [pdf],
  recipients: {
    inOrder: true,
    externUsers: [
      {
        recipient: 'user@example.com',
        sendEmails: true,
        roles: ['Role1'],
        orderNumber: 1,
      },
    ],
  },
});

Diese Positionsangabe resultiert in folgender Position auf einem A4-Testdokument, hier in der inSign-Oberfläche.

Anzeige des Signaturfeldes in inSign

Beispiel für eine Anfrage mit inSign SIG-Tags im Dokument

inSign unterstützt die Angabe von sogenannten SIG-Tags im Dokument. Dabei handelt es sich um Textangaben im Dokument, die mit ##SIG eingeleitet werden, um Signaturfelder zu spezifizieren. Für weitere Informationen zu SIG-Tags siehe die inSign-Dokumentation. Beispiel:

##SIG{required:'true',w:'10cm'}

Wenn ein Dokument SIG-Tags enthält, können Sie beim Übergeben des Dokuments angeben, dass diese ausgelesen werden sollen:

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('714614d0-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);
let configUser = settings.getUserConfigByClientId(user, '2a29157e-c459-414d-bba2-254406e24c38');
let config = settings.getUserConfig(user);

let pdf = objects.find('7b1f38b0-950a-11ef-a11a-00007f000101');

insign.sign({
  user: user,
  displayName: 'Test Session Name',
  parameter: {
    documents: [
      {
        scanSigTags: true,
      },
    ],
  },
  documents: [pdf],
});

agorum.insign/js/lib/insign Funktionen

cancel

Die Funktion cancel bricht eine Signaturanfrage für ein angegebenes Dokument ab.

Syntax

insign.cancel(objects)

Parameter

Parameter Beschreibung Pflicht Standard
objects Ein oder mehrere agorum-Objekte, deren Signaturanfrage abgebrochen werden soll. ja -

Beispiel

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');

insign.cancel([objects.find('1f43d880-74d9-11ef-876a-02420a0a0015')]);

Rückgabewert

Wenn Sie über die Funktion cancel eine Signaturanfrage für ein Dokument abbrechen, erhalten Sie eine Rückgabe nach folgendem Muster:

{
  "d497b450-9139-11ef-a076-00007f000101" : {
    "sessionId" : "eb11c79f174a4fdc1b8ff560",
    "error" : 0,
    "message" : "OK"
  }

checkLoginData

Die Funktion checkLoginData prüft, ob die in einer Konfiguration angegebenen Login-Daten korrekt sind.

Syntax

insign.checkLoginData(clientId)

Parameter

Parameter Beschreibung Pflicht Standard
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */

let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

insign.checkLoginData(clientId);

Rückgabewert

{
  "success" : true
}

checkSigned

Diese Funktion überprüft eine inSign-Session darauf, ob alle Signaturen vollständig vorliegen. Zurückgegeben wird ein boolescher Wert.

Syntax

insign.checkSigned(sessionId, clientId)

Parameter

Parameter Beschreibung Pflicht Standard
sessionId Die verschlüsselte sessionId der inSign-Session, deren Statusinformationen abgefragt werden sollen. ja -
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */

let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('714614d0-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);

insign.checkSigned('eecae66a8f1049f63c591289', clientId);

getCheckStatus

Die Funktion getCheckStatus fragt den Prüfstatus einer bestimmten Session anhand ihrer ID ab.

Syntax

insign.getCheckStatus(sessionId, clientId)

Parameter

Parameter Beschreibung Pflicht Standard
sessionId Die sessionId der inSign-Session, deren Statusinformationen abgefragt werden sollen. ja -
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('715d9471-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);

insign.getCheckStatus('5be7184be43360f782fec00', clientId);

Rückgabewert

Wenn Sie über die Funktion getCheckStatus den Status einer inSign-Session abfragen, erhalten Sie eine Rückgabe nach folgendem Muster:

{
  "inQes" : false,
  "numberOfSignaturesNeededDone" : 1,
  "processStep" : "inprogress",
  "extern" : true,
  "sessionid" : "eecae66a8f1049f63c591289",
  "completed" : false,
  "error" : 0,
  "message" : "OK",
  "offline" : false,
  "qesResultPreliminary" : false,
  "offlineAvailable" : false,
  "numberOfSignaturesNeeded" : 2,
  "status" : "extern"
}

getStatus

Die Funktion getStatus fragt den Status einer bestimmten Session anhand ihrer ID ab.

Syntax

insign.getStatus(sessionId, clientId)

Parameter

Parameter Beschreibung Pflicht Standard
sessionId Die sessionId der inSign-Session, deren Statusinformationen abgefragt werden sollen. ja -
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('715d9471-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);

insign.getStatus('5be7184be43360f782fec00', clientId);

Rückgabewert

Wenn Sie über die Funktion getStatus den Status einer inSign-Session abfragen, erhalten Sie eine Rückgabe nach folgendem Muster:

{
  "emails_abgeschlossen" : [ ],
  "emails_ausgehaendigt" : [ ],
  "numberOfSignatures" : 1,
  "docs_abgeschlossen" : [ "0dd82a50-8718-11ef-9101-02420a0a0006" ],
  "numberOfSignaturesFields" : 1,
  "sucessfullyCompleted" : false,
  "error" : 0,
  "message" : "OK",
  "documentData" : [ {
    "numberOfSignaturesNeededDone" : 1,
    "hasbeensignedCompletely" : true,
    "hasbeenread" : true,
    "userAusgefuellt" : false,
    "docid" : "0dd82a50-8718-11ef-9101-02420a0a0006",
    "numberOfSignatures" : 1,
    "numberOfSignaturesNeededWithOptional" : 1,
    "hasbeensignedRequired" : true,
    "hasbeenchanged" : false,
    "completedQESList" : null,
    "hasrequired" : false,
    "docchecksumSHA512" : "9d51aecf864befc657bda5f9d05e88091352d6d60ee083ce170f32ead6c9f6bc0aefb37ed434ea9132bca0502ee64b4a9f3fccc27b46bdae5a7382e44b816ad1",
    "displayname" : "Kaufvertrag (1).pdf",
    "additionalInfo" : null,
    "numberOfSignaturesNeeded" : 1,
    "docchecksum" : "e2186b9c2238e7da9871e951166e428c5f28572924b22901cd73256d2ff4a564",
    "docname" : "Kaufvertrag (1).pdf:Kaufvertrag (1).pdf",
    "hasbeenedited" : false,
    "signaturFieldsStatusList" : [ {
      "role" : "Role1",
      "signatureBitmap" : null,
      "signed" : true,
      "quickinfo" : "userA@example.com",
      "mandatory" : true,
      "deviceId" : "ip:88.152.185.68,ua:Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:131.0) Gecko/20100101 Firefox/131.0,platform:Win32,id:null",
      "displayname" : "userA@example.com",
      "documentID" : "0dd82a50-8718-11ef-9101-02420a0a0006",
      "positionIndex" : 0,
      "quickInfoParsedRole" : null,
      "externRole" : null,
      "fieldID" : "1",
      "signTimestamp" : "10.10.2024 15:19:50 UTC(+0000)"
    } ],
    "isbipro" : false,
    "numberofpages" : 2,
    "hasbeensigned" : true
  } ],
  "numberOfMandatorySignatureFields" : 1,
  "aushaendigungen" : [ {
    "sms" : [ ],
    "abschliesen" : true,
    "docInfos" : [ {
      "checksumSHA512" : "9d51aecf864befc657bda5f9d05e88091352d6d60ee083ce170f32ead6c9f6bc0aefb37ed434ea9132bca0502ee64b4a9f3fccc27b46bdae5a7382e44b816ad1",
      "numberOfPages" : 2,
      "fileSize" : 65727,
      "displayname" : "Kaufvertrag (1).pdf",
      "checksum" : "e2186b9c2238e7da9871e951166e428c5f28572924b22901cd73256d2ff4a564",
      "id" : "0dd82a50-8718-11ef-9101-02420a0a0006"
    } ],
    "email" : [ "userA@example.com" ],
    "docids" : [ "0dd82a50-8718-11ef-9101-02420a0a0006" ],
    "typen" : [ ],
    "timestamp" : 1.728573591E12
  } ],
  "numberOfOptionalSignatureFields" : 0,
  "gdprDeclined" : false,
  "modifiedTimestamp" : 1.728573591E12,
  "docs_ausgehaendigt" : [ ],
  "signaturFieldsStatusList" : [ {
    "role" : "Role1",
    "signatureBitmap" : null,
    "signed" : true,
    "quickinfo" : "userA@example.com",
    "mandatory" : true,
    "deviceId" : "ip:88.152.185.68,ua:Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:131.0) Gecko/20100101 Firefox/131.0,platform:Win32,id:null",
    "displayname" : "userA@example.com",
    "documentID" : "0dd82a50-8718-11ef-9101-02420a0a0006",
    "positionIndex" : 0,
    "quickInfoParsedRole" : null,
    "externRole" : null,
    "fieldID" : "1",
    "signTimestamp" : "10.10.2024 15:19:50 UTC(+0000)"
  } ],
  "numberOfOptionalSignatures" : 0,
  "numberOfMandatorySignatures" : 1
}

getUrlClient

Die Funktion getUrlClient fragt die URL für das inSign-Dokument mit der Session-ID ab.

Syntax

insign.getUrlClient(sessionId, clientId)

Parameter

Parameter Beschreibung Pflicht Standard
sessionId Die sessionId der inSign-Session, deren Statusinformationen abgefragt werden sollen. ja -
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('715d9471-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);

insign.getUrlClient('eecae66a8f1049f63c591289', clientId);

Rückgabewert

Wenn Sie über die Funktion getUrlClient die URL mit Session-ID für das inSign-Dokument anfragen, erhalten Sie eine Rückgabe nach folgendem Muster:

https://connect.test.getinsign.show/index?sessionid=eecae66a8f1049f63c591289

open

Die Funktion open öffnet eine angegebene inSign-Session in einem neuen Fenster.

Syntax

insign.open(url)

Parameter

Parameter Beschreibung Pflicht Standard
url Die inSign-URL, die geöffnet werden soll. ja -

Beispiel

/* global sc */
let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');

insign.open('https://connect.test.getinsign.show/index?sessionid=eecae66a8f1049f63c591289');

save

Die Funktion save speichert ein Dokument aus einer inSign-Session in einem angegeben Zielobjekt in agorum core.

Syntax

insign.save(sessionId, object, clientId)

Parameter

Parameter Beschreibung Pflicht Standard
sessionId Die sessionId der inSign-Session, aus der das Dokument abgefragt werden soll. ja -
object Das agorum-Zielobjekt, wo das Dokument gespeichert werden soll. ja -
clientId Die Konfiguration, über die der inSign-Zugriff hergestellt wird. ja -

Beispiel

/* global sc */

let insign = require('/agorum/roi/customers/agorum.insign/js/lib/insign');
let objects = require('common/objects');
let settings = require('/agorum/roi/customers/agorum.insign/js/lib/settings');

let user = objects.find('714614d0-ce62-11e0-b47a-0800276e2399');
let clientId = settings.getClientId(user);

// Beispiel für save
insign.save('db8961883ef81ff287eeb4eb', objects.find('6c382860-91e6-11ef-a076-00007f000101'), clientId);

Rückgabewert

Wenn die angegebene inSign-Session nicht vorhanden ist oder kein vollständig unterschriebenes Dokument enthält, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: javax.ws.rs.ServerErrorException: {"error":599,"message":"Dokument nicht gefunden. (obsxx)","trace":"document.missing","errorPageData":{"lastErrortitle":"Zugriff verweigert","lastErrormessage":"Dokument nicht gefunden. (obsxx)"}}

sign

Die Funktion sign erstellt eine Signaturanfrage für ein oder mehrere PDF-Dokumente beim Signaturanbieter inSign. Die Angaben dienen dazu, eine REST-Anfrage für inSign zu erstellen. Die Angaben müssen der Spezifikation der inSign-Schnittstelle entsprechen.

Syntax

insign.sign({
  user: user,
  displayName: 'session name',
  parameter: {},
  documents: [pdf],
  recipients: {},
})

Parameter

Parameter Beschreibung Pflicht Standard
user Der Benutzer (agorum.Object), der die Session erstellt, und dessen Name in der E-Mail mit Bitte um Signatur verwendet wird. ja -
displayName Der Name für den Signaturprozess, der in der E-Mail und der inSign-Session angezeigt wird. ja -
parameter Weitere Parameter für die inSign-Session.

Sie können optional weitere Parameter zu den zu signierenden Dokumenten und weitere Angaben für die inSign-Session mitgeben. Mit diesen Parametern können Sie die POST-Anfrage erweitern.

Mit den zusätzlichen Parametern können Sie etwa über das Objekt documents angeben, an welcher Stelle im Dokument die Empfänger unterschreiben sollen. Dazu haben Sie verschiedene Möglichkeiten: 

  • Sie können die geeignete Position über eine Textsuche (textsearch) angeben. Wenn Sie diese Möglichkeit verwenden, empfiehlt es sich, diesen Text nur einmal im Dokument zu verwenden und ggf. als weißen Text zu positionieren. Sonst werden die Unterschriften eventuell nicht richtig positioniert.
  • Sie können die Position für die Unterschrift durch Angabe der Koordinaten (x0, y0) auf der PDF-Seite (page, Wert 0-basierend) und der Breite (w) und Höhe (h) des Unterschriftenfelds genau angeben.

Die Dokumentation aller möglichen Parameter finden Sie hier.

 nein -
documents Ein oder mehrere Dokumente (agorum.Object), die signiert werden sollen. ja -
recipients Die Angaben zu den Empfängern, die die Dokumente signieren sollen.

Die hier angegebenen E-Mail-Empfänger werden mit dem Dokument an inSign übermittelt. inSign verschickt E-Mails mit der Aufforderung zur elektronischen Signatur an die angegebenen E-Mail-Adressen.

Sie können über die Datenfelder die POST-Anfrage zusammenstellen, die an inSign geschickt wird. Für die Anfrage benötigen Sie mindestens das Objekt externUsers mit den E-Mail-Adressen der Empfänger als Schlüssel-Wert-Paare. Daneben stehen Ihnen weitere Angaben zur Verfügung, über die Sie den Inhalt der E-Mail und die Reihenfolge der Unterschriften steuern können. Die Dokumentation aller möglichen Felder finden Sie hier.

 nein, wenn Sie keine E-Mail-Empfänger angeben, müssen diese manuell in inSign angegeben werden -

Beispiel

Siehe das Beispiel für eine Signaturanfrage