Document Webhooks-API

Adobe Workfront Document Webhooks definiert eine Reihe von API-Endpunkten, über die Workfront autorisierte API-Aufrufe an einen externen Dokumentanbieter sendet. Dadurch kann jeder ein Middleware-Plugin für jeden Dokumentenspeicher erstellen.

Das Benutzererlebnis für webhook-basierte Integrationen ähnelt dem von vorhandenen Dokumentenintegrationen wie Google Drive, Box und Dropbox. Ein Workfront-Benutzer kann beispielsweise die folgenden Aktionen durchführen:

Referenzimplementierung

Um die Entwicklung einer neuen Webhooks-Implementierung zu beschleunigen, stellt Workfront eine Referenzimplementierung bereit. Der Code dafür finden Sie unter https://github.com/Workfront/webhooks-app. Diese Implementierung ist Java-basiert und ermöglicht es Workfront, Dokumente in einem Netzwerkdateisystem zu verbinden.

Registrieren einer Webhook-Integration

Workfront-Administratoren können eine benutzerdefinierte Webhook-Integration für ihr Unternehmen hinzufügen, indem sie zu Einrichtung > Dokumente > Benutzerdefinierte Integrationen in Workfront navigieren. Auf der Seite Benutzerspezifische Integration unter Einrichtung können Administratoren eine Liste der vorhandenen Dokument-Webhook-Integrationen anzeigen. Auf dieser Seite können Integrationen hinzugefügt, bearbeitet, aktiviert und deaktiviert werden. Um eine Integration hinzuzufügen, klicken Sie auf die Schaltfläche "Integration hinzufügen".

Verfügbare Felder

Beim Hinzufügen einer Integration gibt der Administrator Werte für die folgenden Felder ein:

Authentifizierung

Workfront Document Webhooks unterstützt zwei verschiedene Authentifizierungsformen: OAuth2 und ApiKey. In beiden Fällen übergibt Workfront beim Ausführen eines API-Aufrufs Authentifizierungstoken in der Kopfzeile.

OAuth2

Mit OAuth2 kann Workfront im Auftrag eines Benutzers autorisierte API-Aufrufe an einen Webhook-Provider senden. Dazu muss der Benutzer sein externes Document Provider-Konto mit Workfront verbinden und Workfront gewähren

Zugang zu Handlungen in ihrem Namen. Dieser Handshaking-Prozess erfolgt nur einmal für jeden Benutzer. So funktioniert es:

ApiKey

Autorisierte API-Aufrufe an einen Webhook-Provider mithilfe eines APIKey durchzuführen, ist viel einfacher als OAuth2. Beim Ausführen eines API-Aufrufs übergibt Workfront einfach den ApiKey- und Workfront-Benutzernamen im HTTP-Anforderungsheader:

-------------------------------

apiKey: 12345

username: johndoe@foo.com

-------------------------------

Der Webhook-Provider kann den Benutzernamen verwenden, um benutzerspezifische Berechtigungen anzuwenden. Dies funktioniert am besten, wenn beide Systeme über Single Sign On (SSO) eine Verbindung zu LDAP herstellen.

Hinzufügen von Anforderungsheadern (optional)

Zusätzlich zur Verwendung von OAuth2-Token oder einem ApiKey zur Authentifizierung kann Workfront für jeden API-Aufruf einen vordefinierten Header-Satz an den Webhook-Provider senden. Ein Workfront-Administrator kann diese Einrichtung bei der Registrierung oder Bearbeitung einer Webook-Integration einrichten, wie im obigen Abschnitt beschrieben. Siehe Registrieren einer Webhook-Integration .

Dies kann beispielsweise für die einfache Authentifizierung verwendet werden. Dazu fügt der Workfront-Administrator die folgenden Request Header-Informationen im Dialogfeld "Benutzerdefinierte Integration"hinzu:

Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ===

wobei QWxhZGRpbjpvcGVuIHNlc2FtZQ== eine Base-64-kodierte Zeichenfolge von "username:password"ist. Siehe Grundlegende Authentifizierung . Sofern dies hinzugefügt wurde, übergibt Workfront dies zusätzlich zu anderen Anforderungsheadern im HTTP-Anforderungsheader:

­­­­­­­­­­­­­­­­­­­­­­­­­­-------------------------------

apiKey: 12345

username: johndoe@foo.com

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

API-Spezifikation

Im Folgenden finden Sie eine Liste der APIs, die der Webhook-Provider implementieren sollte, damit Dokument-Webhooks funktionieren.

