DocuSign-Verbindungshandbuch für Jitterbit App Builder

Übersicht

In diesem Handbuch werden die Systemanforderungen und Anweisungen zum Verbinden von App Builder mit einem Docusign Online-Datenbankserver als Voraussetzung für die Nutzung als Dienst in einer Anwendung beschrieben.

Notiz

Sie müssen je nach den Anforderungen Ihrer Anwendung weitere Endpoints hinzufügen. Weitere Informationen finden Sie im offiziellen DocuSign API Referenzhandbuch.

Systemanforderungen

Datenbankserver

DocuSign-Entwicklerkonto

Client-Webbrowser

• Chrome TM 60 oder neuer

• Firefox ® 55 oder neuer

Safari ® 11.0.2 oder neuer

• Postman v9.10 oder neuer

Anschlusshinweise

Anmeldeinformationen aus der DocuSign Sandbox abrufen

1. Melden Sie sich hier bei DocuSign an: https://account-d.docusign.com/

2. Klicken Sie oben rechts auf der Zielseite auf Einstellungen

3. Scrollen Sie in der linken Seitenleiste nach unten zu Integrationen und klicken Sie auf Apps & Keys

4. Erstellen Sie eine Anwendung, indem Sie auf die Schaltfläche APP UND INTEGRATIONSSCHLÜSSEL HINZUFÜGEN klicken.

   

5. Geben Sie den Anwendungsnamen ein (dieses Beispiel ist * App Builder DocuSign*)

6. Integrationsschlüssel kopieren und für den nächsten Schritt speichern

   • Sie werden in späteren Schritten auch die API Konto-ID und die Basis-URI des Kontos verwenden

7. Klicken Sie unter „Authentifizierung“ auf die Schaltfläche „+ GEHEIMEN SCHLÜSSEL HINZUFÜGEN“ und kopieren Sie diesen Wert. Sie benötigen diesen Schlüssel und können ihn später nicht vollständig anzeigen.

8. Scrollen Sie nach unten zu „Zusätzliche Einstellungen“ und fügen Sie diese Umleitungs-URI hinzu: https://oauth.pstmn.io/v1/callback (Dies gilt nur bei Verwendung von Postman. Wenn Sie andere API Entwicklungstools verwenden, lesen Sie bitte deren Dokumentation.)

9. Klicken Sie auf Speichern

10. Klicken Sie im Menü der oberen Leiste auf Vorlagen

11. Klicken Sie oben links auf Neu, um eine neue Vorlage zu erstellen, die beim Verbindungsaufbau verwendet werden soll

12. Benennen Sie Ihre Vorlage, laden Sie ein Dokument hoch und klicken Sie auf Weiter. Fügen Sie dem Dokument optional Signaturbereiche hinzu und klicken Sie dann auf Speichern.

13. Klicken Sie unter dem Namen Ihrer neuen Vorlage auf VORLAGEN-ID, kopieren und speichern Sie diesen Wert. Sie benötigen ihn in einem späteren Schritt.

Aktualisierungstoken mit Postman abrufen

1. Erstellen Sie eine neue POST-Anfrage mit den folgenden Parametern:

   • URL: https://account-d.docusign.com/oauth/token >/

   • Autorisierung: Basisauthentifizierung

     • Benutzername = Integrationsschlüssel aus dem vorherigen Abschnitt

     • Passwort = Geheimschlüssel aus dem vorherigen Abschnitt

   • Text: x-www-form-urlunencoded

     • Schlüssel: grant_type

     • Wert: Autorisierungscode

     • Schlüssel: Code

     • Wert: *Diesen zweiten Wert erhalten Sie im nächsten Schritt

2. Gehen Sie in einem Webbrowser auf die folgende Website und ersetzen Sie die Werte, die zwischen < Und >, d. h. <value>.

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signatureextended&client_id=<Integration Key from DocuSign Sandbox>&state=a39fh23hnf23&redirect_uri=https://oauth.pstmn.io/v1/callback
   

3. Nachdem Sie die Eingabetaste mit der obigen URI gedrückt haben, kopieren Sie den Inhalt des URL Felds und fügen Sie ihn an einer Stelle ein, an der die vollständige URL sichtbar ist (sie ist extrem lang). Kopieren Sie den Wert nach code= und vor &state=. Dies ist Ihr code-Wert. Fügen Sie ihn in das Feld „Wert“ aus Schritt 1 in diesem Abschnitt ein und klicken Sie in Postman auf Senden. **Dieser Schritt muss schnell ausgeführt werden, da das Aktualisierungstoken des Webbrowsers nur etwa 2 Minuten gültig ist. **

   

