/
SoapPlugin.txt
193 lines (157 loc) · 9.02 KB
/
SoapPlugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
%META:TOPICINFO{author="ProjectContributor" date="1269028908" format="1.1" version="1.6"}%
---+!! %TOPIC%
%SHORTDESCRIPTION%
%TOC%
!SoapPlugin is an way to integrate webservices using the SOAP transport
protocol. It has got support for service definitions using WSDL as far as
supported by [[CPAN:SOAP:Lite][SoapLite]], the underlying perl library of SOAP
operatiosn. For those cases of more complicated WSDL descriptions not covered
by !SoapLite, endpoints can be be specified manually.
This plugin supports accessing SOAP webservices using basic authentication,
that is allows accessing endpoints secured by HTTP credentials.
The xml response of a service endpoint can be parsed and formatted using basic
xpath expressions.
---++ Syntax
---+++ SOAP
| *Parameter* | *Description* |
| "..." | client to use to access a specific webservice; \
clients are defined in =configure= in ={SoapPlugin}{Clients}=; see the "Configuring Clients" below |
| id="..." | stores the retrieved result under the given ID to be reused in =SOAPFORMAT= |
| method="..." | remote procedure to be executed on the server side; this is an identifier \
specific to the service; if not defined =defaultMethod= is used as specified in the service definition |
| format="..." %BR% \
header="..." %BR% \
footer="..." %BR% \
separator="..." | these format strings are used to format non-scalar results |
| hidenull="on/off" | if switched on, the empty response or node won't be displayed, that is even =head= and =footer= content is omitted |
| raw="on/off" | if switched on, the xml response is returned as is, that is no formatting is applied |
| verbatim="on/off" | this behaves like =raw="on"= basically but also pretty-prints the output to ease reading the xml and then puts it into a <verbatim> environment to format it as html |
| valueof="..." | xpath expression to filter the output |
| depth="int" | the depth to which an XML response object should be traversed while rendering it using =format=, =header=, =footer= and =separator= |
| warn="on/off" | if switched off all error warnings will be suppressed (defaults to on) |
Any additional parameter like for example =EMPLOYEEID= in
=%<nop>SOAP{"client-id" method="getVacationOfEmployee" EMPLOYEEID="1606"}%=
will be passed over to the server and are not interpreted by the !SoapPlugin
itself. This also means that any required parameter to a webservice method must
not overlap with those documented above as part of the =%SOAP= command.
A parameter may contain nested argument structures which are then translated to nested xml structures. For example
<verbatim class="tml">
%SOAP{
...
STORNO="
STARTDATE=\"20101101\"
ENDDATE=\"20101107\"
"
}%
</verbatim>
Will be translated to a call using
<verbatim class="html">
<STORNO>
<STARTDATE>20101101</STARTDATE>
<ENDDATE>20101107</ENDDATE>
</STORNO>
</verbatim>
---+++ SOAPFORMAT
| *Parameter* | *Description* |
| "..." (or id="...") | this refers to a previous =%SOAP= call that was stored at the given ID using the =id= parameter to =%SOAP= |
| format="..." %BR% \
header="..." %BR% \
footer="..." %BR% \
separator="..." | these format strings are used to format non-scalar results |
| hidenull="on/off" | if switched on, the empty response or node won't be displayed, that is even =head= and =footer= content is omitted |
| raw="on/off" | if switched on, the xml response is returned as is, that is no formatting is applied |
| verbatim="on/off" | this behaves like =raw="on"= basically but also pretty-prints the output to ease reading the xml and then puts it into a <verbatim> environment to format it as html |
| valueof="..." | xpath expression to filter the output |
| depth="int" | the depth to which an XML response object should be traversed while rendering it using =format=, =header=, =footer= and =separator= |
So the parameters to =%SOAPFORMAT= are mostly the same as those for =%SOAP=
except =method=. This is not needed as SOAPFORMAT formats the response already
received by accessing the server/method of the previous =%SOAP= call.
If the node selected by the =valueof= xpath expression is not a scalar value,
e.g. addresses a node in the xml response which contains further child nodes,
then the result is rendered recursively using =format=, =header=, =footer= and
=separator= while traversing the xml output.
When visiting a node, the following variables can be used to access its
properties:
* =$name=: (or =$key=): the name of the node
* =$value=: the value of the node; this expands recursively when the value is not a final child node
* =$type=: the type of the node according to the WSDL definition
* =$uri=: the URI that will be used as the namespace
* =$prefix=: the prefix used when associating the node with a specific namespace
* =$attr(...)=: the value of the named attribute
* =$index=: the index of this node in a list of sibling nodes
* =$depth=: the distance from the root node of the contained xml document
* =$valueof(...)=: the value of the node as specified by the enclosed xpath expression; note: in contrast to the =valueof= parameter of the =%SOAP/SOAPFORMAT= tag itself, this only returns the first matching value
Standard escapes may be used in all format strings, that is =$percnt=, =$nop=, =$n= and =$dollar=.
---++ Configuring Clients
Each client specifies an service that Foswiki might talk to using SOAP. These have to be defined upfront using
[[%SCRIPTURLPATH{"configure"}%][configure]]. A service is then connected
using =%<nop>SOAP{"service-id" ...}%=.
Example:
<verbatim>
$Foswiki::cfg{SoapPlugin}{Clients} = [
{
id => 'portal',
uri => 'urn:company.com:xi:ess_r2',
proxy => 'http://company.com:50000/XISOAPAdapter/MessageServlet?channel=:Portal:Portal_Webservice',
xmlns => 'urn:sap-com:document:sap:rfc:functions',
user => 'soap_user',
password => 'soap_password',
defautMethod => 'EMPLOYEE_FUNCTION'
},
{
id => 'mockup',
uri => 'urn:company.com:xi:ess_r2',
proxy => 'http://127.0.0.1:8088/mockPortalBinding',
xmlns => 'urn:sap-com:document:sap:rfc:functions',
}
];
</verbatim>
This defines two clients that are stored under the IDs =portal= and =mockup=. These are then used by a
=%<nop>SOAP{"portal" method="..."}%= or =%<nop>SOAP{"mockup" method="..."}%= statement respectively.
The following list of parameters might be used to configure a service:
| *Parameter* | *Description* |
| id => "..." | symbolic name to make use of the connection |
| uri => "..." %BR% \
proxy => "..." %BR% \
xmlns => "..." | resource specification of the given endpoint definition; please look up the SOAP documentation of that service for more details |
| wsdl => "..." | url of the WSDL definition; either use =uri= + =proxy= or =wsdl= to specifiy a connection |
| defaultMethod => "..." | default method to be used by this client; can be overriden using the =method= parameter of a =%SOAP= call |
| user => "..." %BR% \
password =>" | user name and password in case the webservice is access protected using HTTP credentials |
| namespace => [ %BR% \
"id" => "urn", %BR% \
"id" => "urn", %BR% \
... %BR% \
] | list of namespaces to be defined as part of the protocol; this is a set of extra namespaces that might be used when talking to the SOAP server; most of the time specifying =xmlns= is enough to defined the default namespace with which methods are called |
---++ Foswiki specific SOAP headers
Every message created by !SoapPlugin adds a set of foswiki-specific headers which are defined in the
=foswiki:http//schema.foswiki.org/soap= namespace. These are
| *Header* | *Description* |
| =foswiki:wikiName= %BR% =foswiki:loginName= | WikiName of the user currently logged in triggering the SOAP call |
| =foswiki:web= %BR% =foswiki.topic= | web and topic from where the SOAP call was issued |
| =foswiki:isAdmin= | a boolean flag indicating whether the current user is a wiki admin |
---++ Installation Instructions
%$INSTALL_INSTRUCTIONS%
---++ Known Problems
1 On some systems CPAN:SOAP::Lite throws a tainted error. !SoapPlugin comes with a patch to SOAP::Transport::HTTP
to mitigate the problem.
1 WSDL support of Soap::Lite is rather limitted.
---++ Plugin Info
<!--
* Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
-->
| Author(s): | Foswiki:Main/MichaelDaum |
| Copyright: | © 2010 Michael Daum http://michaeldaumconsulting.com |
| License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
| Release: | %$RELEASE% |
| Version: | %$VERSION% |
| Change History: | <!-- versions below in reverse order --> |
| 14 Jun 2010: | added =warn= parameter to suppress error messages; \
fixed perl rookie error for default values retrieved from a SOM object |
| 10 May 2010: | added support for nested argument structures |
| 19 Mar 2010: | rewrite of serializer; implemented =$valueof()= etc; fixed UTF8 handling |
| 16 Mar 2010: | initial release |
| Dependencies: | %$DEPENDENCIES% |
| Home page: | Foswiki:Extensions/%TOPIC% |
| Support: | Foswiki:Support/%TOPIC% |
<!-- Do _not_ attempt to edit this topic; it is auto-generated. -->