API dei webhook dei documenti

Adobe Workfront Document Webhooks definisce un set di endpoint API attraverso i quali Workfront effettua chiamate API autorizzate a un provider di documenti esterno. Questo consente a chiunque di creare un plug-in middleware per qualsiasi provider di archiviazione dei documenti.

L’esperienza utente per le integrazioni basate su webhook sarà simile a quella delle integrazioni di documenti esistenti, come Google Drive, Box e Dropbox. Ad esempio, un utente di Workfront sarà in grado di eseguire le azioni seguenti:

Implementazione di riferimento

Per aiutarti a iniziare lo sviluppo di una nuova implementazione di webhook, Workfront fornisce un’implementazione di riferimento. Il codice relativo a questo elemento è disponibile all'indirizzo https://github.com/Workfront/webhooks-app. Questa implementazione è basata su Java e consente a Workfront di collegare documenti su un file system di rete.

Registrazione di un'integrazione webhook

Gli amministratori di Workfront possono aggiungere un’integrazione di webhook personalizzata per la propria società da Configurazione > Documenti > Integrazioni personalizzate in Workfront. Dalla pagina Integrazione personalizzata all’interno di Configurazione, gli amministratori possono visualizzare un elenco delle integrazioni dei webhook dei documenti esistenti. Da questa pagina è possibile aggiungere, modificare, abilitare e disabilitare le integrazioni. Per aggiungere un’integrazione, fai clic sul pulsante "Aggiungi integrazione".

Campi disponibili

Quando aggiungi un’integrazione, l’amministratore immetterà i valori per i seguenti campi:

Autenticazione

I webhook dei documenti di Workfront supportano due diverse forme di autenticazione: OAuth2 e ApiKey. In entrambi i casi, Workfront trasmette i token di autenticazione nell’intestazione quando effettua una chiamata API.

OAuth2

OAuth2 consente a Workfront di effettuare chiamate API autorizzate a un provider di webhook per conto di un utente. Prima di eseguire questa operazione, l'utente deve connettere l'account del provider di documenti esterno a Workfront e concedere a Workfront

poter agire per loro conto. Questo processo di handshake viene eseguito una sola volta per ogni utente. Ecco come funziona:

ApiKey

Effettuare chiamate API autorizzate a un provider di webhook utilizzando un’ApiKey è molto più semplice di OAuth2. Quando effettui una chiamata API, Workfront passa semplicemente il nome utente ApiKey e Workfront nell’intestazione della richiesta HTTP:

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

apiKey: 12345

username: johndoe@foo.com

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

Il provider del webhook può utilizzare il nome utente per applicare autorizzazioni specifiche dell'utente. Questa funzione è particolarmente utile quando entrambi i sistemi si connettono a LDAP utilizzando Single Sign On (SSO).

Aggiunta di intestazioni di richiesta (facoltativo)

Oltre a utilizzare i token OAuth2 o un ApiKey per l’autenticazione, Workfront può inviare un set predefinito di intestazioni al provider del webhook per ogni chiamata API. Un amministratore di Workfront può effettuare questa configurazione durante la registrazione o la modifica di un'integrazione di Windows, come descritto nella sezione precedente. Consulta Registrazione di un’integrazione webhook.

Ad esempio, può essere utilizzato per l’autenticazione di base. A questo scopo, l’amministratore di Workfront aggiungerà le seguenti informazioni sull’intestazione della richiesta nella finestra di dialogo Integrazione personalizzata:

Autorizzazione Base QWxhZGRpbjpvcGVuIHNlc2FtZQ==

dove QWxhZGRpbjpvcGVuIHNlc2FtZQ== è una stringa con codifica base 64 di "username:password". Consulta Autenticazione di base. Se aggiunto, Workfront lo trasmetterà nell’intestazione della richiesta HTTP, oltre ad altre intestazioni di richiesta:

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

apiKey: 12345

username: johndoe@foo.com

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

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

Specifiche API

Di seguito è riportato un elenco di API che il provider del webhook deve implementare per il funzionamento dei webhook dei documenti.

Recupero token OAuth2 (solo autenticazione OAuth2 necessaria)

Restituisce il token di aggiornamento e il token di accesso OAuth2 per un utente autenticato. Viene richiamato una volta quando l’utente fornisce un provider di documenti. Vengono effettuate chiamate successive per ottenere un token di accesso aggiornato.

