Zum Inhalt springen

XML-Funktionen in Jitterbit Studio

XML-Funktionen werden typischerweise in Transformationsmapping-Skripten verwendet, die die Manipulation und den Zugriff auf XML-Daten erfordern.

Attribute

Deklaration

type Attribute(string attributeName, string attributeValue)

Syntax

Attribute(<attributeName>, <attributeValue>)

Erforderliche Parameter

  • attributeName: Attributname
  • attributeValue: Attributwert

Beschreibung

Erstellt ein Attribut für einen XML-Knoten. Siehe auch die Funktion CreateNode.

Beispiele

// Fügt ein Attribut "name" mit einem Wert von "value" hinzu
Attribute("name","value");

CreateNode

Deklaration

string CreateNode(string namespace, string nodeName, type attributeSubelement[,...])

Syntax

CreateNode(<namespace>, <nodeName>, <attributeSubelement>[,...])

Erforderliche Parameter

  • namespace: Der Namensraum des Knotens
  • nodeName: Name des Knotens
  • attributeSubelement: Ein Unterelement: ein Wert, Attribut oder Unterknoten

Optionale Parameter

  • attributeSubelement: Zusätzliche Unterelemente (ein Wert, Attribut oder Unterknoten), wie erforderlich

Beschreibung

Erstellt eine Zeichenfolge, die einen XML-Knoten darstellt. Wenn der Zielknoten der Wertknoten eines XML Any-Knotens ist, wird ein XML-Element erstellt, das dem nodeName und nodeValue entspricht.

Ab dem dritten Argument kann eine Reihe von Werten, Attributen und Unterknoten angegeben werden. Werte werden direkt angegeben. Attribute und Unterknoten können jeweils mit den Funktionen Attribute und CreateNode erstellt werden.

Beispiele

// Creates a node with a sub-node
CreateNode("http://example.com/xml",
    "Contact", "Bill  G.", Attribute("Type", "VIP"),
    CreateNode("http://example.com/xml",
        "Title", "Manager")
    );

GetNodeName

Deklaration

string GetNodeName(type path)

Syntax

GetNodeName(<path>)

Erforderliche Parameter

  • path: Ein String-Verweis-Pfad-Ausdruck, der einen einzelnen Knoten in der aktuellen Transformation oder rohen XML auswählt

Beschreibung

Ruft den Namen eines Knotens ab. Diese Methode wird typischerweise verwendet, um den Namen eines Knotens abzurufen, der von einer der Funktionen SelectNodeFromXMLAny oder SelectSingleNode zurückgegeben wird.

Um einen Pfad zu einem Knoten in die Funktion für den Parameter path einzugeben, ziehen Sie den gewünschten XML-Knotenordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle des Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Beispiele

// Ruft den Namen eines Knotens ab
GetNodeName(SelectNodeFromXMLAny("Account", Root$Any.));

GetNodeValue

Deklaration

string GetNodeValue(type path)

Syntax

GetNodeValue(<path>)

Erforderliche Parameter

  • path: Ein String-Verweis-Pfad-Ausdruck, der einen einzelnen Knoten in der aktuellen Transformation oder rohen XML auswählt

Beschreibung

Ruft den Wert eines Knotens ab. Diese Methode wird typischerweise verwendet, um den Wert eines Knotens abzurufen, der von einer der Funktionen SelectNodeFromXMLAny oder SelectSingleNode zurückgegeben wird.

Um einen Pfad zu einem Knoten in die Funktion für den Parameter path einzugeben, ziehen Sie den gewünschten XML-Knotenordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle des Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Beispiele

Beispiel 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve the name of the second child:

exampleArray = GetNodeValue(SelectNodes(xmlInput, "/root/father/child[position() = 2]/name"));
result = exampleArray[0];
// Equals "Jordan Coleman"
Beispiel 2
// Ruft den Wert eines Knotens ab
GetNodeValue(SelectNodeFromXMLAny("Account", Root$Any.));

GetXMLString

Deklaration

string GetXMLString(type path[, bool qualified])

Syntax

GetXMLString(<path>[, <qualified>])

