Incompatibiliteit tussen Zendesk API en de Nieuwe Artikelbewerker – Swifteq

Samenvatting

Artikelen en vertalingen die zijn gemaakt of bijgewerkt via de Zendesk REST API worden door de Zendesk UI gemarkeerd als legacy editor-inhoud, zelfs wanneer het bronartikel in de nieuwe editor is geschreven. Dit is een bekende incompatibiliteit aan de kant van Zendesk die elke Swifteq-app (Help Center Manager, Help Center Translate, enz.) evenals elke andere integratie, script of workflow die via de API naar Zendesk Help Center schrijft, beïnvloedt.

Dit artikel legt de oorzaak uit, hoe het probleem kan worden gereproduceerd en hoe het zich manifesteert binnen Zendesk.

Achtergrond: waarom dit gebeurt

Zendesk heeft twee artikeleditors voor Help Center-artikelen:

Legacy editor — accepteert willekeurige HTML met zeer weinig beperkingen.
Nieuwe editor — gebruikt een strikt inhoudsschema met een gedefinieerde set inhoudsblokken (alinea's, koppen, lijsten, callouts, HTML-blokken, enz.).

De Zendesk REST API voor artikelen en vertalingen accepteert alleen vrije HTML in het body-veld. Er is geen API-parameter om aan te geven dat inhoud als nieuwe-editor-inhoud moet worden opgeslagen, en er is geen gepubliceerd schema waarop API-gebruikers zich kunnen richten. Als gevolg hiervan, wanneer een tool via de API naar een artikel of vertaling schrijft, verwerkt Zendesk die HTML via het strikte schema van de nieuwe editor, en komt het artikel/de vertaling in een staat terecht die door de Zendesk UI als legacy wordt gemarkeerd.

Dit is rechtstreeks bevestigd door het engineeringteam van Zendesk:

Kort tot middellang termijn: het huidige gedrag is verwacht. De API en de nieuwe editor zijn niet direct compatibel, dus elk artikel of vertaling die via de API wordt geschreven, wordt gemarkeerd als legacy-editor-inhoud.
Lange termijn: Zendesk werkt aan een herontworpen Help Center API die aansluit bij het inhoudsmodel van de nieuwe editor. Er is momenteel geen geschatte tijd van oplevering.

De ontwikkelaarsdocumentatie van Zendesk over dit onderwerp is hier beschikbaar: https://developer.zendesk.com/documentation/help_center/help-center-api/article-editor-troubleshooting/

Hoe het probleem te reproduceren

Het gedrag kan in twee scenario's worden gereproduceerd. Beide reproduceren dezelfde onderliggende bug.

Scenario A — Een gemigreerd artikel bijwerken via de API

Migreer in Zendesk een artikel naar de nieuwe editor via de Knowledge UI en bevestig dat het als gemigreerd wordt weergegeven.
Open dat artikel in een Swifteq-app (bijv. Help Center Manager). De app haalt de gemigreerde HTML op uit de Zendesk API.
Breng een wijziging aan — zelfs een triviale, zoals het toevoegen van een enkele spatie — en sla de wijziging op.
Swifteq duwt het bijgewerkte artikel terug naar Zendesk via de standaard Update Article / Update Translation REST-endpoint.
Open het artikel opnieuw in de Knowledge UI van Zendesk.

Resultaat: Het artikel wordt niet langer als gemigreerd gemarkeerd. Zendesk toont het als legacy-editor-inhoud en vereist dat het opnieuw wordt gemigreerd, ook al kwam de HTML die terug naar Zendesk werd gestuurd oorspronkelijk uit de gemigreerde versie van het artikel.

Scenario B — Een vertaling maken voor een artikel dat in de nieuwe editor is geschreven

Maak in Zendesk een gloednieuw artikel aan met de nieuwe editor.
Gebruik Help Center Translate (of een andere tool die vertalingen maakt via de Zendesk API) om het artikel in een of meer doeltalen te vertalen.
Open een van de nieuwe vertalingen in Zendesk.

Resultaat: De vertaling wordt door Zendesk gemarkeerd als gemaakt in de legacy editor, ook al is het bronartikel in de nieuwe editor geschreven en nooit via de API bewerkt.

Hoe het probleem zich manifesteert in Zendesk

Na een API-schrijfactie vertoont het getroffen artikel of de vertaling een of meer van de volgende kenmerken:

Het artikel toont een banner of bericht bovenaan waarin staat dat het voor het laatst is bewerkt via de API of met de legacy-editor.
Bij het openen van het artikel voor bewerking toont de editor een waarschuwingsbericht en kan het in alleen-lezen modus openen, waarbij de gebruiker moet bevestigen voordat er bewerkt kan worden.
Het artikel verschijnt in filters of rapporten als niet gemigreerd naar de nieuwe editor.
Opmaak die eerder geldig was in de nieuwe editor (zoals aangepaste HTML-oproepen, afbeeldingsafstand of HTML-blokken) kan opnieuw geïnterpreteerd worden door het schema van de nieuwe editor, wat resulteert in zichtbare opmaakwijzigingen.
HTML-blokken die aanwezig zijn in het oorspronkelijke artikel kunnen worden verwijderd of gewijzigd wanneer het artikel opnieuw wordt weergegeven door de nieuwe editor.

Opmerking: de onderliggende artikelinhoud wordt correct naar Zendesk geschreven. Het probleem zit in hoe de Zendesk UI die inhoud labelt en weergeeft na een API-schrijfbewerking.

Wat dit betekent voor onze klanten

Het gedrag is niet specifiek voor Swifteq-apps. Het beïnvloedt elke integratie, automatisering of script dat Zendesk Help Center-artikelen of vertalingen aanmaakt of bijwerkt via de REST API.
Er is geen instelling aan de Swifteq-kant die dit kan voorkomen — de Zendesk API biedt simpelweg geen mogelijkheid om inhoud als nieuwe-editor inhoud te schrijven.
Totdat Zendesk de herontworpen Help Center API uitbrengt, moeten klanten die API-gebaseerde workflows gebruiken rekening houden met legacy-editor waarschuwingen op artikelen en vertalingen die via de API zijn bijgewerkt.

Wat wij aanbevelen

Breng het probleem direct onder de aandacht bij Zendesk Support. Hoe meer getroffen accounts dit intern escaleren, hoe meer zichtbaarheid en urgentie de API-herontwerp krijgt. Verwijs bij het openen van een ticket naar het feit dat dit een bekende incompatibiliteit is tussen de Zendesk REST API en de nieuwe artikel-editor, bevestigd door het engineeringteam van Zendesk.
Raadpleeg de ontwikkelaarsdocumentatie van Zendesk voor de laatste richtlijnen: Probleemoplossing artikel-editor.
Neem contact op met Swifteq support als u hulp wilt bij het beschrijven van het probleem bij het escaleren naar Zendesk, of als u begeleiding nodig heeft om de impact op uw specifieke workflow te minimaliseren.

Status

Swifteq is actief betrokken bij Zendesk Support en engineering bij dit probleem en volgt de voortgang van de herontworpen Help Center API. We zullen dit artikel bijwerken zodra Zendesk wijzigingen uitbrengt die de incompatibiliteit oplossen.