Abrufen von OAuth2-Token (nur OAuth2-Authentifizierung erforderlich)

Gibt das OAuth2-Aktualisierungstoken und Zugriffstoken für einen authentifizierten Benutzer zurück. Dies wird einmal aufgerufen, wenn der Benutzer einen Dokumentanbieter bereitstellt. Nachfolgende Aufrufe werden durchgeführt, um ein aktualisiertes Zugriffstoken zu erhalten.

HTTP-Anforderungs-POST /any/url

Die URL kann konfiguriert werden und entspricht dem URL-Wert des Token-Endpunkts auf der Setup-Seite der benutzerdefinierten Integration.

Abfrageparameter

Reaktion

Beispiel

POST /oauth2/token
grant_type=authorization_code
code=d9ac7asdf6asdf579d7a8
client_id=123456
client_secret=6asdf7a7a9a4af

Reaktion

{
"access_token":"ad8af5ad5ads759",
"refresh_token":"9a0h5d87d808ads",
"expires_id":"3600"
}

Abrufen von Metadaten für Dateien oder Ordner

Gibt Metadaten für die angegebene Datei oder den angegebenen Ordner zurück.

URL

GET /metadata?id=[Dokument- oder Ordner-ID]

Abfrageparameter

Reaktion

Beispiel: https://www.acme.com/api/metadata?id=12345

Reaktion

{
"title":"My Document",
"kind":"file"
"id":"12345",
"viewLink":"https://www.acme.com/viewDocument?id=12345",
"downloadLink":"https://www.acme.com/downloadDocument?id=12345",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size": "32554694"
}

Abrufen einer Liste von Elementen in einem Ordner

Gibt Metadaten für die Dateien und Ordner eines bestimmten Ordners zurück.

URL

GET /files

Abfrageparameter

Die Document Webhooks-API unterstützt derzeit keine Paginierung.

Reaktion

JSON mit einer Liste von Dateien und Ordnern. Die Metadaten für jedes Element sind mit denen identisch, die vom Endpunkt /metadata zurückgegeben werden.

Beispiel: https://www.acme.com/api/files?parentId=123456

Reaktion

[
{
"title":"Folder A",
"kind":"folder",
"id":"2lj23lkj",
"viewLink":"https://www.acme.com/viewDocument?id=2lj23lkj",
"downloadLink":"https://www.acme.com/downloadDocument?id=2lj23lkj",
"mimeType":"",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":""
},
{
"title":"My Document",
"kind":"file",
"id":"da8cj234"
"viewLink":"https://www.acme.com/viewDocument?id=da8cj234",
"downloadLink":"https://www.acme.com/downloadDocument?id=da8cj234",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":"32554694"
},
]

Suchen

Gibt Metadaten für die Dateien und Ordner zurück, die von einer Suche zurückgegeben wurden. Dies kann als Volltextsuche oder als reguläre Datenbankabfrage implementiert werden. Workfront ruft den Endpunkt /search auf, wenn der Benutzer eine Suche über den externen Dateibrowser durchführt.

URL

GET /search

Abfrageparameter

Die Document Webhooks-API unterstützt derzeit keine Paginierung.

Reaktion

JSON mit einer Liste von Metadaten für Dateien und Ordner, die der Abfrage entsprechen. Was eine "Übereinstimmung"ausmacht, wird vom Webhook-Provider bestimmt. Idealerweise sollte eine Volltextsuche durchgeführt werden. Eine filename-basierte Suche funktioniert ebenfalls.

Beispiel: https://www.acme.com/api/search?query=test-query

Reaktion

[
{ File/Folder Metadata },
{ File/Folder Metadata }
]

Abrufen des Inhalts eines Dokuments

Gibt die unformatierten Bytes für ein Dokument aus

URL

GET /download

Abfrageparameter

Reaktion

Die rohen Bytes des Dokuments.

Beispiel: https://www.acme.com/api/download?id=123456

Miniaturansicht für ein Dokument abrufen

Gibt die unformatierten Miniaturansichten für ein Dokument zurück.

URL

GET /thumbnail

Abfrageparameter

Reaktion

Die unformatierten Miniaturansichten.

Beispiel: https://www.acme.com/api/thumbnail?id=123456

Datei hochladen - Teil 1 von 2

