SoapCall lets you call a SOAP web-service operation from a ViewModel by using OCL or EAL, for integrations that require a SOAP request.

Use SoapCall from a ViewModel

SoapCall is an OCL operator available on selfVM in any ViewModel. It builds a SOAP envelope from the ViewModel structure, sends the request, and returns the body of the SOAP envelope returned by the service.

Use the following signature:

selfVM.SoapCall(targeturl, action, actionnamespace, user, pwd, nestingWithParams, passwordDigest, SOAPAction)

For example, this call requests the GetQuote SOAP operation:

vNewVar := selfVM.SoapCall(
  'http://www.webserviceX.NET/stockquote.asmx',
  'GetQuote',
  'http://www.webserviceX.NET/',
  '',
  '',
  'NestingWParams',
  '',
  ''
)

The action is included in the request body and is used as the SOAPAction header unless you provide a value for SOAPAction.

Arguments

Argument	Meaning
targeturl	URL of the SOAP service endpoint.
action	SOAP operation to call. For example, GetQuote.
actionnamespace	Namespace used for the operation. The generated SOAP body declares this as nsAction.
user	User name to send when the service requires authentication.
pwd	Password to send when the service requires authentication.
nestingWithParams	Nesting whose parameters SoapCall uses to construct the request.
passwordDigest	Controls whether the password is sent as clear text or with nonce, creation time, and hash information.
SOAPAction	Value for the SOAPAction HTTP header.

Define request parameters in the ViewModel

SoapCall obtains request parameters from the specified nesting. Define the ViewModel columns that represent the values the SOAP operation expects.

For example, if the operation expects a string element named SomeString, provide a column/value that produces:

<nsAction:SomeString>Hello</nsAction:SomeString>

With action set to TheAction and actionnamespace set to TheNameSpace, the operation itself is represented as:

<nsAction:TheAction>
  <nsAction:SomeString>Hello</nsAction:SomeString>
</nsAction:TheAction>

The complete returned value is the response SOAP body. Store it in a variable, as in vNewVar in the earlier example, and process it according to the response format required by the service.

Control XML namespaces

SOAP services can require elements in more than one namespace. You can declare additional namespaces with root ViewModel columns of type String whose names start with ns.

1. Add a root String ViewModel column named nsTheNameSpace.
2. Give it the namespace URI, for example http://something.
3. Prefix an element column with that column name followed by an underscore. For example, use nsTheNameSpace_SomeElement for an element in that namespace.

For example, the following convention:

nsAdditionalNameSpace = 'AdditionalNameSpaceAdded'
nsAdditionalNameSpace_SomeString = 'Hello'

produces an element equivalent to:

<nsAdditionalNameSpace:SomeString xmlns:nsAdditionalNameSpace="AdditionalNameSpaceAdded">Hello</nsAdditionalNameSpace:SomeString>

A column name beginning with an underscore (_) denotes an element with no namespace. This is useful when one SOAP operation expects both action-namespace elements and unqualified elements.

Authentication and client certificates

When user and pwd are supplied, SoapCall can include WS-Security username-token information in the SOAP header. The passwordDigest argument determines whether this uses clear-text password handling or nonce, creation-time, and hash information.

To use a client certificate, add a root ViewModel column named ClientCertThumbPrint. SoapCall looks up the certificate identified by that thumbprint and uses it for the call.

Check the generated request

The SOAP request uses a SOAP envelope with a SOAP header and body. The body declares the action namespace as nsAction, then contains the action element and the elements built from the selected nesting.

When a service rejects a request, verify these items first:

• The endpoint URL, operation name, and action namespace match the service contract.
• The nesting passed in nestingWithParams contains the expected parameter columns and values.
• Each required element has the expected namespace. Use the ns... root-column convention for additional namespaces and _ for no namespace.
• The service's authentication requirement matches the supplied user name, password, and password-digest setting.
• The required SOAPAction header is present and has the expected value.

For the broader SOAP envelope format and additional examples, see Documentation:SOAP.

See also

• Documentation:SoapCall
• Documentation:SOAP
• Learn OCL
• Documentation:OCL General Operators