Einrichten der Aktualisierungstoken API im App Builder

1. Klicken Sie im Menü „Verbinden“ auf den Link „Mit Ihrem Unternehmen verbinden“

2. Klicken Sie links auf Datenserver und dann auf Erstellen

3. Konfigurieren Sie den Server wie folgt:

   • Name: Wiedererkennbarer Name

   • Typ: REST API

   • URL: https://account-d.docusign.com

   • Anfrageinhaltstyp: Formular

   • Antwortinhaltstyp: JSON

   

4. Klicken Sie auf Speichern.

Einen API Endpoint hinzufügen

1. Schließen Sie das Popup „Datenserver erstellen“ und klicken Sie dann in der Liste der Datenserver auf den Namen des Servers, den Sie gerade erstellt haben.

2. Klicken Sie im Bereich Endpoints unten links auf Erstellen

3. Fügen Sie die folgenden Details hinzu:

   • Name: Benennen Sie Ihren Endpoint

   • Endpoint: /oauth/token

   • Methode: POST

4. Als Nächstes fügen Sie die folgenden Endpoint hinzu, indem Sie oben rechts im Bereich „Endpoint “ auf Erstellen klicken und die folgenden Details hinzufügen:

   • Parameter 1

     • Name: Autorisierung

     • Datentyp: Zeichenfolge

     • Testwert: Basic {Autorisierung vom Postboten}

       Dieser Wert befindet sich im Tab „Header“ in Postman nach dem POST-Aufruf zum Abrufen des Aktualisierungstokens. Er lautet „basic“, gefolgt von einer langen ID. (Möglicherweise müssen Sie in versteckten Headern nachsehen.)

     • Typ: Kopfzeile

     • Richtung: Eingabe

   • Parameter 2

     • Name: Grant-Typ

     • Datentyp: Zeichenfolge

     • Testwert: refresh_token

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 3

     • Name: Refresh_Token

     • Datentyp: Zeichenfolge

     • Testwert: Das Aktualisierungstoken, das Sie im vorherigen Schritt in Postman abgerufen haben

     • Typ: Abfrage

     • Richtung: Eingabe

   

5. Klicken Sie auf Speichern.

6. Klicken Sie auf Verbindung testen, um den Zugriffstoken für den nächsten Schritt zu erhalten.

7. Fügen Sie der Beispieleingabe die Abfrageparameter wie folgt hinzu:

   { "grant_type": "refresh_token", "refresh_token": "<refresh token from postman>"}
   

8. Klicken Sie auf Importieren

App Builder für DocuSign konfigurieren

1. Klicken Sie im Menü „Verbinden“ auf den Link „Mit Ihrem Unternehmen verbinden“

2. Klicken Sie links auf Datenserver und dann auf Erstellen

3. Konfigurieren Sie den Server wie folgt:

   • Name: Wiedererkennbarer Name

   • Typ: REST API

   • URL: https://demo.docusign.net/restapi (Dies stammt aus der DocuSign Sandbox, siehe erster Abschnitt)

   • Anforderungsinhaltstyp: JSON

   • Antwortinhaltstyp: JSON

   

Fügen Sie einen API Endpoint für die DocuSign-Vorlage hinzu

1. Schließen Sie das Popup „Datenserver erstellen“ und klicken Sie dann in der Liste der Datenserver auf den Namen des Servers, den Sie gerade erstellt haben.

2. Klicken Sie im Bereich Endpoints unten links auf Erstellen

3. Fügen Sie die folgenden Details hinzu:

   • Name: Benennen Sie Ihren Endpoint

   • Endpoint: /v2/accounts/<AccountID>/envelopes

   • Methode: POST

