Document Webhooks API

Adobe Workfront Document Webhooks definierar en uppsättning API-slutpunkter genom vilka Workfront gör auktoriserade API-anrop till en extern dokumentleverantör. På så sätt kan vem som helst skapa ett plugin-program för mellanvara för alla dokumentlagringsleverantörer.

Användarupplevelsen för webkrosbaserade integreringar liknar den för befintliga dokumentintegreringar, som Google Drive, Box och Dropbox. En Workfront-användare kan till exempel utföra följande åtgärder:

Referenskörning

Workfront tillhandahåller en referensimplementering som hjälper dig att snabbt komma igång med utvecklingen av en ny webbhooksimplementering. Kod för detta finns på https://github.com/Workfront/webhooks-app. Implementeringen är Java-baserad och gör att Workfront kan ansluta dokument i ett nätverksfilsystem.

Registrera en Webkroks-integrering

Workfront-administratörer kan lägga till en anpassad webbkrokintegrering för sitt företag genom att gå till Inställningar > Dokument > Anpassade integreringar i Workfront. På sidan Anpassad integrering i installationsprogrammet kan administratörer visa en lista över befintliga webkrok-integreringar för dokument. Från den här sidan kan integreringar läggas till, redigeras, aktiveras och inaktiveras. Om du vill lägga till en integrering klickar du på knappen "Lägg till integrering".

Tillgängliga fält

När du lägger till en integrering anger administratören värden för följande fält:

Autentisering

Workfront dokumentwebhooks stöder två olika typer av autentisering: OAuth2 och ApiKey. I båda fallen skickar Workfront autentiseringstoken i huvudet när ett API-anrop görs.

OAuth2

Med OAuth2 kan Workfront göra auktoriserade API-anrop till en webkrok-leverantör för en användares räkning. Innan du gör det måste användaren ansluta sitt externa dokumentleverantörskonto till Workfront och bevilja Workfront

behörighet att agera å deras vägnar. Den här handskakningsprocessen utförs bara en gång för varje användare. Så här fungerar det:

ApiKey

Det är mycket enklare än OAuth2 att göra auktoriserade API-anrop till en webbkrokleverantör med en ApiKey. När du gör ett API-anrop skickar Workfront bara ApiKey och Workfront-användarnamn i HTTP-begärandehuvudet:

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

apiKey: 12345

username: johndoe@foo.com

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

Webkrockprovidern kan använda användarnamnet för att tillämpa användarspecifika behörigheter. Detta fungerar bäst när båda systemen ansluter till LDAP med enkel inloggning (SSO).

Lägga till begäranderubriker (valfritt)

Förutom att använda antingen OAuth2-token eller en ApiKey för autentisering, kan Workfront skicka en fördefinierad uppsättning huvuden till webbkrokprovidern för varje API-anrop. En Workfront-administratör kan konfigurera detta när en Webook-integrering registreras eller redigeras, vilket beskrivs i avsnittet ovan. Mer information finns i Registrera en webbkrokintegrering.

Detta kan till exempel användas för grundläggande autentisering. För att göra detta lägger Workfront-administratören till följande information om begärandehuvud i dialogrutan Anpassad integrering:

Grundläggande behörighet QWxhZGRpbjpvcGVuIHNlc2FtZQ==

där QWxhZGRpbjpvcGVuIHNlc2FtZQ=== är en base-64-kodad sträng med "username:password". Se Grundläggande autentisering. Under förutsättning att detta läggs till, skickar Workfront detta i HTTP-begärandehuvudet, förutom andra begäranrubriker:

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

apiKey: 12345

username: johndoe@foo.com

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

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

API-specifikation

Nedan finns en lista med API:er som webkrockprovidern ska implementera för att dokumentwebbhooks ska fungera.

Hämtar OAuth2-token (endast nödvändig OAuth2-autentisering)

Returnerar OAuth2-uppdateringstoken och åtkomsttoken för en autentiserad användare. Detta anropas en gång när användaren tillhandahåller en dokumentleverantör. Efterföljande anrop görs för att få en uppdaterad åtkomsttoken.

POST för HTTP-begäran /any/url

