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