Inlezen extra velden van Exact Online artikelen

Extra velden op Artikelen

Exact Online stelt gebruikers in staat om extra velden te definiëren op artikelen. De extra velden kunnen bijvoorbeeld een tekst bevatten of een waarde uit een lijst. De structuur van de extra velden wordt per administratie ingesteld in Exact Online als stamgegevens. Meer informatie over deze extra artikelvelden vind je bij Oproepen van Extra Velden in de Power BI connector.

Uitlezen via REST API

Het uitlezen van de waardes van de extra velden kan via de tabellen op basis van de Exact Online REST API’s zoals ItemExtraFieldValues. Oorspronkelijk was het alleen mogelijk om de inhoud van extra velden per artikel uit te lezen, maar dit kan nu ook voor meerdere artikelen tegelijk wat de snelheid ten goede komt. De API voor de velden blinkt niet uit door stabiliteit; reserveer daarom wat meer tijd om koppelingen te maken.

Inlezen via XML API

Het inlezen van gegevens in de vrije velden kan uitsluitend via de Exact Online XML API. Met behulp van de volgende instructies wordt dit uitgelegd.

De waardes kun je importeren via de UploadXMLTopics view. Bij een insert op deze view wordt de XML opgeknipt in logisch correcte brokken zodat de XML niet de beperkingen van de XML API overschrijdt. De gegevens worden daarna geïmporteerd in een of meerdere administraties.

Het is dus ook mogelijk om met een import meerdere administraties tegelijk te laden met extra productinformatie. Echter, de definities van de vrije velden moeten dan wel in elke Exact administratie gelijk zijn.

Samenstellen XML voor Exact

De eerste stap om waardes te importeren is het samenstellen van de XML volgens de specificaties. De onderstaande query selecteert eerst twee administraties en maakt vervolgens een in-memory tabel met twee rijen: één per Exact Online administratie (“division”).

Per administratie wordt voor elk artikel een waarde opgegeven voor het eerste extra veld. Dat extra veld moet “KOPIE OMSCHRIJVING” heten. De waarde zal gelijkgetrokken worden met de omschrijving van het product.

De listagg groepfunctie in de binnenste query zorgt er voor dat de XML van elk artikel achterelkaar gezet wordt in een lange tekst, zonder scheiding tekens. De buitenste query neemt alle data per administratie en voegt hier de verplichte kop en voet in XML aan toe. Via de xmlformat functie wordt de XML eerst gecontroleerd op geldigheid en daarna in een makkelijk leesbaarder formaat omgezet met voldoende regelovergangen en inspringing.

--
-- Selecteer two Exact Online administraties.
--
use 2123456, 2344242

create or replace table xmlupload@inmemorystorage
as
select 'voorbeeld.xml' filename
,      'Items' topic
,      to_char(division) division
,       xmlformat
       ( '<?xml version="1.0" encoding="utf-8"?>'
       || '<eExact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="eExact-XML.xsd">'
       || xmlcomment('For division ' || division)
       || '<Items>'
       || xml
       || '</Items>'
       || '</eExact>'
       )
       filecontents
from   ( select division
         ,      listagg
                ( '<Item ID="{' || itm.id || '}" code="' || itm.code || '" >'
                  || '<ItemExtraFields>'
                  || '<ExtraField1 description="KOPIE OMSCHRIJVING">'
                  || xmlelement('Description', itm.description)
                  || '</ExtraField1>'
                  || '</Item>'
                , ''
                )
                xml
         from   itemsbulk itm
         group
         by     division
)

Automatisch inlezen XML

De inhoud van de laadtabel kan daarna in Exact Online geïmporteerd worden met de volgende SQL. Deze SQL knipt de XML op in brokken van 25.000 tekens en laadt ze in Exact Online. Dit gaat verbazingwekkend snel; de XML API is nog steeds bij verre het snelste alternatief voor het massaal laden en/of bijwerken van data in Exact Online: niet alleen voor artikelen. Zie voor meer achtergrondinformatie over de prestaties op Exact Online bijvoorbeeld Does Invantive SQL match the speed of Infinite Probability Drive?.

--
-- Load into Exact Online. Errors are logged in UploadXMLTopicFragments.
--
insert into UploadXMLTopics
( topic
, payload
, division_code
, orig_system_reference
, fragment_payload_flag
, fragment_max_size_characters
, fail_on_error
)
select topic
,      filecontents
,      division
,      filename
--
-- Try to split into pieces of 25 KB at most.
--
,      true fragment_payload_flag
,      25000 fragment_max_size_characters 
,      true fail_on_error
from   xmlupload@inmemorystorage
order 
by     division
,      filename

--
-- Check everything was loaded correctly in Exact Online.
-- There may be NO row with success = false.
--
select *
from   UploadXMLTopicFragments

De insert op UploadXMLTopics slaagt altijd. Eventuele fouten kunnen meteen na het laden gecontroleerd worden in UploadXMLTopicFragments. Deze view bevat ook een kolom met alleen de afgewezen mutaties. Na correctie kunnen die hetzij handmatig ingelezen worden via “Import/Export” in de Exact Online web interface hetzij nogmaals aangeboden via UploadXMLTopics.