Hoe functies werken in transformaties, variabelen en aanroepvoorwaarden

U opent ze via het dialoogvenster Edit transformation of assigned value, en overal waar transformaties voorkomen, wordt dezelfde engine gebruikt.

Elke transformatie verloopt in twee fasen, altijd in deze volgorde:

1. De primaire expressie wordt eenmaal geëvalueerd en levert een waarde op.
2. Vervolgens wordt een reeks transformatieacties op die waarde toegepast, de een na de ander.

[data] is de placeholder voor „de waarde die op dat moment wordt bewerkt”. Nadat de expressie is uitgevoerd, bevat [data] het resultaat ervan. Bij elke actie die wordt uitgevoerd, wordt [data] bijgewerkt naar de uitvoer van die actie en doorgegeven aan de volgende actie.

Waarnaar u kunt verwijzen

Binnen een expressie (en binnen de meeste actievelden) kunt u verschillende soorten elementen plakken. De werkbalkknoppen Paste column, Paste variable en Paste value, of het snelmenu via de rechtermuisknop, voegen de juiste notatie voor u in.

Notatie	Verwijst naar
[My field name]	Een bronkolom in DataETL- en File Management-transformaties.
[<my variable>]	Een variabele die u hebt gedefinieerd.
[<#my auto generated variable>]	Een automatisch gegenereerde variabele. Identiek aan een normale variabele; het voorvoegsel # geeft alleen aan dat deze is gegenereerd en niet door u is aangemaakt.
[data]	De huidige waarde: onafhankelijk van het type en bijgewerkt terwijl de reeks acties wordt uitgevoerd.
[original]	De waarde die de primaire expressie retourneert, voordat een transformatieactie deze heeft gewijzigd.

[data] verandert mee met de reeks; [original] verandert nooit meer nadat de expressie is uitgevoerd. Gebruik [original] in een latere actie wanneer u de waarde van vóór de acties weer nodig hebt.

Verwijzen naar kolommen binnen een For Each

Een ForEach-component genereert voor elk van zijn bronkolommen een variabele op het moment dat u de component opslaat. Binnen de ForEach kunt u daarom op twee manieren naar een bronkolom verwijzen:

• Via de gegenereerde variabele: [<#my auto generated variable>]
• Via de bronkolomnotatie: [#source columns]

Beide leveren dezelfde waarde op.

De bestemming bepaalt het type

Het resultaat van een transformatie wordt weggeschreven naar een bestemming waarvan het gegevenstype vastligt op Tekst, DateTime of Number. Uw expressie (en de uiteindelijke waarde na alle acties) moet dat type opleveren. Een Number-bestemming accepteert bijvoorbeeld geen waarde die de engine niet als getal kan lezen.

[data] zelf is onafhankelijk van het type: het bevat gewoon de huidige waarde, wat die ook is. Als u een waarde toewijst aan een bestemmingskolom of een bestemmingsvariabele, staat [data] voor die waarde.

Fase 1: de primaire expressie

In de expressie doen functies hun werk: If(), Pos(), Dec(), Char() en de overige. De volledige lijst, met syntaxis en voorbeelden, vindt u achter de knop Expression documentation. Gebruik Test expression om een expressie uit te proberen met een testwaarde die u voor de placeholder [data] invoert, voordat u deze definitief maakt.

Een expressie kan geen letterlijk dubbel aanhalingsteken (") bevatten. Als u er een moet uitvoeren, maakt u het aan met Char(34): Char() kan het teken " uitvoeren, ook al kunt u het niet rechtstreeks in de expressie typen.

Rechtsklikken: plakken, functies en commentaar

Als u in de expressie-editor met de rechtermuisknop klikt, opent u een snelmenu dat vaak sneller werkt dan de werkbalk:

• Search and replace: zoeken en vervangen binnen de tekst van de expressie zelf.
• Paste [data]: voegt de placeholder [data] in.
• Paste function: een submenu met alle ingebouwde functies, gegroepeerd per categorie: Logical, String, Numeric, Date and Time, File handling, Folder, Other, SQL en SharePoint. Als u er een kiest, wordt het skelet ervan met de argumentnamen in de editor geplaatst, bijvoorbeeld Mid( 'string', start {, length } ) of IndexValue( 'sourcestring', 'delimiterstring', indexnumber ). Argumenten tussen { } zijn optioneel.
• Paste Column… / Paste Variable…: hetzelfde als de werkbalkknoppen.
• Comment / Uncomment: zet commentaartekens op de geselecteerde regel(s) of verwijdert ze, zodat u een deel van een expressie kunt uitschakelen zonder het te verwijderen.
• De standaardopties Kopiëren, Knippen, Plakken en Verwijderen.

Enkele String-functies die u al vroeg nuttig zult vinden: Char(34) voor een dubbel aanhalingsteken, GenerateGUID(), JSONDecode() / JSONEncode(), ExtractMetadataColumn('metadata','column name','default value') en SkipString('My reason') om de waarde over te slaan met een gelogde reden. De volledige lijst per categorie staat in de functiereferentie.

Een SQL SELECT als expressie gebruiken

Vink SQL SELECT 1 row/column aan; de keuzelijst Manage Database Connections wordt dan geopend, waarin u een willekeurige geconfigureerde verbinding kiest (SQL Server, MS Access, ODBC of de interne database). Uw expressie wordt vervolgens één SQL-SELECT die één kolom retourneert:

SELECT dbo.bindtest.col_customer_name FROM dbo.bindtest WHERE mycol = [data]

Het enige SQL-sleutelwoord dat in een expressie wordt ondersteund, is SELECT. Bovendien kan de SQL SELECT alleen in de eerste, primaire expressie worden gebruikt.

Regels voor de SQL SELECT-vorm:

• De instructie moet één kolom retourneren.
• Als er meerdere rijen worden geretourneerd, worden deze samengevoegd met %NewLine% en worden maximaal 250 rijen verwerkt.
• U kunt [data], kolommen en variabelen overal in de instructie als argument gebruiken:

SELECT Max(MyCol) FROM MyTable WHERE abc = [<MyVar>] AND xyz = [data]

Fase 2: transformatieacties

Zodra de expressie een waarde heeft opgeleverd, voegt u acties toe via het menu Add action. Ze worden van boven naar beneden uitgevoerd, waarbij elke actie de uitvoer van de vorige actie als [data] ontvangt. Er zijn er vijf:

Actie	Wat het doet
Data validation	Controleert de waarde en schrijft berichten naar het sessielogboek van de job; kan de reeks stoppen.
Expression	Voert nog een expressie uit op de waarde.
Extract XML/JSON tag	Haalt de waarde(n) van benoemde tags uit een XML-/JSON-string.
Lookup	Koppelt de waarde 1:1 via een Value Mapping List.
Replace occurrences	Zoekt en vervangt binnen de waarde met behulp van een Value Mapping List.

Data validation

Het invoertype is String en de actie moet een String retourneren die met een van deze voorvoegsels begint. Tekst na de dubbele punt wordt naar het sessielogboek van de job geschreven.

Voorvoegsel	Effect
Ok:	Waarde geaccepteerd. Er wordt geen rij aan het sessielogboek toegevoegd.
Warning:	Tekst na de dubbele punt wordt als waarschuwing gelogd.
Error:	Tekst na de dubbele punt wordt als fout gelogd.
Ignore:	Tekst na de dubbele punt wordt gelogd; de waarde wordt genegeerd.
Return:	Stopt de evaluatie van verdere acties.

Zowel [data] als [original] zijn beschikbaar. Voorbeelden:

If( Dec('[data]') > 100.01 , 'Error:[data]>100.01' , 'Ok:' )
If( 'xyz' + [data] = 'xyz1' , 'Ok:' , 'Warning:[data]' )
If( Pos( '[data]' , 'Apple' ) > 0 , 'Ok:[data]' , 'Ignore:' )
If( Pos( '[data]' , 'Apple' ) > 0 , 'Ok:' , 'Return:[data]' )

Expression (actie)

Een tweede expressie, maar met één beperking die de primaire expressie niet heeft: deze moet hetzelfde gegevenstype retourneren als het type dat ze ontving. [data] is de huidige waarde, [original] het resultaat van de primaire expressie.

Extract value from XML/JSON tag

Voer een of meer tagnamen in, gescheiden door puntkomma's, en de actie retourneert de bijbehorende waarde(n). Er zijn twee opties:

• When a tag is found, stop processing remaining actions.
• If tag is not found, then set value to empty string.

Lookup (Map 1:1)

Koppelt de huidige waarde via een Value Mapping List: bij een overeenkomst in de kolom Search value van de lijst wordt de bijbehorende Replacement value geretourneerd. Kies de lijst, of stel er een samen met New mapping list / Edit mapping values.

De instelling If no mapping found bepaalt wat er gebeurt als er geen overeenkomst is:

Optie	Gedrag zonder overeenkomst
<No mapping>	De waarde ongewijzigd laten.
<No mapping - Add to Mapping List>	Ongewijzigd laten en de waarde aan de lijst toevoegen.
<Map to blank>	Vervangen door een lege string.
Map to the value I type here	Vervangen door een vaste waarde die u opgeeft.

Vink When mapped, stop processing remaining actions aan om de reeks te beëindigen na een geslaagde koppeling.

Replace occurrences

Ook deze actie werkt met een Value Mapping List, maar vervangt binnen de waarde in plaats van de hele waarde te koppelen. Twee instellingen bepalen het gedrag:

Replacement scope: welke overeenkomsten worden vervangen:

• All occurrences
• All but first occurrence
• All but last occurrence
• Only first occurrence
• Only last occurrence

Value pairs: welke vervangende waarde wordt gebruikt wanneer meerdere items in de lijst overeenkomen:

• Use all matched replacement values
• Use first matched replacement value only
• Substitute with first matched replacement value
• Substitute with list of matched replacement values

Opties: When replaced, stop processing actions en If no replacement, set the value to empty string.

Value Mapping Lists

Zowel Lookup als Replace occurrences maken gebruik van Value Mapping Lists, die u beheert via Manage mapping lists. Elke lijst bevat rijen Search value → Replacement value met een kolom Order.

U kunt een lijst op drie manieren bijhouden:

• Handmatig: in het venster Edit Value Mapping List (Nieuw, Kopiëren, Verwijderen, Opslaan, Renumber sort order).
• Vanuit Excel: kopieer twee kolommen (Search value en Replacement value) in Excel en gebruik Paste from clipboard/Excel om ze in één keer te laden. Lijsten kunnen ook naar Excel of Kladblok worden geëxporteerd.
• Vanuit een job: DataETL kan rijen van een mappinglijst programmatisch invoegen, bijwerken en verwijderen, zodat een lijst automatisch als onderdeel van een run kan worden opgebouwd of vernieuwd in plaats van alleen handmatig.

Laat DataETL naar de interne database verwijzen om waarden van mappinglijsten programmatisch te bewerken.

Expressies als aanroepvoorwaarden in een Collection

Dezelfde expressie-engine stuurt ook aanroepvoorwaarden binnen een Collection aan. Een Collection groepeert meerdere componenten (Steps) tot één geheel, en een Collection kan andere Collections bevatten. Elke component kan een voorwaarde hebben, ingesteld met Create Condition, die tijdens de uitvoering bepaalt of die component wordt aangeroepen.

Een aanroepvoorwaarde is beperkter dan een transformatie. Deze:

• is één enkele expressie: er is geen reeks transformatieacties en geen placeholder [data];
• kan alleen naar variabelen verwijzen, met de notatie [<MyVariable>]. In deze context zijn er geen bronkolommen, dus Paste Variable is de enige plakknop (naast Test expression en Expression documentation).

De expressie moet een string retourneren, en die string is een besturingssleutelwoord dat de job vertelt wat er met de component moet gebeuren:

Retourwaarde	Effect
True	De component uitvoeren.
False	De component overslaan.
ExitGroup	Deze en de overige componenten in de groep overslaan.
ExitGroupWarning	Hetzelfde als ExitGroup, maar logt een waarschuwing.
StopJob	De job direct stoppen.
StopJobWarning	De job direct stoppen en een waarschuwing loggen.

Net als bij de voorvoegsels van Data validation kunt u na een dubbele punt een bericht toevoegen, dat naar het sessielogboek van de job wordt geschreven:

If( [<MyVariable>] > 0 , 'True' , 'False' )
If( [<MyVariable>] > 0 , 'True' , 'StopJob:Job cannot continue' )