Wiki source code of Default eMagiz XSLT Functions

Last modified by Eva Torken on 2023/08/10 12:10
Show last authors
1
2 {{container}}
3 {{container layoutStyle="columns"}}
4 (((
5
6 In this microlearning, we will explain some standard eMagiz XSLT Functions that the platform offers you can use when transforming messages.
7
8 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
9
10 == 1. Prerequisites ==
11
12 * Basic knowledge of the eMagiz platform
13
14 == 2. Key concepts ==
15
16 This microlearning discusses the standard eMagiz XSLT Functions that the platform offers.
17
18 Some of these XSLT Functions are:
19
20 * remove-timezone-from-dateTime
21 * adjust-timezone-to-dateTime
22 * call-xslt-extension-gateway
23
24 Apart from that, multiple other XSLT Functions will be described.
25
26 == 3. eMagiz XSLT Functions ==
27
28 In addition to the standard XPath/XSLT functions (see [[W3Schools>>https://www.w3schools.com/xml/xpath_intro.asp||target="blank"]]), eMagiz also supports the functions that are listed below. These extension functions are located in following namespaces:
29
30 * {{code}}http://www.emagiz.com/ns/mapping/1.0/{{/code}} for the mapping functions (prefixed with `mapping` in this document)
31 * {{code}}http://www.emagiz.com/ns/xml/1.0/{{/code}} for generic eMagiz extension functions (prefixed with `ezx` in this document)
32
33 === 3.1 lookup-cdm-code ===
34
35 {{code}}string mapping:lookup-cdm-code(string system, string codeType, string systemCode, boolean mustExist){{/code}}
36
37 Looks up the CDM code for the given system code. If caching is enabled, the CDM code will be returned from the cache if possible, otherwise it will be added to the cache after performing the lookup so subsequent calls can use this cached value.
38
39 ==== Parameters ====
40
41 * **system** identifier of the system to do the lookup for (not null or empty, max length 64)
42 * **codeType** type of code to do the lookup for (not null or empty, max length 64)
43 * **systemCode** system code to do the lookup for (not null or empty, max length 64)
44 * **mustExist** if true, a `MappingException` is thrown when the resulting CDM code would be null or empty
45
46 ==== Returns ====
47
48 The requested CDM code (if _mustExist_ is false, the value might be null or empty, indicating no code element was present in the mapping service response or the code element was present but didn't have a value)
49
50 === 3.2 lookup-system-code ===
51
52 {{code}}string mapping:lookup-system-code(string system, string codeType, string cdmCode, boolean mustExist){{/code}}
53
54 Looks up the system code for the given CDM code. If caching is enabled, the system code will be returned from the cache if possible, otherwise it will be added to the cache after performing the lookup so subsequent calls can use this cached value.
55
56 ==== Parameters ====
57
58 * **system** identifier of the system to do the lookup for (not null or empty, max length 64)
59 * **codeType** type of code to do the lookup for (not null or empty, max length 64)
60 * **cdmCode** CDM code to do the lookup for (not null or empty, max length 64)
61 * **mustExist** if true, a `MappingException` is thrown when the resulting system code would be null or empty
62
63 ==== Returns ====
64
65 the requested system code (if _mustExist_ is false, the value might be null or empty, indicating no code element was present in the mapping service response or the code element was present but didn't have a value)
66
67 === 3.3 lookup-custom-attribute ===
68
69 {{code}}string mapping:lookup-custom-attribute(string codeType, string cdmCode, string customAttribute, boolean mustExist){{/code}}
70
71 Looks up the value for the specified custom attribute of the given CDM code. If caching is enabled, the custom attribute value will be returned from the cache if possible, otherwise it will be added to the cache after performing the lookup so subsequent calls can use this cached value.
72
73 ==== Parameters ====
74
75 * **codeType** type of code to do the lookup for (not null or empty, max length 64)
76 * **cdmCode** CDM code to do the lookup for (not null or empty, max length 64)
77 * **customAttribute** custom attribute to do the lookup for (not null or empty, max length 64)
78 * **mustExist** if true, a `MappingException` is thrown when the resulting custom attribute value would be null or empty
79
80 ==== Returns ====
81
82 the value of the requested custom attribute (if _mustExist_ is false, the value might be null or empty, indicating no value element was present in the mapping service response or the value element was present but didn't have a value)
83
84 === 3.4 format-dateTime ===
85
86 {{code}}
87 string ezx:format-dateTime(dateTime dateTime, string pattern)
88
89 string ezx:format-dateTime(dateTime dateTime, string pattern, string timeZone)
90 {{/code}}
91
92 Formats a given date/time as a string using the specified pattern.
93
94 ==== Parameters ====
95
96 * **dateTime** the date/time to format
97 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for formatting the date/time
98 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when formatting the output; if not specified the time zone of the input date/time is used (which, when unspecified, defaults to UTC if the input is an instance of xs:dateTime or the JVM local time zone otherwise)
99
100 ==== Returns ====
101
102 The formatted date/time as a string value.
103
104 ==== Example ====
105
106 {{code}}ezx:format-dateTime('2014-01-01T04:45:30.000+01:00', 'E MMM dd yyyy h:mma Z'){{/code}}
107
108 **Result** {{code}}Wed Jan 01 2014 4:45AM +0100{{/code}}
109
110 ==== Example ====
111
112 {{code}}ezx:format-dateTime('2014-01-01T04:45:30.000+01:00', 'E MMM dd yyyy h:mma Z', 'America/New_York'){{/code}}
113
114 **Result** {{code}}Tue Dec 31 2013 10:45PM -0500{{/code}}
115
116 === 3.5 format-date ===
117
118 {{code}}
119 string ezx:format-date(date date, string pattern)
120
121 string ezx:format-date(date date, string pattern, string timeZone)
122 {{/code}}
123
124 Formats a given date as a string using the specified pattern.
125
126 ==== Parameters ====
127
128 * **date** the date to format
129 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for formatting the date
130 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when formatting the output; if not specified the time zone of the input date is used (which, when unspecified, defaults to UTC if the input is an instance of xs:date or the JVM local time zone otherwise)
131
132 ==== Returns ====
133
134 The formatted date as a string value.
135
136 ==== Example ====
137
138 {{code}}ezx:format-date('2014-01-01+01:00', 'E MMM dd yyyy Z'){{/code}}
139
140 **Result** {{code}}Wed Jan 01 2014 +0100{{/code}}
141
142 ==== Example ====
143
144 {{code}}ezx:format-date('2014-01-01+01:00', 'E MMM dd yyyy Z', 'America/New_York'){{/code}}
145
146 **Result** {{code}}Tue Dec 31 2013 -0500{{/code}}
147
148 === 3.6 format-time ===
149
150 {{code}}
151 string ezx:format-time(time time, string pattern)
152
153 string ezx:format-time(time time, string pattern, string timeZone)
154 {{/code}}
155
156 Formats a given time as a string using the specified pattern.
157
158 ==== Parameters ====
159
160 * **time** the time to format
161 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for formatting the time
162 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when formatting the output; if not specified the time zone of the input time is used (which, when unspecified, defaults to UTC if the input is an instance of xs:time or the JVM local time zone otherwise)
163
164 ==== Returns ====
165
166 The formatted time as a string value.
167
168 ==== Example ====
169
170 {{code}}ezx:format-time('04:45:30.000+01:00', 'h:mma Z'){{/code}}
171
172 **Result** {{code}}4:45AM +0100{{/code}}
173
174 ==== Example: ====
175
176 {{code}}ezx:format-time('04:45:30.000+01:00', 'h:mma Z', 'America/New_York'){{/code}}
177
178 **Result** {{code}}10:45PM -0500{{/code}}
179
180 === 3.7 parse-dateTime ===
181
182 {{code}}
183 dateTime ezx:parse-dateTime(string stringValue, string pattern)
184
185 dateTime ezx:parse-dateTime(string stringValue, string pattern, string timeZone)
186 {{/code}}
187
188 Parses a given string value into a date/time using the specified pattern.
189
190 ==== Parameters ====
191
192 * **stringValue** the string value to parse into a date/time
193 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for parsing the string value into a date/time
194 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when parsing the input, completely ignoring any time zone information in the string value; if not specified the time zone information in the string value is used (which, when not present, defaults to the JVM local time zone)
195
196 ==== Returns ====
197
198 The parsed date/time as a dateTime value.
199
200 ==== Example ====
201
202 {{code}}ezx:parse-dateTime('Wed Jan 01 2014 4:45AM +0100', 'E MMM dd yyyy h:mma Z'){{/code}}
203
204 **Result** {{code}}2014-01-01T04:45:00+01:00{{/code}}
205
206 ==== Example ====
207
208 {{code}}ezx:parse-dateTime('Wed Jan 01 2014 4:45AM +0100', 'E MMM dd yyyy h:mma Z', 'America/New_York'){{/code}}
209
210 **Result** {{code}}2014-01-01T04:45:00-05:00{{/code}}
211
212 === 3.8 parse-date ===
213
214 {{code}}
215 date ezx:parse-date(string stringValue, string pattern)
216
217 date ezx:parse-date(string stringValue, string pattern, string timeZone)
218 {{/code}}
219
220 Parses a given string value into a date using the specified pattern.
221
222 ==== Parameters ====
223
224 * **stringValue** the string value to parse into a date
225 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for parsing the string value into a date
226 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when parsing the input, completely ignoring any time zone information in the string value; if not specified the time zone information in the string value is used (which, when not present, defaults to the JVM local time zone)
227
228 ==== Returns ====
229
230 The parsed date as a date value.
231
232 ==== Example ====
233
234 {{code}}ezx:parse-date('Wed Jan 01 2014 +0100', 'E MMM dd yyyy Z'){{/code}}
235
236 **Result** {{code}}2014-01-01+01:00{{/code}}
237
238 ==== Example: ====
239
240 {{code}}ezx:parse-date('Wed Jan 01 2014 +0100', 'E MMM dd yyyy Z', 'America/New_York'){{/code}}
241
242 **Result** {{code}}2014-01-01-05:00{{/code}}
243
244 === 3.9 parse-time ===
245
246 {{code}}
247 time ezx:parse-time(string stringValue, string pattern)
248
249 time ezx:parse-time(string stringValue, string pattern, string timeZone)
250 {{/code}}
251
252 Parses a given string value into a time using the specified pattern.
253
254 ==== Parameters ====
255
256 * **stringValue** the string value to parse into a time
257 * **pattern** the pattern (a string following the [DateTimeFormat pattern syntax]) to use for parsing the string value into a time
258 * **timeZone** [Optional] the time zone (a string as accepted by [DateTimeZone.forID(String)]) to use when parsing the input, completely ignoring any time zone information in the string value; if not specified the time zone information in the string value is used (which, when not present, defaults to the JVM local time zone)
259
260 ==== Returns ====
261
262 The parsed time as a time value.
263
264 ==== Example ====
265
266 {{code}}ezx:parse-time('4:45AM +0100', 'h:mma Z'){{/code}}
267
268 **Result** {{code}}04:45:00+01:00{{/code}}
269
270 ==== Example ====
271
272 {{code}}ezx:parse-time('4:45AM +0100', 'h:mma Z', 'America/New_York'){{/code}}
273
274 **Result** {{code}}04:45:00-05:00{{/code}}
275
276 === 3.10 remove-timezone-from-dateTime ===
277
278 {{code}}
279 dateTime ezx:remove-timezone-from-dateTime(dateTime dateTime)
280 {{/code}}
281
282 Removes all timezone information from the given date/time without changing its value.
283
284 ==== Parameters ====
285
286 * **dateTime** the date/time to remove the timezone information from
287
288 ==== Returns ====
289
290 The date/time without any timezone information as a dateTime value.
291
292 ==== Example ====
293
294 {{code}}ezx:remove-timezone-from-dateTime('2014-01-01T04:45:30.000+01:00'){{/code}}
295
296 **Result** {{code}}2014-01-01T04:45:30{{/code}}
297
298 === 3.11 remove-timezone-from-date ===
299
300 {{code}}
301 date ezx:remove-timezone-from-date(date date)
302 {{/code}}
303
304 Removes all timezone information from the given date without changing its value.
305
306 ==== Parameters ====
307
308 * **date** the date to remove the timezone information from
309
310 ==== Returns ====
311
312 The date without any timezone information as a date value.
313
314 ==== Example ====
315
316 {{code}}ezx:remove-timezone-from-date('2014-01-01+01:00'){{/code}}
317
318 **Result** {{code}}2014-01-01{{/code}}
319
320 === 3.12 remove-timezone-from-time ===
321
322 {{code}}
323 time ezx:remove-timezone-from-time(time time)
324 {{/code}}
325
326 Removes all timezone information from the given time without changing its value.
327
328 ==== Parameters ====
329
330 * **time** the time to remove the timezone information from
331
332 ==== Returns ====
333
334 The time without any timezone information as a time value.
335
336 ==== Example ====
337
338 {{code}}ezx:remove-timezone-from-time('04:45:30.000+01:00'){{/code}}
339
340 **Result** {{code}}04:45:30{{/code}}
341
342 === 3.13 adjust-dateTime-to-timezone ===
343
344 {{code}}dateTime ezx:adjust-dateTime-to-timezone(dateTime dateTime, string timeZone){{/code}}
345
346 Adjusts the given date/time to the specified timezone (respecting the original timezone).
347
348 ==== Parameters ====
349
350 * **dateTime** the date/time to adjust to a timezone; when the timezone of this date/time is unspecified, it defaults to UTC if the input is an instance of xs:dateTime or the JVM local time zone otherwise
351 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to adjust the date/time to
352
353 ==== Returns ====
354
355 The adjusted date/time as a dateTime value.
356
357 ==== Example ====
358
359 {{code}}ezx:adjust-dateTime-to-timezone('2014-01-01T04:45:30.000+01:00', 'America/New_York'){{/code}}
360
361 **Result** {{code}}2013-12-31T22:45:30-05:00{{/code}}
362
363 === 3.14 adjust-date-to-timezone ===
364
365 {{code}}date ezx:adjust-date-to-timezone(date date, string timeZone){{/code}}
366
367 Adjusts the given date to the specified timezone (respecting the original timezone).
368
369 ==== Parameters ====
370
371 * **date** the date to adjust to a timezone; when the timezone of this date is unspecified, it defaults to UTC if the input is an instance of xs:date or the JVM local time zone otherwise
372 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to adjust the date to
373
374 ==== Returns ====
375
376 The adjusted date as a date value.
377
378 ==== Example ====
379
380 {{code}}ezx:adjust-date-to-timezone('2014-01-01+01:00', 'America/New_York'){{/code}}
381
382 **Result** {{code}}2013-12-31-05:00{{/code}}
383
384 === 3.15 adjust-time-to-timezone ===
385
386 {{code}}time ezx:adjust-time-to-timezone(time time, string timeZone){{/code}}
387
388 Adjusts the given time to the specified timezone (respecting the original timezone).
389
390 ==== Parameters ====
391
392 * **time** the time to adjust to a timezone; when the timezone of this time is unspecified, it defaults to UTC if the input is an instance of xs:time or the JVM local time zone otherwise
393 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to adjust the time to
394
395 ==== Returns ====
396
397 The adjusted time as a time value.
398
399 ==== Example ====
400
401 {{code}}ezx:adjust-time-to-timezone('04:45:30.000+01:00', 'America/New_York'){{/code}}
402
403 **Result** {{code}}22:45:30-05:00{{/code}}
404
405 === 3.16 override-timezone-of-dateTime ===
406
407 {{code}}dateTime ezx:override-timezone-of-dateTime(dateTime dateTime, string timeZone){{/code}}
408
409 Overrides the timezone of the given date/time with the specified timezone (ignoring the original timezone).
410
411 ==== Parameters ====
412
413 * **dateTime** the date/time to override the timezone of; whether this date/time specifies a timezone or not is irrelevant, as it will be overridden anyway
414 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to override the date/time with
415
416 ==== Returns ====
417
418 The date/time with the new timezone as a dateTime value.
419
420 ==== Example ====
421
422 {{code}}ezx:override-timezone-of-dateTime('2014-01-01T04:45:30.000+01:00', 'America/New_York'){{/code}}
423
424 **Result** {{code}}2014-01-01T04:45:30-05:00{{/code}}
425
426 === 3.17 override-timezone-of-date ===
427
428 {{code}}date ezx:override-timezone-of-date(date date, string timeZone){{/code}}
429
430 Overrides the timezone of the given date with the specified timezone (ignoring the original timezone).
431
432 ==== Parameters ====
433
434 * **date** the date to override the timezone of; whether this date specifies a timezone or not is irrelevant, as it will be overridden anyway
435 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to override the date with
436
437 ==== Returns ====
438
439 The date with the new timezone as a date value.
440
441 ==== Example ====
442
443 {{code}}ezx:override-timezone-of-date('2014-01-01+01:00', 'America/New_York'){{/code}}
444
445 **Result** {{code}}2014-01-01-05:00{{/code}}
446
447 === 3.18 override-timezone-of-time ===
448
449 {{code}}time ezx:override-timezone-of-time(time time, string timeZone){{/code}}
450
451 Overrides the timezone of the given time with the specified timezone (ignoring the original timezone).
452
453 ==== Parameters ====
454
455 * **time** the time to override the timezone of; whether this time specifies a timezone or not is irrelevant, as it will be overridden anyway
456 * **timeZone** the time zone (a string as accepted by [DateTimeZone.forID(String)]) to override the time with
457
458 ==== Returns ====
459
460 The time with the new timezone as a time value.
461
462 ==== Example ====
463
464 {{code}}ezx:override-timezone-of-time('04:45:30.000+01:00', 'America/New_York'){{/code}}
465
466 **Result** {{code}}04:45:30-05:00{{/code}}
467
468 === 3.19 call-xslt-extension-gateway ===
469
470 {{code}}node ezx:call-xslt-extension-gateway(gateway gateway, node request){{/code}}
471
472 Calls the given XSLT extension gateway and returns the response XML message.
473
474 ==== Parameters ====
475
476 * **gateway** the XSLT extension gateway to call (should be passed to the stylesheet as an `<xsl:param/>` value)
477 * **request** the request message (a single XML node) to send to the gateway; this XML node will be serialized into a string value before sending it to the gateway
478
479 ==== Returns ====
480
481 The response message (a single XML node) received from the gateway; the gateway's string response will be parsed as an XML document before it is returned.
482
483 ==== Example ====
484
485 {{code}}ezx:call-xslt-extension-gateway($gateway, //Customer[1]){{/code}}
486
487 **Result** {{code}}<CustomerDetails>...</CustomerDetails>{{/code}}
488
489 == 4. Key takeaways ==
490
491 Some of these XSLT Functions are:
492
493 * remove-timezone-from-dateTime
494 * adjust-timezone-to-dateTime
495 * call-xslt-extension-gateway
496
497 Apart from that, multiple other XSLT Functions will be described.
498
499 == 5. Suggested Additional Readings ==
500
501 If you are interested in this topic and want more information on it please read the following links:
502
503 * [[XSL Functions>>https://www.w3schools.com/xml/xsl_functions.asp||target="blank"]]
504 * [[DateTime format syntax>>http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html||target="blank"]]
505 * [[DateTimeZone For ID>>http://joda-time.sourceforge.net/apidocs/org/joda/time/DateTimeZone.html#forID(java.lang.String)||target="blank"]]
506
507 )))
508
509 ((({{toc/}}))){{/container}}
510 {{/container}}