API Document Webhooks

Adobe Workfront Document Webhooks définit un ensemble de points d’entrée d’API par le biais desquels Workfront effectue des appels API autorisés à un fournisseur de documents externe. Cela permet à n’importe qui de créer un plug-in d’intergiciel pour n’importe quel fournisseur de stockage de documents.

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

Implémentation de référence

Pour aider à démarrer le développement d’une nouvelle implémentation de webhooks, Workfront fournit une implémentation de référence. Le code correspondant se trouve à l’adresse suivante : 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 en réseau.

Enregistrement d’une intégration de webhook

Les administrateurs et administratirces Workfront peuvent ajouter une intégration de webhook personnalisée pour leur société en naviguant vers Configuration > Documents > Intégrations personnalisées dans Workfront. À partir de la page Intégration personnalisée de la configuration, les administrateurs et administratrices peuvent afficher une liste des intégrations de webhook de documents existantes. Cette page permet d’ajouter, de modifier, d’activer et de désactiver des intégrations. 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 ou administratrice saisit des valeurs pour les champs suivants :

Authentification

Workfront Document Webhooks prend 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 webhooks au nom d’un utilisateur ou d’une utilisatrice. Avant cela, l’utilisateur ou l’utilisatrice doit connecter son compte de fournisseur de documents externe à Workfront et accorder à Workfront l’accès pour agir en son nom. Ce processus de liaison ne s’opère qu’une seule fois pour chaque personne. Voici comment cela fonctionne :

ApiKey

Il est beaucoup plus simple d’effectuer des appels API autorisés vers un fournisseur de webhooks avec ApiKey plutôt qu’avec OAuth2. Lors d’un appel API, Workfront transmet simplement les noms d’utilisateur ou d’utilisatrice ApiKey et Workfront dans l’en-tête de la requête HTTP :

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

apiKey: 12345

username: johndoe@foo.com

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

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

Ajouter des en-têtes de requête (optionnel)

En plus des jetons OAuth2 ou d’une ApiKey pour l’authentification, Workfront peut transmettre un ensemble prédéfini d’en-têtes au fournisseur de webhooks pour chaque appel API. Un administrateur Workfront peut le configurer lors de l’enregistrement ou de la modification d’une intégration Webook, comme décrit dans la section ci-dessus.

Par exemple, cela peut être utilisé pour l’authentification de base. Pour cela, l’administration Workfront doit inclure les informations suivantes dans l’en-tête de la requête dans la boîte de dialogue de l’intégration personnalisée :

Autorisation de base QWxhZGRpbjpvcGVuIHNlc2FtZQ==

où QWxhZGRpbjpvcGVuIHNlc2FtZQ== est une chaîne encodée en Base64 de « username:password ». Voir Authentification de base. Si ce paramètre est ajouté, Workfront le transmettra dans l’en-tête de requête HTTP en plus d’autres en-têtes de requête :

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

apiKey: 12345

username: johndoe@foo.com

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

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

Spécifier les API

Vous trouverez ci-dessous une liste des API que le fournisseur de webhooks doit mettre en œuvre pour que Document Webhooks fonctionne.

Obtenir des jetons OAuth2 (seule une authentification OAuth2 est nécessaire)

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

Requête HTTP POST /any/url

L’URL est configurable et correspond à la valeur de l’URL du point d’entrée de jeton sur la page 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"
}

Obtenir les métadonnées d’un fichier ou d’un dossier

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

URL

GET /metadata?id=[ID du document ou du 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"
}

Obtenir une liste d’éléments d’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 pas en charge la pagination pour le moment.

Réponse

Le fichier JSON contenant une liste de fichiers et de dossiers. Les métadonnées de chaque élément sont identiques à celles renvoyées par le point d’entrée /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"
},
]

Effectuer une recherche

Renvoie les métadonnées des fichiers et dossiers renvoyés à partir d’une recherche. Cela peut être mis en œuvre 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 d’entrée /search lorsque l’utilisateur ou l’utilisatrice effectue une recherche à partir du navigateur de fichiers externe.

URL

GET /search

Paramètres de requête

L’API Document Webhooks ne prend pas en charge la pagination pour le moment.

Réponse

JSON contenant une liste de métadonnées pour les fichiers et les dossiers correspondant à la requête. Le fournisseur de webhook détermine ce qui constitue une « correspondance ». Idéalement, il doit effectuer une recherche de texte intégral ou basée sur un nom de fichier.

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

Réponse

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

Obtenir le 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

Obtenir une miniature pour un document

Renvoie les octets bruts de la miniature pour un document.

URL

GET /thumbnail