4. Als Nächstes fügen Sie die folgenden Endpoint hinzu, indem Sie oben rechts im Bereich „Endpoint “ auf Erstellen klicken und die folgenden Details hinzufügen:

   • Parameter 1

     • Name: Konto-ID

     • Datentyp: Zeichenfolge

     • Testwert: API Konto-ID aus der DocuSign Sandbox (siehe ersten Abschnitt)

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 2

     • Name: Autorisierung

     • Datentyp: Zeichenfolge

     • Testwert: Träger <Returned Access Token from the Token API>

     • Typ: Kopfzeile

     • Richtung: Eingabe

   • Parameter 3

     • Name: E-Mail-Text

     • Datentyp: Zeichenfolge

     • Testwert: Email Text Ihrer Wahl, in diesem Beispiel „Ein Dokument muss unterzeichnet werden“.

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 4

     • Name: E-Mail-Betreff

     • Datentyp: Zeichenfolge

     • Testwert: Email Betreff Ihrer Wahl, in diesem Beispiel „Signing“

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 5

     • Name: Status

     • Datentyp: Zeichenfolge

     • Testwert: gesendet

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 6

     • Name: Vorlagen-ID

     • Datentyp: Zeichenfolge

     • Testwert: Die Vorlagen-ID aus dem ersten Abschnitt

     • Typ: Abfrage

     • Richtung: Eingabe

5. Klicken Sie auf Verbindung testen, um sicherzustellen, dass die Parameter richtig eingegeben wurden, und um die Testergebnisse anzuzeigen. Im nächsten Schritt wird die EnvelopeID verwendet.

6. Klicken Sie oben links auf die Schaltfläche „Zurück“, um zum Webdienst zurückzukehren und weitere Endpoint hinzuzufügen.

Fügen Sie einen API Endpoint für den Dokumentstatus hinzu

1. Klicken Sie im Bereich Endpoints unten links auf Erstellen

2. Fügen Sie die folgenden Details hinzu:

   • Name: Benennen Sie Ihren Endpoint

   • Endpoint: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>

   • Methode: GET

3. Als Nächstes fügen Sie die folgenden Endpoint hinzu, indem Sie oben rechts im Bereich „Endpoint “ auf Erstellen klicken und die folgenden Details hinzufügen:

   • Parameter 1

     • Name: Konto-ID

     • Datentyp: Zeichenfolge

     • Testwert: API Konto-ID aus der DocuSign Sandbox (siehe ersten Abschnitt)

     • Typ: Abfrage

     • Richtung: Eingabe

   • Parameter 2

     • Name: Autorisierung

     • Datentyp: Zeichenfolge

     • Testwert: Träger <Returned Access Token from the Token API>

     • Typ: Kopfzeile

     • Richtung: Eingabe

   • Parameter 3

     • Name: Umschlag-ID

     • Datentyp: Zeichenfolge

     • Testwert: Umschlag-ID, die beim Testen des vorherigen Endpoint zurückgegeben wurde

     • Typ: Abfrage

     • Richtung: Eingabe

4. Klicken Sie auf Verbindung testen, um sicherzustellen, dass die Parameter korrekt eingegeben wurden, und um die Testergebnisse anzuzeigen

Machen Sie DocuSign-Tabellen zur späteren Verwendung öffentlich

1. Klicken Sie in der App Builder IDE auf Erstellen Sie Ihre Anwendung

2. Klicken Sie auf die Datenspeicherebene und suchen Sie unter Webdienste die DocuSign Rest API, die Sie im vorherigen Schritt erstellt haben

3. Klicken Sie auf das Zahnradsymbol Tabellen

4. Doppelklicken Sie für jede Tabelle auf die Tabelle und klicken Sie auf Edge Case-Einstellungen

5. Klicken Sie unter Öffentlicher Zugriff auf Lesen zulassen und Schreiben zulassen

6. Führen Sie dieselben Schritte für die DocuSign Token REST API und alle anderen Endpoints aus, die Sie für DocuSign-Informationen erstellt haben.

App Builder-Regeln für DocuSign konfigurieren

Spalten für DocuSign Informationen hinzufügen

1. Klicken Sie in der App Builder IDE auf Erstellen Sie Ihre Anwendung

2. Klicken Sie auf die Business Logic Layer und suchen Sie die Datenquelle, in der Sie DocuSign-Informationen speichern möchten

3. Klicken Sie im Bereich „Business Layer Data Source“ auf der rechten Seite auf Link Sources und fügen Sie die DocuSign REST API hinzu, die Sie im vorherigen Schritt erstellt haben. *Stellen Sie sicher, dass Sie die Tabellen als „Lesen/Schreiben zulassen“ markiert haben.

4. Klicken Sie auf das Business Objects-Symbol und suchen Sie die Tabelle, in der Sie die DocuSign Einstellungen speichern möchten (in diesem Beispiel wird ParamDocusign verwendet).

