API de webhooks de documentos

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

La experiencia del usuario para integraciones basadas en ganchos web 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 esto 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.

Registro de una integración de webhook

Los administradores de Workfront pueden añadir una integración de webhook para su empresa 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, activar y desactivar. Para añadir una integración, haga clic en el botón "Añadir integración".

Campos disponibles

Al añadir una integración, el administrador introduce valores en 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 pasa 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 ganchos web en nombre de un usuario. Antes de hacerlo, el usuario debe conectar su cuenta de proveedor de documentos externa a Workfront y conceder a Workfront

acceso para actuar en su nombre. Este proceso de establecimiento de la mano solo se produce una vez por cada usuario. Funciona de la siguiente manera:

ApiKey

Realizar llamadas de API autorizadas a un proveedor de ganchos web mediante una clave API es mucho más sencillo que OAuth2. Al realizar una llamada de API, Workfront simplemente pasa la ApiKey y el nombre de usuario de Workfront en el encabezado de la solicitud HTTP:

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

apiKey: 12345

username: johndoe@foo.com

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

El proveedor de webhook 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 del gancho web para cada llamada de API. Un administrador de Workfront puede configurar esto al registrar o editar una integración de libro web, tal como se describe en la sección anterior. Consulte Registro de una integración de webhook.

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

QWxhZGRpbjpvcGVuIHNlc2FtZQ básico de autorización==

donde 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 ganchos web debe implementar para que los ganchos web 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 de extremo 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

Ejemplo: https://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 Document Webhooks no admite la paginación.

Respuesta

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

Ejemplo: https://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 extremo /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 Document Webhooks 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 gancho web. Lo ideal es que realice una búsqueda de texto completo. También funciona la búsqueda basada en nombres de archivo.

Ejemplo: https://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/descarga

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 miniatura sin procesar de un documento.

URL

GET/miniatura

Parámetros de consulta

Respuesta

Los bytes de 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 dos extremos 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 podría proceder de campos de datos personalizados del documento y contener tareas, problemas o proyectos.

URL

POST /uploadInit

Parámetros de consulta

Respuesta

Los metadatos del archivo, tal como se definen en el extremo /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 usado por el proveedor de documentos.

Cargar un archivo: parte 2 de 2

Carga los bytes de un documento al proveedor de ganchos web.

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 lanzamiento: 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 gancho web contiene algunas acciones personalizadas, el 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

Ninguna. Además, las llamadas a este extremo 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 define en el extremo /metadata.

Ejemplo: POST 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 la ID proporcionada en el sistema externo. Al eliminar una carpeta, también se elimina su contenido.

URL

PUT /delete

Parámetros de consulta

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

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 la ID proporcionada en el sistema externo.

URL

PUT /name

Parámetros de consulta

Respuesta

Una cadena JSON que indica éxito o error, como se especifica en la sección Gestión de errores 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 lanzamiento: por determinar) Este punto de conexión 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 extremo /customAction acepta un parámetro "name", que permite al proveedor de ganchos web implementar varias operaciones personalizadas.

El proveedor de ganchos web 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 ganchos web 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, como se especifica en la sección Gestión de errores 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"
}

Control de errores

Pueden surgir problemas al procesar solicitudes de API. Esto debe gestionarse de forma coherente en todos los extremos de la API. Cuando se produce un error, el proveedor del gancho web 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 extremos de la implementación del webhook.

Requisitos previos

Para ejecutar estas pruebas, necesitará lo siguiente:

Estas pruebas también suponen que ya ha registrado la instancia de Document Webhook en Workfront en Configuración > Documentos > Integraciones personalizadas.

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

Prueba la URL de autenticación y la URL de extremo de token para proveedores de webhook basados en OAuth.

Prueba 2: Vincular un documento a Workfront Prueba los siguientes extremos: /files, /metadata

Prueba 3: Navegar a un documento en el sistema de administración de contenido

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

Prueba 4: Navegar a 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

Prueba los siguientes extremos: /search

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

Prueba los siguientes extremos: /files, /uploadInit, /upload

Prueba 8: Ver miniaturas en Workfront

Prueba los siguientes extremos: /thumbnail

Prueba 9: Obtener los bytes de contenido

Prueba los siguientes extremos: /download

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

Prueba los siguientes extremos: URL de extremo de token

Versiones