Skip to content

Sys.Soap

Sys.Soap calls operations of SOAP web services from server-side code. It builds the SOAP envelope from a JavaScript value, sends it with fetch, and converts the response back into a value. The operations and types are described by a SoapServiceMetadata object.

A SOAP Service Integration generates this metadata from its WSDL and wraps call() in one typed function per operation, so you rarely need to call Sys.Soap directly. Use it for services without a Service Integration, or to look at the metadata types used by generated code.

Availability: Server

call<T>(metadata: SoapServiceMetadata, operationName: string, input: unknown, options: SoapCallOptions): Promise<SoapCallResult<T>>

Calls one operation of a SOAP service and returns the result together with the raw request and response. SOAP faults and HTTP errors do not throw: they are returned in error. The call throws only if the operation is not in the metadata, or if the request itself fails, for example when the host cannot be reached.

ParameterTypeDescription
metadataSoapServiceMetadataDescription of the service’s operations and types.
operationNamestringKey of the operation in metadata.operations.
inputunknownContent of the request element. For a complex type, the properties named in its fields become child elements, in field order; other properties are ignored. Properties that are undefined are left out, null is sent as xsi:nil, and Date values are sent in ISO 8601 format.
optionsSoapCallOptionsEndpoint and request options.

SoapCallOptions fields

FieldTypeRequiredDescription
endpointUrlstringYesURL the request is posted to.
headersRecord<string, string>NoAdditional HTTP headers, for example authorization. They override the headers Lowgile sets.
soapHeaderXmlstringNoRaw XML placed inside soap:Header, for example a WS-Security header.
fetchtypeof fetchNofetch implementation used to send the request. Default: the global fetch.

Returns: Promise<SoapCallResult<T>> · Availability: Server

const metadata: Sys.Soap.SoapServiceMetadata = {
types: {
GetQuote: { fields: [{ name: 'symbol', ns: 'http://example.com/stock', type: '#string' }] },
GetQuoteResponse: { fields: [{ name: 'price', ns: 'http://example.com/stock', type: '#number' }] },
},
operations: {
GetQuote: {
soapAction: 'http://example.com/stock/GetQuote',
soapVersion: '1.1',
input: { name: 'GetQuote', ns: 'http://example.com/stock', type: 'GetQuote' },
output: { name: 'GetQuoteResponse', ns: 'http://example.com/stock', type: 'GetQuoteResponse' },
},
},
}
const result = await Sys.Soap.call<{ price: number }>(metadata, 'GetQuote', { symbol: 'ACME' }, {
endpointUrl: 'https://example.com/stock-service',
})
if (result.error) throw new Error(`${result.error.code}: ${result.error.message}`)
const price = result.data?.price
interface SoapServiceMetadata {
types: Record<string, SoapComplexType>
operations: Record<string, SoapOperation>
}

Describes a SOAP service: its complex types by name, and its operations by name.

FieldTypeRequiredDescription
typesRecord<string, SoapComplexType>YesComplex types, referenced by name from SoapField.type.
operationsRecord<string, SoapOperation>YesOperations, called by name with call().

Availability: Server

interface SoapOperation {
soapAction: string
soapVersion: SoapVersion
input: SoapField
output: SoapField
}

One operation of the service.

FieldTypeRequiredDescription
soapActionstringYesSOAP action, sent in the SOAPAction header (SOAP 1.1) or the action parameter of the content type (SOAP 1.2).
soapVersionSoapVersionYesSOAP version, which decides the envelope namespace and content type.
inputSoapFieldYesThe element sent as the child of soap:Body.
outputSoapFieldYesThe element expected as the child of soap:Body in the response.

Availability: Server

interface SoapField {
name: string
ns: string
type: string
isArray?: boolean
}

An XML element, used for operation inputs and outputs and for the fields of complex types.

FieldTypeRequiredDescription
namestringYesLocal element name, also used as the property name in JavaScript values.
nsstringYesNamespace of the element; empty if the element is unqualified.
typestringYesA SoapPrimitiveType, or the name of a complex type in SoapServiceMetadata.types.
isArraybooleanNoIf true, the element can repeat: an array value is sent as one element per item, and in the response the property is an array whenever the element is present.

Availability: Server

interface SoapComplexType {
fields: SoapField[]
}

A complex type: its child elements, in the order in which they are written. Response elements that are not listed are still read, without type conversion.

Availability: Server

type SoapPrimitiveType = '#string' | '#number' | '#boolean' | '#any'

Built-in value types. In responses, #number is converted with Number() (empty becomes null), #boolean is true for true or 1, #string is kept as text, and #any is read without type conversion: text for a simple element, an object for an element with children.

Availability: Server

type SoapVersion = '1.1' | '1.2'

SOAP protocol version.

Availability: Server

interface SoapRequestOptions {
headers?: Record<string, string>
soapHeaderXml?: string
fetch?: typeof fetch
}

Request options without the endpoint, accepted by the operation functions that a SOAP Service Integration generates. The fields are described under call().

Availability: Server

interface SoapCallOptions extends SoapRequestOptions {
endpointUrl: string
}

SoapRequestOptions plus the endpoint URL. The fields are described under call().

Availability: Server

interface SoapCallResult<T> {
data?: T
error?: SoapFault
request: Request
response: Response
requestXml: string
responseXml: string
}

The result of call().

FieldTypeRequiredDescription
dataTNoThe response element, converted according to the operation’s output field. Set only when the call succeeded.
errorSoapFaultNoSet for a SOAP fault, an HTTP error status, or a response that is not a SOAP envelope.
requestRequestYesThe HTTP request that was sent.
responseResponseYesThe HTTP response. Its body has already been read.
requestXmlstringYesThe SOAP envelope that was sent.
responseXmlstringYesThe response body as text.

Availability: Server

interface SoapFault {
code: string
message: string
detail?: unknown
}

An error returned by the service or the HTTP layer.

FieldTypeRequiredDescription
codestringYesThe fault code, or HTTP <status> for HTTP errors and invalid responses.
messagestringYesThe fault text, or the HTTP status text.
detailunknownNoContent of the fault’s detail element, read without type conversion.

Availability: Server