GetConnector Skip/Take, sortering en outputformaat

Dit onderwerp beschrijft extra opties in de aanroep van een GetConnector. Gebruik één van deze methoden:

• GetData

  Eenvoudige aanroep met een filter en het indelen van de records in pakketjes.

• GetDataWithOptions

  Zoals de methode 'GetData', maar met extra mogelijkheden ten aanzien van sortering en outputformaat van de opgehaalde records.

Je kunt het veldtype niet wijzigen, een datumveld blijft dus altijd een datumveld en een bedragveld blijft altijd een bedragveld. Wel kun je bepalen hoe een veld uitgevoerd wordt door de GetConnector, een datum kan bijvoorbeeld getoond worden als 10-12-2022 of als 10 december 2022. Je bepaalt het uitvoerformaat in de gegevensverzameling van de GetConnector.

Aanroep testen met skip/take

Een GetConnector kan veel records opleveren, ondanks het gebruik van filters. Daarom is het aan te raden de records op te halen in pakketjes met de velden 'skip' en 'take'.

Sleutelveld achterhalen:

Bij skip/take is het belangrijk dat je de records bij de aanroep sorteert op het sleutelveld (of de sleutelvelden) van de tabel. Om dit makkelijk te maken, kun je in de Management tool zien wat de sleutelvelden zijn.

1. Ga naar: Algemeen / Beheer / Management tool.
2. Open de juiste tabel.
3. Voeg het veld Sleutelveld zelf toe aan de weergave. De aangevinkte velden zijn sleutelvelden.

Aanroep met Skip/take uitvoeren:

1. Start https://connect.afas.nl en log in.
2. Ga naar: SOAP/XML / GetConnectoren.
3. Login met een token.
   • Selecteer AFAS Online en vul je deelnemersnummer in.

     Let op:

     Het deelnemernummer is het numerieke gedeelte in de naam van de omgeving. Als de omgevingsnaam bijvoorbeeld O12345AA is, dan is 12345 het deelnemersnummer.

     Ter informatie: de beginletter is het type omgeving. O = productie, T=Test, A=Accept. Zie ook Omgeving kopiëren.

   • Vul de Token in.

     

4. Selecteer de GetConnector.
   • skip: het aantal records dat moet worden overgeslagen.
   • take: het aantal records dat moet worden opgehaald.

   Je moet voor elk op te halen pakketje een aparte aanroep doen, tot je een pakketje terugkrijgt dat geen records meer bevat.

   Let op:

   Gebruik altijd een sortering bij het uitvoeren van een opdracht met skip/take. Sorteer bij voorkeur op een sleutelveld, zoals factuurnummer of medewerkercode, of een combinatie van velden.

   Voorbeeld: je wilt data ophalen in pakketjes van 10 records.

   Aanroep 1: skip = 0, take = 10. Record 1 t/m 10 ophalen.

   Voorbeeldcode:

   <Options>

   <Skip>0</Skip>

   <Take>10</Take>

   </Options>

   Aanroep 2: skip = 10, take = 10. Record 11 t/m 20 ophalen.

   Aanroep 3: skip = 20, take = 10. Record record 21 t/m 30 ophalen.

   Etc.

   

   Let op:

   Het gebruik van 'skip' en 'take' is verplicht. Als je alle records in één keer wilt ophalen, vul je de waarde -1 in bij zowel 'skip' als 'take'. Dit neemt wel risico's met zich mee, want hierdoor kan het aantal records erg groot worden.

   Let op: maximale omvang van de take

   ls het aantal regels dat wordt opgehaald te groot is, kan er een "Out of Stringspace" of een "Out of memory" foutmelding ontstaan. Om dat te voorkomen, zorg je ervoor dat de Take niet te groot is. Wij adviseren deze deze regel: [Aantal kolommen] x [Aantal regels] < 150.000. Oftewel: kies de Take zo, dat het aantal velden in je GetConnector keer de Take niet groter is dan 150.000. Dit is nu een advies, geen voorschrift. Wel verzoeken we je om je requests na te lopen en waar nodig aan te passen, omdat in de toekomst een limiet aan de maximale omvang van een Get-request ingebouwd zal worden in onze software. Zodra bekend is op welke termijn dit gebeurt, zullen we dit uitgebreid communiceren naar onze klanten.

Extra mogelijkheden met GetDataWithOptions

Deze methode biedt de volgende extra mogelijkheden:

