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||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 files in DigDash to host the information needed to retrieve a data source via SOAP.

46

47

48

|[[image:soap_en_html_829eaa34e529ef0c.png||height="54" width="54"]]

49

|(((

50

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

51

52

//Why create a WLNK file?//

53

54

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.

55

56

Be careful, a WLNK file only contains the information for **one and only one SOAP request**.

57

58

⇒ **1 WLNK file = a SOAP request**

)))

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.

64

65

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.

66

67

68

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

69

70

71

__Schema : Description of SOAP calls from DigDash__

72

73

= Installation and configuration of the SOAP module =

74

75

== Installation and deployment of the web application ==

76

77

First of all, stop the Tomcat server.

78

79

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

80

81

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.

86

87

== soap_props.properties configuration ==

88

89

Configure the **ddsoap/soap_props.properties **file with the following properties:

90

91

=== Miscellaneous properties ===

92

93

|Propriétés|Description

94

|PRINT_DEBUG|(((

95

This property must be set to ‘true’ to display any traces. Only error traces are always displayed.

96

97

This property allows to display debug traces in logs.

98

)))

99

|SHOW_REQUESTS|Allows to display the SOAP requests (in XML) sent to the Web Service.

100

|SHOW_RESPONSES|Allows to display the SOAP responses (in XML) sent by the Web Service.

101

|LOGIN_BEFORE_CALL_SERVICE|Allows authentication before any SOAP call. Credentials properties must start with _creds (see next point).

102

|REMOVE_REQUEST_EMPTY_VALUES|Removes empty values (identified by « ? ») of the SOAP request.

103

|REMOVE_REQUEST_EMPTY_NODES|Removes empty nodes of the SOAP request.

104

105

__Table : Miscellaneous properties for the SOAP module configuration__

106

107

=== Credentials properties ===

108

109

Authentication may be necessary before any SOAP calls.

110

111

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

112

113

|Properties|Description

114

|(% colspan="2" %)**Caution **: You must escape special characters in keys (property name) if needed (use \= for = , use \: for

115

|**creds_**binding|(Mandatory) The name of the authentication service.

116

|**creds_**operation|(Mandatory) The name of the authentication method.

117

|**creds_**<username>|The possible login name for authentication.

118

|**creds_**<password>|The possible password for authentication.

119

|**creds_**<any other parameter>|The possible other authentication parameters.

120

121

__Table : Properties used for authentication for the SOAP module__

122

123

124

= Configuration in DigDash Enterprise =

125

126

== Creation of a WLNK file ==

127

128

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

129

130

Data source > Add > Any file…

131

132

Select the documents server to use

133

134

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

135

136

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

137

138

→ The URL to call is the URL of the web application, **ddsoap** previously deployed (basically **<digdash_server>/ddsoap**).

139

140

→ The name of your WLNK file must end with **.xml**

141

142

→ Check the option « Only add the URL link to the Documents server ». This option will create the WLNK file.

143

144

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

145

146

[[image:soap_en_html_ce75b9c82fc22c3.png||height="415" width="450"]]

147

\\

148

149

__Screenshot: creation of the WLNK file__

150

151

You can enter the SOAP parameters as key-value in the GET parameters.

152

153

**You IMPERATIVELY must at least mention these two parameters:**

154

155

**_binding** : the name of the Service to call

156

**_operation** : the name of the operation (or method) of the Service to call

157

158

[[image:soap_en_html_1da100bad7bbced9.png||height="336" width="335"]]

159

\\

160

161

__Screenshot: SOAP parameters__

162

163

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.

164

165

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

170

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

196

)))

197

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

207

)))

208

209

__Table:Naming rules to access a specific node__

210

211

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

212

213

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

214

215

== Pagination management ==

216

217

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

218

219

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

220

221

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

222

223

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

224

225

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

226

227

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

228

229

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

230

231

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

232

233

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

234

235

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.

236

237

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

238

239

240

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

307

)))

308

309

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.

310

311

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

312

313

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

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

318

\\

319

320

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

321

\\

322

323

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

324

325

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

= Lexicon =

*

** In this document, we give the following definitions :(((

331

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)

332

333

WSDL : Web Services Description Language. It is an XML file describing a web service.

334

)))

335

336

WLNK : Web LiNK. Files with the extension .wlnk host links to a data source.

337

338

= References =

339