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:

Referentie-implementatie

Workfront biedt een voorbeeldimplementatie om de ontwikkeling van een nieuwe webhooks-implementatie te versnellen. Code hiervoor is te vinden op https://github.com/Workfront/webhooks-app. 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:

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.

Zoekparameters

Antwoord

Voorbeeld

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

Antwoord

{
"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 map-id]

Zoekparameters

Antwoord

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

Antwoord

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

Een lijst met items in een map ophalen

Retourneert metagegevens voor de bestanden en mappen voor een bepaalde map.

URL

GET/bestanden

Zoekparameters

De API voor documentwebhooks biedt momenteel geen ondersteuning voor paginering.

Antwoord

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

Antwoord

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

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

Zoekparameters

De API voor documentwebhooks biedt momenteel geen ondersteuning voor paginering.

Antwoord

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

Antwoord

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

De inhoud van een document ophalen

Hiermee worden de onbewerkte bytes van een document geretourneerd

URL

GET/download

Zoekparameters

Antwoord

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

Zoekparameters

Antwoord

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

Zoekparameters

Antwoord

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

Antwoord

[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

Zoekparameters

Indieningsinstantie

De onbewerkte inhoudbytes voor het document.

Antwoord

{
"result": "success"
}

of

{
"result": "fail"
}

Voorbeeld: https://www.acme.com/api/upload?id=1234 [documentbytes die zijn opgenomen in updatestroom]

Antwoord

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

Antwoord

JSON met informatie over deze service

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

Retourneert

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

Zoekparameters

Antwoord

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":"2014­06­05T17: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

Zoekparameters

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

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

Zoekparameters

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

Zoekparameters

Antwoord

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:

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

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.

Test 2: Een document koppelen aan Workfront Test de volgende eindpunten: /files, /metadata

Testen 3: naar een document navigeren in het inhoudsbeheersysteem

Test de volgende eindpunten: /metadata (specifiek viewLink)

Testen 4: naar een document navigeren in het inhoudsbeheersysteem (met aanmelding)

Test de volgende eindpunten: /metadata (specifiek viewLink)

Test 5: Download het document van het contentbeheersysteem

Test de volgende eindpunten: /metadata (in het bijzonder downloadLink)

Testen 6: inhoud zoeken

Test de volgende eindpunten: /search

Testen 7: document vanuit Workfront naar contentbeheersysteem verzenden

Test de volgende eindpunten: /files, /uploadInit, /upload

Testen 8: Miniaturen weergeven in Workfront

Test de volgende eindpunten: /thumbnail

Testen 9: De bytes van de inhoud ophalen

Test de volgende eindpunten: /download

Test 10: toegangstoken vernieuwen (alleen OAuth2 Webhaak-providers)

Test de volgende eindpunten: Token Endpoint URL

Versies