HTTP Request POST /any/url

L’URL è configurabile e corrisponde al valore dell’URL dell’endpoint del token nella pagina di configurazione dell’integrazione personalizzata.

Parametri query

Risposta

Esempio

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

Risposta

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

Ottieni metadati per file o cartella

Restituisce i metadati per il file o la cartella specificata.

URL

GET /metadata?id=[ID documento o cartella]

Parametri query

Risposta

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

Risposta

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

Ottenere un elenco di elementi in una cartella

Restituisce i metadati per i file e le cartelle di una determinata cartella.

URL

GET/file

Parametri query

L'API Document Webhooks non supporta attualmente l'impaginazione.

Risposta

JSON contenente un elenco di file e cartelle. I metadati per ogni elemento sono gli stessi restituiti dall’endpoint /metadata.

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

Risposta

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

Esegui una ricerca

Restituisce i metadati per i file e le cartelle restituiti da una ricerca. Questa può essere implementata come ricerca full-text o come normale query di database. Workfront chiama l’endpoint /search quando l’utente esegue una ricerca dal browser di file esterno.

URL

GET/ricerca

Parametri query

L'API Document Webhooks non supporta attualmente l'impaginazione.

Risposta

JSON contenente un elenco di metadati per file e cartelle che corrispondono alla query. Che cosa costituisce una "corrispondenza" è determinato dal provider del webhook. Idealmente, dovrebbe eseguire una ricerca full-text. È anche possibile eseguire una ricerca basata sul nome del file.

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

Risposta

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

Ottenere il contenuto di un documento

Restituisce i byte non elaborati di un documento

URL

GET/download

Parametri query

Risposta

Byte non elaborati del documento.

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

Ottenere una miniatura per un documento

Restituisce i byte delle miniature non elaborati per un documento.

URL

GET/miniatura

Parametri query

Risposta

Byte delle miniature non elaborati.

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

Caricare un file - Parte 1 di 2

Il caricamento di un file in un provider di archiviazione documenti è un processo in due fasi che richiede due endpoint API separati. Workfront avvia il processo di caricamento chiamando /uploadInit. Questo endpoint restituisce un ID documento che viene quindi passato a /upload durante il caricamento dei byte del documento. A seconda del sistema di archiviazione dei documenti sottostante, potrebbe essere necessario creare un documento di lunghezza zero e quindi aggiornare il contenuto del documento in un secondo momento.

Aggiunto alla versione 1.1 di questa specifica, l'ID documento e l'ID versione documento possono essere utilizzati per recuperare informazioni aggiuntive da Workfront. Ad esempio, se il sistema di gestione dei documenti richiede informazioni aggiuntive sul documento, il codice di implementazione del webhook potrebbe utilizzare l’ID del documento per recuperare tali informazioni utilizzando l’API RESTful di Workfront. È buona norma che queste informazioni provengano dai campi dati personalizzati del documento che contengono l'attività, il problema o il progetto.

URL

POST /uploadInit

Parametri query

Risposta

I metadati del file, come definito dall’endpoint /metadata.

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

Risposta

[file_metadata] include il nuovo ID documento utilizzato dal provider di documenti.

Caricare un file - Parte 2 di 2

Carica i byte di un documento nel provider del webhook.

URL

PUT /upload

Parametri query

Corpo richiesta

Byte di contenuto non elaborato per il documento.

Risposta

{
"result": "success"
}

oppure

{
"result": "fail"
}

Esempio: https://www.acme.com/api/upload?id=1234 [byte del documento inclusi nel flusso di aggiornamento]

Risposta

{
"result":"success"
}

Ottieni informazioni sul servizio

(Data di rilascio: da definire) Restituisce informazioni sul servizio, ad esempio funzioni e funzionalità. Workfront utilizzerà queste informazioni per personalizzare l’interfaccia utente in Workfront. Ad esempio, se l’implementazione del webhook contiene alcune azioni personalizzate, il JSON deve elencare tali operazioni nel JSON. Gli utenti potranno quindi richiamare queste azioni da Workfront.

URL

GET /serviceInfo

Parametri di query

Nessuno. Inoltre, le chiamate a questo endpoint non devono richiedere l’autenticazione.

