API de webhooks do documento

Os Webhooks de documentos do Adobe Workfront definem um conjunto de endpoints de API pelos quais o Workfront faz chamadas de API autorizadas para um Provedor de documentos externo. Isso permite que qualquer pessoa crie um plug-in middleware para qualquer provedor de armazenamento de documentos.

A experiência do usuário para integrações baseadas em webhook será semelhante àquela das integrações de documento existentes, como Google Drive, Box e Dropbox. Por exemplo, um usuário do Workfront poderá executar as seguintes ações:

Implementação de referência

Para ajudar a iniciar o desenvolvimento de uma nova implementação de webhooks, o Workfront fornece uma implementação de referência. O código para isso pode ser encontrado em https://github.com/Workfront/webhooks-app. Essa implementação é baseada em Java e permite que o Workfront conecte documentos em um sistema de arquivos de rede.

Registrar uma integração do Webhook

Os administradores do Workfront podem adicionar uma integração de webhook personalizada para a empresa navegando até Configuração > Documentos > Integrações personalizadas no Workfront. Na página Integração personalizada da Configuração, os administradores podem exibir uma lista de integrações existentes do Webhook. Nessa página, as integrações podem ser adicionadas, editadas, ativadas e desativadas. Para adicionar uma integração, clique no botão "Adicionar integração".

Campos disponíveis

Ao adicionar uma integração, o administrador inserirá valores nos seguintes campos:

Autenticação

Os webhooks de documento do Workfront são compatíveis com duas formas diferentes de autenticação: OAuth2 e ApiKey. Em ambos os casos, o Workfront transmite tokens de autenticação no cabeçalho ao fazer uma chamada de API.

OAuth2

O OAuth2 permite que o Workfront faça chamadas de API autorizadas para um provedor de webhook em nome de um usuário. Antes de fazer isso, o usuário deve conectar a conta do provedor de documentos externo ao Workfront e conceder o Workfront

acesso para agirem em seu nome. Esse processo de handshaking só ocorre uma vez para cada usuário. Veja como isso funciona:

ApiKey

Fazer chamadas de API autorizadas para um provedor de webhook usando uma ApiKey é muito mais simples do que o OAuth2. Ao fazer uma chamada de API, o Workfront simplesmente passará o ApiKey e o nome de usuário do Workfront no cabeçalho da solicitação HTTP:

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

apiKey: 12345

username: johndoe@foo.com

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

O provedor Webhook pode usar o nome de usuário para aplicar permissões específicas do usuário. Isso funciona melhor quando ambos os sistemas se conectam ao LDAP usando o Logon único (SSO).

Adicionar cabeçalhos de solicitação (opcional)

Além de usar tokens OAuth2 ou uma ApiKey para autenticação, o Workfront pode enviar um conjunto predefinido de cabeçalhos para o provedor do webhook para cada chamada de API. Um administrador do Workfront pode configurar isso ao registrar ou editar uma Integração de webook, conforme descrito na seção acima. Consulte Registrar uma integração de Webhook.

Por exemplo, pode ser usado para a Autenticação básica. Para fazer isso, o administrador do Workfront adicionaria as seguintes informações do Cabeçalho da solicitação na caixa de diálogo Integração personalizada:

Autorização básica QWxhZGRpbjpvcGVuIHNlc2FtZQ==

onde QWxhZGRpbjpvcGVuIHNlc2FtZQ== é uma string codificada na base 64 de "username:password". Consulte Autenticação básica . Desde que tenha sido adicionado, o Workfront passará isso no cabeçalho da solicitação HTTP, além de outros cabeçalhos de solicitação:

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

apiKey: 12345

username: johndoe@foo.com

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

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

Especificação da API

Veja abaixo uma lista de APIs que o provedor de webhook deve implementar para que os webhooks de documento funcionem.

Obter tokens OAuth2 (somente autenticação OAuth2 necessária)

Retorna o token de atualização OAuth2 e o token de acesso para um usuário autenticado. Isso é chamado uma vez quando o usuário provisiona um Provedor de documentos. As chamadas subsequentes são feitas para obter um token de acesso atualizado.

POST de solicitação HTTP /any/url

