# SOAP Compat +

{% hint style="danger" %}
This component is only available to [Boxlang+/++ subscribers only](https://ww.boxlang.io/plans) but can be installed in conjunction with the [`bx-plus` Module](https://forgebox.io/view/bx-plus) with a limited trial.
{% endhint %}

The `bx-compat-soap` module provides comprehensive SOAP (Simple Object Access Protocol) web services functionality for BoxLang applications. It provides Compatibility for existing CFML Axis-based web services functionality. This module enables you to create and manage SOAP-based web services with automatic WSDL generation, request/response handling, and full support for complex data types.

### Features

* 🌐 **Automatic WSDL Generation** - Generate standards-compliant WSDL documents from BoxLang classes
* 🔄 **SOAP Request/Response Handling** - Parse and process SOAP envelopes with namespace support
* 🎯 **Type Coercion** - Automatic type conversion between SOAP XML types and BoxLang types
* 📋 **Metadata Extraction** - Extract function metadata for WSDL operation definitions
* 🚀 **Web Context Support** - Full integration with BoxLang web request/response cycle
* ⚡ **SOAPAction Routing** - Automatic routing based on SOAPAction headers or XML body

### Installation

Install the module using CommandBox:

```bash
box install bx-compat-soap
```

### Usage

#### Creating a SOAP Web Service

To create a SOAP web service, simply create a BoxLang class with `remote` methods:

```javascript
/**
 * Calculator Web Service
 */
class {
    
    /**
     * Add two numbers
     * @a First number
     * @b Second number
     * @return The sum
     */
    remote numeric function add( required numeric a, required numeric b ) {
        return arguments.a + arguments.b;
    }
    
    /**
     * Get user information
     * @userId The user ID to lookup
     * @return User struct
     */
    remote struct function getUser( required string userId ) {
        return {
            id: arguments.userId,
            name: "John Doe",
            email: "john@example.com"
        };
    }
    
    /**
     * Get list of users
     * @limit Maximum number of users to return
     * @return Array of user structs
     */
    remote array function getUsers( numeric limit = 10 ) {
        var users = [];
        for( var i = 1; i <= arguments.limit; i++ ) {
            users.append({
                id: i,
                name: "User #i#"
            });
        }
        return users;
    }
    
    /**
     * This method is NOT accessible via SOAP (not marked as remote)
     */
    public numeric function multiply( required numeric a, required numeric b ) {
        return arguments.a * arguments.b;
    }
}
```

#### Accessing the WSDL

The WSDL is automatically generated and accessible via the `?wsdl` parameter:

```
http://yourserver/path/to/Calculator.bx?wsdl
```

#### SOAP XML Request Format

Send SOAP requests to your service endpoint using standard SOAP envelope format:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <ns1:add soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            xmlns:ns1="http://DefaultNamespace">
            <a xsi:type="xsd:double">5.0</a>
            <b xsi:type="xsd:double">10.0</b>
        </ns1:add>
    </soapenv:Body>
</soapenv:Envelope>
```

#### SOAP Response Format

The service returns standard SOAP responses:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <addResponse xmlns="http://boxlang.ortussolutions.com/soap/">
            <return>15.0</return>
        </addResponse>
    </soap:Body>
</soap:Envelope>
```

#### Error Handling (SOAP Faults)

Errors are returned as standard SOAP faults:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <soap:Fault>
            <faultcode>Server</faultcode>
            <faultstring>Method not found or not accessible: multiply</faultstring>
            <detail>Only methods with access="remote" can be invoked via SOAP</detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>
```

### Consuming SOAP Web Services

#### Using createObject()

The easiest way to consume a SOAP web service is using BoxLang's `createObject()` function:

```javascript
// Create a SOAP web service instance
ws = createObject( "webservice", "http://example.com/Calculator.bx?wsdl" );

// Call methods directly on the web service object
result = ws.add( 5, 10 );
writeOutput( "5 + 10 = #result#" );

// Call methods with named arguments
user = ws.getUser( userId = "123" );
writeOutput( "User: #user.name# (#user.email#)" );

// Get multiple results
users = ws.getUsers( limit = 5 );
for( user in users ) {
    writeOutput( "#user.id#: #user.name#<br>" );
}
```

#### Advanced SOAP Client Usage

For more control over the SOAP request, you can configure the web service instance:

```javascript
// Create web service with custom configuration
ws = createObject( 
    "webservice", 
    "http://example.com/Calculator.bx?wsdl",
    {
        timeout: 30,
        username: "admin",
        password: "secret"
    }
);

// Call methods
result = ws.complexCalculation( 
    operation = "multiply",
    values = [1, 2, 3, 4, 5]
);
```

#### Handling SOAP Faults

SOAP faults are automatically converted to BoxLang exceptions:

```javascript
try {
    ws = createObject( "webservice", "http://example.com/Calculator.bx?wsdl" );
    
    // Try to call a non-remote method (will throw exception)
    result = ws.multiply( 5, 10 );
    
} catch( any e ) {
    writeOutput( "SOAP Error: #e.message#" );
    writeOutput( "Detail: #e.detail#" );
}
```

### Supported Data Types

#### Simple Types

* `string` → `xsd:string`
* `numeric` → `xsd:double`
* `boolean` → `xsd:boolean`
* `date` → `xsd:dateTime`

#### Complex Types

* `binary` → `xsd:base64Binary`
* `struct` → `apachesoap:map` or `xsd:complexType`
* `array` → Array type with sequential items
* `any` → `xsd:anyType`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-+-++/modules/soap-compat-+.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.