Documentation:SOAP the protocol from the stone age

SOAP the protocol from the stone age

This page was created by Alexandra on 2018-10-28. Last edited by Wikiadmin on 2026-07-29.

You can call a SOAP web service from a ViewModel by using the SoapCall operator in OCL or EAL; this page is for developers who need to send SOAP actions and use their responses in MDriven.

Call a SOAP action

Use selfVM.SoapCall in a ViewModel action. The operator creates a SOAP envelope from a parameter nesting in the ViewModel, sends it to the service endpoint, and returns the body of the SOAP response as a string.

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

In this example, the returned response body is assigned to the ViewModel variable vNewVar.

SoapCall arguments

The basic call has this form:

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

Argument	What you provide	Example
`targetUrl`	The SOAP service endpoint, not the URL for one individual method.	`'http://www.webserviceX.NET/stockquote.asmx'`
`action`	The service method to invoke. SoapCall uses this action in the SOAP request body and as the SOAPAction header.	`'GetQuote'`
`actionNamespace`	The namespace for the SOAP action. Read it from the service WSDL and preserve its exact spelling, casing, and trailing slash.	`'http://www.webserviceX.NET/'`
`user`	User name when the service requires SOAP username authentication; otherwise an empty string.
`password`	Password when the service requires it; otherwise an empty string.
`nestingWithParams`	The name of the ViewModel nesting that supplies the action parameters.	`'NestingWParams'`

The documented extended signature is:

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

Use the additional arguments only when the target service requires a particular password format or SOAPAction header value. See Documentation:OCLOperators SoapCall for the operator reference.

Build parameters in a ViewModel nesting

SoapCall obtains request parameters from a named ViewModel nesting (the blue box in the ViewModel editor). Its columns become SOAP elements. Create the nesting with the exact name passed as nestingWithParams.

For a service action that takes one string parameter called symbol:

Add a ViewModel action.
Set its expression to the SoapCall expression, using 'NestingWParams' as the final basic argument.
Create a ViewModel nesting named NestingWParams.
Add a column named symbol to that nesting.
Set the column expression to an OCL value, for example 'IBM', a model attribute, or a ViewModel variable.
Add a String ViewModel variable named vNewVar if you want to retain the action result.
Add a ViewModel column that displays vNewVar, then run the action.

For example, a symbol column with expression 'IBM' produces a parameter element for that value. In production, the expression can read the symbol from the model rather than hard-code it.

Represent nested input types

SOAP actions can require complex input: a parameter can contain child parameters. Represent this with nested ViewModel nestings. The nesting and column order must match the order expected by the service.

For example, if a service expects an action parameter named BarCodeParam that contains a Barcode value, create a parameter structure equivalent to:

<BarCodeParam>
  <Barcode>...</Barcode>
</BarCodeParam>

Create the corresponding parent column and detail nesting in the ViewModel. Set the inner Barcode column to the required OCL expression. Inspect the generated envelope before relying on a complex request; see Debug the generated request.

Control XML namespaces

The actionNamespace argument defines the standard nsAction namespace used for action parameters. Some SOAP services also require parameters in another namespace or parameters without a namespace.

Add namespace definitions as String columns on the root ViewModel class. A root column whose runtime name begins with ns is treated as a namespace definition.

Requirement	ViewModel setup	Result
Use the action namespace	Name the parameter column normally, for example `SomeString`.	The element uses the `nsAction` namespace.
Use an additional namespace	Add root String column `nsAdditionalNameSpace` with expression `'AdditionalNameSpaceAdded'`. Name the parameter column `nsAdditionalNameSpace_SomeString`.	The request emits `nsAdditionalNameSpace:SomeString` and declares that namespace on the element.
Send an element with no namespace	Start the parameter column runtime name with an underscore, for example `_SomeString`.	The request emits `SomeString` without a namespace prefix.

For example, the namespace setup above can produce the following action body:

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

Authenticate and use a client certificate

Pass the user name and password arguments when the SOAP service requires username authentication:

vNewVar2 := selfVM.SoapCall(
  'http://www.webserviceX.NET/genericbarcode.asmx',
  'GenerateBarCode',
  'http://www.webservicex.net/',
  'SomeUserName',
  'SomePassword',
  'genericbarcodeParams'
)

When credentials are supplied, MDriven adds a SOAP security header containing a username token. SOAP services may require a specific password representation; use the documented passwordDigest argument where required.

If the service requires a client certificate, add a root ViewModel column named ClientCertThumbPrint. SoapCall looks up and uses the certificate identified by that value.

Debug the generated request

Add a String ViewModel variable named vSoapDebug. Before the request is sent, SoapCall assigns the complete SOAP envelope to this variable.

Use this procedure for a failed request:

Add vSoapDebug and display it in the ViewModel.
Execute the action.
Compare the generated envelope with the service WSDL or its required request example.
Check the endpoint, action name, action namespace, element names, namespace prefixes, parameter order, and nesting depth.
Correct the ViewModel nesting or namespace columns, then execute the action again.

This is especially important for complex parameter types, where an incorrect nesting level or element order can make an otherwise valid SOAP call fail.

Handle the response

SoapCall returns the body from the SOAP envelope returned by the service. Store the result in a String ViewModel variable such as vNewVar or vSoapResult and inspect it before importing data.

A service can return XML as escaped text inside its result element. For example, the result may contain <StockQuotes> rather than an XML <StockQuotes> element. Decode or otherwise prepare that result as required before treating it as XML.

When the response XML matches your model structure, use XmlToObjects to create matching model objects. Keep SOAP transport concerns in the calling action and put response-to-object mapping in the XML import logic.

Response errors

Add a String ViewModel variable named vSoapError to capture exceptions that occur while parsing the response. Display both the result and error variables while developing the integration.

Variable	Purpose
`vSoapDebug`	Complete outbound SOAP envelope, assigned before sending the request.
`vSoapResult`	Returned service value; MDriven attempts to convert it to XML.
`vSoapError`	Exception information when response parsing fails.

Troubleshooting

Symptom	Check
The service rejects the action	Verify that `action` exactly matches the WSDL operation and that `actionNamespace` has the required case and trailing slash.
The service reports missing or invalid parameters	Verify the nesting name passed to SoapCall, parameter column names, nested structure, and column order. Inspect `vSoapDebug`.
A parameter is in the wrong namespace	Use a normal column for `nsAction`, an `ns...` root namespace column plus an `ns..._Element` parameter column for another namespace, or prefix the parameter name with `_` for no namespace.
Authentication fails	Confirm whether the service expects username/password credentials, a password digest, or a client certificate. For a certificate, provide `ClientCertThumbPrint` on the root ViewModel class.
HTTPS connectivity fails in custom .NET code	Review Documentation:.net version for the .NET and TLS requirements.

Contents