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
Functions
Section titled “Functions”call()
Section titled “call()”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.
| Parameter | Type | Description |
|---|---|---|
metadata | SoapServiceMetadata | Description of the service’s operations and types. |
operationName | string | Key of the operation in metadata.operations. |
input | unknown | Content 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. |
options | SoapCallOptions | Endpoint and request options. |
SoapCallOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
endpointUrl | string | Yes | URL the request is posted to. |
headers | Record<string, string> | No | Additional HTTP headers, for example authorization. They override the headers Lowgile sets. |
soapHeaderXml | string | No | Raw XML placed inside soap:Header, for example a WS-Security header. |
fetch | typeof fetch | No | fetch 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?.priceSoapServiceMetadata
Section titled “SoapServiceMetadata”interface SoapServiceMetadata { types: Record<string, SoapComplexType> operations: Record<string, SoapOperation>}Describes a SOAP service: its complex types by name, and its operations by name.
| Field | Type | Required | Description |
|---|---|---|---|
types | Record<string, SoapComplexType> | Yes | Complex types, referenced by name from SoapField.type. |
operations | Record<string, SoapOperation> | Yes | Operations, called by name with call(). |
Availability: Server
SoapOperation
Section titled “SoapOperation”interface SoapOperation { soapAction: string soapVersion: SoapVersion input: SoapField output: SoapField}One operation of the service.
| Field | Type | Required | Description |
|---|---|---|---|
soapAction | string | Yes | SOAP action, sent in the SOAPAction header (SOAP 1.1) or the action parameter of the content type (SOAP 1.2). |
soapVersion | SoapVersion | Yes | SOAP version, which decides the envelope namespace and content type. |
input | SoapField | Yes | The element sent as the child of soap:Body. |
output | SoapField | Yes | The element expected as the child of soap:Body in the response. |
Availability: Server
SoapField
Section titled “SoapField”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.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Local element name, also used as the property name in JavaScript values. |
ns | string | Yes | Namespace of the element; empty if the element is unqualified. |
type | string | Yes | A SoapPrimitiveType, or the name of a complex type in SoapServiceMetadata.types. |
isArray | boolean | No | If 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
SoapComplexType
Section titled “SoapComplexType”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
SoapPrimitiveType
Section titled “SoapPrimitiveType”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
SoapVersion
Section titled “SoapVersion”type SoapVersion = '1.1' | '1.2'SOAP protocol version.
Availability: Server
SoapRequestOptions
Section titled “SoapRequestOptions”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
SoapCallOptions
Section titled “SoapCallOptions”interface SoapCallOptions extends SoapRequestOptions { endpointUrl: string}SoapRequestOptions plus the endpoint URL. The fields are described under call().
Availability: Server
SoapCallResult
Section titled “SoapCallResult”interface SoapCallResult<T> { data?: T error?: SoapFault request: Request response: Response requestXml: string responseXml: string}The result of call().
| Field | Type | Required | Description |
|---|---|---|---|
data | T | No | The response element, converted according to the operation’s output field. Set only when the call succeeded. |
error | SoapFault | No | Set for a SOAP fault, an HTTP error status, or a response that is not a SOAP envelope. |
request | Request | Yes | The HTTP request that was sent. |
response | Response | Yes | The HTTP response. Its body has already been read. |
requestXml | string | Yes | The SOAP envelope that was sent. |
responseXml | string | Yes | The response body as text. |
Availability: Server
SoapFault
Section titled “SoapFault”interface SoapFault { code: string message: string detail?: unknown}An error returned by the service or the HTTP layer.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The fault code, or HTTP <status> for HTTP errors and invalid responses. |
message | string | Yes | The fault text, or the HTTP status text. |
detail | unknown | No | Content of the fault’s detail element, read without type conversion. |
Availability: Server
Related
Section titled “Related”- Service Integration API
- Service Integration
- Sys API overview