URL:en är konfigurerbar och motsvarar värdet för Token Endpoint URL på sidan Anpassade integrationsinställningar.

Frågeparametrar

Svar

Exempel

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

Svar

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

Hämta metadata för fil eller mapp

Returnerar metadata för den angivna filen eller mappen.

URL

GET /metadata?id=[dokument- eller mapp-ID]

Frågeparametrar

Svar

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

Svar

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

Hämta en lista med objekt i en mapp

Returnerar metadata för filer och mappar för en viss mapp.

URL

GET/filer

Frågeparametrar

Dokumentets webhooks-API har för närvarande inte stöd för sidnumrering.

Svar

JSON som innehåller en lista med filer och mappar. Metadata för varje objekt är samma som returneras av /metadata-slutpunkten.

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

Svar

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

Gör en sökning

Returnerar metadata för de filer och mappar som returneras från en sökning. Detta kan implementeras som en fulltextsökning eller som en vanlig databasfråga. Workfront anropar slutpunkten /search när användaren utför en sökning från den externa filläsaren.

URL

GET/sökning

Frågeparametrar

Dokumentets webhooks-API har för närvarande inte stöd för sidnumrering.

Svar

JSON innehåller en lista med metadata för filer och mappar som matchar frågan. Vad som utgör en matchning bestäms av webbkrokleverantören. Helst ska det göras en textsökning. Det går också att göra en filnamnsbaserad sökning.

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

Svar

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

Hämta innehållet i ett dokument

Returnerar oformaterade byte för ett dokument

URL

GET/nedladdning

Frågeparametrar

Svar

Dokumentets raw-byte.

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

Hämta en miniatyrbild för ett dokument

Returnerar byte för miniatyrbilder i Raw-format för ett dokument.

URL

GET/miniatyrbild

Frågeparametrar

Svar

Byte till miniatyrbilden för Raw.

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

Överför en fil - del 1 av 2

Att överföra en fil till en dokumentlagringsleverantör är en tvåstegsprocess som kräver två separata API-slutpunkter. Workfront påbörjar överföringen genom att anropa /uploadInit. Den här slutpunkten returnerar ett dokument-ID som sedan skickas till /upload när dokumentbyte överförs. Beroende på det underliggande dokumentlagringssystemet kan det vara nödvändigt att skapa ett dokument med längden noll och sedan uppdatera innehållet i dokumentet senare.

Dokument-ID och dokumentversions-ID kan läggas till i version 1.1 av den här specifikationen för att hämta extra information från Workfront. Om dokumenthanteringssystemet till exempel vill ha extra information om dokumentet, kan webhochimplementeringskoden använda dokument-ID:t för att hämta informationen med Workfront RESTful API. Som en god vana kan den här informationen komma från anpassade datafält i dokumentet och innehålla uppgifter, problem eller projekt.

URL

POST /uploadInit

Frågeparametrar

Svar

Metadata för filen, enligt definitionen i /metadata-slutpunkten.

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

Svar

[file_metadata] innehåller det nya dokument-ID som används av dokumentprovidern.

Överför en fil - del 2 av 2

Överför byte i ett dokument till webbholleverantören.

URL

PUT /upload

Frågeparametrar

Begär brödtext

Dokumentets byte med Raw-innehåll.

Svar

{
"result": "success"
}

eller

{
"result": "fail"
}

Exempel: https://www.acme.com/api/upload?id=1234 [dokumentbyte ingår i uppdateringsströmmen]

Svar

{
"result":"success"
}

Hämta information om tjänsten

(Releasedatum - TBD) Returnerar information om tjänsten, t.ex. funktioner. Workfront använder den här informationen för att anpassa användargränssnittet i Workfront. Om webkromimplementeringen till exempel innehåller vissa anpassade åtgärder, ska JSON visa dessa åtgärder i JSON. Användarna kan sedan aktivera dessa åtgärder från Workfront.

URL

GET /serviceInfo

Frågeparametrar

Ingen. Dessutom ska anrop till den här slutpunkten inte kräva autentisering.

Svar

JSON som innehåller information om den här tjänsten

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

Returnerar

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