Das Hochladen einer Datei in einen Dokumentenspeicheranbieter ist ein zweistufiger Prozess, der zwei separate API-Endpunkte erfordert. Workfront startet den Upload-Prozess durch Aufruf von /uploadInit . Dieser Endpunkt gibt eine Dokument-ID zurück, die beim Hochladen der Dokument-Bytes an /upload übergeben wird. Je nach zugrunde liegendem Dokumentenspeicher kann es erforderlich sein, ein Dokument mit einer Länge von null zu erstellen und den Inhalt des Dokuments später zu aktualisieren.

Wird Version 1.1 dieser Spezifikation hinzugefügt, können die Dokument-ID und die Dokumentversions-ID verwendet werden, um zusätzliche Informationen aus Workfront abzurufen. Wenn das Document Management-System beispielsweise zusätzliche Informationen zum Dokument benötigt, kann der Webhook-Implementierungscode die Dokument-ID verwenden, um diese Informationen mithilfe der Workfront-RESTful-API abzurufen. Als Best Practice empfiehlt sich, diese Informationen aus benutzerdefinierten Datenfeldern im Dokument zu erhalten, die Aufgaben, Probleme oder Projekte enthalten.

URL

POST /uploadInit

Abfrageparameter

Reaktion

Die Metadaten für die Datei, wie vom Endpunkt /metadata definiert.

Beispiel: https://www.acme.com/api/uploadInit?parentId=12345&filename=new-file.png&docu mentId=511ea6e000023edb38d2effb2f4e6e3b&documentVersionId=511ea6e000023edb38d2e ffb2f4e6e3b

Reaktion

[file_metadata] enthält die neue Dokument-ID, die vom Dokumentanbieter verwendet wird.

Datei hochladen - Teil 2 von 2

Lädt die Bytes eines Dokuments in den Webhook-Provider hoch.

URL

PUT /upload

Abfrageparameter

Anfrageinhalt

Die rohen Inhalts-Bytes für das Dokument.

Reaktion

{
"result": "success"
}

oder

{
"result": "fail"
}

Beispiel: https://www.acme.com/api/upload?id=1234 [Dokument-Bytes, die im Aktualisierungsstream enthalten sind]

Reaktion

{
"result":"success"
}

Informationen zum Dienst erhalten

(Releasedatum - TBD) Gibt Informationen zum Dienst zurück, z. B. Funktionen. Workfront verwendet diese Informationen, um die Benutzeroberfläche in Workfront anzupassen. Wenn die Webhook-Implementierung beispielsweise einige benutzerdefinierte Aktionen enthält, sollte die JSON diese Vorgänge in der JSON auflisten. Benutzer können diese Aktionen dann über Workfront aufrufen.

URL

GET /serviceInfo

Abfrageparameter

Keine. Darüber hinaus sollten Aufrufe an diesen Endpunkt keine Authentifizierung erfordern.

Reaktion

JSON mit Informationen zu diesem Dienst

Beispiel: https://www.acme.com/api/serviceInfo

Rückgabe

{
"webhook version": "1.2", "version": "1.0", "publisher": "Acme, LLC", "availableEndpoints": ["files", "metadata", "search", "download"

"thumbnail", "uploadInit", "upload" ], "customActions" [
{
"name": "archive", "displayName": "Archive" }, {

"name": "doSomethingElse", "displayName": "Do Something" }, ] }

Erstellen eines Ordners

(Hinzugefügt in Version 1.2) Erstellt einen Ordner in einem bestimmten Verzeichnis.
URL

POST /createFolder

Abfrageparameter

Reaktion

Die Metadaten für den neu erstellten Ordner, wie vom Endpunkt /metadata definiert.

Beispiel: POST https://www.acme.com/api/createFolder

-------------------------------

parentId=1234

name=New Folder ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

return

{"title":"New Folder",
 "kind":"folder""id":"5678",
 "viewLink":"",
 "downloadLink":"",
 "mimeType":"",
 "dateModified":"2014­06­05T17:39:45.251Z"
 "size": ""
 }

Löschen eines Dokuments oder Ordners

(Veröffentlichungsdatum - TBD) Löscht ein Dokument oder einen Ordner mit der angegebenen ID im externen System. Durch Löschen eines Ordners werden auch dessen Inhalte gelöscht.

URL

PUT/Löschen

Abfrageparameter

Antwort Eine JSON-Zeichenfolge, die auf Erfolg oder Fehler hinweist, wie im Abschnitt Umgang mit Fehlern unten angegeben.

Beispiel: PUT https://www.acme.com/api/delete id=1234

return

{
"status": "success"
}

return

{
"status": "failure", "error": "File not found"
}

Umbenennen eines Dokuments oder Ordners

