API de webhooks de documentos

Adobe Workfront Document Webhooks define un conjunto de puntos finales de API a través de los cuales Workfront realiza llamadas de API autorizadas a un proveedor de documentos externo. Esto permite a cualquier usuario crear un complemento de middleware para cualquier proveedor de almacenamiento de documentos.

La experiencia del usuario para integraciones basadas en webhooks será similar a la de integraciones de documentos existentes, como Google Drive, Box y Dropbox. Por ejemplo, un usuario de Workfront podrá realizar las siguientes acciones:

Implementación de referencia

Para ayudar a impulsar el desarrollo de una nueva implementación de webhooks, Workfront proporciona una implementación de referencia. El código para ello se encuentra en https://github.com/Workfront/webhooks-app. Esta implementación está basada en Java y permite a Workfront conectar documentos en un sistema de archivos de red.

Registrar una integración de webhook

Los administradores de Workfront pueden añadir una integración de webhook para su compañía navegando hasta Configuración > Documentos > Integraciones personalizadas en Workfront. Desde la página Integración personalizada dentro de Configuración, los administradores pueden ver una lista de las integraciones de webhook de documentos existentes. Desde esta página, las integraciones se pueden añadir, editar, habilitar y deshabilitar. Para añadir una integración, haga clic en el botón Add Integration.

Campos disponibles

Al añadir una integración, el administrador introduce valores para los campos siguientes:

Autenticación

Los webhooks de documentos de Workfront admiten dos formas diferentes de autenticación: OAuth2 y ApiKey. En ambos casos, Workfront transfiere tokens de autenticación en el encabezado al realizar una llamada de API.

OAuth2

OAuth2 permite a Workfront realizar llamadas de API autorizadas a un proveedor de webhooks en nombre de un usuario. Antes de hacerlo, el usuario debe conectar su cuenta de proveedor de documentos externa a Workfront y conceder acceso a Workfront para que actúe en su nombre. Este proceso de establecimiento de comunicación solo se produce una vez por cada usuario. Funciona de la siguiente manera:

ApiKey

Realizar llamadas de API autorizadas a un proveedor de webhooks mediante una ApiKey es mucho más sencillo que mediante OAuth2. Al realizar una llamada de API, Workfront simplemente transfiere la ApiKey y el nombre de usuario de Workfront en el encabezado de la petición HTTP:

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

apiKey: 12345

username: johndoe@foo.com

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

El proveedor de webhooks puede utilizar el nombre de usuario para aplicar permisos específicos del usuario. Esto funciona mejor cuando ambos sistemas se conectan a LDAP mediante el inicio de sesión único (SSO).

Añadir encabezados de solicitud (opcional)

Además de utilizar tokens de OAuth2 o una ApiKey para la autenticación, Workfront puede enviar un conjunto predefinido de encabezados al proveedor de webhooks para cada llamada de API. Un administrador de Workfront puede configurar esto al registrar o editar una integración de libro web como se describe en la sección anterior.

Por ejemplo, esto se puede utilizar para la autenticación básica. Para ello, la persona con la función de administrador de Workfront añadiría la siguiente información de encabezado de solicitud en el diálogo Integración personalizada:

Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

en que QWxhZGRpbjpvcGVuIHNlc2FtZQ== es una cadena codificada en base 64 de “username:password”. Consulte Autenticación básica. Siempre que se agregue, Workfront pasará esto en el encabezado de solicitud HTTP además de otros encabezados de solicitud:

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

apiKey: 12345

username: johndoe@foo.com

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

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

Especificación de API

A continuación se muestra una lista de las API que el proveedor de webhooks debe implementar para que los webhooks de documentos funcionen.

Obtención de tokens de OAuth2 (solo se necesita autenticación de OAuth2)

Devuelve el token de actualización de OAuth2 y el token de acceso de un usuario autenticado. Se invoca una vez cuando el usuario aprovisiona un proveedor de documentos. Se realizan llamadas posteriores para obtener un token de acceso actualizado.

POST de solicitudes HTTP /any/url

La dirección URL es configurable y corresponde al valor URL del punto final de token en la página Configuración de integración personalizada.

Parámetros de consulta

Respuesta

Ejemplo

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