5. Erstellen Sie in der Tabelle die folgenden Spalten:

   • DocusignBaseURL (NVarchar(50))

   • DocusignGrantType (NVarchar(50))

   • DocusignRefreshToken (NVarchar(-1))

   • DocusignClientIDSecretID (NVarchar(-1))

6. Nachdem die Spalten erstellt wurden, klicken Sie auf Ergebnisse und fügen Sie den folgenden Spalten Werte hinzu:

   • DocusignBaseURL: Die Basis URL aus der DocuSign Sandbox

   • DocusignGrantType: Der wörtliche Zeichenfolgenwert „refresh_token“

   • DocusignRefreshToken: Der Endpoint refresh_token in der Token-REST- API (die erste REST- API, die Sie erstellt haben)

   • DocusignClientIDSecretID: Der Endpoint in der Token-REST API

7. Sie können auch andere Spalten hinzufügen, um sie in der Benutzeroberfläche zu bearbeiten, z. B. Email Text, Email-Betreff und Rolle (dies sind Parameter der DocuSign Vorlage).

Erstellen Sie eine XP-Einfügeregel, um Anmeldeinformationen in den Token-Post-Aufruf einzufügen

1. Navigieren Sie vom vorherigen Schritt zurück zur App Workbench

2. Klicken Sie im mittleren Bereich auf Geschäftsregel hinzufügen, um ein neues Geschäftsobjekt zu erstellen.

3. Füllen Sie die folgenden Angaben aus:

   • Name: Tabelle (Aktualisierungszugriffstoken einfügen)

   • Zweck: XP CRUD

   • Deaktivieren Sie „Business-Layer überspringen“

   • Aktion: Einfügen

   • Quelldatum Quelle: Datenbank, in der die Tabelle mit den DocuSign-Informationen gespeichert ist

   • Zieldatenquelle: Die erste REST- API, die Sie zum Aktualisieren des Zugriffstokens erstellt haben

   • Ziel: Tabelle aus der Aktualisierungstoken-API (in diesem Beispiel Token)

   

4. Klicken Sie im Tabellenbereich auf +Tabellen und fügen Sie die Tabelle aus Ihrer Quelldatenquelle hinzu, in der die DocuSign Informationen gespeichert sind. In diesem Fall ParamDocusign.

5. Suchen Sie auf der Tab „Spalten“ die Spalten, die Sie zum Speichern des Aktualisierungstokens, der ClientID/SecretID und des Berechtigungstyps angegeben haben, und ordnen Sie sie den entsprechenden Spalten in der Token-Tabelle zu, wie unten gezeigt.

   

Erstellen Sie eine XP-Aktualisierungsregel zum Aktualisieren des Zugriffstokens

1. Navigieren Sie vom vorherigen Schritt zurück zur App Workbench

2. Klicken Sie im mittleren Bereich auf Geschäftsregel hinzufügen, um ein neues Geschäftsobjekt zu erstellen.

3. Füllen Sie die folgenden Angaben aus:

   • Name: Tabelle (Aktualisieren, Aktualisieren, Zugriffstoken)

   • Zweck: XP CRUD

   • Deaktivieren Sie „Business-Layer überspringen“

   • Aktion: Aktualisieren

   • Quelldatum Quelle: Die erste REST- API, die Sie zum Aktualisieren des Zugriffstokens erstellt haben

   • Zieldatenquelle: Wo sich die Tabelle mit DocuSign-Informationen befindet

   • Ziel: Tabelle, in der DocuSign Informationen gespeichert sind, in diesem Beispiel ParamDocusign

   

4. Klicken Sie im Tabellenbereich auf Erstellen und fügen Sie die Tabelle mit dem Zugriffstoken hinzu (dies ist der Name des Endpoint, den Sie in der ersten REST- API erstellt haben).

5. Klicken Sie auf Alle, um alle Spalten aus der Tabelle hinzuzufügen

6. Suchen Sie die Spalte mit dem Namen access_token und richten Sie sie auf die Spalte DocusignClientIDSecretID aus, die Sie in der Tabelle erstellt haben.

7. Fügen Sie API Konto-ID als Spalte zu ParamDocusign hinzu und geben Sie deren Wert ein

8. Fügen Sie API Konto-ID als Parameter am Refresh-Token Endpoint hinzu und geben Sie den Wert ein

