SoapCall lets you call a SOAP web service from a ViewModel by using an OCL expression or Executable Action Language (EAL) action, for integrations that require a SOAP envelope rather than a REST request.

What SoapCall does

SoapCall is an operator on selfVM, so you can use it in any ViewModel. It builds a SOAP request from the selected ViewModel nesting, sends the request to the target URL, and returns the soap:Body from the SOAP envelope returned by the service.

For example, an EAL assignment can store the returned SOAP body in a variable:

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

In this example, GetQuote is both the action in the request body and the SOAP action used by the call. NestingWParams is the ViewModel nesting whose values provide the request parameters.

Syntax

The documented core form is:

selfVM.SoapCall(url, action, actionNamespace, user, password, nestingWithParams)

Argument	Meaning
url	The SOAP service endpoint. Example: 'http://www.webserviceX.NET/stockquote.asmx'.
action	The operation to invoke. The operation is included in the SOAP body as nsAction:action. Example: 'GetQuote'.
actionNamespace	The namespace assigned to nsAction in the SOAP body. Example: 'http://www.webserviceX.NET/'.
user	User name for a service that requires SOAP username security. Use an empty string when the service does not require it.
password	Password for the SOAP user. Use an empty string when the service does not require it.
nestingWithParams	Name of the ViewModel nesting that contains the request values. Example: 'NestingWParams'.

The available SoapCall form may also include passwordDigest and SOAPAction arguments after nestingWithParams:

selfVM.SoapCall(targetUrl, action, actionNamespace, user, password, nestingWithParams, passwordDigest, SOAPAction)

passwordDigest controls whether the password is sent as clear text or by using nonce, creation time, and a hash. SOAPAction supplies the value of the HTTP SOAPAction header. Confirm the supported argument form and accepted passwordDigest values for the MDriven version you deploy.

Build the request from a ViewModel nesting

The nesting named by nestingWithParams supplies the elements inside the SOAP operation. Create the nesting and add the columns that represent the parameters required by the service.

1. In MDriven Designer, open the ViewModel that performs the integration.
2. Add a nesting for the SOAP operation parameters. For this example, name it NestingWParams.
3. Add columns for the elements the service expects and populate them before calling SoapCall.
4. Call selfVM.SoapCall, passing the nesting name as a string.
5. Read the returned SOAP body and map or process the response as required by the ViewModel action.

For a service operation named TheAction, a parameter column named SomeString with the value Hello produces an element equivalent to:

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

With action = 'TheAction' and actionNamespace = 'TheNameSpace', the operation is represented as:

<soap:Body xmlns:nsAction="TheNameSpace">
  <nsAction:TheAction>
    <nsAction:SomeString>Hello</nsAction:SomeString>
  </nsAction:TheAction>
</soap:Body>

Control XML namespaces

SOAP services often require elements in different XML namespaces. SoapCall derives namespace declarations from root ViewModel columns of type String whose names start with ns.

Create a root ViewModel column whose name begins with ns, and set its value to the namespace URI. Then prefix a request element column with that root-column name followed by an underscore.

ViewModel column	Value	Result in request
nsAdditionalNameSpace (root String column)	'AdditionalNameSpaceAdded'	Declares the additional namespace.
nsAdditionalNameSpace_SomeString (parameter column)	'Hello'	Creates <nsAdditionalNameSpace:SomeString xmlns:nsAdditionalNameSpace="AdditionalNameSpaceAdded">Hello</nsAdditionalNameSpace:SomeString>.

The actionNamespace argument defines the nsAction namespace used for the SOAP operation and its standard action parameters. Use an additional root namespace column only when an element must use a namespace other than nsAction.

Send an element with no namespace

Prefix a ViewModel column name with an underscore (_) to denote that the generated element has no namespace.

For example, a parameter column named _SomeString with the value Hello produces:

<SomeString>Hello</SomeString>

Authentication and client certificates

When you provide a user name and password, SoapCall adds SOAP security information including a username token. The request can use password text or password digest behavior, depending on the supported call form and passwordDigest setting.

If the root ViewModel contains a column named ClientCertThumbPrint, SoapCall looks up that certificate and uses it for the call. Populate this column only when the SOAP service requires a client certificate.

SOAPAction behavior

SoapCall uses the action as the SOAP action and also includes the action in the request body. When the service requires a specific HTTP SOAPAction header value that differs from the action, use the SOAPAction argument where that extended signature is supported.

Troubleshooting

• Check that the endpoint URL, operation name, and action namespace match the service contract.
• Ensure that nestingWithParams exactly matches the ViewModel nesting name and that its columns have values before the call.
• For namespace errors, verify the root String namespace column name starts with ns, and verify that element columns use the same prefix followed by _.
• Use an underscore-prefixed parameter column only when the service expects an unqualified XML element.
• If the service requires mutual TLS, verify that the root ViewModel includes ClientCertThumbPrint and that the referenced certificate is available to the environment running the call.
• If authentication fails, verify whether the service expects password text or password digest security and confirm the supported passwordDigest values for your MDriven version.

For REST integrations, use the REST-specific operators instead; for example, Documentation:OCLOperators RestPut sends a complete representation to a remote URL.

See also

• Documentation:OCLOperators SoapCall
• Documentation:SOAP
• Documentation:OCLOperators RestPut
• Documentation:Rest API
• Documentation:Api documentation