Paramètres de requête

Réponse

Octets bruts de la miniature.

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

Charger un fichier - Partie 1 sur 2

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

Ajoutés à la version 1.1 de cette spécification, l’identifiant du document et l’identifiant de la version du document peuvent être utilisés pour extraire des informations supplémentaires de Workfront. Par exemple, si le système de gestion des documents souhaite obtenir des informations supplémentaires sur le document, le code d’implémentation du webhook pourrait utiliser l’identifiant du document pour récupérer ces informations à l’aide de l’API RESTful de Workfront. Il est recommandé que ces informations proviennent de champs de données personnalisés sur le document et la tâche, le problème ou le projet qui le contient.

URL

POST /uploadInit

Paramètres de requête

Réponse

Métadonnées du fichier, telles que définies par le point d’entrée /metadata.

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

Réponse

[file_metadata] comprend le nouvel identifiant du document utilisé par le fournisseur du document.

Charger un fichier - Partie 2 sur 2

Charge les octets d’un document vers le fournisseur du webhook.

URL

PUT /upload

Paramètres de requête

Corps de la requête

Octets du 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"
}

Obtenir des informations sur le service

(Date de publication - à déterminer) Renvoie des informations sur le service, telles que ses caractéristiques et ses capacités. Workfront utilisera ces informations pour personnaliser l’interface d’utilisation de Workfront. Par exemple, si la mise en œuvre du webhook contient des actions personnalisées, le fichier JSON doit énumérer ces opérations dans le fichier JSON. Les utilisateurs et utilisatrices pourront alors invoquer ces actions à partir de Workfront.

URL

GET /serviceInfo

Paramètres de requête

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

Réponse

JSON contenant des informations sur ce service.

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

Retours

{
"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éer 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 d’entrée /metadata.

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

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

parentId=1234

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

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

returns

{"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’identifiant donné dans le système externe. Supprimer un dossier entraîne également la suppression de son contenu.

URL

PUT /delete

Paramètres de requête

Réponse : chaîne JSON indiquant le succès ou l’échec, comme spécifié dans la section sur la gestion des erreurs ci-dessous.

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

returns

{
"status": "success"
}

returns

{
"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’identifiant donné dans le système externe.

URL

PUT /rename

Paramètres de requête

Réponse

Chaîne JSON indiquant le succès ou l’échec, tel que spécifié 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."
}

Effectuer une action personnalisée

(Date de publication - à déterminer) Ce point d’entrée permettra à un utilisateur ou une utilisatrice de 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 « nom », qui permet au fournisseur du webhook de mettre en œuvre plusieurs opérations personnalisées.

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

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

URL

GET /customAction

Paramètres de requête

Réponse

Chaîne JSON indiquant le succès ou l’échec, tel que spécifié dans la section Gestion des erreurs ci-dessous. En cas d’échec (c’est-à-dire si le statut = «échec »), Workfront affichera le message d’erreur envoyé à l’utilisateur ou l’utilisatrice.

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 requêtes API. Cela doit être géré de manière cohérente dans tous les points d’entrée de l’API. Lorsqu’une erreur se produit, le fournisseur du webhook effectue les opérations suivantes :

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

Tests

Pour vérifier que la mise en œuvre du webhook de votre document fonctionne correctement, effectuez les tests suivants : Il s’agit de tests manuels qui passent par l’interface web de Workfront et qui touchent indirectement les points d’entrée de la mise en œuvre de votre webhook.

Conditions préalables

Pour effectuer 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 : allouer le service Document Webhook aux utilisateurs et aux utilisatrices

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

Test 2 : lier un document dans Workfront teste les points d’entrée suivants : /files, /metadata.

Test 3 : accéder à un document dans le système de gestion de contenu

Teste les points d’entrée suivants : /metadata (en particulier le viewLink).

Test 4 : accéder à un document dans le système de gestion de contenu (avec connexion)

Teste les points d’entrée suivants : /metadata (en particulier le viewLink).

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

Teste les points d’entrée suivants : /metadata (en particulier downloadLink).

Test 6 : rechercher du contenu

Teste les points d’entrée suivants : /search.

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

Teste les points d’entrée suivants : /files, /uploadInit, /upload.

Test 8 : afficher des miniatures dans Workfront

Teste les points d’entrée suivants : /thumbnail.

Test 9 : obtenir les octets de contenu

Teste les points d’entrée suivants : /download.

Test 10 : actualiser le jeton d’accès (fournisseurs de webhooks basés sur OAuth2 uniquement)

Teste les points d’entrée suivants : URL du point d’entrée de jeton.

Versions