• Het resultaat wordt teruggegeven als XML of tekst.
• Metadata kan worden teruggegeven.
• Indeling van de gegevens die worden teruggegeven.
• Op te halen records opdelen in pakketjes, dit komt de performance ten goede.
• Sortering van de records.

De basiswerking is hetzelfde als de hierboven beschreven methode 'GetData'. In het veld 'GetDataWithOptions' kun je echter een XML-string met de hieronder vermelde opties meegeven.

Voorbeelden:

• Uitvoer in XML, zonder metadata

  <Options><Outputmode>1</Outputmode><Metadata>0</Metadata></Options>

• Uitvoer in XML, met metadata

  <Options><Outputmode>1</Outputmode><Metadata>1</Metadata></Options>

• Uitvoer in CSV-formaat

  <Options><Outputmode>2</Outputmode></Options>

• Uitvoer in XML, zonder metadata, records opdelen in pakketjes, records sorteren

  <Options><Outputmode>1</Outputmode><Metadata>0</Metadata><Skip>0</Skip><Take>5</Take><Index><Field FieldId="saldo" OperatorType="0"/></Index></Options>

  Let op: 

  Je kunt de velden 'skip / take' op twee manieren aanbieden:

  1. Als aparte velden, zie de methode 'GetData'.

  2. Als onderdeel van de hier beschreven <Options> string.

  De velden 'skip / take' in de <Options> string hebben voorrang op de aparte velden. Als je bijvoorbeeld Take 2 gebruikt in het veld 'Take' en Take 5 in de <Options> string, dan zal Take 5 worden toegepast.

options (diverse instellingen)

• Outputmode: 1=xml, 2=text
• Metadata: 0=False, 1=True.
• Outputoptions: De mogelijkheden zijn afhankelijk van je keuze voor XML of Text. De veldnaam 'Outputoptions' is hoofdlettergevoelig.

Het gebruik van de Outputoptions hangt af van de Outputmode.

Outputoptions bij XML (Outputmode 1)

2 = Microsoft DataSet

3 = Microsoft DataSet. Lege elementen (elementen zonder waarde) worden ook meegenomen in de XML.

Outputoptions bij Tekst met scheidingstekens (Outputmode 2)

1 = Puntkomma (datums en getallen in formaat van regionale instellingen)

2 = Tab (datums en getallen in formaat van regionale instellingen)

3 = Puntkomma (dd-mm-yy voor datums en punt als decimaal scheidingteken voor getallen)

4 = Tab (dd-mm-yy voor datums en punt als decimaal scheidingteken voor getallen)

index (sortering)

Je sorteert records op een veld naar keuze (het sorteren is niet verplicht). Als je deze optie gebruikt, is het gebruik van de velden ‘skip / take’ verplicht.

Neem het veld op waarop je wilt sorteren, en geef met de parameter ‘OperatorType’ aan hoe je wilt sorteren.

• OperatorType 0 = Aflopend sorteren (van hoog naar laag)
• OperatorType 1 = Oplopend sorteren (van laag naar hoog)

In het onderstaande voorbeeld haal je de eerste 10 records op en sorteer je deze aflopend op het veld ‘DebtorId’ en daarbinnen oplopend op het veld 'Date'.

<Options>

<Skip>0</Skip>

<Take>10</Take>

<Index>

<Field FieldId="DebtorId" OperatorType="0"/>

<Field FieldId="Date" OperatorType="1"/>

</Index>

</Options>

Opvragen in AFAS Connect:

1. Klik op Enable extra options en vul de gegevens in.

   

SOAP-aanroep (GetData)

Xml-voorbeeld-bestand downloaden

• token

  Token van de gebruiker die de connector uitvoert. Je moet een CDATA-tag gebruiken bij de token, zie het te downloaden XML-voorbeeld.

Specifiek voor deze connector:

• ConnectorId: Naam van de GetConnector.
• filtersXml: Filter in de vorm van XML-code.

SOAP-aanroep (GetDataWithOptions)

Xml-voorbeeld-bestand downloaden

• token

  Token van de gebruiker die de connector uitvoert. Je moet een CDATA-tag gebruiken bij de token, zie het te downloaden XML-voorbeeld.

• ConnectorId: Naam van de GetConnector.
• filtersXml: Filter in de vorm van XML-code.

Specifiek voor deze connector:

• options
• Skip / Take
• Index