Document Webhooks-API

Adobe Workfront Document Webhooks definiert einen Satz von API-Endpunkten, über die Workfront autorisierte API-Aufrufe an einen externen Dokumentanbieter sendet. Dadurch kann jeder ein Middleware-Plug-in für einen beliebigen Dokumentspeicheranbieter erstellen.

Das Benutzererlebnis bei Webhook-basierten Integrationen ähnelt dem von vorhandenen Dokumentenintegrationen, z. B. Google Drive, Box und Dropbox. Beispielsweise kann ein Workfront-Benutzer die folgenden Aktionen ausführen:

Referenzimplementierung

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

Registrieren von Webhook-Integrationen

Workfront-Administratoren können eine benutzerdefinierte Webhook-Integration für ihr Unternehmen hinzufügen, indem sie in Workfront zu Einrichtung > Dokumente > Benutzerdefinierte Integrationen navigieren. Auf der Seite „Benutzerdefinierte Integration“ im Setup können Admins 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-Dokument-Webhooks unterstützen zwei verschiedene Authentifizierungsformen: OAuth2 und ApiKey. In beiden Fällen übergibt Workfront bei einem API-Aufruf Authentifizierungs-Token in der -Kopfzeile.

OAuth2

Mit OAuth2 kann Workfront im Namen eines Benutzers autorisierte API-Aufrufe an einen Webhook-Anbieter durchführen. Zuvor muss der Benutzer sein externes Dokumentenanbieterkonto mit Workfront verbinden und Workfront gewähren

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

ApiKey

Die Durchführung autorisierter API-Aufrufe an einen Webhook-Anbieter mithilfe eines APIkeys ist viel einfacher als OAuth2. Wenn Sie einen API-Aufruf ausführen, übergibt Workfront einfach den API-Schlüssel und den Workfront-Benutzernamen in der HTTP-Anfrage-Kopfzeile:

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

apiKey: 12345

username: johndoe@foo.com

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

Der Webhook-Anbieter 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 Anfrage-Headern (optional)

Zusätzlich zur Verwendung von OAuth2-Token oder eines API-Schlüssels zur Authentifizierung kann Workfront für jeden API-Aufruf einen vordefinierten Satz von Kopfzeilen an den Webhook-Anbieter senden. Ein Workfront-Administrator kann dies beim Registrieren oder Bearbeiten einer Webook-Integration einrichten, wie im obigen Abschnitt beschrieben. Siehe Registrieren einer Webhook-Integration.

Dies kann beispielsweise für die Standardauthentifizierung verwendet werden. Dazu fügt der Workfront-Administrator die folgenden Anfrage-Header-Informationen im Dialogfeld für die benutzerdefinierte Integration hinzu:

Zulassung Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

wobei QWxhZGRpbjpvcGVuIHNlc2FtZQ== eine base-64-kodierte Zeichenfolge von „username:password“ ist. Siehe Standardauthentifizierung . Sofern dies hinzugefügt wurde, übergibt Workfront dies zusätzlich zu anderen Anfrage-Headern in der HTTP-Anfrage-Kopfzeile:

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

apiKey: 12345

username: johndoe@foo.com

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

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

API-Spezifikation

Nachfolgend finden Sie eine Liste der APIs, die der Webhook-Anbieter implementieren sollte, damit Dokument-Webhooks funktionieren.

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

Gibt das OAuth2-Aktualisierungs-Token und Zugriffs-Token für einen authentifizierten Benutzer zurück. Dieser wird einmal aufgerufen, wenn der Benutzer einen Dokumentanbieter bereitstellt. Nachfolgende Aufrufe erfolgen, um ein aktualisiertes Zugriffstoken abzurufen.

HTTP-Anfrage-POST /any/url

Die URL ist konfigurierbar und entspricht dem Token-Endpunkt-URL-Wert auf der Seite „Benutzerdefiniertes Integrations-Setup“.

Abfrageparameter

Antwort

Beispiel

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

Antwort

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

Abrufen von Metadaten für Datei oder Ordner

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

URL

GET /metadata?id=[document or folder ID]

Abfrageparameter

Antwort

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

Antwort

