Sage X3 SOAP Web Services: Architecture, Operations, and Limitations

TL;DR

• Bottom line: Sage X3 exposes SOAP web services via the CAdxWebServiceXmlCC generic service using RPC/encoded style. Published X3 objects and subprograms are callable through CRUD, query, import/export, and subprogram operations. For new development, evaluate whether the REST/SData 2.0 Web API meets your needs first - SOAP is the only option for write operations on classic (non-service-oriented) modules. [src1, src2]
• Key limit: Data volume is license-controlled (WSSIZELIMIT in MB per WSPERIOD). Exceeding the limit does not reject calls but progressively throttles speed by the WSGRACESLOWDOWN factor. Pool concurrency is bounded by the Maximum Size setting per node.js process. [src1]
• Watch out for: The WSDL endpoint URL changed in PU9 from /adxwsvc/services/CAdxWebServiceXmlCC?wsdl to /soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl. The old WSDL still validates but calls silently fail at runtime. [src4]
• Best for: Write operations (create, modify, delete) on classic X3 objects, import/export file-based data exchange, and executing custom subprograms. [src1, src2]
• Authentication: Basic authentication (username/password) for on-premise; OAuth 2.0 for Sage X3 Online (cloud). Certificate authentication available for on-premise. [src2]

System Profile

Sage X3 (also known as Sage Enterprise Management) is a mid-market ERP system that exposes its business logic through SOAP web services. The SOAP interface has been available since V6 and remains the primary mechanism for write operations on classic modules - the REST/SData 2.0 Web API provides read-only access to classic module data. This card covers the SOAP web services architecture in V12 (PU9 and later), which introduced significant changes to endpoint URLs, authentication, and pool management. [src1, src2, src4]

API Surfaces & Capabilities

Sage X3 offers two primary API surfaces. SOAP is the mature, full-featured option for classic modules. REST (SData 2.0) is the modern successor, but only supports write operations on service-oriented (migrated) modules. [src1, src2]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Concurrency Limits

Authentication

Sage X3 SOAP web services support three authentication mechanisms, with availability depending on deployment model. [src2]

Authentication Gotchas

• PU9 changed authentication from SOAP context to HTTP headers. Old integration code that embeds credentials in the SOAP context will silently authenticate against the wrong user or fail. [src4]
• Web service user must have explicit authorization for web services access in Setup > Users > Users. Standard user accounts without this flag will be rejected. [src5]
• User password must never expire. Expired passwords cause pool startup failures. [src5]
• OAuth 2.0 is cloud-only. Basic and certificate authentication are unavailable on Sage X3 Online. [src2]

Constraints

• RPC/encoded SOAP style limits client compatibility - many modern SOAP libraries default to Document/Literal and have poor or no support for RPC/encoded. [src1, src4]
• Objects must be explicitly published as web services before they are accessible via SOAP. [src5]
• Any object modification requires re-validation of all changed entities AND republication of the web service. Failing to republish causes silent data errors. [src5]
• Pool clients consume server resources even when idle. Over-provisioning pools degrades server performance. [src3, src6]
• Data volume licensing controls throughput, not access. Exceeding WSSIZELIMIT silently throttles speed without clear error messages. [src1]
• SOAP services are in maintenance mode. Sage is progressively migrating modules to REST/SData 2.0. [src2]

Integration Pattern Decision Tree

START - User needs to integrate with Sage X3
|-- What operations are needed?
|   |-- Read-only data access
|   |   |-- Module is service-oriented (migrated)?
|   |   |   |-- YES --> Use REST/SData 2.0 Web API (simpler, JSON, modern)
|   |   |   |-- NO --> REST provides read-only representations; sufficient for reads
|   |   |-- Need complex queries with criteria?
|   |       |-- YES --> SOAP query with listSize and criteria parameters
|   |       |-- NO --> REST GET with $filter is simpler
|   |-- Write operations (create, modify, delete)
|   |   |-- Module is service-oriented?
|   |   |   |-- YES --> REST POST/PUT/DELETE available
|   |   |   |-- NO --> SOAP is required (only write path for classic modules)
|   |-- Batch import/export
|   |   --> SOAP import/export (AOWSIMPORT/AOWSEXPORT) operations
|   |-- Execute custom business logic (subprograms)
|       --> SOAP subprogram call (only available via SOAP)
|-- What's the deployment model?
|   |-- On-premise --> Basic auth or certificate auth
|   |-- Sage X3 Online (cloud) --> OAuth 2.0 (mandatory)
|-- What's the data volume?
|   |-- < WSSIZELIMIT per period --> Normal speed
|   |-- > WSSIZELIMIT --> Speed throttled by WSGRACESLOWDOWN factor
|   |-- > WSSIZELIMIT + WSGRACELIMIT --> Maximum throttling until period resets
|-- Pool sizing?
    |-- Low volume (< 100 calls/hour) --> Init: 1, Max: 2
    |-- Medium volume (100-1000 calls/hour) --> Init: 2, Max: 4-6
    |-- High volume (> 1000 calls/hour) --> Init: 4, Max: 8 (avoid > 8 init)
    |-- Schedule periodic pool restarts (daily/weekly) for stability

