Document Webhooks-API
Adobe Workfront Document Webhooks definieert een set API-eindpunten waarmee Workfront geoorloofde API-aanroepen uitvoert naar een externe documentprovider. Hierdoor kan iedereen een middleware-insteekmodule maken voor elke leverancier van documentopslag.
De gebruikerservaring voor integratie op basis van een webhaak is vergelijkbaar met die van bestaande documentintegratie, zoals Google Drive, Box en Dropbox. Een Workfront-gebruiker kan bijvoorbeeld de volgende handelingen uitvoeren:
- Navigeren door de mapstructuur van de externe documentprovider
- Bestanden zoeken
- Bestanden koppelen naar Workfront
- Bestanden uploaden naar de externe documentprovider
- Een miniatuur voor het document weergeven
Referentie-implementatie
Workfront biedt een voorbeeldimplementatie om de ontwikkeling van een nieuwe webhooks-implementatie te versnellen. De code voor dit kan in https://github.com/Workfront/webhooks-appworden gevonden. Deze implementatie is gebaseerd op Java en maakt het Workfront mogelijk om verbinding te maken met documenten op een netwerkbestandssysteem.
Registreren van een Integratie Webhaak
Workfront-beheerders kunnen een aangepaste webshintegratie voor hun bedrijf toevoegen door te navigeren naar Setup > Documenten > Aangepaste integratie in Workfront. Van de pagina van de Integratie van de Douane binnen Opstelling, kunnen de beheerders een lijst van bestaande integratie van documentWebHaak bekijken. Vanaf deze pagina kunnen integraties worden toegevoegd, bewerkt, ingeschakeld en uitgeschakeld. Klik op de knop Integratie toevoegen om een integratie toe te voegen.
Beschikbare velden
Wanneer de beheerder een integratie toevoegt, zal hij waarden voor de volgende gebieden ingaan:
Verificatie
Websites van Workfront-documenten ondersteunen twee verschillende verificatievormen: OAuth2 en ApiKey. In beide gevallen geeft Workfront verificatietokens door in de header wanneer een API-aanroep wordt uitgevoerd.
OAuth2
OAuth2 staat Workfront toe om erkende API vraag aan een websiteleverancier namens een gebruiker te maken. Voordat de gebruiker dit doet, moet hij zijn externe account voor de documentprovider verbinden met Workfront en Workfront verlenen
toegang om namens hen te handelen. Dit handshaking proces gebeurt slechts eenmaal voor elke gebruiker. Zo werkt het:
-
De gebruiker begint de integratie met de webhaak aan te sluiten op zijn of haar account. Dit gebeurt momenteel door te klikken op het vervolgkeuzemenu Document toevoegen > Service toevoegen > Aangepaste integratienaam.
-
Workfront navigeert door de gebruiker naar de verificatie-URL, die de gebruiker kan vragen zich aan te melden bij de externe documentprovider. Deze pagina wordt gehost door de websiteprovider of het externe documentbeheersysteem. Als u dit doet, voegt Workfront een parameter "state" toe aan de URL van de verificatie. Deze waarde moet worden doorgegeven aan Workfront door dezelfde waarde toe te voegen aan de Workfront Return URI in de onderstaande stap.
-
Na het registreren aan het externe systeem (of als de gebruiker reeds het programma wordt geopend), wordt de gebruiker genomen aan een pagina van de "Authentificatie", die verklaart dat Workfront toegang aanvraagt om een reeks acties namens de gebruiker uit te voeren.
-
Als de gebruiker "toestaat"knoop klikt, zal browser aan Workfront Redirect URI opnieuw richten, toevoegend "code=
<code>
"aan het querystring. Conform de OAuth2-specificatie is dit token van korte duur. Het querystring moet ook het volgende hebben, "state=<sent_by_workfront>
". -
Workfront verwerkt dit verzoek en doet een API vraag aan het Symbolische Eindpunt URL met de vergunningscode.
-
De Symbolische URL van het Eindpunt keert vernieuwt teken en toegangstoken terug.
-
Workfront slaat deze tokens op en past de integratie van de webhaak volledig toe op deze gebruiker.
-
Vanaf dat moment kan Workfront geoorloofde API-aanroepen uitvoeren naar de websiteprovider. Wanneer het maken van deze vraag, zal Workfront het toegangstoken in de HTTP- verzoekkopbal zoals hieronder getoond verzenden:
code language-none ------------------------------- Authorization: Bearer [access_token] -------------------------------
-
Als het toegangstoken is verlopen, zal Workfront een vraag aan het Symbolische Eindpunt URL maken om een nieuw toegangstoken terug te winnen dan de geautoriseerde API vraag met het nieuwe toegangstoken opnieuw proberen.
ApiKey
Het maken van geautoriseerde API-aanroepen naar een webhakprovider met behulp van een ApiKey is veel eenvoudiger dan OAuth2. Wanneer Workfront een API-aanroep maakt, geeft het gewoon de gebruikersnaam van ApiKey en Workfront door in de HTTP-aanvraagheader:
-------------------------------
apiKey: 12345
username: johndoe@foo.com
-------------------------------
De leverancier Webhaak kan de gebruikersbenaming gebruiken om gebruiker-specifieke toestemmingen toe te passen. Dit werkt het beste wanneer beide systemen verbinding maken met LDAP via Single Sign On (SSO).
Aanvraagheaders toevoegen (optioneel)
Naast het gebruiken van of OAuth2 tokens of een ApiKey voor authentificatie, kan Workfront een vooraf bepaalde reeks kopballen naar de webhaleverancier voor elke API vraag verzenden. Een Workfront-beheerder kan dit instellen bij het registreren of bewerken van een Webook-integratie, zoals beschreven in de bovenstaande sectie. Zie Registreren van een Integratie Webhaak.
Dit kan bijvoorbeeld worden gebruikt voor Basic Authentication. Hiervoor voegt de Workfront-beheerder de volgende informatie over Aanvraagkoptekst toe in het dialoogvenster Aangepaste integratie:
Autorisatie standaard QWxhZGRpbjpvcGVuIHNlc2FtZQ==
waarbij QWxhZGRpbjpvcGVuIHNlc2FtZQ== een base-64-gecodeerde tekenreeks is van "username:password". Zie Basisverificatie. Op voorwaarde dat dit is toegevoegd, geeft Workfront dit in de HTTP-aanvraagheader door, naast andere aanvraagheaders:
-------------------------------
apiKey: 12345
username: johndoe@foo.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
-------------------------------
API-specificatie
Hieronder vindt u een lijst met API's die de webshaakprovider moet implementeren om documentwebhooks te laten werken.
Het krijgen OAuth2 Tokens (nodig slechts authentificatie OAuth2)
Keert OAuth2 terug verfrist teken en toegangstoken voor een voor authentiek verklaarde gebruiker. Dit wordt eenmaal aangeroepen wanneer de gebruiker een Document Provider levert. De verdere vraag wordt gemaakt om een bijgewerkt toegangstoken te krijgen.
HTTP-aanvraagPOST /any/url
URL is configureerbaar en beantwoordt aan de Symbolische waarde van URL van het Eindpunt op de pagina van de Opstelling van de douanevertegratie.
Parameters van de Vraag
Reactie
Voorbeeld
POST /oauth2/token
grant_type=authorization_code
code=d9ac7asdf6asdf579d7a8
client_id=123456
client_secret=6asdf7a7a9a4af
Reactie
{
"access_token":"ad8af5ad5ads759",
"refresh_token":"9a0h5d87d808ads",
"expires_id":"3600"
}
Metagegevens ophalen voor bestand of map
Retourneert metagegevens voor het opgegeven bestand of de opgegeven map.
URL
GET /metadata?id= [ document of omslagidentiteitskaart ]
Parameters van de Vraag
De id van het bestand of de map, waarnaar wordt verwezen door de websiteprovider. Dit is anders dan de Workfront-document-id. Gebruik de waarde '/' om de metagegevens van de hoofdmap op te halen.
Opmerking: de id mag maximaal 255 tekens lang zijn.
Reactie
Voorbeeld: https://www.acme.com/api/metadata?id=12345
Reactie
{
"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"
}
Een lijst met items in een map ophalen
Retourneert metagegevens voor de bestanden en mappen voor een bepaalde map.
URL
GET/bestanden
Parameters van de Vraag
De API voor documentwebhooks biedt momenteel geen ondersteuning voor paginering.
Reactie
JSON bevat een lijst met bestanden en mappen. De meta-gegevens voor elk punt zijn het zelfde dat door het /metadata eindpunt is teruggekeerd.
Voorbeeld: https://www.acme.com/api/files?parentId=123456
Reactie
[
{
"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"
},
]
Een zoekopdracht uitvoeren
Retourneert metagegevens voor de bestanden en mappen die door een zoekopdracht worden geretourneerd. Dit kan als full-text onderzoek of als regelmatige gegevensbestandvraag worden uitgevoerd. Workfront roept het /search eindpunt wanneer de gebruiker een onderzoek van externe dossierbrowser uitvoert.
URL
GET/zoekopdracht
Parameters van de Vraag
De API voor documentwebhooks biedt momenteel geen ondersteuning voor paginering.
Reactie
JSON bevat een lijst met metagegevens voor bestanden en mappen die overeenkomen met de query. Wat een "gelijke"is wordt bepaald door de websiteleverancier. In het ideale geval wordt een zoekopdracht in volledige tekst uitgevoerd. Het uitvoeren van een op bestandsnaam gebaseerde zoekopdracht werkt ook.
Voorbeeld: https://www.acme.com/api/search?query=test-query
Reactie
[
{ File/Folder Metadata },
{ File/Folder Metadata }
]
De inhoud van een document ophalen
Hiermee worden de onbewerkte bytes van een document geretourneerd
URL
GET/download
Parameters van de Vraag
Reactie
The raw bytes of the document.
Voorbeeld: https://www.acme.com/api/download?id=123456
Een miniatuur voor een document ophalen
Retourneert de onbewerkte miniatuurbytes voor een document.
URL
GET /miniatuur
Parameters van de Vraag
Reactie
De onbewerkte miniatuurbytes.
Voorbeeld: https://www.acme.com/api/thumbnail?id=123456
Een bestand uploaden - Deel 1 van 2
Het uploaden van een dossier aan een leverancier van de documentopslag is een proces in twee stappen dat twee afzonderlijke API eindpunt vereist. Workfront begint het uploadproces door /uploadInit te roepen. Dit eindpunt keert een document identiteitskaart terug die dan tot /upload wordt overgegaan wanneer het uploaden van de documentbytes. Afhankelijk van het onderliggende documentopslagsysteem kan het nodig zijn om een document met een lengte van nul te maken en de inhoud van het document later bij te werken.
De document-id en de document-versie-id zijn toegevoegd aan versie 1.1 van deze specificatie en kunnen worden gebruikt om extra informatie van Workfront op te halen. Als het documentbeheersysteem bijvoorbeeld extra informatie over het document wil, kan de webhimplementatiecode de document-id gebruiken om die informatie op te halen met behulp van de Workfront RESTful-API. Als goede praktijk, kon deze informatie uit de gebieden van douanegegevens op het document komen en het bevat taak, kwestie, of project.
URL
POST /uploadInit
Parameters van de Vraag
Reactie
De meta-gegevens voor het dossier, zoals die door het /metadata eindpunt wordt bepaald.
Voorbeeld: https://www.acme.com/api/uploadInit?parentId=12345&filename=new-file.png&docu mentId=511ea6e000023edb38d2effb2f4e6e3b&documentVersionId=511ea6e000023edb38d2e ffb2f4e6e3b
Reactie
[file_metadata]
bevat de nieuwe document-id die door de documentprovider wordt gebruikt.
Een bestand uploaden - Deel 2 van 2
Hiermee uploadt u de bytes van een document naar de websiteprovider.
URL
PUT /upload
Parameters van de Vraag
Lichaam van het Verzoek
De onbewerkte inhoudbytes voor het document.
Reactie
{
"result": "success"
}
of
{
"result": "fail"
}
Voorbeeld: https://www.acme.com/api/upload?id=1234
[documentbytes inbegrepen in updatestroom]
Reactie
{
"result":"success"
}
Informatie ophalen over de service
(Releasedatum - TBD) Retourneert informatie over de service, zoals functies en mogelijkheden. Workfront gebruikt deze informatie om de gebruikersinterface in Workfront aan te passen. Als de implementatie van de webhaak bijvoorbeeld aangepaste handelingen bevat, moet de JSON deze bewerkingen in de JSON opnemen. Gebruikers kunnen deze acties dan aanroepen vanuit Workfront.
URL
GET/serviceInfo
Zoekparameters
Geen. Bovendien zouden de vraag aan dit eindpunt geen authentificatie moeten vereisen.
Reactie
JSON met informatie over deze service
Voorbeeld: https://www.acme.com/api/serviceInfo
Keert terug
{
"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" }, ] }
Een map maken
(Toegevoegd in versie 1.2) Hiermee maakt u een map in een bepaalde map.
URL
POST /createFolder
Parameters van de Vraag
Reactie
De meta-gegevens voor de pas gecreëerde omslag, zoals die door het /metadata eindpunt wordt bepaald.
Voorbeeld: POST https://www.acme.com/api/createFolder
-------------------------------
parentId=1234
name=New Folder
-------------------------------
retourneert
{"title":"New Folder",
"kind":"folder""id":"5678",
"viewLink":"",
"downloadLink":"",
"mimeType":"",
"dateModified":"20140605T17:39:45.251Z"
"size": ""
}
Een document of map verwijderen
(Releasedatum - TBD) Hiermee verwijdert u een document of map met de opgegeven id in het externe systeem. Als u een map verwijdert, wordt ook de inhoud van de map verwijderd.
URL
PUT /delete
Parameters van de Vraag
Antwoord Een JSON-tekenreeks die aangeeft of de functie is gelukt of mislukt, zoals is opgegeven in de sectie Foutafhandeling hieronder.
Voorbeeld: PUT https://www.acme.com/api/delete id=1234
retourneert
{
"status": "success"
}
retourneert
{
"status": "failure", "error": "File not found"
}
De naam van een document of map wijzigen
(Releasedatum - TBD) Hiermee wijzigt u de naam van een document of map met de opgegeven id in het externe systeem.
URL
PUT /naam wijzigen
Parameters van de Vraag
Antwoord
Een JSON-tekenreeks die aangeeft of de functie is gelukt of mislukt, zoals is opgegeven in de sectie Foutafhandeling hieronder.
Voorbeeld:
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."
}
Een aangepaste handeling uitvoeren
(Releasedatum - TBD) Met dit eindpunt kan een Workfront-gebruiker (of misschien een geautomatiseerde workflowgebeurtenis) een actie uitvoeren in het externe systeem. Het /customAction eindpunt keurt een "naam"parameter goed, die de websiteleverancier toestaat om veelvoudige douaneverrichtingen uit te voeren.
De websiteleverancier registreert douaneacties met Workfront door de acties in de /serviceInfo reactie onder customActions te omvatten. Workfront laadt deze lijst bij het instellen of vernieuwen van de websiteprovider onder Instellen > Documenten > Aangepaste integratie.
Gebruikers kunnen de aangepaste handeling activeren door de sectie onder "Documenthandelingen" te selecteren
URL
GET /customAction
Parameters van de Vraag
Reactie
Een JSON-tekenreeks die aangeeft of de functie is gelukt of mislukt, zoals is opgegeven in de sectie Foutafhandeling hieronder. Bij een fout (d.w.z. status = "mislukking") geeft Workfront het aangeboden foutbericht aan de gebruiker weer.
Voorbeeld: https://sample.com/webhooks/customName?name=archive&documentId=5502082c003a4f30 ddec2fb2b739cb7c&documentVersionId=54b598a700e2342d6971597a5df1a8d3
reactie
{
"status": "success"
}
Foutafhandeling
Er kunnen zich problemen voordoen bij het verwerken van API-aanvragen. Dit zou op een verenigbare manier over alle API eindpunten moeten worden behandeld. Wanneer er een fout optreedt, doet de websiteprovider het volgende:
-
Neem een foutcode op in de antwoordkop. Foutcodes zijn:
- 403 - Verboden. Geeft aan dat de aanvraagtokens ontbreken of ongeldig zijn of dat referenties die aan de tokens zijn gekoppeld, geen toegang hebben tot de opgegeven bron. Workfront probeert nieuwe toegangstokens op te halen voor webhaken die op OAuth zijn gebaseerd.
- 404 - Niet gevonden. Geeft aan dat het opgegeven bestand of de map niet bestaat.
- 500 - Interne serverfout. Een ander type fout.
-
Beschrijf de fout in het reactievermogen gebruikend het volgende formaat:
{
"status": "error"
"error": "Sample error message"
}
Testen
Voer de volgende tests uit om te controleren of de implementatie van uw documentwebhaak correct werkt. Dit zijn handtests die de Workfront-webinterface doorlopen en indirect de eindpunten voor uw webhaakimplementatie raken.
Vereisten
Voor het uitvoeren van deze tests hebt u het volgende nodig:
- Een Workfront-account met ADM (Advanced Document Management) ingeschakeld
- Een Workfront-gebruiker voor dit account met System Admin Rights
- Een WebHaakinstantie van het Document, die de eindpunten van HTTP voor Workfront toegankelijk zijn
Bij deze tests wordt er ook van uitgegaan dat u de instantie WebHaak van document al in Workfront hebt geregistreerd onder Instellen > Documenten > Aangepaste integratie.
Testen 1: De Document Webhaak-service verlenen aan een gebruiker
Test URL van de Authentificatie en Symbolische Eindpunt URL voor op OAuth-Gebaseerde Leveranciers van Webhaken.
- Ga in Workfront naar de hoofdpagina Documenten door op de koppeling Documenten in de bovenste navigatiebalk te klikken.
- Klik op Add dropdown Documenten en selecteer uw dienst van Webhaak van het Document onder Add de Dienst.
- (Alleen OAuth-services) Nadat u de vorige stap hebt uitgevoerd, wordt de pagina voor OAuth2-verificatie van uw service geladen in een pop-upvenster. (Opmerking: u wordt mogelijk eerst gevraagd u aan te melden bij uw service.) Via de verificatiepagina geeft u Workfront toegang tot de account van de gebruiker door op de knop Vertrouwd of Toestaan te klikken.
- Controleer of uw service is toegevoegd aan de vervolgkeuzelijst Documenten toevoegen. Vernieuw de browser als deze standaard niet wordt weergegeven.
Test 2: Een document koppelen aan Workfront Test de volgende eindpunten: /files, /metadata
- Ga in Workfront naar de hoofdpagina Documenten door op de koppeling Documenten in de bovenste navigatiebalk te klikken.
- Selecteer de documentservice Webhaak onder Documenten toevoegen.
- Navigeer in het modaal door de mappenstructuur.
- Controleer of u de mapstructuur correct kunt navigeren.
- Een document selecteren en koppelen naar Workfront
Testen 3: naar een document navigeren in het inhoudsbeheersysteem
Test de volgende eindpunten: /metadata (specifiek viewLink)
- Een document koppelen aan Workfront
- Selecteer het document en klik op de koppeling Openen.
- Controleer of het document op een nieuw tabblad wordt geopend.
Testen 4: naar een document navigeren in het inhoudsbeheersysteem (met aanmelding)
Test de volgende eindpunten: /metadata (specifiek viewLink)
- Zorg ervoor dat u bent afgemeld bij het inhoudsbeheersysteem.
- Koppel een document aan Workfront.
- Selecteer het document en klik op de koppeling Openen.
- Controleer of het aanmeldingsscherm van het inhoudsbeheersysteem op een nieuw tabblad wordt geladen.
- Aanmelden en controleren of u naar het document bent gegaan
Test 5: Download het document van het contentbeheersysteem
Test de volgende eindpunten: /metadata (in het bijzonder downloadLink)
- Koppel een document aan Workfront.
- Selecteer het document en klik op de koppeling Downloaden.
- Controleer of het downloaden begint.
Testen 6: inhoud zoeken
Test de volgende eindpunten: /search
- Ga in Workfront naar de hoofdpagina Documenten door op de koppeling Documenten in de bovenste navigatiebalk te klikken.
- Selecteer de documentservice Webhaak onder Documenten toevoegen.
- Voer een zoekopdracht uit vanuit het modaal.
- Controleer of de zoekresultaten correct zijn.
Testen 7: document vanuit Workfront naar contentbeheersysteem verzenden
Test de volgende eindpunten: /files, /uploadInit, /upload
- Ga in Workfront naar de hoofdpagina Documenten door op de koppeling Documenten in de bovenste navigatiebalk te klikken.
- Een document vanaf uw computer uploaden naar Workfront
- Ga naar de pagina met documentdetails
- Selecteer in het vervolgkeuzemenu Documenthandelingen de documentservice onder Verzenden naar…
- Ga naar de gewenste doelmap en klik op Opslaan.
- Controleer of het document naar de juiste locatie in het inhoudsbeheersysteem is geüpload.
Testen 8: Miniaturen weergeven in Workfront
Test de volgende eindpunten: /thumbnail
- Koppel een document aan Workfront.
- Selecteer het document in de lijst.
- Controleer of de miniatuur in het rechterdeelvenster wordt weergegeven.
Testen 9: De bytes van de inhoud ophalen
Test de volgende eindpunten: /download
- Koppel een document aan Workfront.
- Ga naar de pagina met documentdetails.
- Het document naar Workfront verzenden door Documenthandelingen > Verzenden naar… > Workfront te selecteren. Hiermee wordt een nieuwe documentversie in Workfront gemaakt.
- Download het document vanuit Workfront door op de koppeling Downloaden te klikken.
Test 10: toegangstoken vernieuwen (alleen OAuth2 Webhaak-providers)
Test de volgende eindpunten: Token Endpoint URL
- Verricht de dienst van Webhaak van het Document voor een gebruiker
- Maak het toegangstoken van de gebruiker ongeldig door 1 te wachten op time-out, of 2) het manueel ongeldig te maken in het externe systeem.
- Vernieuw het toegangstoken in Workfront. U kunt dit bijvoorbeeld doen door een document aan Workfront te koppelen. Het toegangstoken is vernieuwd als u naar een document kunt navigeren en er een koppeling naar kunt maken.
Versies
-
Versie 1.0 (Releasedatum - mei 2015)
- Oorspronkelijke specificatie
-
Versie 1.1 (Releasedatum - juni 2015)
- Bijgewerkt /uploadInit - Toegevoegde documentId en documentVersionId
-
Versie 1.2 (Releasedatum - oktober 2015)
- Toegevoegde /createFolder