Respuesta

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

Obtener metadatos para archivo o carpeta

Devuelve los metadatos del archivo o la carpeta especificados.

URL

GET /metadata?id=[ID de documento o carpeta]

Parámetros de consulta

Respuesta

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

Respuesta

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

Obtener una lista de elementos de una carpeta

Devuelve los metadatos de los archivos y carpetas de una carpeta determinada.

URL

GET /files

Parámetros de consulta

Actualmente, la API de webhooks de documentos no admite la paginación.

Respuesta

JSON que contiene una lista de archivos y carpetas. Los metadatos de cada elemento son los mismos que devuelve el extremo /metadata.

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

Respuesta

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

Realizar una búsqueda

Devuelve metadatos de los archivos y carpetas devueltos por una búsqueda. Esto se puede implementar como una búsqueda de texto completo o como una consulta de base de datos normal. Workfront llama al punto final /search cuando el usuario realiza una búsqueda desde el explorador de archivos externo.

URL

GET /search

Parámetros de consulta

Actualmente, la API de webhooks de documentos no admite la paginación.

Respuesta

JSON que contiene una lista de metadatos para archivos y carpetas que coinciden con la consulta. Lo que constituye una “coincidencia” lo determina el proveedor del webhook Lo ideal es que realice una búsqueda de texto completo o basada en nombres de archivo.

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

Respuesta

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

Obtener el contenido de un documento

Devuelve los bytes sin procesar de un documento.

URL

GET /download

Parámetros de consulta

Respuesta

Los bytes sin procesar del documento.

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

Obtener una miniatura de un documento

Devuelve los bytes de la miniatura sin procesar de un documento.

URL

GET /thumbnail

Parámetros de consulta

Respuesta

Los bytes de la miniatura sin procesar.

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

Cargar un archivo: parte 1 de 2

La carga de un archivo a un proveedor de almacenamiento de documentos es un proceso de dos pasos que requiere 2 puntos de conexión de API independientes. Workfront inicia el proceso de carga llamando a /uploadInit Este extremo devuelve un ID de documento, que luego se pasa a /upload al cargar los bytes del documento. Según el sistema de almacenamiento de documentos subyacente, puede ser necesario crear un documento de longitud cero y actualizar el contenido del documento más adelante.

Añadido a la versión 1.1 de esta especificación, el ID de documento y el ID de versión de documento se pueden utilizar para recuperar información adicional de Workfront. Por ejemplo, si el sistema de administración de documentos desea información adicional sobre el documento, el código de implementación del webhook podría utilizar el ID del documento para recuperar esa información mediante la API RESTful de Workfront. Como práctica recomendada, esta información puede proceder de campos de datos personalizados del documento y de su tarea, problema o proyecto contenedor.

URL

POST /uploadInit

Parámetros de consulta

Respuesta

Los metadatos del archivo, tal como se definen en el punto final /metadata.

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

Respuesta

[file_metadata] incluye el nuevo identificador de documento utilizado por el proveedor de documentos.

Cargar un archivo: parte 2 de 2

Carga los bytes de un documento en el proveedor de webhooks.

URL

PUT /upload

Parámetros de consulta

Cuerpo de solicitud

Los bytes de contenido sin procesar del documento.

Respuesta

{
"result": "success"
}

o

{
"result": "fail"
}

Ejemplo: https://www.acme.com/api/upload?id=1234 [bytes de documento incluidos en el flujo de actualización]

Respuesta

{
"result":"success"
}

Obtener información sobre el servicio

(Fecha de publicación: por determinar) Devuelve información sobre el servicio, como las características y funcionalidades. Workfront utilizará esta información para personalizar la interfaz de usuario en Workfront. Por ejemplo, si la implementación del webhook contiene algunas acciones personalizadas, JSON debe enumerar esas operaciones en el JSON. Los usuarios podrían entonces invocar estas acciones desde Workfront.

URL

GET /serviceInfo

Parámetros de consulta

Ninguno. Además, las llamadas a este punto final no deben requerir autenticación.

Respuesta

JSON que contiene información sobre este servicio.

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

Devuelve

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

Crear una carpeta

(Añadido en la versión 1.2) Crea una carpeta en un directorio determinado.
URL

