DocuSign Verbindungshandbuch für Jitterbit App Builder

Übersicht

Diese Anleitung beschreibt die Systemanforderungen und Anweisungen zum Anschließen App Builder an einen Docusign Online-Datenbankserver als Voraussetzung für die Nutzung als Dienst in einer Anwendung.

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

Anschlussanleitung

Anmeldeinformationen aus der DocuSign Sandbox abrufen

Melden Sie sich hier bei DocuSign an: https://account-d.docusign.com/
Klicken Sie oben rechts auf der Zielseite auf Einstellungen
Scrollen Sie in der linken Seitenleiste nach unten zu Integrationen und klicken Sie auf Apps & Keys
Erstellen Sie eine Anwendung, indem Sie auf die Schaltfläche APP UND INTEGRATIONSSCHLÜSSEL HINZUFÜGEN klicken.
Geben Sie den Anwendungsnamen ein (in diesem Beispiel ist App Builder DocuSign)
Integrationsschlüssel kopieren und für den nächsten Schritt speichern
- Sie werden die API Konto-ID und die Basis-URI des Kontos auch in späteren Schritten verwenden
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 mehr vollständig anzeigen.
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.)
Klicken Sie auf Speichern
Klicken Sie im Menü der oberen Leiste auf Vorlagen
Klicken Sie oben links auf Neu, um eine neue Vorlage zu erstellen, die beim Verbindungsaufbau verwendet werden soll
Geben Sie Ihrer Vorlage einen Namen, laden Sie ein Dokument hoch und klicken Sie auf Weiter. Fügen Sie dem Dokument optional Signaturbereiche hinzu und klicken Sie dann auf Speichern.
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.

Abrufen eines Aktualisierungstokens mit Postman

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
- Textkörper: x-www-form-urlunencoded
  - Schlüssel: grant_type
  - Wert: authorization_code
  - Schlüssel: Code
  - Wert: *diesen zweiten Wert erhalten Sie im nächsten Schritt

Rufen Sie in einem Webbrowser die folgende Website auf und ersetzen Sie die Werte 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

Nachdem Sie die Eingabe-Taste gedrückt haben, kopieren Sie den Inhalt des URL Felds und fügen Sie ihn an einer Stelle ein, an der Sie die gesamte URL sehen können (sie ist extrem lang). Kopieren Sie den Wert nach code= und vor &state=, dies ist Ihr code-Wert, fügen Sie ihn in den Wert aus Schritt 1 in diesem Abschnitt ein und klicken Sie in Postman auf Senden. **Dieser Schritt muss schnell ausgeführt werden, das Aktualisierungstoken des Webbrowsers ist nur etwa 2 Minuten lang gültig. **

Einrichten der Aktualisierungstoken-API in App Builder

Klicken Sie im Menü „Verbinden“ auf den Link „Mit Ihrem Unternehmen verbinden“
Klicken Sie links auf Datenserver und dann auf Erstellen
Konfigurieren Sie den Server wie folgt:
- Name: Erkennbarer Name
- Typ: REST- API
- URL: https://account-d.docusign.com
- Anforderungsinhaltstyp: Formular
- Antwortinhaltstyp: JSON
Klicken Sie auf Speichern.

Einen API Endpoint hinzufügen

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.
Klicken Sie im Bereich Endpoints unten links auf Erstellen
Fügen Sie die folgenden Details hinzu:
- Name: Benennen Sie Ihren Endpoint
- Endpoint: /oauth/token
- Methode: POST
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 ist in der Tab „Header“ in Postman nach dem POST-Aufruf zum Abrufen des Aktualisierungstokens zu finden. Dort steht basic, gefolgt von einer langen ID. (Möglicherweise müssen Sie in versteckten Headern nachsehen.)
  - Typ: Header
  - Richtung: Eingabe
- Parameter 2
  - Name: Zuwendungstyp
  - 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
Klicken Sie auf Speichern
Klicken Sie auf Verbindung testen, um den Zugriffstoken für den nächsten Schritt zu erhalten

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

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

Klicken Sie auf Importieren

Konfigurieren App Builder für DocuSign

Klicken Sie im Menü „Verbinden“ auf den Link „Mit Ihrem Unternehmen verbinden“
Klicken Sie links auf Datenserver und dann auf Erstellen
Konfigurieren Sie den Server wie folgt:
- Name: Erkennbarer 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

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.
Klicken Sie im Bereich Endpoints unten links auf Erstellen
Fügen Sie die folgenden Details hinzu:
- Name: Benennen Sie Ihren Endpoint
- Endpoint: /v2/accounts/<AccountID>/envelopes
- Methode: POST
Als Nächstes fügen Sie die folgenden Endpoint hinzu, indem Sie im Bereich „Endpoint “ oben rechts 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: Header
  - Richtung: Eingabe
- Parameter 3
  - Name: Email-Text
  - Datentyp: Zeichenfolge
  - Testwert: Email Text Ihrer Wahl, in diesem Beispiel „Ein Dokument muss unterzeichnet werden“
  - Typ: Abfrage
  - Richtung: Eingabe
- Parameter 4
  - Name: Email-Betreff
  - Datentyp: Zeichenfolge
  - Testwert: Email Betreff Ihrer Wahl, in diesem Beispiel „Unterzeichnung“
  - 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
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.
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

Klicken Sie im Bereich Endpoints unten links auf Erstellen
Fügen Sie die folgenden Details hinzu:
- Name: Benennen Sie Ihren Endpoint
- Endpoint: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>
- Methode: GET
Als Nächstes fügen Sie die folgenden Endpoint hinzu, indem Sie im Bereich „Endpoint “ oben rechts 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: Header
  - 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
Klicken Sie auf Verbindung testen, um sicherzustellen, dass die Parameter korrekt eingegeben wurden, und um die Testergebnisse anzuzeigen.

