Wiki source code of Module SOAP
Last modified by Aurelie Bertrand on 2025/02/07 10:18
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
30.1 | 1 | SOAP module - Documentation |
| |
1.1 | 2 | |
| |
30.1 | 3 | Retreiving a data source via a SOAP web service |
| |
1.1 | 4 | |
| |
2.1 | 5 | |
| |
30.1 | 6 | **Summary :** |
| |
1.1 | 7 | |
| |
30.1 | 8 | {{toc/}} |
| |
1.1 | 9 | |
| |
30.1 | 10 | = Prerequisite = |
| |
1.1 | 11 | |
| |
30.1 | 12 | * Acronyms in this document are defined in the lexicon at the end. |
| 13 | * Make sure the folder **<digdash_installation>/add-ons/soap** is provided in your DigDash installation. It contains the web application needed to make SOAP calls from DigDash. The installation procedure is described in this document. | ||
| 14 | * Make sure you have all the needed WSDL files describing all the services to call | ||
| 15 | * Make sure you know at least the SOAP requests structure (in XML), the methods to call as well. A documentation of the Service Provider (that DigDash does not provide) may be necessary. | ||
| 16 | * Make sure you know the different data formats that you will need to mention. A documentation of the Service Provider (that DigDash does not provide) may be necessary. | ||
| 17 | |||
| 18 | |[[image:soap_en_html_c801e156356d3a0a.png||queryString="width=50&height=50" height="50" width="50"]] | ||
| 19 | |((( | ||
| 20 | DigDash offers a helper to preview a SOAP request. | ||
| 21 | |||
| 22 | Go to | ||
| 23 | |||
| 24 | **<digdash_server>/ddsoap?about=true** | ||
| 25 | |||
| 26 | to have information about your SOAP configuration. | ||
| |
1.1 | 27 | ))) |
| 28 | |||
| 29 | = Description = | ||
| 30 | |||
| |
30.1 | 31 | == General == |
| |
1.1 | 32 | |
| |
30.1 | 33 | DigDash Enterprise offers the possibility to retrieve data sources calling SOAP web services. |
| |
1.1 | 34 | |
| |
30.1 | 35 | SOAP communication is possible via the XML format. The point is to get the SOAP reponses in XML format and to use them directly as a data source as DigDash already knows how to proceed this format. |
| |
1.1 | 36 | |
| |
30.1 | 37 | To do so, DigDash will mainly work with the web services’ interfaces, known as WSDL files that you must provide. Indeed, these files provide a description of what the web service to call offers, in detail. |
| |
1.1 | 38 | |
| |
30.1 | 39 | This add-on is based on the SOAP UI API (SOAP UI is a well known SOAP client). The way you call the web service will be kind of the same way SOAP UI does it. Namely you will have to fill in the values of the SOAP request parameters. |
| |
1.1 | 40 | |
| |
30.1 | 41 | Hence the importance of knowing the SOAP request structure in XML as said in the prerequisite. |
| |
1.1 | 42 | |
| |
30.1 | 43 | == Technical description == |
| |
1.1 | 44 | |
| |
30.1 | 45 | DigDash Enterprise offers this functionality as a module (or add-on) to install (it is not natively installed). We will use the existing principle of WLNK (**W**eb **L**i**nk**) files in DigDash to host the information needed to retrieve a data source via SOAP. |
| |
1.1 | 46 | |
| |
18.1 | 47 | (% class="box infomessage" %) |
| 48 | ((( | ||
| |
30.1 | 49 | A WLNK (**W**eb **L**i**nk**) file in DigDash contains a URL. The content of this URL is downloaded by the DigDash server every time is needed (for a data source or on the user demand). |
| |
1.1 | 50 | |
| |
30.1 | 51 | //Why create a WLNK file?// |
| |
1.1 | 52 | |
| |
30.1 | 53 | We could create a simple XML file as a data source but this one would be just a snapshot of the data. The WLNK file allows you to refresh the data every time when needed. |
| 54 | Be careful, a WLNK file only contains the information for **one and only one SOAP request**. | ||
| 55 | ⇒ **1 WLNK file = 1 SOAP request** | ||
| 56 | ))) | ||
| |
1.1 | 57 | |
| |
30.1 | 58 | DigDash will never connect to the web service endpoint directly. Indeed, DigDash will call a web application instead (deployable on the same DigDash Tomcat server) developed by DigDash. The add-on mainly consists of this web application. |
| |
1.1 | 59 | |
| |
30.1 | 60 | The goal of this web application is to reach the web service with the information you will have provided. It eventually will return the SOAP response to DigDash in XML. |
| |
1.1 | 61 | |
| 62 | |||
| |
30.1 | 63 | [[image:soap_en_html_5e3e099e5561dd5e.png||queryString="width=667&height=423" height="423" width="667"]] |
| 64 | |||
| |
1.1 | 65 | |
| |
30.1 | 66 | __Schema : Description of SOAP calls from DigDash__ |
| |
1.1 | 67 | |
| |
30.1 | 68 | = Installation and configuration of the SOAP module = |
| |
1.1 | 69 | |
| |
30.1 | 70 | == Installation and deployment of the web application == |
| |
1.1 | 71 | |
| |
30.1 | 72 | First of all, stop the Tomcat server. |
| |
1.1 | 73 | |
| |
30.1 | 74 | Copy the web application **ddsoap.war** located in **<digdash_installation>/add-ons/soap **to **<digdash_install>/apache-tomcat/webapps.** |
| |
1.1 | 75 | |
| |
30.1 | 76 | Restart the DigDash server to deploy the web application. |
| |
1.1 | 77 | |
| |
30.1 | 78 | == wsdls folder == |
| |
1.1 | 79 | |
| |
30.1 | 80 | Place in the folder : « **<digdash_installation>/add-ons/ddsoap/wsdls » **the list of the WSDL files (.wsdl) describing the web services you want to call. |
| |
1.1 | 81 | |
| |
30.1 | 82 | == soap_props.properties configuration == |
| |
1.1 | 83 | |
| |
30.1 | 84 | Configure the **ddsoap/soap_props.properties **file with the following properties: |
| 85 | |||
| 86 | === Miscellaneous properties === | ||
| 87 | |||
| 88 | |Propriétés|Description | ||
| 89 | |PRINT_DEBUG|((( | ||
| 90 | This property must be set to ‘true’ to display any traces. Only error traces are always displayed. | ||
| 91 | |||
| 92 | This property allows to display debug traces in logs. | ||
| |
1.1 | 93 | ))) |
| |
30.1 | 94 | |SHOW_REQUESTS|Allows to display the SOAP requests (in XML) sent to the Web Service. |
| 95 | |SHOW_RESPONSES|Allows to display the SOAP responses (in XML) sent by the Web Service. | ||
| 96 | |LOGIN_BEFORE_CALL_SERVICE|Allows authentication before any SOAP call. Credentials properties must start with _creds (see next point). | ||
| 97 | |REMOVE_REQUEST_EMPTY_VALUES|Removes empty values (identified by « ? ») of the SOAP request. | ||
| 98 | |REMOVE_REQUEST_EMPTY_NODES|Removes empty nodes of the SOAP request. | ||
| |
1.1 | 99 | |
| |
30.1 | 100 | __Table : Miscellaneous properties for the SOAP module configuration__ |
| |
1.1 | 101 | |
| |
30.1 | 102 | === Credentials properties === |
| |
1.1 | 103 | |
| |
30.1 | 104 | Authentication may be necessary before any SOAP calls. |
| |
1.1 | 105 | |
| |
30.1 | 106 | **__ALL__ these properties __MUST__ start with « creds_ » __AND__ the property LOGIN_BEFORE_CALL_SERVICE must be set to ‘true’ ** |
| |
1.1 | 107 | |
| |
30.1 | 108 | |Properties|Description |
| 109 | |(% colspan="2" %)**Caution **: You must escape special characters in keys (property name) if needed (use \= for = , use \: for | ||
| 110 | |**creds_**binding|(Mandatory) The name of the authentication service. | ||
| 111 | |**creds_**operation|(Mandatory) The name of the authentication method. | ||
| 112 | |**creds_**<username>|The possible login name for authentication. | ||
| 113 | |**creds_**<password>|The possible password for authentication. | ||
| 114 | |**creds_**<any other parameter>|The possible other authentication parameters. | ||
| |
1.1 | 115 | |
| |
30.1 | 116 | __Table : Properties used for authentication for the SOAP module__ |
| |
1.1 | 117 | |
| 118 | |||
| |
30.1 | 119 | = Configuration in DigDash Enterprise = |
| |
1.1 | 120 | |
| |
30.1 | 121 | == Creation of a WLNK file == |
| |
1.1 | 122 | |
| |
30.1 | 123 | Let’s start with extracting data from an XML file. |
| |
1.1 | 124 | |
| |
30.1 | 125 | Data source > Add > Any file… |
| |
1.1 | 126 | |
| |
30.1 | 127 | Select the documents server to use |
| |
1.1 | 128 | |
| |
30.1 | 129 | Add a new document to the server clicking the « Add a file to the server... » button. |
| |
1.1 | 130 | |
| |
30.1 | 131 | Three options are available. To get the content via SOAP, we are going to select the second option « Enter a URL ». |
| |
1.1 | 132 | |
| |
30.1 | 133 | → The URL to call is the URL of the web application, **ddsoap** previously deployed (basically **<digdash_server>/ddsoap**). |
| 134 | |||
| 135 | → The name of your WLNK file must end with **.xml** | ||
| 136 | |||
| 137 | → Check the option « Only add the URL link to the Documents server ». This option will create the WLNK file. | ||
| 138 | |||
| 139 | → It is possible to customize the request timeout (in seconds) for a WLNK (only values > 0 will be taken into accout, the default request timeout will be applied otherwise). | ||
| 140 | |||
| 141 | [[image:soap_en_html_ce75b9c82fc22c3.png||queryString="width=450&height=415" height="415" width="450"]] | ||
| 142 | \\ | ||
| 143 | |||
| 144 | __Screenshot: creation of the WLNK file__ | ||
| 145 | |||
| 146 | You can enter the SOAP parameters as key-value in the GET parameters. | ||
| 147 | |||
| 148 | **You IMPERATIVELY must at least mention these two parameters:** | ||
| 149 | |||
| 150 | **_binding** : the name of the Service to call | ||
| 151 | **_operation** : the name of the operation (or method) of the Service to call | ||
| 152 | |||
| 153 | [[image:soap_en_html_1da100bad7bbced9.png||queryString="width=335&height=336" height="336" width="335"]] | ||
| 154 | \\ | ||
| 155 | |||
| 156 | __Screenshot: SOAP parameters__ | ||
| 157 | |||
| 158 | For the other parameters, you will need to mention their name (do not forget the namespace). If the name appears more than once in the request, you will need to specify its parents to access this specific node. | ||
| 159 | |||
| 160 | In general, the first node in the request with the specified name will be selected unless the path to a specific node is specified (without needing to start from the root node). | ||
| 161 | |||
| 162 | |||
| 163 | |||
| 164 | |Separators|Description|Example | ||
| 165 | |/|Path separator in the XML.|((( | ||
| |
1.1 | 166 | <a> |
| 167 | |||
| 168 | <a1> | ||
| 169 | |||
| 170 | <b>?</b> | ||
| 171 | |||
| 172 | **<c>?</c>** | ||
| 173 | |||
| 174 | </a1> | ||
| 175 | |||
| 176 | <b>?</b> | ||
| 177 | |||
| 178 | **<c>?</c>** | ||
| 179 | |||
| 180 | </a> | ||
| 181 | |||
| 182 | <a1> | ||
| 183 | |||
| 184 | <b>?</b> | ||
| 185 | |||
| 186 | <c>?</c> | ||
| 187 | |||
| 188 | </a1> | ||
| 189 | |||
| |
30.1 | 190 | **To access the element c, we will specify a/c (specifying c will select the first element c)** |
| |
1.1 | 191 | ))) |
| |
30.1 | 192 | |@|To access an element attribute.|((( |
| |
1.1 | 193 | <a> |
| 194 | |||
| 195 | <b>?</b> | ||
| 196 | |||
| |
30.1 | 197 | <c** attr=?**>?</c> |
| |
1.1 | 198 | |
| |
30.1 | 199 | </a> |
| |
1.1 | 200 | |
| |
30.1 | 201 | **To access the attribute attr of the element c, we will specify a/c@attr (or c@attr directly)** |
| |
1.1 | 202 | ))) |
| 203 | |||
| |
30.1 | 204 | __Table:Naming rules to access a specific node__ |
| |
1.1 | 205 | |
| |
30.1 | 206 | Once the SOAP parameters are entered, click on « OK » and the WLNK file will be created and uploaded to the selected documents server. |
| |
1.1 | 207 | |
| |
30.1 | 208 | This WLNK file can now be loaded as a classical XML data source file. |
| 209 | |||
| 210 | |||
| |
8.1 | 211 | (% class="box infomessage" %) |
| 212 | ((( | ||
| |
30.1 | 213 | The created WLNK file can be modified later if needed. Right click on your WLNK file and open the menu "Configure the WLNK file" to edit the link and the request parameters. |
| 214 | \\[[image:1617957700408-612.png]] | ||
| 215 | \\[[image:1617957937570-960.png]] | ||
| |
8.1 | 216 | ))) |
| 217 | |||
| |
30.1 | 218 | == Pagination management == |
| |
1.1 | 219 | |
| |
30.1 | 220 | The SOAP module can help you gather and get all data in DigDash from a request with pagination. |
| |
1.1 | 221 | |
| |
30.1 | 222 | You **must** provide the following GET parameters to your URL : |
| |
1.1 | 223 | |
| |
30.1 | 224 | **_pagination** : this parameter must be set to true to specify pagination is required. |
| |
1.1 | 225 | |
| |
30.1 | 226 | **_pageTag** : the value must be the name tag of the element or attribute that drives the pagination (see table : //Naming rules to access a specific node //to define this parameter). |
| |
1.1 | 227 | |
| |
30.1 | 228 | **_pageStartElement** : you must provide the name of the structure containing the lines we are interested in (see next part). If you do not know the SOAP response structure, you might have to send a first request first without pagination to know this tag name (see table : //Naming rules to access a specific node //to define this parameter). |
| |
1.1 | 229 | |
| |
30.1 | 230 | **_pageInc** : the index of the page starts with 0. this parameter must define the incrementation of this index. |
| |
1.1 | 231 | |
| |
30.1 | 232 | _//resultSize// (optional) : specifying the result size can optimize the response time. |
| |
1.1 | 233 | |
| |
30.1 | 234 | //IV.3Configuration of the XML data source// |
| |
1.1 | 235 | |
| |
30.1 | 236 | When loading the XML response into DigDash, the data source may be difficult to read at first glance. |
| |
1.1 | 237 | |
| |
30.1 | 238 | Indeed, you need to mention where the data source must start the lecture in the XML structure. This is possible in the advanced options of the data source. |
| |
1.1 | 239 | |
| |
30.1 | 240 | For example : let’s consider the following SOAP response in XML : |
| |
1.1 | 241 | |
| |
9.1 | 242 | {{code language="XML" cssClass="notranslate"}} |
| |
1.1 | 243 | <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> |
| |
30.1 | 244 | |
| |
1.1 | 245 | <soapenv:Body> |
| 246 | |||
| 247 | <a></a> | ||
| 248 | |||
| 249 | <structs> | ||
| 250 | |||
| |
30.1 | 251 | <struct1> |
| 252 | |||
| 253 | <s11></s11> | ||
| 254 | |||
| 255 | <s12> | ||
| 256 | |||
| 257 | <s121></s121> | ||
| 258 | |||
| 259 | </s12> | ||
| 260 | |||
| 261 | <s13></s13> | ||
| 262 | |||
| 263 | <s14></s14> | ||
| 264 | |||
| 265 | </struct1> | ||
| 266 | |||
| 267 | <struct2> | ||
| 268 | |||
| 269 | <s21></s21> | ||
| 270 | |||
| 271 | <s22> | ||
| 272 | |||
| 273 | <s221></s221> | ||
| 274 | |||
| 275 | </s22> | ||
| 276 | |||
| 277 | <s23></s23> | ||
| 278 | |||
| 279 | <s24></s24> | ||
| 280 | |||
| 281 | </struct2> | ||
| 282 | |||
| 283 | <struct3> | ||
| 284 | |||
| 285 | <s31></s31> | ||
| 286 | |||
| 287 | <s32> | ||
| 288 | |||
| 289 | <s321></s321> | ||
| 290 | |||
| 291 | </s32> | ||
| 292 | |||
| 293 | <s33></s33> | ||
| 294 | |||
| 295 | <s34></s34> | ||
| 296 | |||
| 297 | </struct3> | ||
| 298 | |||
| |
1.1 | 299 | </structs> |
| 300 | |||
| 301 | </soapenv:Body> | ||
| |
30.1 | 302 | |
| |
1.1 | 303 | </soapenv:Envelope> |
| 304 | {{/code}} | ||
| 305 | |||
| 306 | ((( | ||
| |
30.1 | 307 | |
| 308 | |||
| 309 | __Example : Example of a SOAP reponse in XML__ | ||
| |
1.1 | 310 | ))) |
| 311 | |||
| |
30.1 | 312 | We need to identify the structure containing the structures (the lines) we are interested in. In this example, the structures //**struct1**//, //**struct2**// and //**struct3**// are our lines. |
| |
1.1 | 313 | |
| |
30.1 | 314 | The structure //**structs**// is the structure that contains our lines. |
| |
1.1 | 315 | |
| |
30.1 | 316 | So we need to specify it in the advanced options of the data source ; |
| |
1.1 | 317 | |
| 318 | |||
| 319 | |||
| |
30.1 | 320 | [[image:soap_en_html_1934d3df1390c07f.png||queryString="width=496&height=328" height="328" width="496"]] |
| 321 | \\ | ||
| |
1.1 | 322 | |
| |
30.1 | 323 | [[image:soap_en_html_7f1972291bc6cc7b.png||queryString="width=359&height=405" height="405" width="359"]] |
| 324 | \\ | ||
| |
1.1 | 325 | |
| |
30.1 | 326 | Check the option « Start reading XML from a specified tag » and mention the strucure we want to start reading from. |
| |
1.1 | 327 | |
| |
30.1 | 328 | Also, we will uncheck the option « Expand child nodes and attributes into columns ». |
| 329 | |||
| 330 | = Lexicon = | ||
| 331 | |||
| 332 | * | ||
| 333 | ** In this document, we give the following definitions :((( | ||
| 334 | SOAP : Simple Object Access Protocol. It is a messaging protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses XML Information Set for its message format […]. (Wikipédia) | ||
| 335 | |||
| 336 | WSDL : Web Services Description Language. It is an XML file describing a web service. | ||
| 337 | ))) | ||
| 338 | |||
| 339 | WLNK : Web LiNK. Files with the extension .wlnk host links to a data source. | ||
| 340 | |||
| 341 | = References = | ||
| 342 | |||
| 343 | //DigDash uses the Open Source API SOAPUI from SmartBear Software to support SOAP communication with web services// | ||
| 344 | |||
| |
1.1 | 345 | [[https:~~/~~/www.soapui.org>>url:https://www.soapui.org/]] |