Migratie PS API 40 naar 50

Transcriptie

1 Migratie PS API 40 naar 50 Inhoud Introductie... 2 Migratie... 2 Wijziging link ophalen beeldmateriaal... 2 Wijzigingen vertaalbare velden (translationtype)... 3 Targetmarkets (TM)... 4 Velden die zijn verwijderd... 4 Velden die zijn toegevoegd... 5 Velden die van naam zijn gewijzigd... 6 Geen vertalingen van masterdate in xml... 6 Bijlage / 8

2 Introductie Dit document is bedoeld om de migratie van de huidige v40 versie van de PS API naar v50 versie zo makkelijk en duidelijk mogelijk te maken. Alle aangepaste onderdelen worden besproken, maar niet alle onderdelen zijn voor iedereen van belang. De belangrijkste reden voor de totstandkoming van v50 is de ondersteuning voor meertaligheid en meerdere targetmarkets. De meertaligheid is al beschikbaar in de DataEntry en met de update naar v50 komt dit ook in de PS-API beschikbaar. De ondersteuning van meerdere targetmarkets (TM) is volgt later dit jaar. Tot die tijd zal het targetmarket gevuld worden met NL. De v50 is a wel helemaal voorbereid voor het ontvangen en sturen van meerdere TM. De v50 bevat een aantal breaking changes. Dit klinkt zwaar. Toch vallen de aanpassingen mee, omdat de meeste wijzigingen zitten in een uitbreiding op vertaalbare velden. Ook is een aantal velden verwijderd en toegevoegd. Migratie Om te migreren zijn samengevat de volgende stappen nodig Aanpassing van de Url. Dit was en dit wordt Aanpassen van de XML volgens de XSD versie V50 specificatie (zie De oude PS-API V40 blijft tot 1 januari 2017 beschikbaar en dan wordt hij afgesloten. PS zal in de komende 4 maanden zorgen dat er een mapping wordt gedaan van het oude naar het nieuwe formaat (en vica versa) via een transformatie van de XML. Wijziging link ophalen beeldmateriaal Binnen de XML zijn ook verwijzingen naar beeldmateriaal (packshots, commerciële foto s en logo s). Deze staan als link in de PS-XML. In de oude situatie had deze link het volgende formaat: In de nieuwe situatie zal het formaat veranderen in: F7DB0E1D840D?w=250&h=250 Gebruik je deze links rechtstreeks, dan moeten alle producten opnieuw worden binnengehaald om de nieuwe link op te slaan. Bij nieuwe updates komen automatisch de nieuwe URL s binnen. Doe je niks met afbeeldingen dan is een volledige update niet nodig. Er verandert niets inhoudelijk aan de afbeeldingen. TIP het standaardformaat is 250 x 250 px. Wil je een groter formaat dan kan je de waarde in de w en h aanpassen. Bijvoorbeeld naar 1000x / 8

3 Wijzigingen vertaalbare velden (translationtype) Het ontvangen en sturen van meertaligheid is een van de belangrijkste aanpassingen in de update van de PS-API. Het huidige xml kent al het translationtype. <xs:complextype name="translationtype"> <xs:sequence> <xs:element name="value" type="xs:string" minoccurs="1" maxoccurs="1"/> <xs:element name="translation" minoccurs="0" maxoccurs="unbounded"> <xs:complextype> <xs:all> <xs:element name="culture" type="xs:string"/> <xs:element name="value" type="xs:string"/> </xs:all> </xs:complextype> </xs:element> </xs:sequence></xs:complextype> Dit element bevat een <value> welke de (taalonafhankelijke) standaardwaarde is. Verder kan er een lijst van vertalingen worden opgevoerd of opgehaald (indien aanwezig). De vertalingen zijn echter optioneel en indien er geen vertaling is opgevoerd van een bepaalde taal, kan men terugvallen op de standaardwaarde. Een voorbeeld van een gevuld translation object in de nieuwe situatie ziet er als volgt uit: <name> <value>melk</value> <translation> <value>milcheiweiß</value> <culture>de-de</culture> </translation> <translation> <value>milk</value> <culture>en-us</culture> </translation> <translation> <value>lait</value> <culture>fr-fr</culture> </translation> </name> De culture kan een waarde hebben van: nl-nl, de-de, en-us en fr-fr In het bovenstaande voorbeeld is er geen Nederlands opgevoerd en dan kan men terugvallen op de standaardwaarde. We zullen als PS promoten om alles zo compleet mogelijk in te voeren 3 / 8

4 In het v40 xml formaat waren veel tekstvelden al vertaalbaar, doormiddel van het type translationtype. In het v50 formaat is dit verder doorgevoerd. In de bijlage is een overzicht welke tekstvelden zijn aangepast naar het type translationtype. Een voorbeeld van een migratie naar translationtype is bijvoorbeeld: Oud: <functionalname>brood< /functionalname> wordt Nieuw: <functionalname><value>brood</value></ functionalname> Voor de migratie moet de waarde dus alleen worden gemapt naar de <value> binnen het element i.p.v. het element zelf. Uiteraard kunnen beschikbare vertalingen nu worden meegenomen in het ophalen of sturen van data. Targetmarkets (TM) In de nieuwe v50 versie moet er worden aangegeven voor welke TM het product bedoeld is. Indien dit niet bekend is, dan kan er TM NL (id=1) worden opgevoerd. Bij meerdere TM moet het product per TM apart worden opgevoerd. Bij het ophalen van de data zal hetzelfde product voor meerdere TM als aparte producten worden teruggestuurd. Voor de nieuwe situatie t.a.v. TM gaat het volgende gelden: TM wordt op product niveau vastgelegd Ieder product krijgt één TM. Een GTIN moet binnen iedere TM uniek zijn. Voor iedere TM krijg je een apart product binnen. Dus als een product (met hetzelfde GTIN) in 2 TM is opgevoerd, dan ontvang je 2 losse producten Filter in de PS-API: bijvoorbeeld filterontargetmarket=2 is filteren op TM België. Als geen filter opgevoerd wordt voor TM dan is de default NL (id=1) Filter in de PS-API: je kunt filteren op meerdere TM tegelijk: filterontargetmarket=1;2 Filter in de PS-API: includealltargetmarkets=true ontvang alle TM. De ontvangende kant moet dan zelf actie ondernemen om de TM te scheiden Alle huidige producten zijn TM NL Extra TM komen pas binnen als de transitie naar meerdere TM klaar is. Indien het zover is komen ze automatisch binnen. Er is dan geen aanpassing meer nodig voor in de interface van de API Velden die zijn verwijderd In de bijlage is een overzicht van velden die zijn verwijderd. Dosageinfotype, dosagesettype, dosageinfolisttype, specificationinfotype\dosageset Doseringen zijn al eerder al uit gefaseerd en worden al niet meer gestuurd. Ze zijn te vinden onder de bereidingswijze (preparation). Nu worden ze ook uit de XSD verwijderd preparationinformationinfotype\preparationwarninginfolist, preparationinformationinfotype\preparationinstructioninfolist, preparationwarninginfolisttype, preparationwarninginfotype, preparationinstructioninfolisttype, preparationinstructioninfotype 4 / 8

5 Bereidingen werden voorheen in stappen opgevoerd worden nu als één tekst opgevoerd in het veld preparationdescription. De elementen behorend bij de stappen zijn nu ook verwijderd. producttype\ismixpackage Mixverpakkingen zijn nooit aangeboden via de API. In de nieuwe DataEntry worden de mixverpakkingen opgevoerd als een monoverpakking. Hierdoor is het element overbodig geworden. allergentype\type Dit veld geeft dezelfde informatie als allergentype\isrequiredbylaw en daarom wordt deze verwijderd. logisticinfotype\compulsoryadditiveslabelinformation Deze is uiteindelijk nooit gebruikt en wordt uit de XSD verwijderd logisticinfotype\servingunitpackagingtypeid logisticinfotype\servingunitpackagingtypename Het aantal plakken komt te vervallen en wordt nu vastgelegd in servingquantity logisticinfotype\targetmarketid logisticinfotype\targetmarketname logisticinfotype\targetmarketinfolist targetmarketinfolisttype targetmarketinfotype Targetmarket wordt in de nieuwe situatie, op product niveau vastgelegd (zie bij toegevoegde velden) Velden die zijn toegevoegd Preparationtypetype, masterstype\preparationtypelist\preparationtypetype, globalproductspecificationtype, masterstype\globalproductclassifications fishcatchzonetype, masterstype\fishcatchzones fishcapturemethodtype, masterstype\fishcapturemethods scientificfishnametype, masterstype\scientificfishnames targetmarkettype, masterstype\targetmarket storageconditionstagetype, mastertype\storageconditionstages taxrateapplicabilitytype, mastertype\taxrateapplicabilities In de lijst van masterdata zijn nu ook bovenstaande types te vinden productinfotype\targetmarketid, productinfotype\targetmarketname, productinfotype\targetmarketabbrevation Op productinfo nivo wordt er aangegeven voor welke doelmarkt dit product is bedoeld. Hetzelfde product kan voor meerdere doelmarkten worden opgevoerd. Deze komen ieder afzonderlijk binnen. Deze functionaliteit komt in de loop van het jaar beschikbaar, echter het veld wordt alvast opgenomen in de XSD. Tot die tijd zal targetmarket gevuld zijn met NL fishingredientinfolisttype, fishingredientinfotype, fishcatchzoneinfotype, scientificfishname, productinfotype\fishingredientinfolist op productinfo nivo kan bij vis de vangstgebieden worden vastgelegd en opgevraagd countryinfotype, ingredientinfotype\countroforigins op ingredient nivo kan het land van herkomst worden vastgelegd en opgevraagd storageconditioninfo/comment meertalig veld voor extra commentaar t.a.v. een storagecondition 5 / 8

6 Velden die van naam zijn gewijzigd logisticinfotype\servingunitquantity wordt logisticinfotype\servingquantity Geen vertalingen van masterdate in xml In de xml van een product wordt bij ieder iedere verwijzing naar een id uit de masterdata ook een naam van het betreffende item mee gestuurd. Bijvoorbeeld bij allergenen. In het allergeninfo element wordt een levelofcontainmentid=1 opgevoerd en de bijbehorende naam bevat is aanwezig. In de huidige situatie werden ook de vertalingen meegestuurd, zoals contains. De standaard naam blijft, maar de vertalingen zijn alleen beschikbaar in de masterdata. Dit is gedaan om het niet te veel herhaalde data mee te sturen in het bericht. Dit geldt uiteraard niet voor vertaalbare velden die door de producenten zelf zijn ingevuld. 6 / 8

7 Bijlage Opmerking: er waren al veel vertaalbare velden, dit zijn aanvullingen daarop velden die van type veranderen (o.a. meertalige velden) ingredientsettype\ingredientcomment van string naar translationtype ingredientsettype\ingredientdeclaration van string naar translationtype ingredientsettype\ingredientdeclarationpreview van string naar translationtype ingredientsettype\gs1ingredientallergensummary van string naar translationtype measurementprecisiontype\name van string naar translationtype measurementprecisiontype\abbreviation van string naar translationtype measurementprecisiontype\description van string naar translationtype unitofmeasurementtype\name van string naar translationtype unitofmeasurementtype\abbreviation van string naar translationtype unitofmeasurementtype\description van string naar translationtype commercialinfotype\legalname van string naar translationtype commercialinfotype\globalproductclassificationname van string naar translationtype microbiologicalorganisminfotype\measurementprecisionname van string naar translationtype microbiologicalorganisminfotype\unitofmeasurename van string naar translationtype storageconditionsettype\comment van string naar translationtype physiochemicalcharacteristicinfotype\unitofmeasurename velden die zijn toegevoegd (masters) preparationtypetype masterstype\preparationtypes globalproductspecificationtype masterstype\globalproductclassifications targetmarkettype masterstype\targetmarkets fishcatchzonetype masterstype\fishcatchzones fishcapturemethodtype masterstype\fishcapturemethods scientificfishnametype masterstype\scientificfishnames storageconditionstagetype mastertype\storageconditionstages taxrateapplicabilitytype 7 / 8

8 mastertype\taxrateapplicabilities velden die zijn toegevoegd (body) relationlisttype, relationtype body/relations velden die zijn toegevoegd (product) productinfotype\targetmarketid productinfotype\targetmarketname productinfotype\targetmarketisocode fishingredientinfolisttype fishingredientinfotype fishcatchzoneinfotype productinfotype\fishingredientinfolist countryinfotype ingredientinfotype\countroforigins storageconditioninfo/comment velden die zijn komen te vervallen producttype\ismixpackage dosageinfotype dosagesettype dosageinfolisttype specificationinfotype\dosageset preparationinformationinfotype\preparationwarninginfolist preparationinformationinfotype\preparationinstructioninfolist preparationwarninginfolisttype, preparationwarninginfotype preparationinstructioninfolisttype, preparationinstructioninfotype allergentype\type logisticinfotype\compulsoryadditiveslabelinformation logisticinfotype\servingunitpackagingtypeid logisticinfotype\servingunitpackagingtypename logisticinfotype\targetmarketid logisticinfotype\targetmarketname logisticinfotype\targetmarketinfolist targetmarketinfolisttype targetmarketinfotype velden die van naam veranderen logisticinfotype\servingunitquantity wordt logisticinfotype\servingquantity 8 / 8