Wiki source code of XSLT Extension Gateway

Last modified by Erik Bakker on 2023/08/15 14:08
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on the XSLT extension gateway.
3 The XSLT extension gateway is a component in eMagiz that helps you to enrich your output XML message by retrieving data from an outside source.
4
5 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6
7 == 1. Prerequisites ==
8
9 * Advanced knowledge of the eMagiz platform
10 * Advanced knowledge of XSLT
11
12 == 2. Key concepts ==
13
14 This microlearning centers around the XSLT extension gateway component in eMagiz
15 By XSLT extension gateway we mean: A component within eMagiz that gives you the option to retrieve additional data while executing the transformation from an outside source
16
17 Via the XSLT extension gateway you can retrieve data from multiple sources (REST Webservice, SOAP Webservice, Database, etc.) as long as the outside source can supply a response in near real-time.
18
19 == 3. XSLT Extension Gateway ==
20
21 An XSLT Extension Gateway is a component within eMagiz that gives you the option to retrieve additional data while executing the transformation from an outside source.
22 Via the XSLT extension gateway you can retrieve data from multiple sources (REST Webservice, SOAP Webservice, Database, etc.) as long as the outside source can supply a response in near real-time.
23 This response is in turn used to enrich your output message with the correct information.
24
25 === 3.1 Setting up the XSLT Extension Gateway ===
26
27 The first step of setting up an XSLT Extension Gateway is to add the XSLT Extension Gateway component to your flow and create two channels (one for the request and one for the response).
28 You can do so by dragging the correct component on the canvas, creating the channels and linking the channels to the XSLT Extension Gateway.
29 An example of how this will look is shown below:
30
31 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--xslt-extension-gateway-added-to-canvas.png]]
32
33 === 3.2 Connect to the outside source ===
34
35 As stated before, via the XSLT extension gateway you can retrieve data from multiple sources (REST Webservice, SOAP Webservice, Database, etc.) as long as the outside source can supply a response in near real-time.
36 In this example we will assume that you want to retrieve a Token from a REST Webservice that you need as part of your authorization when executing subsequent calls.
37
38 In this case we will have to call a certain endpoint via a POST method. In the body of our message we need to send the username and password that we have received from the outside source.
39 This outside source expects the body in XML.
40
41 To make this a reality in eMagiz we first need to add an HTTP Outbound Gateway to the canvas and fill in the details.
42
43 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--http-outbound-gateway-xslt-extension.png]]
44
45 This automatically links the XSLT extension gateway to the HTTP oubound gateway, provided you selected the correct request and response channel.
46
47 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--http-outbound-gateway-xslt-extension-result.png]]
48
49 === 3.3 Error handling ===
50
51 It could happen that something goes wrong while retrieving the relevant data from the outside will using the XSLT Extension Gateway.
52 To ensure that the error handling does its work you need to link the XSLT Extension Gateway to the default error handling of eMagiz.
53
54 You can easily do so by opening the XSLT Extension Gateway component, navigating to the Advanced tab, selecting the correct Error channel and setting the Reply timeout.
55
56 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--xslt-extension-gateway-error-channel.png]]
57
58 The result of this action will be that the XSLT extension will send his errors to the standard error handling process of eMagiz.
59
60 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--xslt-extension-gateway-error-channel-result.png]]
61
62 === 3.4 Write the XSLT ===
63
64 To succesfully call an XSLT extension gateway your custom XSLT needs five things:
65
66 * A parameter that defines which component the XSLT extension gateway is within the flow
67 * A variable that calls the XSLT extension gateway and will hold the result
68 * A variable that defines what the input for your XSLT extension gateway will be
69 * A template match that copies your input
70 * A template match that ensures that the result of your XSLT extension gateway is correctly outputted
71
72 An example of such an XSLT is depicted below. Within the XSLT we have described which part is responsible for what exactly.
73
74 {{code}}
75 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
76 xmlns:ezx="http://www.emagiz.com/ns/xml/1.0/"
77 version="2.0">
78 <xsl:param name="Username"/>
79 <xsl:param name="Password"/>
80 <!-* This segment will house the parameter that will identify which component to call within the flow -->
81 <xsl:param name="ExtGateway"/>
82 <!-* This segment will house the variable that will identify when you want to call the extension gateway, what the input of the extension gateway should be and what you want as a result -->
83 <xsl:variable name="Token" select="if (exists(//ID) and //ID != '') then ezx:call-xslt-extension-gateway($ExtGateway, $RetrieveToken) else ''"/>
84
85 <!-* This segment will copy the incoming message to the output -->
86
87 <xsl:template match="@* | node()">
88 <xsl:copy>
89 <xsl:apply-templates select="@* | node()"/>
90 </xsl:copy>
91 </xsl:template>
92
93 <!-* This segment will ensure that the Token will be filled in correctly -->
94
95 <xsl:template match="Token">
96 <Token>
97 <xsl:value-of select="$Token"/>
98 </Token>
99 </xsl:template>
100 <!-* The variable defined below will be the input to retrieve the token from the outside source -->
101 <xsl:variable name="RetrieveToken">
102 <xsl:if test="exists(//ID) and //ID != ''">
103 <root>
104 <username><xsl:value-of select="$Username"/></username>
105 <password><xsl:value-of select="$Password"/></password>
106 </root>
107 </xsl:if>
108 </xsl:variable>
109 </xsl:stylesheet>
110 {{/code}}
111
112 Now that we have an example of a custom XSLT that we can use we now need to make sure that this XSLT will work within the context of our flow.
113
114 === 3.5 Connect XSLT to flow ===
115
116 The first step we need to take is to link the resource to the flow. To do so you navigate to the tab Resources on flow level, while in "Start Editing" mode.
117 In this tab you have the option to Upload new resource
118
119 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--upload-new-resource.png]]
120
121 When you select this option you can upload your custom XSLT. Ensure that you select the correct resource type and give the resource a good descriptive name
122
123 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--upload-new-resource-filled-in.png]]
124
125 Now that we have added the resource to the flow we can return to the flow overview and add a XSLT transformer component to the canvas and fill in the details
126
127 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--xslt-transformer-basic.png]]
128
129 When you are finished with the basic config you can move to the Advanced section. In this section we need to define the values for our parameter(s).
130 The end result will look something like this:
131
132 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-xslt-extension-gateway--xslt-transformer-advanced.png]]
133
134 As you can see the ExtGateway parameter refers to the ID of the XSLT extension gateway component within our flow.
135 Now that we have set our XSLT transformer component up correctly the we have automatically linked the XSLT Transformer to the XSLT extension gateway.
136
137 With these steps you can successfully use the XSLT extension gateway component in eMagiz. Based on your use case the details of the configuration can differ.
138
139 == 4. Key takeaways ==
140
141 * An XSLT Extension Gateway is a component within eMagiz that gives you the option to retrieve additional data while executing the transformation from an outside source.
142 * Via the XSLT extension gateway you can retrieve data from multiple sources (REST Webservice, SOAP Webservice, Database, etc.) as long as the outside source can supply a response in near real-time.
143 * This response is in turn used to enrich your output message with the correct information.
144 * Setting up an XSLT extension gateway means several components need to work in perfect unison
145 * Don't forget about the error handling
146
147 == 5. Suggested Additional Readings ==
148
149 If you are interested in this topic and want more information on it please read the release notes provided by eMagiz that accompany the components you have selected.
150 )))((({{toc/}}))){{/container}}{{/container}}