9. Setzen Sie in der Aktualisierungsregel die API Konto-ID des Aktualisierungstokens auf „Ziel“ für die Konto-ID von ParamDocusign bei der Typbindung und legen Sie sie als PK fest. Dies hat den zusätzlichen Vorteil, dass dies die Konfiguration erleichtert, wenn Sie der Anwendung weitere DocuSign-Konten hinzufügen.

   

Erstellen Sie einen Zeitplan zum Ausführen des Ereignisses „Zugriffstoken aktualisieren“

1. Da das Zugriffstoken abläuft und regelmäßig aktualisiert werden muss, fügen Sie diese Regel einem Ereignis hinzu und erstellen Sie einen Zeitplan.

2. Erstellen Sie das Ereignis, indem Sie zur Business-Logik-Ebene navigieren und im Ereignis-Popup für ParamDocusign auf +Tabellenereignis klicken.

   • Name: Aktualisierungstoken

   • Aktualisierungsbereich: Zeile

   Hinweis

   Stellen Sie sicher, dass unter „Edge Case“ der Ausführungstyp auf „Starten nach Zeitplan mit maximaler Parallelität: 1“ eingestellt ist.

   

3. Klicken Sie unter Aktionen auf Vorhandenes registrieren und fügen Sie die zuvor erstellte CRUD-Regel hinzu: Tabelle (Aktualisieren, Zugriffstoken aktualisieren).

4. Navigieren Sie anschließend zum App Builder Monitor (unten links)  Zeitpläne. Benennen Sie Ihren Zeitplan und wählen Sie die Anwendung aus, in der das für die Regel erstellte Ereignis erstellt wird. Belassen Sie die Häufigkeit bei „Periodische Ausführung des Zeitplans“. Legen Sie unter „Zeitplaninformationen“ die Ausführungshäufigkeit des Zeitplans fest. Empfohlen werden 4 Stunden.

   

   

Da Sie nun Ihren Zugriffstoken planmäßig aktualisieren, können Sie die Verbindung zu Ihrer DocuSign API aufrechterhalten. Erstellen Sie bei Bedarf weitere XP-CRUD-Regeln, um Informationen vom verbundenen DocuSign Konto zu senden oder abzurufen, z. B. die in der zweiten REST- API erstellten Endpoints für Dokumentstatus und Vorlage.

Für einige Funktionen fallen möglicherweise Kosten an, z. B. für die Rückgabe einer Datei über einen Webhook. Alternativ können Sie das HTTP-Retriever-Plugin verwenden.

Förderung der Anwendung für die DocuSign-Produktion

Wenn die von Ihnen erstellten Endpoints und CRUD-Regeln zuverlässig funktionieren, können Sie diese Anwendung in die DocuSign Produktion übernehmen. Dazu müssen Sie die API in DocuSign überprüfen lassen. Für eine erfolgreiche Überprüfung benötigen Sie 20 erfolgreiche API Aufrufe an einem Tag.

1. Navigieren Sie im ersten Schritt zum DocuSign Sandbox-Link und klicken Sie auf Admin. Klicken Sie dann im Menü auf der linken Seite auf Apps & Schlüssel

2. Suchen Sie unter Apps und Integrationsschlüssel die App, die Sie im ersten Schritt erstellt haben, und klicken Sie auf Aktionen. Wählen Sie dann Go-Live-Überprüfung starten und geben Sie ein Datum mit 20 oder mehr erfolgreichen API -Aufrufen ein.

3. Ein DocuSign Administrator überprüft und authentifiziert die Anfrage manuell. Dies kann bis zu 3 Werktage dauern.

4. Nach der Authentifizierung von Go-Live müssen die vorherigen Schritte mit den Produktions DocuSign Anmeldeinformationen wiederholt werden. Der Integrationsschlüssel bleibt unverändert, die anderen Anmeldeinformationen sind jedoch unterschiedlich und müssen in Postman und App Builder aktualisiert werden.

5. Änderungen der oben genannten Schritte:

   • Erstellen Sie in Postman einen neuen GET-Aufruf mit der URL: https://account.docusign.com/oauth/userinfo

   • Kopieren Sie in der Antwort des GET-Aufrufs die „base_uri“, um sie in den POSTs, GETs und HTTP-Abruf URLs für die Umfeld zu verwenden.

   • Beim Erstellen der Refresh Token API für die Produktion lautet die URL https://account.docusign.com