O URL é configurável e corresponde ao valor do URL do endpoint do token na página de configuração da integração personalizada.

Parâmetros de consulta

Resposta

Exemplo

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

Resposta

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

Obter metadados para arquivo ou pasta

Retorna os metadados do arquivo ou pasta especificada.

URL

GET /metadata?id=[ID de documento ou pasta]

Parâmetros de consulta

Resposta

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

Resposta

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

Obter uma lista de itens em uma pasta

Retorna metadados dos arquivos e pastas de uma determinada pasta.

URL

GET /arquivos

Parâmetros de consulta

No momento, a API de webhooks de documentos não é compatível com paginação.

Resposta

JSON contendo uma lista de arquivos e pastas. Os metadados de cada item são os mesmos retornados pelo endpoint /metadata.

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

Resposta

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

Fazer uma pesquisa

Retorna metadados dos arquivos e pastas retornados de uma pesquisa. Isso pode ser implementado como uma pesquisa de texto completo ou como uma consulta de banco de dados regular. O Workfront chama o endpoint /search quando o usuário realiza uma pesquisa no navegador de arquivos externos.

URL

GET /search

Parâmetros de consulta

No momento, a API de webhooks de documentos não é compatível com paginação.

Resposta

JSON que contém uma lista de metadados para arquivos e pastas que correspondem à consulta. O que constitui uma "correspondência" é determinado pelo provedor de webhook. Idealmente, ele deve fazer uma pesquisa de texto completo. Fazer uma pesquisa baseada em nome de arquivo também funciona.

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

Resposta

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

Obter o conteúdo de um documento

Retorna os bytes brutos de um documento

URL

GET /download

Parâmetros de consulta

Resposta

Os bytes brutos do documento.

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

Obter uma miniatura de um documento

Retorna os bytes brutos da miniatura de um documento.

URL

GET /miniatura

Parâmetros de consulta

Resposta

Os bytes brutos da miniatura.

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

Carregar um arquivo - Parte 1 de 2

O upload de um arquivo para um provedor de armazenamento de documentos é um processo de duas etapas que requer dois endpoints de API separados. O Workfront inicia o processo de upload chamando /uploadInit. Esse ponto de extremidade retorna uma ID de documento que é passada para /upload ao carregar os bytes do documento. Dependendo do sistema de armazenamento de documentos subjacente, pode ser necessário criar um documento de comprimento zero e, em seguida, atualizar o conteúdo do documento posteriormente.

Adicionado à versão 1.1 desta especificação, o ID do documento e o ID da versão do documento podem ser usados para recuperar informações adicionais do Workfront. Por exemplo, se o sistema de gerenciamento de documentos quiser informações adicionais sobre o documento, o código de implementação do webhook poderá usar a ID do documento para recuperar essas informações usando a API RESTful do Workfront. Como prática recomendada, essas informações podem vir de campos de dados personalizados no documento e estão contendo tarefas, problemas ou projetos.

URL

POST /uploadInit

Parâmetros de consulta

Resposta

Os metadados do arquivo, conforme definido pelo endpoint /metadata.

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

Resposta

[file_metadata] inclui a nova ID de documento usada pelo provedor de documentos.

Carregar um arquivo - Parte 2 de 2

Carrega os bytes de um documento para o provedor de webhook.

URL

PUT /upload

Parâmetros de consulta

Solicitar corpo

Os bytes de conteúdo bruto do documento.

Resposta

{
"result": "success"
}

ou

{
"result": "fail"
}

Exemplo: https://www.acme.com/api/upload?id=1234 [bytes de documentos incluídos no fluxo de atualização]

Resposta

{
"result":"success"
}

Obter informações sobre o serviço

(Data de lançamento - A ser definido) Retorna informações sobre o serviço, como recursos e funcionalidades. O Workfront usará essas informações para personalizar a interface do usuário no Workfront. Por exemplo, se a implementação de webhook contiver algumas ações personalizadas, o JSON deverá listar essas operações no JSON. Os usuários poderão então invocar essas ações a partir do Workfront.

URL

GET /serviceInfo

Parâmetros de consulta

Nenhum. Além disso, as chamadas para esse endpoint não devem exigir autenticação.

Resposta

JSON contendo informações sobre este serviço

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