Erforderliche Parameter

  • path: Ein String-Verweis-Pfad-Ausdruck, der einen einzelnen Knoten in der aktuellen Transformation auswählt. Der definierte Pfad muss für einen Knoten sein; spezifische Felder und Attribute werden bei der Pfadbewertung ignoriert.

Optionale Parameter

  • qualified: Ein boolescher Wert (Standard false); wenn qualifiziert (true), ist der zurückgegebene XML-String leichter zu lesen, könnte aber für sich genommen ungültiges XML sein.

Beschreibung

Gibt (wenn in einer Transformationszuordnung verwendet) den entsprechenden XML-String zurück, der im Quell-XML-Dokument am angegebenen Pfad gefunden wurde.

Um einen Pfad zu einem Knoten in die Funktion für den Parameter path einzugeben, ziehen Sie den gewünschten XML-Knotenordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle Ihres Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Hinweis

Der definierte Pfad muss für einen Knoten sein; spezifische Felder und Attribute werden bei der Pfadbewertung ignoriert.

Beispiele

// Ruft den entsprechenden XML-String am angegebenen Pfad ab
GetXMLString([Header$DETAIL.]);
// Ruft den entsprechenden XML-String am angegebenen Pfad ab
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);

IsNil

Deklaration

bool IsNil(string path)

Syntax

IsNil(<path>)

Erforderliche Parameter

  • path: Ein String-Verweis-Pfad-Ausdruck, der einen einzelnen Knoten in der aktuellen Transformation auswählt

Beschreibung

Gibt (wenn in einer Formel-Builder-Zuordnung verwendet) zurück, ob der entsprechende XML-Knoten das Attribut "xsi:nil" mit dem Wert true (oder 1) hat.

Um einen Pfad zu einem Knoten in die Funktion für den path-Parameter einzugeben, ziehen Sie den gewünschten XML-Knoten-Ordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle Ihres Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Wie in XML-Schema beschrieben, kann ein Element ohne Inhalt gültig sein, wenn es das Attribut xsi:nil mit dem Wert true hat.

Beispiele

// Gibt zurück, ob der Knoten nil ist
IsNil("Header$DETAIL.");

RunXSLT

Deklaration

