API Document Webhooks

Les webhooks de document Adobe Workfront définissent un ensemble de points de terminaison d’API par le biais desquels Workfront effectue des appels d’API autorisés à un fournisseur de document externe. Cela permet à tous les utilisateurs de créer un module externe middleware pour n’importe quel fournisseur de stockage de documents.

L’expérience utilisateur des intégrations basées sur webhook est similaire à celle des intégrations de documents existantes, telles que Google Drive, Box et Dropbox. Par exemple, un utilisateur Workfront peut effectuer les actions suivantes :

Implémentation de référence

Pour accélérer le développement d’une nouvelle implémentation de webhooks, Workfront fournit une implémentation de référence. Vous trouverez le code pour cela à l’adresse https://github.com/Workfront/webhooks-app. Cette implémentation est basée sur Java et permet à Workfront de connecter des documents sur un système de fichiers réseau.

Enregistrement d’une intégration Webhook

Les administrateurs Workfront peuvent ajouter une intégration webhook personnalisée pour leur entreprise en accédant à Configuration > Documents > Intégrations personnalisées dans Workfront. Sur la page Intégration personnalisée de Configuration, les administrateurs peuvent afficher une liste des intégrations Webhook de document existantes. Depuis cette page, les intégrations peuvent être ajoutées, modifiées, activées et désactivées. Pour ajouter une intégration, cliquez sur le bouton "Ajouter une intégration".

Champs disponibles

Lors de l’ajout d’une intégration, l’administrateur saisit les valeurs des champs suivants :

Authentification

Les webhooks de documents Workfront prennent en charge deux formes d’authentification différentes : OAuth2 et ApiKey. Dans les deux cas, Workfront transmet des jetons d’authentification dans l’en-tête lors d’un appel API.

OAuth2

OAuth2 permet à Workfront d’effectuer des appels API autorisés à un fournisseur de webhook au nom d’un utilisateur. Avant cela, l’utilisateur doit connecter son compte de fournisseur de documents externe à Workfront et octroyer Workfront.

l'accès pour agir en leur nom. Ce processus de prise en main ne se produit qu’une seule fois pour chaque utilisateur. Voici comment cela fonctionne :

ApiKey

Il est beaucoup plus simple d’effectuer des appels API autorisés à un fournisseur webhook à l’aide d’une ApiKey que OAuth2. Lors d’un appel API, Workfront transmet simplement le nom d’utilisateur ApiKey et Workfront dans l’en-tête de la requête HTTP :

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

apiKey: 12345

username: johndoe@foo.com

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

Le fournisseur Webhook peut utiliser le nom d’utilisateur pour appliquer des autorisations spécifiques à l’utilisateur. Cela fonctionne mieux lorsque les deux systèmes se connectent à LDAP à l’aide de l’authentification unique (SSO).

Ajout d’en-têtes de requête (facultatif)

Outre l’utilisation de jetons OAuth2 ou d’une ApiKey pour l’authentification, Workfront peut envoyer un ensemble prédéfini d’en-têtes au fournisseur webhook pour chaque appel API. Un administrateur Workfront peut configurer cette configuration lors de l’enregistrement ou de la modification d’une intégration de Webook, comme décrit dans la section ci-dessus. Voir Enregistrement d’une intégration Webhook.

Par exemple, cela peut être utilisé pour l’authentification de base. Pour ce faire, l’administrateur de Workfront ajoute les informations d’en-tête de requête suivantes dans la boîte de dialogue Intégration personnalisée :

Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

où QWxhZGRpbjpvcGVuIHNlc2FtZQ== est une chaîne codée en base 64 de "username:password". Voir Authentification de base . A condition que cela ait été ajouté, Workfront transmettra cette information dans l’en-tête de requête HTTP, en plus des autres en-têtes de requête :

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

apiKey: 12345

username: johndoe@foo.com

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

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

Spécification de l’API

Vous trouverez ci-dessous une liste des API que le fournisseur webhook doit implémenter pour que les webhooks de document fonctionnent.

Obtention de jetons OAuth2 (authentification OAuth2 requise uniquement)

Renvoie le jeton d’actualisation OAuth2 et le jeton d’accès pour un utilisateur authentifié. Il est appelé une fois lorsque l’utilisateur a configuré un fournisseur de documents. Les appels suivants sont effectués pour obtenir un jeton d’accès mis à jour.

POST de requêtes HTTP /any/url

