SOAP-C Messages
Introduction
Any application may use SOAP-C-… messages to the SoapClientApp to request that an outbound SOAP/HTTP(S) request be made to an external SOAP/HTTP(S) Server.
The following applications from the core n2svcd
module make requests to
SoapClientApp.
TesterApp
(initates outbound SOAP requests for OSD operations)
The following LuaApp agents from the core n2svcd
module use SoapClientApp.
SoapLuaAgent
(initates outbound SOAP requests)
The internal SOAP-C-… messages are:
SOAP-C-REQUEST
SOAP-C-SENT
SOAP-C-RESPONSE
Note that this page uses the term “on-the-wire” to refer to the sending or receiving of SOAP content by the SoapClientApp. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).
SOAP-C-REQUEST
The SOAP-C-REQUEST
message is sent to SoapClientApp by any application that wishes
to perform an outbound SOAP request.
Refer to the SoapClientApp Configuration documentation for more information on setting default parameters.
The attributes of the SOAP-C-REQUEST
message are:
Field
Type
Description
soap
Object
Container for the parameters of the SOAP request that we are to send.
.path
String
The URI path with which the request should be sent.
(Default = Path from action
, or /
root path)
.query
String
The URI query string (the part following “?” in the URI).
(Default = None)
.fragment
String
The URI fragment string (the part following “#” in the URI).
(Default = None)
.action
String
[Required] The fully-specified SOAP action for the
SOAPAction
HTTP header.
.message_name
String
[Required] The name of the SOAP method within the
Body
.
This should not include any namespace part.
.message_namespace
Object
A container for the message namespace information.
.uri
String
The message namespace URI, if one should be used.
.alias
String
The message namespace alias, if a URI is being used.
(Default = oper
)
.location
envelope
/message
The message namespace alias location, if a URI is being used.
(Default = As configured in the SoapClientApp)
.args
Object
User parameters to encode into the request message.
The encoding (and decoding of the response) will vary according to quirks_mode
.
.http_headers
Array of Objects
Additional user-level header objects to apply to an outbound HTTP Request (see below for object structure).
These headers are added after any headers defined by static SoapClientApp
application configuration.
You should not set the Content-Type
or Content-Length
headers.
(Default = No Additional Headers)
Note that it is not possible to set or override connection or SSL parameters in the SOAP-C-REQUEST
message.
Connection and SSL parameters can only be set in the SoapClientApp configuration.
Each object in the soap.http_headers
Array for SOAP-C-REQUEST
has the following structure.
Field
Type
Description
.name
String
[Required] The name of the HTTP Request header.
.value
String
[Required] The full string value of the HTTP Request header.
.replace
0
/ 1
If
1
then all previous headers of this name are removed, and this header replaces them.
(Default = Append to the existing headers, do not replace)
SOAP-C-SENT
The SOAP-C-SENT
message is sent by SoapClientApp to the requesting application
when the original SOAP-C-REQUEST
is placed on-the-wire.
The attributes of the SOAP-C-SENT
message are:
Field
Type
Description
soap
Object
The SOAP parameters used to encode the final on-the-wire HTTP Request.
This Object has the same structure as the soap
Object in SOAP-C-REQUEST
.
Note however that this object will also contain any field values which were filled-in using
default values configured within SoapClientApp itself.
http
String
The full HTTP Request message. This field may or may not be present.
The SoapClientApp may decide not to supply it in order to reduce traffic on the message bus.
Note that the on-the-wire HTTP Request is not returned in the SOAP-C-SENT. This is a decision made for efficiency, since these messages can be quite large.
SOAP-C-RESPONSE
The SOAP-C-RESPONSE
message is sent by SoapClientApp to the requesting application
when a HTTP Response is received to the original SOAP-C-REQUEST
, or if a failure occurs
which indicates that no HTTP Response will be received.
The attributes of the SOAP-C-RESPONSE
message are:
Field
Type
Description
success
0
/1
[Required] Indicates if the request was successful or not.
error
String
Indicates the reason why the request failed.
Present and applicable only if success
== 0
.
soap
Object
Container for the SOAP response parameters received.
Present only if success
== 1
.
.result_name
String
The name of the result message received.
This will exclude the namespace alias (if present).
.fault
Object
A container for the SOAP Fault contents, if a SOAP fault is present.
.code
String
The SOAP Fault
faultcode
/faultCode
value.
.string
String
The SOAP Fault
faultstring
/faultString
value.
.detail
String
The SOAP Fault
detail
value, if it is a simple scalar string.
Structured detail result values are not currently processed.
.result_namespace
Object
A container for the result namespace information.
These are not present in the case of a SOAP Fault.
.uri
String
The result namespace URI, if one was returned.
.location
envelope
/message
Location of the result namespace URI, if one was used.
.args
Object
The decoded result attributes.
The decoding of the response will vary according to quirks_mode
.
These are not present in the case of a SOAP Fault.
.code
Integer
The returned HTTP Response status code, e.g.
200
.
.content_type
String
The HTTP Response
Content-Type
header value which is always present for success.
.http_headers
Array of Object
The list of HTTP headers parsed from the HTTP Response (see below for object structure).
All HTTP headers are present, including Content-Length
and Content-Type
.
If a HTTP header was repeated in the HTTP Response, then it is repeated in this Array.
Each object in the soap.http_headers
Array for SOAP-C-RESPONSE
has the following structure.
Field
Type
Description
.name
String
[Required] The name of the HTTP Response header.
.value
String
[Required] The full string value of the HTTP Response header.