array RunXSLT(string xslt, string xml1[, string xml2,... string xmlN)

Syntax

RunXSLT(<xslt>, <xml1>[, <xml2>,... <xmlN>])

Erforderliche Parameter

  • xslt: Ein String-Verweis-Pfad zu einer Aktivität, die mit einem Dateityp-Endpunkt im aktuellen Projekt verbunden ist und ein XSLT-Stylesheet zurückgibt
  • xml1...xmlN: Ein String-Verweis-Pfad zu einer Aktivität, die mit einem Dateityp-Endpunkt im aktuellen Projekt verbunden ist und ein oder mehrere XML-Dokumente zurückgibt

Beschreibung

Unterstützt das Ausführen von XSLT (v1-3) auf einer Reihe von Eingabe-XML-Dokumenten. Nimmt ein XSLT-Stylesheet und ein oder mehrere XML-Dokumente als Eingabe und gibt ein Array von XML-Dokumenten zurück.

Der xslt-Parameter, der in diesem Funktionsaufruf verwendet wird, muss als Aktivität definiert sein, die mit einem Dateityp-Endpunkt im aktuellen Projekt verknüpft ist und ein XSLT-Stylesheet zurückgibt. Die xml1...xmlN-Parameter, die in diesem Funktionsaufruf verwendet werden, müssen als eine oder mehrere Aktivitäten definiert sein, die mit Dateityp-Endpunkten im aktuellen Projekt verknüpft sind und ein oder mehrere XML-Dokumente zurückgeben. Dazu gehören konfigurierte File Share-, FTP-, HTTP-, Local Storage- und Temporary Storage-Aktivitäten. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Endpunkten.

Wenn Ihre XSLT-Stylesheets Instanzen von eingebettetem, geschachteltem JSON enthalten, die erhalten bleiben müssen, setzen Sie die jitterbit.transformation.ignore_default_value Variable vor dieser Funktion auf true. Diese Variable wird unterstützt, wenn 11.36-Agenten und höher verwendet werden.

Verweisen auf Dateien aus einem XSLT-Stylesheet

Während Jitterbit eine breite Unterstützung für XSLT bietet, müssen Projekte, die XSLT verwenden, Regeln befolgen, um die Sicherheitsstandards einzuhalten. Diese Regeln bedeuten, dass der Zugriff auf Dateien oder URIs immer über die Verwendung von Aktivitäten erfolgen muss, die im selben Projekt definiert sind.

Um auf diese Dateien oder URIs in einem Stylesheet zu verweisen, verwenden Sie die XLST-Funktion fn:doc und geben Sie 'param1' für die erste XML-Eingabe, 'param2' für die zweite XML-Eingabe und so weiter für jede zusätzliche XML-Datei an.

Angenommen, Sie verarbeiten drei XML-Dateien (customers, salesPeople, salesOrders), könnten Sie in einem XSLT-Stylesheet wie folgt auf sie verweisen:

<xsl:for-each select="doc('param1')/*:Customers/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">
...
<xsl:for-each select="doc('param2')/*:SalesPeople/*:Account[*:customer_id/string(number(text()))=$CustomerExtId][1]">
...
<xsl:for-each select="doc('param3')/*:SalesOrders/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">

Wenn Sie eine einzelne Eingabe-XML-Datei haben, ist es nicht erforderlich, die doc('param1')-Syntax zu verwenden, da Jitterbit den ursprünglichen Kontext auf diese einzelne Datei setzt.

Festlegen einer Startvorlage im Stylesheet

In einigen Situationen muss Jitterbit wissen, wo im Stylesheet mit der Verarbeitung begonnen werden soll. Dies wird erreicht, indem im Stylesheet eine Vorlage mit dem spezifischen Namen start_here enthalten ist:

<xsl:template name="start_here" match="/">

Beispiele

// Running XSLT on XML Files

// Read in a stylesheet
xslt = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XSLT</TAG>");

// Read in two XML files for processing
xml1 = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XML1</TAG>");
xml2 = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XML2</TAG>");

// RunXSLT on the stylesheet and the two XML files
output = RunXSLT(xslt, xml1, xml2);

// As RunXSLT() returns an array,
// retrieve the output from each element
i = 0;
While(i < Length(output),
  // Write output to a file
  WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/XML Output FTP</TAG>",
    output[i], "output" + (i+1) + ".xml");
  i++;
);

SelectNodeFromXMLAny

Deklaration

type SelectNodeFromXMLAny(string nodeName, type anyNodes)

Syntax

SelectNodeFromXMLAny(<nodeName>, <anyNodes>)

Erforderliche Parameter

  • nodeName: Der gewünschte Knotenname
  • anyNodes: Der Daten-Element-Pfad eines Wertknotens eines XML Any-Elements, ein String-Referenzpfad-Ausdruck zu einem Array von XML-Knoten in der aktuellen Transformation oder rohes XML

Beschreibung

Gibt den ersten XML-Knoten aus einer Liste von XML Any-Knoten zurück, die mit dem Knotennamen übereinstimmen.

Um einen Pfad zu einem Array von XML-Knoten in die Funktion für den Parameter anyNodes einzugeben, ziehen Sie den gewünschten XML-Knoten-Ordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle Ihres Cursors einzufügen, oder geben Sie seinen Referenzpfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Beispiele

