diff --git a/nifi-extension-bundles/nifi-standard-bundle/nifi-standard-processors/src/main/resources/docs/org.apache.nifi.processors.standard.TransformXml/additionalDetails.md b/nifi-extension-bundles/nifi-standard-bundle/nifi-standard-processors/src/main/resources/docs/org.apache.nifi.processors.standard.TransformXml/additionalDetails.md new file mode 100644 index 000000000000..b289e0dd31eb --- /dev/null +++ b/nifi-extension-bundles/nifi-standard-bundle/nifi-standard-processors/src/main/resources/docs/org.apache.nifi.processors.standard.TransformXml/additionalDetails.md @@ -0,0 +1,199 @@ + + +# TransformXml + +## XSLT Transform with Parameters + +XSLT parameters are placeholders within an XSLT stylesheet that allow external values +to be passed into the transformation process at runtime. +Parameters are accessible within a stylesheet as normal variables, using the ```$name``` syntax, +provided they are declared using a top-level ```xsl:param``` element. +If there is no such declaration, the supplied parameter value is silently ignored. + +### XSLT with Parameter Defined +Consider the following XML +```xml + + + Some data + +``` +and XSLT stylesheet +```xml + + + + + + + Value Selected: + + + + +``` +If the following parameter name ```customParam``` and parameter value ```From NIFI``` pair are added +as a dynamic property, then the output would be +```xml + + + + Value Selected: From NIFI + +``` +Note the value of the ```customParam``` parameter became ```From NIFI``` even though +the declared ```xsl:param``` element had a default value of ```From XSLT```. + +### XSLT without Parameter Defined +If the XSLT stylesheet does not have a top-level ```xsl:param``` element declared +```xml + + + + + + Value Selected: + + + + +``` +even if the following parameter name ```customParam``` and parameter value ```From NIFI``` pair +are added as a dynamic property, they are ignored and the output would be +```xml + + + + Value Selected: + + +``` +In a case where the parameter is not declared in a ```xsl:param``` element, but attempted to be used in an XSLT stylesheet, +```xml + + + + + + Value Selected: + + + + +``` +even if the following parameter name ```customParam``` and parameter value ```From NIFI``` pair are added as a dynamic property, +the transform will fail with an error message containing text ```Variable $customParam has not been declared```. + +### XSLT Parameter Defined with Required Type +Starting in XSLT 2.0, an ```as``` attribute was added to parameters allowing for +specifying the type of parameter. The following are some of the more common types supported and what +valid values to use for each: + +| Type Name | Type Value | +|:------------------|:-------------------------------------------------------------------------------------------------------------------------| +| ```xs:string``` | Any string value. | + | ```xs:boolean``` | A lowercase value of true or false. | +| ```xs:integer``` | A signed integer value. | +| ```xs:float``` | A 32-bit IEEE single-precision floating-point. | +| ```xs:double``` | A 64-bit IEEE single-precision floating-point. | +| ```xs:date``` | A date in ISO 8601 format YYYY-MM-DD | +| ```xs:dateTime``` | A date time in ISO 8601 format: YYYY-MM-DDThh:mm:ss with optional uses of Z to represent UTC or an offset (e.g. -05:00). | +| ```xs:time``` | A time in format HH:mm:ss or HH:mm:ss.SSS with optional uses of Z to represent UTC or an offset (e.g. -05:00). | +| ```xs:anyURI``` | A valid URI. | + + +The following XSLT stylesheet demonstrates the use of specifying types in an XSLT +and populating their values with dynamic properties. + +Consider the following XSLT stylesheet +```xml + + + + + + + + + + + + + + + Param of type xs:string value is + Param of type xs:integer value is + Param of type xs:float value is + Param of type xs:double value is + Param of type xs:boolean value is + Param of type xs:date value is + Param of type xs:dateTime value is + Param of type xs:time value is + Param of type xs:time UTC value is + Param of type xs:time offset value is + Param of type xs:anyURI + + + +``` +and the use of the XML from before + +```xml + + + Some data + +``` + +If the following parameter name and parameter value pairs are added as dynamic properties + +| Parameter Name | Parameter Value | +|:----------------|:----------------------| +| stringParam | From NIFI | +| integerParam | 100 | +| floatParam | 123.456 | +| doubleParam | 12.78e-2 | +| booleanParam | true | +| dateParam | 2026-01-01 | +| dateTimeParam | 2026-01-01T00:00:00 | +| timeParam | 12:34:56.789 | +| utcTimeParam | 12:34:56Z | +| offsetTimeParam | 12:34:56-05:00 | +| uriParam | http://from-nifi.com | + + +then the resulting XML will be +```xml + + + Param of type xs:string value is From NIFI + Param of type xs:integer value is 100 + Param of type xs:float value is 123.456 + Param of type xs:double value is 0.1278 + Param of type xs:boolean value is true + Param of type xs:date value is 2026-01-01 + Param of type xs:dateTime value is 2026-01-01T00:00:00 + Param of type xs:time value is 12:34:56.789 + Param of type xs:time UTC value is 12:34:56Z + Param of type xs:time offset value is 12:34:56-05:00 + Param of type xs:anyURI http://from-nifi.com + +``` +Please note the "static" attribute added to the ```xsl:param``` element in 3.0 +does not work with the dynamic properties in NIFI because as implied, static means +a parameter value must be known at compile time of the XSLT while the dynamic +properties are supplied at run time of the actual transform. \ No newline at end of file