L’URL est configurable et correspond à la valeur de l’URL Point d’entrée du jeton sur la page de configuration de l’intégration personnalisée.

Paramètres de requête

Réponse

Exemple

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

Réponse

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

Obtention de métadonnées pour un fichier ou un dossier

Renvoie les métadonnées du fichier ou du dossier spécifié.

URL

GET /metadata?id=[ID de document ou de dossier]

Paramètres de requête

Réponse

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

Réponse

{
"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"
}

Obtention d’une liste d’éléments dans un dossier

Renvoie les métadonnées des fichiers et des dossiers d’un dossier donné.

URL

GET /files

Paramètres de requête

L’API Document Webhooks ne prend actuellement pas en charge la pagination.

Réponse

JSON contenant une liste de fichiers et de dossiers. Les métadonnées de chaque élément sont les mêmes que celles renvoyées par le point de terminaison /metadata .

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

Réponse

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

Exécution d’une recherche

Renvoie les métadonnées des fichiers et dossiers renvoyés à partir d’une recherche. Cela peut être mis en oeuvre sous la forme d’une recherche de texte intégral ou d’une requête de base de données classique. Workfront appelle le point de terminaison /search lorsque l’utilisateur effectue une recherche à partir du navigateur de fichiers externe.

URL

GET /search

Paramètres de requête

L’API Document Webhooks ne prend actuellement pas en charge la pagination.

Réponse

JSON contenant une liste de métadonnées pour les fichiers et les dossiers correspondant à la requête. Ce qui constitue une "correspondance" est déterminé par le fournisseur webhook. Idéalement, il doit effectuer une recherche de texte intégral. Une recherche basée sur un nom de fichier fonctionne également.

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

Réponse

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

Obtention du contenu d’un document

Renvoie les octets bruts d’un document

URL

GET /download

Paramètres de requête

Réponse

octets bruts du document.

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

Obtention d’une miniature pour un document

Renvoie les octets de miniature bruts d’un document.

URL

GET /thumbnail

Paramètres de requête

Réponse

Octets de miniature bruts.

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

Chargement d’un fichier - Partie 1 de 2

Le téléchargement d’un fichier vers un fournisseur de stockage de documents est un processus en deux étapes qui nécessite deux points de terminaison d’API distincts. Workfront commence le processus de chargement en appelant /uploadInit . Ce point de terminaison renvoie un ID de document qui est ensuite transmis à /upload lors du téléchargement des octets de document. Selon le système de stockage de documents sous-jacent, il peut être nécessaire de créer un document de longueur zéro, puis de mettre à jour le contenu du document ultérieurement.

Ajouté à la version 1.1 de cette spécification, l’ID de document et l’ID de version de document peuvent être utilisés pour récupérer des informations supplémentaires auprès de Workfront. Par exemple, si le système de gestion des documents souhaite des informations supplémentaires sur le document, le code de mise en oeuvre webhook peut utiliser l’ID de document pour récupérer ces informations à l’aide de l’API RESTful de Workfront. En règle générale, ces informations peuvent provenir de champs de données personnalisés sur le document et contiennent une tâche, un problème ou un projet.

URL

POST /uploadInit

Paramètres de requête

Réponse

Métadonnées du fichier, telles que définies par le point de terminaison /metadata .

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

Réponse

[file_metadata] inclut le nouvel ID de document utilisé par le fournisseur de documents.

Chargement d’un fichier - Partie 2 de 2

Télécharge les octets d’un document vers le fournisseur webhook.

URL

PUT /upload

Paramètres de requête

Corps de requête

octets de contenu brut du document.

Réponse

{
"result": "success"
}

ou

{
"result": "fail"
}

Exemple : https://www.acme.com/api/upload?id=1234 [octets de document inclus dans le flux de mise à jour]

Réponse

{
"result":"success"
}

Obtention d’informations sur le service

(Date de publication - À déterminer) Renvoie des informations sur le service, telles que les fonctionnalités. Workfront utilisera ces informations pour personnaliser l’interface utilisateur dans Workfront. Par exemple, si l’implémentation du webhook contient des actions personnalisées, le fichier JSON doit répertorier ces opérations dans le fichier JSON. Les utilisateurs pourront alors appeler ces actions à partir de Workfront.

URL

GET /serviceInfo

Paramètres de requête

Aucun. En outre, les appels à ce point de terminaison ne doivent pas nécessiter d’authentification.