// Sucht nach dem ersten Knoten, der "Account" entspricht
SelectNodeFromXMLAny("Account", Root$Any#.);

SelectNodes

Deklaration

array SelectNodes(type node, string xPathQuery[, string xPathArg1,... string xPathArgN])

Syntax

SelectNodes(<node>, <xPathQuery>[, <xPathArg1>,... <xPathArgN>])

Erforderliche Parameter

  • node: Ein String-Verweis-Pfad-Ausdruck zum gewünschten Knoten in der aktuellen Transformation, ein XML-Fragment, auf dem die Abfrage ausgeführt wird, oder rohes XML
  • xPathQuery: Der Daten-Element-Pfad eines Wertknotens eines XML Any-Elements

Optionale Parameter

  • xPathArg1...xPathArgN: Präfixe, die die Namensräume der Knoten in der XPath-Abfrage angeben

Beschreibung

Führt eine XPath-Abfrage (siehe den XPath-Standard, v1-v3) auf einem XML-Fragment oder einem XML-Knoten aus, der von einer anderen Funktion zurückgegeben wird, und gibt die Ergebnisse der Abfrage zurück.

Wenn die optionalen Präfixe verwendet werden, um die Namensräume des Knotens in der XPath-Abfrage anzugeben, müssen die Präfixe als ein oder mehrere String-Argumente nach dem XPath angegeben werden (siehe das zweite Beispiel).

Um einen Pfad zu einem Knoten in die Funktion für den node-Parameter einzugeben, ziehen Sie den gewünschten XML-Knoten-Ordner aus dem Source Objects-Tab der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle des Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Um HTML-Zeichen zu unterstützen, setzen Sie jitterbit.decode.html.chars auf true vor dieser Funktion. Diese Variable wird mit String-Daten unterstützt, wenn 10.49-Agenten und später verwendet werden.

Beispiele

Beispiel 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve all the XML nodes that match the XPath query:

SelectNodes(xmlInput, "/root/father/child");
// Returns {"<child> <name>John Smith</name> <age>20</age> </child>","<child> <name>Jordan Coleman</name> <age>32</age> </child>","<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}

// Retrieve a range of nodes using a position argument with the XPath query:

SelectNodes(xmlInput, "/root/father/child[position() > 2 and position() <= 4]");
// Returns {"<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}
Beispiel 2
// XML definition with root namespace
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<ns0:root xmlns:ns0="urn:ean.ucc:align:2">
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</ns0:root>';

// Retrieve all the XML nodes that match the XPath query with a namespace considered:

SelectNodes(xmlInput, "/ns0:root/father/child", "ns0=urn:ean.ucc:align:2");
// Returns {"<child> <name>John Smith</name> <age>20</age> </child>","<child> <name>Jordan Coleman</name> <age>32</age> </child>","<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}
Beispiel 3
// Connects to an LDAP server, runs a search,
// and then runs an XPath query on the results
LDAPConnect("directory.company.example.com","ghvwright","1LikesPe@ches",0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
    "(&(objectCategory=person)(objectClass=user))", 1,
    "name", "whenCreated", "description", "telephoneNumber");
resultNodes = SelectNodes(searchResults,
    "/DirectoryResults/Entry[name='Administrator']/whenCreated" );
Beispiel 4
SelectNodes(Root$Any$,
    "ns1:E2/ns2:E3",
    "ns1=http://xyz1.example.com/",
    "ns2=http://xyz2.example.com/");

Hinweis

In diesem zweiten Beispiel ist der Referenzknoten ein XML-Knoten für einen XML Any-Knoten. In der XPath-Abfrage ist ns1:E2 nicht der Referenzknoten selbst.

Da die Präfixe ns1 und ns2 in der XPath-Abfrage verwendet werden, werden sie als zusätzliche Argumente nach der XPath definiert.

SelectNodesFromXMLAny

Deklaration

array SelectNodesFromXMLAny(string xPathQuery, type anyNodes[, string xPathArg1,... string xPathArgN])

Syntax

SelectNodesFromXMLAny(<xPathQuery>, <anyNodes>[, <xPathArg1>,... <xPathArgN>])

Erforderliche Parameter

  • xPathQuery: Eine XPath-Abfrage
  • anyNodes: Der Daten-Element-Pfad eines Wertknotens eines XML Any-Elements, ein String-Referenzpfad-Ausdruck zu einem Array von XML-Knoten in der aktuellen Transformation oder rohes XML

Optionale Parameter

  • xPathArg1...xPathArgN: Präfixe, die die Namensräume der Knoten in der XPath-Abfrage angeben

Beschreibung

Gibt ein Array aller XML-Knoten zurück, die von einer XPath-Abfrage übereinstimmen (siehe den XPath-Standard, v1-v3), die entweder gegen einen Pfad eines Wertknotens eines XML Any-Elements oder ein Array von XML-Knoten ausgeführt wird.

Wenn die optionalen Präfixe verwendet werden, um die Namensräume des Knotens in der XPath-Abfrage anzugeben, müssen die Präfixe als ein oder mehrere String-Argumente nach der XPath angegeben werden (siehe das zweite Beispiel).

Um einen Pfad zu einem Array von XML-Knoten in die Funktion für den Parameter anyNodes einzugeben, ziehen Sie den gewünschten XML-Knoten-Ordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle des Cursors einzufügen, oder geben Sie seinen Referenzpfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Beispiele

Beispiel 1
// Wählen Sie alle Knoten mit den angegebenen Namen aus
SelectNodesFromXMLAny("Account|Customer|Name", Root$Any#.);
Beispiel 2
// Wählen Sie nur Email-Adressen und Telefonnummern aus
$nodes = SelectNodesFromXMLAny("cust:EmailAddress|cust:PhoneNumber",
    Customer$Any#., "cust=urn:xmlns:25hoursaday-com:customer");

SelectSingleNode

Deklaration

type SelectSingleNode(type node, string xPath,...)

Syntax

SelectSingleNode(<node>, <xPath>,...)

Erforderliche Parameter

  • node: Ein String-Verweis-Pfad-Ausdruck zum gewünschten Knoten in der aktuellen Transformation, ein XML-Fragment, auf dem die Abfrage ausgeführt wird, oder rohes XML

  • xPathQuery: Der Daten-Element-Pfad eines Wertknotens eines XML Any-Elements

Optionale Parameter

  • xPathArg1...xPathArgN: Präfixe, die die Namensräume der Knoten in der XPath-Abfrage angeben

Beschreibung

Führt eine XPath-Abfrage (siehe den XPath-Standard, v1-v3) auf einem XML-Fragment oder einem XML-Knoten aus, der von einer anderen Funktion zurückgegeben wird, und gibt den ersten Knoten in den Ergebnissen der Abfrage zurück.

Wenn die optionalen Präfixe verwendet werden, um die Namensräume des Knotens in der XPath-Abfrage anzugeben, müssen die Präfixe als ein oder mehrere String-Argumente nach dem XPath angegeben werden (siehe das zweite Beispiel).

Um einen Pfad zu einem Knoten in die Funktion für den node-Parameter einzugeben, ziehen Sie den gewünschten XML-Knoten-Ordner aus dem Tab Quellobjekte der Skriptkomponenten-Palette in das Skript, um seinen qualifizierten Pfad an der Stelle Ihres Cursors einzufügen, oder geben Sie seinen Verweis-Pfad manuell ein. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Quellobjekten.

Um HTML-Zeichen zu unterstützen, setzen Sie jitterbit.decode.html.chars auf true vor dieser Funktion. Diese Variable wird mit String-Daten unterstützt, wenn 10.49-Agenten und später verwendet werden.

Beispiele

Beispiel 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve the first matching node given an XPath query:

SelectSingleNode(xmlInput, "/root/father/child");
// Returns <child> <name>John Smith</name> <age>20</age> </child>
Beispiel 2
// Connects to an LDAP server, runs a search,
// runs an XPath query on the results, and
// selects the first node in the query results
LDAPConnect("directory.company.example.com", "ghvwright", "1LikesPe@ches", 0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
    "(&(objectCategory=person)(objectClass=user))", 1, "name",
    "whenCreated", "description", "telephoneNumber");
resultNode = SelectSingleNode(searchResults,
    "/DirectoryResults/Entry[name='Administrator']/whenCreated");
Beispiel 3
// Selects the first node in an XPath query result.
// The reference node is an XML node for an XML Any node.
// In the XPath query, "ns1:E2" is not the reference node itself.
// Since the prefixes ns1 and ns2 are used in the XPath query,
// they are defined as additional arguments after the XPath.
SelectSingleNode(Root$Any$,
    "ns1:E2/ns2:E3",
    "ns1=http://xyz1.example.com",
    "ns2=http://xyz2.example.com/");