Quick Reference

Step-by-Step Integration Guide

1. Configure the SOAP pool in Syracuse administration

Navigate to Administration > Administration > Web Services > Classic SOAP pools configuration. Create a pool with alias, endpoint, locale, user, password, initialization size, and maximum size. Always enable "Auto start". [src3, src8]

Pool Configuration:
  Alias:             MYPOOL
  Endpoint:          MAIN (your X3 endpoint name)
  Locale:            English (United States)
  User:              WSUSER (dedicated web service user)
  Maximum Size:      4
  Initialization Size: 2
  Auto Start:        checked

Verify: Navigate to the pool list and confirm status shows green (active).

2. Set up the web service user in X3

Create a dedicated user for web services in Setup > Users > Users. The user must have web services connection authorization, standard authentication type, and password set to never expire. [src5]

User Setup:
  Login:              WSUSER
  Authentication:     Standard
  Password Expires:   Never
  Web Services Auth:  Enabled

Verify: Attempt to log in as the WSUSER via the X3 web interface to confirm the account is active.

3. Publish the target object as a web service

Navigate to Administration > Web Services > Classic SOAP Web services. Select the object to publish and click Publish. Re-validate all changed entities before republishing. [src5]

Verify: Use the built-in web service tester to invoke a read operation and confirm data returns.

4. Consume the WSDL and make a SOAP call

Retrieve the WSDL from the Syracuse server using the PU9+ endpoint URL. Add HTTP Basic Authentication headers to all requests. [src1, src4]

# Input:  Syracuse server URL, pool alias, X3 credentials
# Output: Query results from a published web service object

import requests
from requests.auth import HTTPBasicAuth

SYRACUSE_URL = "https://your-x3-server:8124"
POOL_ALIAS = "MYPOOL"

soap_body = """<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wss="http://www.adonix.com/WSS">
  <soapenv:Body>
    <wss:query>
      <callContext>
        <codeLang>ENG</codeLang>
        <poolAlias>MYPOOL</poolAlias>
        <requestConfig>adxwss.optreturn=JSON</requestConfig>
      </callContext>
      <publicName>SOH</publicName>
      <objectKeys><key/></objectKeys>
      <listSize>10</listSize>
    </wss:query>
  </soapenv:Body>
</soapenv:Envelope>"""

response = requests.post(
    f"{SYRACUSE_URL}/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC",
    data=soap_body,
    headers={"Content-Type": "text/xml; charset=utf-8"},
    auth=HTTPBasicAuth("WSUSER", "password"),
    verify=True
)
print(f"Status: {response.status_code}")
print(response.text)

Verify: Response contains <status>1</status> (success) and resultXml with queried records.

Code Examples

Python: Read a Sales Order by Key

# Input:  Syracuse URL, pool alias, credentials, sales order number
# Output: Sales order details in JSON format

import requests
from requests.auth import HTTPBasicAuth
import xml.etree.ElementTree as ET

SYRACUSE_URL = "https://your-x3-server:8124"
POOL_ALIAS = "MYPOOL"
ORDER_NUMBER = "SO000123"

soap_body = f"""<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wss="http://www.adonix.com/WSS">
  <soapenv:Body>
    <wss:read>
      <callContext>
        <codeLang>ENG</codeLang>
        <poolAlias>{POOL_ALIAS}</poolAlias>
        <requestConfig>adxwss.optreturn=JSON</requestConfig>
      </callContext>
      <publicName>SOH</publicName>
      <objectKeys>
        <key>{ORDER_NUMBER}</key>
      </objectKeys>
    </wss:read>
  </soapenv:Body>
</soapenv:Envelope>"""

resp = requests.post(
    f"{SYRACUSE_URL}/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC",
    data=soap_body,
    headers={"Content-Type": "text/xml; charset=utf-8"},
    auth=HTTPBasicAuth("WSUSER", "password"),
    verify=True
)