POST /createFolder

Parámetros de consulta

Respuesta

Los metadatos de la carpeta recién creada, tal como se definen en el punto final /metadata.

EjemploPOST https://www.acme.com/api/createFolder

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

parentId=1234

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

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

devoluciones

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

Eliminar un documento o una carpeta

(Fecha de lanzamiento: por determinar) Elimina un documento o una carpeta con el ID proporcionado en el sistema externo. Al eliminar una carpeta, también se elimina su contenido.

URL

PUT /delete

Parámetros de consulta

Cadena de respuesta A JSON que indica éxito o error, como se especifica a continuación en la sección Gestión de errores.

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

devoluciones

{
"status": "success"
}

devoluciones

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

Cambiar el nombre de un documento o carpeta

(Fecha de lanzamiento: por determinar) Cambia el nombre de un documento o una carpeta con el ID proporcionado en el sistema externo.

URL

PUT /rename

Parámetros de consulta

Respuesta

Una cadena JSON que indica éxito o error, tal como se especifica en la sección Gestión de errores que viene a continuación.

Ejemplo:

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

Realizar una acción personalizada

(Fecha de publicación: por determinar) Este punto final permite a un usuario de Workfront (o quizás un evento de flujo de trabajo automatizado) realizar una acción en el sistema externo. El punto final /customAction acepta un parámetro “name”, que permite al proveedor de webhook implementar varias operaciones personalizadas.

El proveedor de webhook registra las acciones personalizadas con Workfront al incluir las acciones en la respuesta /serviceInfo en customActions. Workfront carga esta lista al configurar o actualizar el proveedor de webhook en Configuración > Documentos > Integraciones personalizadas.

Los usuarios pueden almacenar en déclencheur la acción personalizada seleccionando la sección en Acciones de documento.

URL

GET /customAction

Parámetros de consulta

Respuesta

Una cadena JSON que indica éxito o error, tal como se especifica en la sección Gestión de errores que viene a continuación. En caso de error (es decir, estado = "error"), Workfront mostrará el mensaje de error proporcionado al usuario.

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

respuesta

{
"status": "success"
}

Gestión de errores

Pueden surgir problemas a la hora de procesar solicitudes de API. Esto debe gestionarse de forma coherente en todos los puntos finales de la API. Cuando se produce un error, el proveedor del webhook hace lo siguiente:

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

Pruebas

Para comprobar que la implementación del webhook de documentos funciona correctamente, ejecute las siguientes pruebas. Son pruebas manuales que pasan por la interfaz web de Workfront e indirectamente llegan a los puntos finales de la implementación del webhook.

Requisitos previos

Para ejecutar estas pruebas, necesitará lo siguiente:

Estas pruebas también presuponen que ya se ha registrado la instancia de webhook de documentos en Workfront, en Configuración > Documentos > Integraciones personalizadas.

Prueba 1: Aprovisionar el servicio de webhook de documentos para un usuario

Comprueba la URL de autenticación y la URL del punto final del token para proveedores de webhook basados en OAuth.

Prueba 2: Vincular un documento en Workfront prueba los siguientes puntos finales: /files, /metadata

Prueba 3: Desplazarse hasta un documento en el sistema de administración de contenido

Prueba los siguientes extremos: /metadata (específicamente viewLink).

Prueba 4: Desplazarse hasta un documento en el sistema de administración de contenido (con inicio de sesión)

Prueba los siguientes extremos: /metadata (específicamente viewLink).

Prueba 5: Descargar el documento desde el sistema de administración de contenido

Prueba los siguientes extremos: /metadata (específicamente downloadLink).

Prueba 6: Buscar contenido

Comprueba los siguientes puntos finales: /search

Prueba 7: Enviar documento desde Workfront al sistema de administración de contenido

Comprueba los siguientes puntos finales: /files, /uploadInit, /upload

Prueba 8: Ver miniaturas en Workfront

Comprueba los siguientes puntos finales: /thumbnail

Prueba 9: obtener los bytes de contenido

Comprueba los siguientes puntos finales: /download

Prueba 10: actualizar el token de acceso (solo proveedores de webhook de OAuth2)

Comprueba los siguientes puntos finales: URL de punto final del token

Versiones