API dei webhook dei documenti
Creato per:
- Sviluppatore
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:
- Spostarsi nella struttura di cartelle del provider di documenti esterno
- Cerca file
- Collegare i file in Workfront
- Carica file nel provider di documenti esterno
- Visualizza una miniatura per il documento
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:
| Nome Campo | Descrizione |
|---|---|
| Nome | Il nome di questa integrazione. |
| URL API base | Posizione dell’API di callback. Quando si effettuano chiamate al sistema esterno, Workfront aggiungerà il nome dell’endpoint a questo indirizzo. Ad esempio, se l’amministratore ha immesso l’URL API di base, "https://www.mycompany.com/api/v1", Workfront utilizza il seguente URL per ottenere i metadati di un documento: https://www.mycompany.com/api/v1/metadata?id=1234. |
| Parametri di richiesta | Valori opzionali da accodare alla stringa di interrogazione di ogni chiamata API. Ad esempio, tipo_di_accesso |
| Tipo di autenticazione | OAuth2 o ApiKey. |
| URL autenticazione | (Solo OAuth2) L’URL completo utilizzato per l’autenticazione dell’utente. Workfront sposterà gli utenti a questo indirizzo come parte del processo di provisioning OAuth. Nota: Workfront aggiungerà un parametro "state" alla stringa di query. Il provider deve restituire questa proprietà a Workfront aggiungendola all'URI di reindirizzamento di Workfront. |
| URL endpoint token | (Solo OAuth2) L’URL API completo utilizzato per recuperare i token OAuth2. È ospitato dal provider del webhook o dal provider di documenti esterno. |
| ID client | (Solo OAuth2) ID client OAuth2 per questa integrazione. |
| Segreto client | (Solo OAuth2) Il segreto client OAuth2 per questa integrazione. |
| URI reindirizzamento Workfront | (Solo OAuth2) Questo è un campo di sola lettura ed è generato da Workfront. Questo valore viene utilizzato per registrare questa integrazione con il provider di documenti esterno. Nota: come descritto in precedenza per l'URL di autenticazione, il provider deve aggiungere il parametro "state" e il relativo valore a querystring durante l'esecuzione del reindirizzamento. |
| ApiKey | (Solo ApiKey) Utilizzato per effettuare chiamate API autorizzate al provider del webhook. La chiave API viene rilasciata dal provider del webhook. |
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 collegare l'account del provider di documenti esterno a Workfront e concedere l'accesso a Workfront per agire per suo conto. Questo processo di handshake viene eseguito una sola volta per ogni utente. Ecco come funziona:
-
L’utente inizia a collegare l’integrazione del webhook al proprio account. Attualmente, questo avviene facendo clic sul menu a discesa Aggiungi documento > Aggiungi servizio > Nome dell’integrazione personalizzata.
-
Workfront porta l’utente all’URL di autenticazione, che potrebbe richiedere all’utente di accedere al provider di documenti esterno. Questa pagina è ospitata dal provider del webhook o dal sistema esterno di gestione dei documenti. Workfront aggiunge un parametro "state" all’URL di autenticazione. Questo valore deve essere restituito a Workfront aggiungendo lo stesso valore all’URI di ritorno Workfront nel passaggio seguente.
-
Dopo aver effettuato l’accesso al sistema esterno (o se l’utente ha già effettuato l’accesso), viene visualizzata una pagina di autenticazione in cui viene spiegato che Workfront richiede l’accesso per eseguire una serie di azioni per conto dell’utente.
-
Se l'utente fa clic sul pulsante Consenti, il browser reindirizzerà all'URI di reindirizzamento di Workfront, aggiungendo "code=
<code>" alla stringa di query. In base alla specifica OAuth2, questo token ha una durata breve. La stringa di query deve inoltre avere il seguente stato: "state=<sent_by_workfront>". -
Workfront elabora questa richiesta e effettua una chiamata API all’URL dell’endpoint del token con il codice di autorizzazione.
-
L’URL dell’endpoint token restituisce un token di aggiornamento e un token di accesso.
-
Workfront memorizza questi token ed esegue il provisioning completo dell’integrazione del webhook per questo utente.
-
Da questo momento in poi, Workfront sarà in grado di effettuare chiamate API autorizzate al provider del webhook. Quando effettui queste chiamate, Workfront invierà il token di accesso nell’intestazione della richiesta HTTP come mostrato di seguito:
------------------------------- Authorization: Bearer [access_token] ------------------------------- -
Se il token di accesso è scaduto, Workfront effettuerà una chiamata all’URL dell’endpoint del token per recuperare un nuovo token di accesso, quindi tenterà di nuovo la chiamata API autorizzata con il nuovo token di accesso.
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 il 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 Webook come descritto nella sezione precedente.
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 trasmetterà questo 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
ID di un file o di una cartella, come indicato dal provider del webhook. È diverso dall’ID documento di Workfront. Per ottenere i metadati della directory principale, utilizza il valore "/".
Nota: la lunghezza massima per l’ID è di 255 caratteri.
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":"20140605T17:39:45.251Z",
"size": "32554694"
}
NOTEOttenere un elenco di elementi in una cartella
Restituisce i metadati per i file e le cartelle di una determinata cartella.
URL
GET /files
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":"20140605T17: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":"20140605T17: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 /search
Parametri query
Nota: questo è un segnaposto per una funzionalità futura di Workfront. Attualmente, Workfront non trasmette questo parametro.
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 o 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 /thumbnail
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 2 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 a lunghezza zero, 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. Come procedura ottimale, queste informazioni possono provenire dai campi dati personalizzati del documento e dell'attività, del problema o del progetto che lo contiene.
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":"20140605T17: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:
-
Includi un codice di errore nell’intestazione della risposta. I codici di errore includono:
- 403 - Non consentito. Indica che i token di richiesta sono mancanti o non validi oppure che le credenziali associate ai token non hanno accesso alla risorsa specificata. Per i provider di webhook basati su OAuth, Workfront tenterà di recuperare i nuovi token di accesso.
- 404 - Non trovato. Indica che il file o la cartella specificata non esiste.
- 500 - Errore interno del server. Qualsiasi altro tipo di errore.
-
Descrivi l’errore nel corpo della risposta utilizzando il seguente formato:
{
"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:
- Un account Workfront con Advanced Document Management (ADM) abilitato.
- Un utente Workfront per questo account con diritti di amministratore di sistema.
- Un'istanza del webhook del documento, i cui endpoint HTTP sono accessibili a Workfront.
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.
- In Workfront, passare alla pagina principale Documenti facendo clic sul collegamento Documenti nella barra di navigazione superiore.
- Fai clic sul menu a discesa Aggiungi documenti e seleziona il servizio Document Webhook in Aggiungi servizio.
- (Solo per i servizi OAuth) Dopo aver completato il passaggio precedente, visualizzerai il caricamento della pagina di autenticazione OAuth2 del servizio in una finestra a comparsa. (Nota: potrebbe essere richiesto di accedere prima al servizio.) Dalla pagina di autenticazione, concedi a Workfront l’accesso all’account dell’utente facendo clic sul pulsante Considera attendibili o Consenti.
- Verifica che il servizio sia stato aggiunto al menu a discesa Aggiungi documenti. Se inizialmente non è visibile, prova ad aggiornare il browser.
Test 2: Collegare un documento in Workfront Test dei seguenti endpoint: /files, /metadata
- In Workfront, passare alla pagina principale Documenti facendo clic sul collegamento Documenti nella barra di navigazione superiore.
- Selezionare il servizio Web Document in Aggiungi documenti.
- Dalla finestra modale, passa alla struttura delle cartelle.
- Verifica di essere in grado di navigare correttamente nella struttura di cartelle.
- Selezionare un documento e collegarlo a Workfront.
Prova 3: passare a un documento nel sistema di gestione dei contenuti
Verifica i seguenti endpoint: /metadata (in particolare viewLink).
- Collegare un documento a Workfront.
- Selezionare il documento e fare clic sul collegamento Apri.
- Verificate che il documento venga aperto in una nuova scheda.
Prova 4: passare a un documento nel sistema di gestione dei contenuti (con accesso)
Verifica i seguenti endpoint: /metadata (in particolare viewLink).
- Assicurarsi di essere disconnessi dal sistema di gestione dei contenuti.
- Collegare un documento a Workfront.
- Selezionare il documento e fare clic sul collegamento Apri.
- Verificare che la schermata di accesso del sistema di gestione dei contenuti venga caricata in una nuova scheda.
- Accedi e verifica di essere reindirizzato al documento.
Prova 5: scarica il documento dal sistema di gestione dei contenuti
Verifica i seguenti endpoint: /metadata (in particolare downloadLink).
- Collegare un documento a Workfront.
- Selezionare il documento e fare clic sul collegamento Scarica.
- Verifica l’inizio del download.
Prova 6: cercare il contenuto
Verifica i seguenti endpoint: /search
- In Workfront, passare alla pagina principale Documenti facendo clic sul collegamento Documenti nella barra di navigazione superiore.
- Selezionare il servizio Web Document in Aggiungi documenti.
- Dal modale, esegui una ricerca.
- Verifica che i risultati della ricerca siano corretti.
Prova 7: inviare il documento da Workfront al sistema di gestione dei contenuti
Verifica i seguenti endpoint: /files, /uploadInit, /upload
- In Workfront, passare alla pagina principale Documenti facendo clic sul collegamento Documenti nella barra di navigazione superiore.
- Carica un documento in Workfront dal computer.
- Passare alla pagina dei dettagli del documento.
- Dal menu a discesa Azioni documento, selezionare il servizio Web Document in Invia a…
- Vai alla cartella di destinazione desiderata e fai clic sul pulsante Salva.
- Verificare che il documento sia caricato nella posizione corretta nel sistema di gestione dei contenuti.
Test 8: visualizzare le miniature in Workfront
Verifica i seguenti endpoint: /thumbnail
- Collegare un documento a Workfront.
- Seleziona il documento nell’elenco.
- Verifica che la miniatura venga visualizzata nel pannello di destra.
Prova 9: recupero dei byte di contenuto
Verifica i seguenti endpoint: /download
- Collegare un documento a Workfront.
- Passare alla pagina dei dettagli del documento.
- Inviare il documento a Workfront selezionando Azioni documento > Invia a… > Workfront. Verrà creata una nuova versione del documento in Workfront.
- Scaricare il documento da Workfront facendo clic sul collegamento Scarica.
Prova 10: aggiorna token di accesso (solo provider del webhook OAuth2)
Verifica i seguenti endpoint: URL endpoint token
- Eseguire il provisioning di un servizio Web Document per un utente.
- Annulla la validità del token di accesso dell’utente attendendo il timeout o annullandolo manualmente nel sistema esterno.
- Aggiorna il token di accesso in Workfront. A tale scopo, ad esempio, è possibile collegare un documento in Workfront. Se sei riuscito a passare a un documento e a collegarlo, saprai che il token di accesso è stato aggiornato correttamente.
NOTEVersioni
-
Versione 1.0 (data di rilascio: maggio 2015)
- Specifiche iniziali
-
Versione 1.1 (data di rilascio: giugno 2015)
- Aggiornato /uploadInit - Aggiunti documentId e documentVersionId
-
Versione 1.2 (data di rilascio: ottobre 2015)
- Aggiunto /createFolder