root = ET.fromstring(resp.text)
ns = {"wss": "http://www.adonix.com/WSS"}
status = root.find(".//status", ns)
if status is not None and status.text == "1":
    result_xml = root.find(".//resultXml", ns)
    print("Success:", result_xml.text)
else:
    messages = root.findall(".//message", ns)
    for msg in messages:
        print("Error:", msg.text)

C#/.NET: Consume SOAP Web Service with Basic Auth

// Input:  Syracuse URL, pool alias, web service user credentials
// Output: Query results via CAdxWebServiceXmlCC

// Custom class to inject Basic Auth headers (required for PU9+)
public class X3WebService : CAdxWebServiceXmlCCService
{
    public string Username { get; set; }
    public string Password { get; set; }

    protected override System.Net.WebRequest GetWebRequest(Uri uri)
    {
        var request = base.GetWebRequest(uri);
        string credentials = Convert.ToBase64String(
            System.Text.Encoding.ASCII.GetBytes($"{Username}:{Password}"));
        request.Headers["Authorization"] = $"Basic {credentials}";
        return request;
    }
}

var service = new X3WebService
{
    Url = "https://x3server:8124/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC",
    Username = "WSUSER",
    Password = "password"
};

var context = new CAdxCallContext { codeLang = "ENG", poolAlias = "MYPOOL" };
var result = service.query(context, "SOH", new CAdxParamKeyValue[0], 10);
if (result.status == 1) Console.WriteLine(result.resultXml);

cURL: Quick SOAP query test

# Input:  Syracuse URL, pool alias, credentials
# Output: SOAP response with queried records

curl -X POST \
  "https://x3server:8124/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC" \
  -u "WSUSER:password" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wss="http://www.adonix.com/WSS">
  <soapenv:Body>
    <wss:query>
      <callContext>
        <codeLang>ENG</codeLang>
        <poolAlias>MYPOOL</poolAlias>
        <requestConfig>adxwss.optreturn=JSON</requestConfig>
      </callContext>
      <publicName>SOH</publicName>
      <objectKeys><key/></objectKeys>
      <listSize>5</listSize>
    </wss:query>
  </soapenv:Body>
</soapenv:Envelope>'

Data Mapping

SOAP Response Format Reference

CAdxCallContext Field Reference

Data Type Gotchas

• Date fields may return in X3 internal format (YYYYMMDD) rather than ISO 8601. Parse carefully. [src1]
• Numeric precision depends on X3 field definition; currency fields have variable decimal places. [src1]
• Multi-line fields use pipe separator in import/export. Your parser must handle the I_RECORDSEP substitution. [src7]
• SOAP envelope must specify charset=utf-8. Non-UTF-8 characters cause parsing failures. [src1]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Pool stops responding after error cascade: Prior errors leave pool clients in corrupted state. Fix: Schedule automated daily/weekly pool restarts via REST API stop/start endpoints. [src6]
• WSDL validates but calls fail after PU9 upgrade: Old WSDL endpoint still serves valid WSDL but runtime calls fail silently. Fix: Update to /soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl [src4]
• Object modification breaks web service without warning: Changes to Entry Transactions, Screens, or Objects invalidate the published service. Fix: Re-validate and republish after ANY object modification. [src5]
• Data volume throttling causes unpredictable slowdowns: Exceeding WSSIZELIMIT silently throttles speed without error messages. Fix: Monitor data volume usage; log CAdxTechnicalInfos.totalDuration to detect slowdowns. [src1]
• Pool client language/user mismatch: When all matching clients are busy, pool may assign a client with different language/user context. Fix: Size pools for concurrent load; use poolId for critical operations. [src1]

Anti-Patterns

Wrong: Using the old WSDL endpoint URL after PU9 upgrade

# BAD - old endpoint still returns a WSDL but calls fail at runtime
wsdl_url = "http://x3server:8124/adxwsvc/services/CAdxWebServiceXmlCC?wsdl"

Correct: Use the PU9+ Syracuse WSDL endpoint

# GOOD - correct endpoint for PU9 and later
wsdl_url = "http://x3server:8124/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl"

Wrong: Embedding credentials in the SOAP context body (pre-PU9 style)

<!-- BAD - PU9+ ignores credentials in SOAP body -->
<callContext>
  <codeLang>ENG</codeLang>
  <poolAlias>MYPOOL</poolAlias>
  <codeUser>ADMIN</codeUser>
  <password>secret</password>
</callContext>

Correct: Use HTTP Basic Authentication headers