Devoluções

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

Criar uma pasta

(Adicionado na versão 1.2) Cria uma pasta em um determinado diretório.
URL

POST /createFolder

Parâmetros de consulta

Resposta

Os metadados da pasta recém-criada, conforme definido pelo endpoint /metadata.

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

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

parentId=1234

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

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

devoluções

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

Excluir um documento ou uma pasta

(Data de lançamento - A ser definida) Exclui um documento ou pasta com a ID fornecida no sistema externo. A exclusão de uma pasta também excluirá seu conteúdo.

URL

PUT /delete

Parâmetros de consulta

Resposta Uma string JSON que indica sucesso ou falha, conforme especificado na seção Tratamento de erros abaixo.

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

devoluções

{
"status": "success"
}

devoluções

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

Renomear um documento ou uma pasta

(Data de lançamento - A ser definida) Renomeia um documento ou pasta com a ID fornecida no sistema externo.

URL

PUT /rename

Parâmetros de consulta

Resposta

Uma string JSON que indica sucesso ou falha, conforme especificado na seção Tratamento de erros abaixo.

Exemplo:

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

Executar uma ação personalizada

(Data de lançamento - A ser definida) Esse endpoint permitirá que um usuário do Workfront (ou talvez um evento de fluxo de trabalho automatizado) execute uma ação no sistema externo. O ponto de extremidade /customAction aceita um parâmetro "name", que permite que o provedor de webhook implemente várias operações personalizadas.

O provedor de webhook registra ações personalizadas com o Workfront incluindo as ações na resposta /serviceInfo em customActions. O Workfront carrega essa lista ao configurar ou atualizar o provedor de webhook em Configurar > Documentos > Integrações personalizadas.

Os usuários podem acionar a ação personalizada selecionando a seção em "Ações do documento"

URL

GET /customAction

Parâmetros de consulta

Resposta

Uma string JSON que indica sucesso ou falha, conforme especificado na seção Tratamento de erros abaixo. Na falha (ou seja, status = "failure"), o Workfront exibirá a mensagem de erro fornecida para o usuário.

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

resposta

{
"status": "success"
}

Tratamento de erros

Problemas podem surgir ao processar solicitações de API. Isso deve ser tratado de forma consistente em todos os endpoints da API. Quando ocorre um erro, o provedor do webhook faz o seguinte:

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

Testes

Para verificar se a implementação do webhook do seu documento funciona corretamente, execute os testes a seguir. Esses são testes manuais que passam pela interface da Web do Workfront e atingem indiretamente os endpoints da implementação do webhook.

Pré-requisitos

Para executar esses testes, você precisará do seguinte:

Esses testes também pressupõem que você já tenha registrado a instância do Webhook do documento no Workfront em Configuração > Documentos > Integrações personalizadas.

Teste 1: provisionar o serviço Webhook do documento para um usuário

Testa o URL de autenticação e o URL do ponto de extremidade do token para provedores de Webhook baseados em OAuth.

Teste 2: vincular um documento no Workfront Testa os seguintes endpoints: /files, /metadata

Teste 3: Navegar até um documento no sistema de gerenciamento de conteúdo

Testa os seguintes pontos de extremidade: /metadata (especificamente o viewLink)

Teste 4: Navegar até um documento no sistema de gerenciamento de conteúdo (com logon)

Testa os seguintes pontos de extremidade: /metadata (especificamente o viewLink)

Teste 5: baixar o documento do sistema de gerenciamento de conteúdo

Testa os seguintes pontos de extremidade: /metadata (especificamente o downloadLink)

Teste 6: pesquisar conteúdo

Testa os seguintes pontos de extremidade: /search

Teste 7: enviar documento do Workfront para o sistema de gerenciamento de conteúdo

Testa os seguintes pontos de extremidade: /files, /uploadInit, /upload

Teste 8: exibir miniaturas no Workfront

Testa os seguintes pontos de extremidade: /thumbnail

Teste 9: obter os bytes de conteúdo

Testa os seguintes pontos de extremidade: /download

Teste 10: atualizar token de acesso (somente provedores de Webhook OAuth2)

Testa os seguintes endpoints: URL do endpoint do token

Versões