DocuSign Tabellen zur späteren Verwendung öffentlich machen

Von der App Builder IDE, klicken Sie auf Erstellen Sie Ihre Anwendung
Klicken Sie auf die Datenspeicherebene und suchen Sie unter Webdienste die DocuSign Rest API, die Sie im vorherigen Schritt erstellt haben
Klicken Sie auf das Zahnradsymbol Tabellen
Doppelklicken Sie für jede Tabelle auf die Tabelle und klicken Sie auf Edge Case Settings
Klicken Sie unter Öffentlicher Zugriff auf Lesen zulassen und Schreiben zulassen
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.

Konfigurieren App Builder Regeln für DocuSign

Spalten für DocuSign Informationen hinzufügen

Von der App Builder IDE, klicken Sie auf Erstellen Sie Ihre Anwendung
Klicken Sie auf die Business Logic Layer und suchen Sie die Datenquelle, in der Sie DocuSign Informationen speichern möchten
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*
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).
Erstellen Sie in der Tabelle die folgenden Spalten:
- DocusignBaseURL (NVarchar(50))
- DocusignGrantType (NVarchar(50))
- DocusignRefreshToken (NVarchar(-1))
- Geheime ID des Docusign-Clients (NVarchar(-1))
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
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 nach dem Aufruf in das Token einzufügen

Navigieren Sie vom vorherigen Schritt zurück zur App Workbench
Klicken Sie im mittleren Bereich auf Geschäftsregel hinzufügen, um ein neues Geschäftsobjekt zu erstellen.
Füllen Sie die folgenden Angaben aus:
- Name: Tabelle (Aktualisierungs-Zugriffstoken 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 Aktualisierungs-Token API (in diesem Beispiel Token)
Klicken Sie im Bereich „Tabellen“ auf +Tabellen und fügen Sie die Tabelle aus Ihrer Quelldatenquelle hinzu, in der die DocuSign Informationen gespeichert werden. In diesem Fall ParamDocusign.
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

Navigieren Sie vom vorherigen Schritt zurück zur App Workbench
Klicken Sie im mittleren Bereich auf Geschäftsregel hinzufügen, um ein neues Geschäftsobjekt zu erstellen.
Füllen Sie die folgenden Angaben aus:
- Name: Tabelle (Update-Aktualisierungs-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
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).
Klicken Sie auf Alle, um alle Spalten aus der Tabelle hinzuzufügen
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.
Fügen Sie API Konto-ID als Spalte zu ParamDocusign hinzu und geben Sie deren Wert ein
Fügen Sie API Konto-ID als Parameter am Refresh-Token-Endpoint hinzu und geben Sie seinen Wert ein
Legen Sie in der Aktualisierungsregel die API Konto-ID des Aktualisierungstokens so fest, dass sie bei der Typbindung auf die Konto-ID von ParamDocusign abzielt, und legen Sie sie als PK fest. Dies hat den zusätzlichen Vorteil, dass diese Konfiguration unterstützt wird, wenn Sie der Anwendung weitere DocuSign-Konten hinzufügen möchten.

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

Da das Zugriffstoken abläuft und regelmäßig aktualisiert werden muss, fügen Sie diese Regel einem Ereignis hinzu und erstellen Sie einen Zeitplan.
Erstellen Sie das Ereignis, indem Sie zur Ebene der Geschäftslogik navigieren und unter „Ereignisse“ für ParamDocusign auf +Tabellenereignis klicken.
- Name: RefreshToken
- Aktualisierungsbereich: Zeile
Hinweis

Stellen Sie sicher, dass unter „Edge Case“ der Ausführungstyp auf „Starten per Zeitplan mit maximaler Parallelität: 1“ eingestellt ist.
Klicken Sie unter Aktionen auf Vorhandenes registrieren und fügen Sie die zuvor erstellte CRUD-Regel hinzu: Tabelle (Update Refresh Access Token).
Navigieren Sie anschließend zu App Builder Monitor (unten links)  Zeitpläne. Benennen Sie Ihren Zeitplan und wählen Sie die Anwendung aus, in der das von Ihnen für die Regel erstellte Ereignis erstellt wird. Lassen Sie die Häufigkeit bei „Periodische Ausführung des Zeitplans“ unverändert. Legen Sie unter Zeitplaninformationen die Häufigkeit fest, mit der der Zeitplan ausgeführt werden soll. 4 Stunden werden empfohlen.

Da Sie nun Ihren Zugriffstoken planmäßig aktualisieren, können Sie eine Verbindung zu Ihrer DocuSign API aufrechterhalten. Erstellen Sie nach 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 „Dokumentstatus“ und „Vorlage“.

Für einige Funktionen können Kosten anfallen, z. B. für die Rückgabe einer Datei über einen Webhook. Eine weitere Option ist die Verwendung des HTTP-Retriever-Plugins.

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 einbinden. Dazu müssen Sie die API in DocuSign überprüfen lassen. Um die Überprüfung zu bestehen, müssen Sie an einem Tag 20 erfolgreiche API Aufrufe durchführen.

Navigieren Sie im ersten Schritt zum DocuSign Sandbox-Link und klicken Sie auf Admin. Klicken Sie dann im linken Menü auf Apps & Keys
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.
Ein DocuSign Administrator überprüft und authentifiziert die Anfrage manuell. Dies kann bis zu 3 Werktage dauern.
Nachdem Go-Live authentifiziert wurde, müssen die vorherigen Schritte mit den Produktions DocuSign Anmeldeinformationen wiederholt werden. Der Integrationsschlüssel bleibt unverändert, aber die anderen Anmeldeinformationen sind anders und müssen in Postman aktualisiert werden. App Builder.
Ä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