Réponse

JSON contenant des informations sur ce service

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

Renvoie

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

Création d’un dossier

(Ajout dans la version 1.2) Crée un dossier dans un répertoire donné.
URL

POST /createFolder

Paramètres de requête

Réponse

Métadonnées du dossier nouvellement créé, telles que définies par le point de terminaison /metadata .

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

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

parentId=1234

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

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

renvoie

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

Supprimer un document ou un dossier

(Date de publication - À déterminer) Supprime un document ou un dossier avec l’ID donné dans le système externe. La suppression d’un dossier entraîne celle de son contenu.

URL

PUT /delete

Paramètres de requête

Réponse Chaîne JSON indiquant un succès ou un échec, comme indiqué dans la section Gestion des erreurs ci-dessous.

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

renvoie

{
"status": "success"
}

renvoie

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

Renommer un document ou un dossier

(Date de publication - à déterminer) Renomme un document ou un dossier avec l’ID donné dans le système externe.

URL

PUT /rename

Paramètres de requête

réponse

Chaîne JSON indiquant la réussite ou l’échec, comme indiqué dans la section Gestion des erreurs ci-dessous.

Exemple:

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."
}

Exécution d’une action personnalisée

(Date de publication - à déterminer) Ce point de terminaison permet à un utilisateur Workfront (ou peut-être à un événement de workflow automatisé) d’effectuer une action dans le système externe. Le point d’entrée /customAction accepte un paramètre "name", qui permet au fournisseur webhook d’implémenter plusieurs opérations personnalisées.

Le fournisseur de webhook enregistre des actions personnalisées avec Workfront en incluant les actions dans la réponse /serviceInfo sous customActions. Workfront charge cette liste lors de la configuration ou de l’actualisation du fournisseur webhook sous Configuration > Documents > Intégrations personnalisées.

Les utilisateurs peuvent déclencher l’action personnalisée en sélectionnant la section située sous "Actions de document".

URL

GET /customAction

Paramètres de requête

Réponse

Chaîne JSON indiquant la réussite ou l’échec, comme indiqué dans la section Gestion des erreurs ci-dessous. En cas d’échec (c.-à-d. status = "failure"), Workfront affiche le message d’erreur fourni à l’utilisateur.

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

response

{
"status": "success"
}

Gestion des erreurs

Des problèmes peuvent survenir lors du traitement des demandes d’API. Cela doit être géré de manière cohérente sur tous les points de terminaison de l’API. Lorsqu’une erreur se produit, le fournisseur webhook effectue les opérations suivantes :

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

Tests

Pour vérifier que l’implémentation de webhook de votre document fonctionne correctement, exécutez les tests suivants. Il s’agit de tests manuels qui passent par l’interface web de Workfront et atteignent indirectement les points de terminaison de votre implémentation de webhook.

Conditions préalables

Pour exécuter ces tests, vous aurez besoin des éléments suivants :

Ces tests supposent également que vous avez déjà enregistré votre instance Document Webhook dans Workfront sous Configuration > Documents > Intégrations personnalisées.

Test 1 : Configuration du service Document Webhook pour un utilisateur

Teste l’URL d’authentification et l’URL du point de terminaison du jeton pour les fournisseurs WebHook basés sur OAuth.

Test 2 : lier un document à Workfront Tests les points de terminaison suivants : /files, /metadata

Test 3 : Accédez à un document dans le système de gestion de contenu

Teste les points de terminaison suivants : /metadata (en particulier viewLink)

Test 4 : Accédez à un document dans le système de gestion de contenu (avec connexion).

Teste les points de terminaison suivants : /metadata (en particulier viewLink)

Test 5 : Téléchargez le document à partir du système de gestion de contenu

Teste les points de terminaison suivants : /metadata (en particulier downloadLink)

Test 6 : Recherche de contenu

Teste les points de terminaison suivants : /search

Test 7 : envoyer le document de Workfront vers le système de gestion de contenu

Teste les points de terminaison suivants : /files, /uploadInit, /upload

Test 8 : Affichage des miniatures dans Workfront

Teste les points de terminaison suivants : /thumbnail

Test 9 : Obtention des octets de contenu

Teste les points de terminaison suivants : /download

Test 10 : Actualiser le jeton d’accès (fournisseurs OAuth2 Webhook uniquement)

Teste les points de terminaison suivants : URL du point de terminaison du jeton

Versions