{
"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 für einen bestimmten Ordner zurück.

URL

GET /files

Abfrageparameter

Die Document Webhooks-API unterstützt derzeit nicht die Paginierung.

Antwort

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

Antwort

[
{
"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"
},
]

Suche durchführen

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

URL

GET/search

Abfrageparameter

Die Document Webhooks-API unterstützt derzeit nicht die Paginierung.

Antwort

JSON mit einer Liste von Metadaten für Dateien und Ordner, die mit der Abfrage übereinstimmen. Was eine „Übereinstimmung“ darstellt, wird vom Webhook-Anbieter bestimmt. Idealerweise sollte dies eine Volltextsuche sein. Eine auf Dateinamen basierende Suche funktioniert ebenfalls.

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

Antwort

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

Abrufen des Inhalts eines Dokuments

Gibt die Rohbytes für ein Dokument zurück.

URL

GET/Download

Abfrageparameter

Antwort

Die Rohbytes des Dokuments.

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

Abrufen einer Miniaturansicht für ein Dokument

Gibt die rohen Miniaturbyte für ein Dokument zurück.

URL

GET/Thumbnail

Abfrageparameter

Antwort

Die rohen Miniaturansichten in Bytes.

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

Datei hochladen - Teil 1 von 2

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

In Version 1.1 dieser Spezifikation können die Dokument-ID und Dokumentversions-ID hinzugefügt werden, um zusätzliche Informationen von Workfront abzurufen. Wenn das Dokumentenverwaltungssystem beispielsweise zusätzliche Informationen zum Dokument benötigt, könnte der Webhook-Implementierungs-Code die Dokument-ID verwenden, um diese Informationen mithilfe der RESTful-API von Workfront abzurufen. Als Best Practice empfiehlt es sich, diese Informationen aus benutzerdefinierten Datenfeldern im Dokument zu generieren, das die Aufgabe, das Problem oder das Projekt enthält.

URL

POST /uploadInit

Abfrageparameter

Antwort

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

Antwort

[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-Anbieter hoch.

URL

PUT/Upload

Abfrageparameter

Anfragetext

Die Rohdaten-Inhaltsbytes für das Dokument.

Antwort

{
"result": "success"
}

oder

{
"result": "fail"
}

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

Antwort

{
"result":"success"
}

Abrufen von Informationen über den Service

(Veröffentlichungsdatum - wird noch bekannt gegeben) Gibt Informationen zum Service zurück, z. B. Funktionen und Merkmale. Workfront verwendet diese Informationen, um die Benutzeroberfläche in Workfront anzupassen. Wenn die Webhook-Implementierung beispielsweise benutzerdefinierte Aktionen enthält, sollte die JSON diese Vorgänge in der JSON-Datei auflisten. Benutzer können dann diese Aktionen von Workfront aus aufrufen.

URL

GET /serviceInfo

Abfrageparameter

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

Antwort

JSON mit Informationen zu diesem Service

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

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

POST /createFolder

Abfrageparameter

Antwort

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 ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

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

Rückgabe

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

Dokument oder Ordner löschen

(Veröffentlichungsdatum - wird noch bekannt gegeben) Löscht ein Dokument oder einen Ordner mit der angegebenen ID im externen System. Beim Löschen eines Ordners wird auch dessen Inhalt gelöscht.

URL

PUT/Löschen

Abfrageparameter

Antwort Eine JSON-Zeichenfolge, die Erfolg oder Fehler angibt, wie im Abschnitt Fehlerbehandlung unten angegeben.

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

Rückgabe

{
"status": "success"
}

Rückgabe

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

Dokument oder Ordner umbenennen

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

URL

PUT/Umbenennen

Abfrageparameter

Antwort

Eine JSON-Zeichenfolge, die Erfolg oder Fehler anzeigt, wie im Abschnitt Fehlerbehandlung 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 - wird noch bekannt gegeben) Dieser Endpunkt ermöglicht es einem Workfront-Benutzer (oder vielleicht einem automatisierten Workflow-Ereignis), eine Aktion im externen System durchzuführen. Der /customAction-Endpunkt akzeptiert einen „name“-Parameter, mit dem der Webhook-Anbieter mehrere benutzerdefinierte Vorgänge implementieren kann.

Der Webhook-Anbieter registriert benutzerdefinierte Aktionen bei Workfront, indem er die Aktionen in die /serviceInfo-Antwort unter customActions aufnimmt. Workfront lädt diese Liste, wenn Sie den Webhook-Anbieter unter Einrichtung > Dokumente > Benutzerdefinierte Integrationen einrichten oder aktualisieren.

Benutzerinnen und Benutzer können die benutzerdefinierte Aktion mit Triggern versehen, indem sie den Abschnitt unter „Dokumentaktionen“ auswählen

URL

GET/customAction

Abfrageparameter

Antwort

Eine JSON-Zeichenfolge, die Erfolg oder Fehler anzeigt, wie im Abschnitt Fehlerbehandlung unten angegeben. Bei einem Fehler (d. h. Status = „Fehler„) zeigt Workfront dem Benutzer die bereitgestellte Fehlermeldung an.

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

Antwort

{
"status": "success"
}

Fehlerbehandlung

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

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

Testen

Um sicherzustellen, dass die Webhook-Implementierung des Dokuments ordnungsgemäß funktioniert, führen Sie die folgenden Tests aus. Hierbei handelt es sich um manuelle Tests, die die Workfront-Web-Schnittstelle durchlaufen und indirekt die Endpunkte für Ihre Webhook-Implementierung treffen.

Voraussetzungen

Um diese Tests auszuführen, benötigen Sie Folgendes:

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

Test 1: Bereitstellen des Document Webhook-Service für einen Benutzer

Testet die Authentifizierungs-URL und Token-Endpunkt-URL für OAuth-basierte Webhook-Anbieter.

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

Test 3: Navigieren zu einem Dokument im Content-Management-System

Testet die folgenden Endpunkte: /metadata (insbesondere den viewLink)

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

Testet die folgenden Endpunkte: /metadata (insbesondere den viewLink)

Test 5: Herunterladen des Dokuments aus dem Content-Management-System

Testet die folgenden Endpunkte: /metadata (insbesondere den downloadLink)

Test 6: Suchen nach Inhalten

Testet die folgenden Endpunkte: /search

Test 7: Senden 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 Endpoint URL

Versionen