Module SOAP

1

SOAP module - Documentation

2

3

Retreiving a data source via a SOAP web service

**Summary :**

= Prerequisite =

* 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.

Go to

**<digdash_server>/ddsoap?about=true**

25

26

to have information about your SOAP configuration.

)))

= Description =

== General ==

DigDash Enterprise offers the possibility to retrieve data sources calling SOAP web services.

34

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.

36

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.

38

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.

40

41

Hence the importance of knowing the SOAP request structure in XML as said in the prerequisite.

42

43

== Technical description ==

44

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.

46

47

(% class="box infomessage" %)

48

(((

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).

50

51

//Why create a WLNK file?//

52

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

)))

57

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.

59

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.

61

62

63

[[image:soap_en_html_5e3e099e5561dd5e.png||queryString="width=667&height=423" height="423" width="667"]]

64

65

66

__Schema : Description of SOAP calls from DigDash__

67

68

= Installation and configuration of the SOAP module =

69

70

== Installation and deployment of the web application ==

71

72

First of all, stop the Tomcat server.

73

74

Copy the web application **ddsoap.war** located in **<digdash_installation>/add-ons/soap **to **<digdash_install>/apache-tomcat/webapps.**

75

76

Restart the DigDash server to deploy the web application.

== wsdls folder ==

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.

81

82

== soap_props.properties configuration ==

83

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.

93

)))

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.

99

100

__Table : Miscellaneous properties for the SOAP module configuration__

101

102

=== Credentials properties ===

103

104

Authentication may be necessary before any SOAP calls.

105

106

**__ALL__ these properties __MUST__ start with « creds_ » __AND__ the property LOGIN_BEFORE_CALL_SERVICE must be set to ‘true’ **

107

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.

115

116

__Table : Properties used for authentication for the SOAP module__

117

118

119

= Configuration in DigDash Enterprise =

120

121

== Creation of a WLNK file ==

122

123

Let’s start with extracting data from an XML file.

124

125

Data source > Add > Any file…

126

127

Select the documents server to use

128

129

Add a new document to the server clicking the « Add a file to the server... » button.

130

131

Three options are available. To get the content via SOAP, we are going to select the second option « Enter a URL ».

132

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).

|Separators|Description|Example

165

|/|Path separator in the XML.|(((

<a>

<a1>

?

**<c>?</c>**

</a1>

?

**<c>?</c>**

</a>

<a1>

?

</a1>

**To access the element c, we will specify a/c (specifying c will select the first element c)**

191

)))

192

|@|To access an element attribute.|(((

<a>

?

<c** attr=?**>?</c>

</a>

**To access the attribute attr of the element c, we will specify a/c@attr (or c@attr directly)**

202

)))

203

204

__Table:Naming rules to access a specific node__

205

206

Once the SOAP parameters are entered, click on « OK » and the WLNK file will be created and uploaded to the selected documents server.

207

208

This WLNK file can now be loaded as a classical XML data source file.

209

210

211

(% class="box infomessage" %)

212

(((

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]]

216

)))

217

218

== Pagination management ==

219

220

The SOAP module can help you gather and get all data in DigDash from a request with pagination.

221

222

You **must** provide the following GET parameters to your URL :

223

224

**_pagination** : this parameter must be set to true to specify pagination is required.

225

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).

227

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).

229

230

**_pageInc** : the index of the page starts with 0. this parameter must define the incrementation of this index.

231

232

_//resultSize// (optional) : specifying the result size can optimize the response time.

233

234

//IV.3Configuration of the XML data source//

235

236

When loading the XML response into DigDash, the data source may be difficult to read at first glance.

237

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.

239

240

For example : let’s consider the following SOAP response in XML :

241

242

243

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>

<a></a>

<s12>

</s12>

</struct1>

<s22>

</s22>

</struct2>

<s32>

</s32>

</struct3>

</structs>

</soapenv:Body>

</soapenv:Envelope>

(((

__Example : Example of a SOAP reponse in XML__

310

)))

311

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.

313

314

The structure //**structs**// is the structure that contains our lines.

315

316

So we need to specify it in the advanced options of the data source ;

[[image:soap_en_html_1934d3df1390c07f.png||queryString="width=496&height=328" height="328" width="496"]]

321

\\

322

323

[[image:soap_en_html_7f1972291bc6cc7b.png||queryString="width=359&height=405" height="405" width="359"]]

324

\\

325

326

Check the option « Start reading XML from a specified tag » and mention the strucure we want to start reading from.

327

328

Also, we will uncheck the option « Expand child nodes and attributes into columns ».

= Lexicon =

*

** 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