(Veröffentlichungsdatum - TBD) Benennt ein Dokument oder einen Ordner mit der angegebenen ID im externen System um.

URL

PUT /rename

Abfrageparameter

Antwort

Eine JSON-Zeichenfolge, die den Erfolg oder Fehler angibt, wie im Abschnitt Umgang mit Fehlern unten angegeben.

Beispiel:

PUT https://www.acme.com/api/rename

-------------------------------

id=1234

name=Folder B ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

{
"status": "success"
}returns
{
"status": "failure", error: "Folder cannot be renamed because a folder with that name already exists."
}

Durchführen einer benutzerdefinierten Aktion

(Veröffentlichungsdatum - TBD) Dieser Endpunkt ermöglicht einem Workfront-Benutzer (oder eventuell einem automatisierten Workflow-Ereignis), eine Aktion im externen System durchzuführen. Der Endpunkt /customAction akzeptiert einen Parameter "name", der es dem Webhook-Provider ermöglicht, mehrere benutzerdefinierte Vorgänge zu implementieren.

Der Webhook-Provider registriert benutzerdefinierte Aktionen bei Workfront, indem er die Aktionen in die Antwort /serviceInfo unter customActions einbezieht. Workfront lädt diese Liste beim Einrichten oder Aktualisieren des Webhook-Providers unter Einrichtung > Dokumente > Benutzerdefinierte Integrationen.

Benutzer können die benutzerdefinierte Aktion durch Auswahl des Bereichs unter "Dokumentaktionen"Trigger haben.

URL

GET /customAction

Abfrageparameter

Reaktion

Eine JSON-Zeichenfolge, die den Erfolg oder Fehler angibt, wie im Abschnitt Umgang mit Fehlern unten angegeben. Bei einem Fehler (d. h. Status = "Fehler") zeigt Workfront die bereitgestellte Fehlermeldung an.

Beispiel: https://sample.com/webhooks/customName?name=archive&documentId=5502082c003a4f30 ddec2fb2b739cb7c&documentVersionId=54b598a700e2342d6971597a5df1a8d3

response

{
"status": "success"
}

Umgang mit Fehlern

Bei der Verarbeitung von API-Anfragen können Probleme auftreten. Dies sollte über alle API-Endpunkte hinweg einheitlich gehandhabt werden. Wenn ein Fehler auftritt, führt der Webhook-Provider die folgenden Schritte aus:

{
"status": "error"
"error": "Sample error message"
}

Test

Führen Sie die folgenden Tests aus, um sicherzustellen, dass Ihre Dokument-Webhook-Implementierung ordnungsgemäß funktioniert. Hierbei handelt es sich um manuelle Tests, die über die Workfront-Web-Oberfläche durchgeführt werden und indirekt die Endpunkte für Ihre Webhook-Implementierung erreichen.

Voraussetzungen

Zum Ausführen dieser Tests benötigen Sie Folgendes:

Bei diesen Tests wird außerdem davon ausgegangen, dass Sie Ihre Document Webhook-Instanz bereits in Workfront unter Einrichtung > Dokumente > Benutzerdefinierte Integrationen registriert haben.

Test 1: Bereitstellung des Document Webhook-Dienstes für einen Benutzer

Testen Sie die Authentifizierungs-URL und die Token-Endpunkt-URL für OAuth-basierte Webhook-Provider.

Test 2: Verknüpfen eines Dokuments mit Workfront Tests die folgenden Endpunkte: /files, /metadata

Test 3: Navigieren Sie zu einem Dokument im Content Management System.

Testet die folgenden Endpunkte: /metadata (insbesondere viewLink)

Test 4: Navigieren Sie zu einem Dokument im Content Management System (mit Anmeldung).

Testet die folgenden Endpunkte: /metadata (insbesondere viewLink)

Test 5: Laden Sie das Dokument aus dem Content Management System herunter

Testet die folgenden Endpunkte: /metadata (insbesondere downloadLink)

Test 6: Suche nach Inhalt

Testet die folgenden Endpunkte: /search

Test 7: Versand eines Dokuments von Workfront an das Content Management System

Testet die folgenden Endpunkte: /files, /uploadInit, /upload

Test 8: Anzeigen von Miniaturansichten in Workfront

Testet die folgenden Endpunkte: /thumbnail

Test 9: Abrufen der Inhalts-Bytes

Testet die folgenden Endpunkte: /download

Test 10: Zugriffstoken aktualisieren (nur OAuth2 Webhook-Anbieter)

Testet die folgenden Endpunkte: Token-Endpunkt-URL

Versionen