# GOOD - PU9+ requires HTTP Basic Auth
import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    soap_url, data=soap_envelope,
    headers={"Content-Type": "text/xml; charset=utf-8"},
    auth=HTTPBasicAuth("WSUSER", "password")
)

Wrong: Never restarting the pool

# BAD - pools accumulate state corruption over time
# Set up pool once, never restart, wonder why calls fail after weeks

Correct: Schedule periodic pool restarts

# GOOD - automated daily pool restart via Syracuse REST API
curl -X POST -u "admin:password" \
  "http://x3server:8124/api1/syracuse/collaboration/syracuse/soapClassicPools('POOL_UUID')/$service/stop"
sleep 10
curl -X POST -u "admin:password" \
  "http://x3server:8124/api1/syracuse/collaboration/syracuse/soapClassicPools('POOL_UUID')/$service/start"

Common Pitfalls

• Over-provisioning pool initialization size: Setting initialization size > 8 can cause timeout errors during pool startup. Fix: Start with init size 2, max 4. Scale up based on observed needs, never > 8 for init. [src3, src5]
• Not monitoring CAdxTechnicalInfos metrics: Every response includes timing data. Ignoring these means missing early warnings of pool saturation. Fix: Log technicalInfos from every response. Alert when poolWaitDuration > 5s or totalDuration > 30s. [src1]
• Using the built-in tester as proof of production readiness: The X3 tester runs in the same server context with no network overhead. Fix: Test from the actual integration client with production-like conditions. [src5]
• Ignoring the Save button on web service definitions: Enabled Save button means the underlying object changed and the service needs republication. Fix: Include web service republication in your change management process. [src5]
• Assuming REST can replace SOAP for all operations: REST/SData 2.0 only supports writes on service-oriented modules. Fix: Check whether the target module has been migrated before choosing REST. [src2]
• Not handling partial success in import operations: Import may partially succeed with status=1 but individual record errors in messages. Fix: Always parse the messages array for record-level errors even when status is 1. [src7]

Diagnostic Commands

# Get WSDL to verify endpoint is accessible
curl -u "WSUSER:password" \
  "https://x3server:8124/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl" \
  -o wsdl.xml

# Check pool status via Syracuse REST API
curl -u "admin:password" \
  "http://x3server:8124/sdata/syracuse/collaboration/syracuse/soapClassicPools?representation=soapClassicPool.\$query" \
  -H "Accept: application/json" | python -m json.tool

# Stop a pool (use pool UUID from status query)
curl -X POST -u "admin:password" \
  "http://x3server:8124/api1/syracuse/collaboration/syracuse/soapClassicPools('POOL_UUID')/\$service/stop"

# Start a pool
curl -X POST -u "admin:password" \
  "http://x3server:8124/api1/syracuse/collaboration/syracuse/soapClassicPools('POOL_UUID')/\$service/start"

# Quick SOAP read test to verify auth and pool connectivity
curl -X POST -u "WSUSER:password" \
  "https://x3server:8124/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wss="http://www.adonix.com/WSS"><soapenv:Body><wss:query><callContext><codeLang>ENG</codeLang><poolAlias>MYPOOL</poolAlias><requestConfig>adxwss.optreturn=JSON</requestConfig></callContext><publicName>SOH</publicName><objectKeys><key/></objectKeys><listSize>1</listSize></wss:query></soapenv:Body></soapenv:Envelope>'

Version History & Compatibility

Deprecation Policy

Sage does not publish a formal API deprecation timeline for X3 SOAP web services. The progressive migration of modules to service-oriented architecture indicates SOAP is in long-term maintenance mode. No sunset date announced, but new investment is directed toward REST/SData 2.0. [src2]

When to Use / When Not to Use

Important Caveats

• SOAP web services are in maintenance mode. Sage is progressively migrating X3 modules to REST/SData 2.0. New features are not being added to the SOAP layer. [src2]
• Data volume licensing parameters (WSSIZELIMIT, WSPERIOD, WSGRACELIMIT, WSGRACESLOWDOWN) vary by license tier and are not publicly documented. Contact your Sage account manager for your specific limits. [src1]
• Pool behavior and performance vary significantly between on-premise and Sage X3 Online (cloud) deployments. Cloud deployments have additional infrastructure-level throttling.
• The RPC/encoded SOAP style is increasingly unsupported by modern tooling. Test your SOAP client library's compatibility before committing. [src1, src4]
• All configuration, pool management, and web service publication must be done by a Sage X3 administrator with Syracuse access.