Skapa en mapp

(Tillagt i version 1.2) Skapar en mapp i en angiven katalog.
URL

POST /createFolder

Frågeparametrar

Svar

Metadata för den nyligen skapade mappen, enligt definitionen i /metadata-slutpunkten.

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

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

parentId=1234

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

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

returnerar

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

Ta bort dokument eller mappar

(Releasedatum - TBD) Tar bort ett dokument eller en mapp med det angivna ID:t i det externa systemet. Om du tar bort en mapp tas även dess innehåll bort.

URL

PUT /delete

Frågeparametrar

Besvara en JSON-sträng som anger om åtgärden lyckades eller misslyckades, enligt avsnittet Felhantering nedan.

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

returnerar

{
"status": "success"
}

returnerar

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

Byta namn på ett dokument eller en mapp

(Releasedatum - TBD) Byter namn på ett dokument eller en mapp med det angivna ID:t i det externa systemet.

URL

PUT /rename

Frågeparametrar

Svar

En JSON-sträng som anger om åtgärden lyckades eller misslyckades, vilket anges i felhanteringsavsnittet nedan.

Exempel:

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

Utför en anpassad åtgärd

(Releasedatum - TBD) Den här slutpunkten gör att en Workfront-användare (eller kanske en automatiserad arbetsflödeshändelse) kan utföra en åtgärd i det externa systemet. Slutpunkten /customAction accepterar en name-parameter, som gör att webkrok-providern kan implementera flera anpassade åtgärder.

Webbholleverantören registrerar anpassade åtgärder med Workfront genom att inkludera åtgärderna i svaret /serviceInfo under customActions. Workfront läser in den här listan när du konfigurerar eller uppdaterar webkrokprovidern under Inställningar > Dokument > Anpassade integreringar.

Användarna kan aktivera den anpassade åtgärden genom att markera avsnittet under Dokumentåtgärder

URL

GET /customAction

Frågeparametrar

Svar

En JSON-sträng som anger om åtgärden lyckades eller misslyckades, vilket anges i felhanteringsavsnittet nedan. Vid fel (d.v.s. status = "error") visas det angivna felmeddelandet för användaren.

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

svar

{
"status": "success"
}

Felhantering

Det kan uppstå problem när API-begäranden behandlas. Detta bör hanteras på ett konsekvent sätt över alla API-slutpunkter. När ett fel inträffar gör webbkrokprovidern följande:

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

Testning

Kör följande tester för att kontrollera att implementeringen av dokumentwebkroken fungerar som den ska. Det här är manuella tester som går igenom Workfront webbgränssnitt och indirekt når slutpunkterna för webkromimplementeringen.

Förutsättningar

För att köra dessa tester behöver du följande:

Dessa tester förutsätter också att du redan har registrerat din Document Webkroch-instans i Workfront under Konfigurera > Dokument > Anpassade integreringar.

Test 1: Tillhandahåll Document Webkroch-tjänsten för en användare

Testar autentiserings-URL:en och tokens slutpunkts-URL:en för OAuth-baserade webkrockproviders.

Test 2: Länka ett dokument till Workfront Testar följande slutpunkter: /files, /metadata

Test 3: Navigera till ett dokument i innehållshanteringssystemet

Testar följande slutpunkter: /metadata (särskilt viewLink)

Test 4: Navigera till ett dokument i innehållshanteringssystemet (med inloggning)

Testar följande slutpunkter: /metadata (särskilt viewLink)

Test 5: Hämta dokumentet från innehållshanteringssystemet

Testar följande slutpunkter: /metadata (speciellt downloadLink)

Test 6: Sök efter innehåll

Testar följande slutpunkter: /search

Test 7: Skicka dokument från Workfront till content management-systemet

Testar följande slutpunkter: /files, /uploadInit, /upload

Test 8: Visa miniatyrbilder i Workfront

Testar följande slutpunkter: /miniatyrbild

Test 9: Hämta innehållets byte

Testar följande slutpunkter: /download

Test 10: Uppdatera åtkomsttoken (endast OAuth2 Webkrok providers)

Testar följande slutpunkter: Token Endpoint URL

Versioner