Risposta

JSON contenente informazioni su questo servizio

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

Restituisce

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

Creare una cartella

(Aggiunto nella versione 1.2) Crea una cartella in una determinata directory.
URL

POST /createFolder

Parametri query

Risposta

I metadati per la cartella appena creata, come definito dall’endpoint /metadata.

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

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

parentId=1234

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

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

restituisce

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

Eliminare un documento o una cartella

(Data di rilascio: da definire) Elimina un documento o una cartella con l’ID specificato nel sistema esterno. L’eliminazione di una cartella ne comporta anche l’eliminazione del contenuto.

URL

PUT /delete

Parametri query

Response Stringa JSON che indica l’esito positivo o negativo, come specificato nella sezione Gestione degli errori di seguito.

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

restituisce

{
"status": "success"
}

restituisce

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

Rinominare un documento o una cartella

(Data di rilascio: da definire) Rinomina un documento o una cartella con l’ID specificato nel sistema esterno.

URL

PUT /rename

Parametri query

Risposta

Stringa JSON che indica l’esito positivo o negativo, come specificato nella sezione Gestione degli errori di seguito.

Esempio:

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

Eseguire un'azione personalizzata

(Data di rilascio: da definire) Questo endpoint consente a un utente di Workfront (o forse a un evento di flusso di lavoro automatizzato) di eseguire un’azione nel sistema esterno. L’endpoint /customAction accetta un parametro "name" che consente al provider del webhook di implementare più operazioni personalizzate.

Il provider webhook registra le azioni personalizzate con Workfront includendo le azioni nella risposta /serviceInfo in customActions. Workfront carica questo elenco durante la configurazione o l’aggiornamento del provider del webhook in Configurazione > Documenti > Integrazioni personalizzate.

Gli utenti possono attivare l’azione personalizzata selezionando la sezione in "Azioni documento"

URL

GET /customAction

Parametri query

Risposta

Stringa JSON che indica l’esito positivo o negativo, come specificato nella sezione Gestione degli errori di seguito. In caso di errore (ossia stato = "errore"), Workfront visualizzerà il messaggio di errore fornito all’utente.

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

risposta

{
"status": "success"
}

Gestione degli errori

Possono verificarsi problemi durante l’elaborazione delle richieste API. Questo deve essere gestito in modo coerente tra tutti gli endpoint API. Quando si verifica un errore, il provider del webhook esegue le operazioni seguenti:

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

Test

Per verificare che l’implementazione del webhook del documento funzioni correttamente, esegui i seguenti test. Si tratta di test manuali che passano attraverso l’interfaccia web di Workfront e colpiscono indirettamente gli endpoint per l’implementazione del webhook.

Prerequisiti

Per eseguire questi test è necessario disporre dei seguenti elementi:

Questi test presuppongono inoltre che sia già stata registrata l’istanza di Document Webhook in Workfront in Configurazione > Documenti > Integrazioni personalizzate.

Prova 1: eseguire il provisioning del servizio Document Webhook per un utente

Verifica l’URL di autenticazione e l’URL dell’endpoint del token per i provider Webhook basati su OAuth.

Test 2: Collegare un documento in Workfront Test dei seguenti endpoint: /files, /metadata

Prova 3: passare a un documento nel sistema di gestione dei contenuti

Verifica i seguenti endpoint: /metadata (in particolare viewLink)

Prova 4: passare a un documento nel sistema di gestione dei contenuti (con accesso)

Verifica i seguenti endpoint: /metadata (in particolare viewLink)

Prova 5: scarica il documento dal sistema di gestione dei contenuti

Verifica i seguenti endpoint: /metadata (in particolare downloadLink)

Prova 6: cercare il contenuto

Verifica i seguenti endpoint: /search

Prova 7: inviare il documento da Workfront al sistema di gestione dei contenuti

Verifica i seguenti endpoint: /files, /uploadInit, /upload

Test 8: visualizzare le miniature in Workfront

Verifica i seguenti endpoint: /thumbnail

Prova 9: recupero dei byte di contenuto

Verifica i seguenti endpoint: /download

Prova 10: aggiorna token di accesso (solo provider del webhook OAuth2)

Verifica i seguenti endpoint: URL endpoint token

Versioni