How to Expose Sage X3 Web Services: Step-by-Step Tutorial (Version 12)

Exposing a Sage X3 Classic SOAP service requires a published Object or Subprogram, a Syracuse endpoint and pool, a validated contract, and proof of the business result. Production exposure also requires controlled retries, monitoring, and reversible publication changes. REST applies only when the required class, representation, and operation support it.

Step 1: Choose the Right Sage X3 V12 Service Surface

Sage X3 Version 12 includes more than one web service model. GESAWE publishes Classic SOAP services linked to legacy Objects and Subprograms. The REST Web API is linked to classes and representations. These models are not interchangeable, so the first design decision is the business operation and the application model that owns it.

Classic Objects and Subprograms use SOAP, while classes and representations use REST. Choose the service surface from the business operation and supported application model rather than from a client's preferred transport.

For read-heavy work, check for an appropriate representation first. Updates depend on the module and its business logic. Classic screen-based transactions may still require Classic SOAP. Newer Sage X3 Services and GraphQL capabilities have a separate component and release path, so a Version 12 label alone does not establish their availability.

Step 2: Define the Exposure Contract

A useful web service starts with a narrow contract. Write down the operation, caller, record keys, required data, business result, and failure behavior before opening GESAWE.

Record the Intended Business Operation

State the actual operation, such as create an e-commerce sales order, read an invoice by number, or query customers changed since a timestamp. Identify whether the caller reads, writes, or runs a command.

Then define these boundaries:

• Keys and Ownership: Identify the Sage X3 key, the external identifier used against duplicates, the system that owns each writable field, and the values Sage X3 calculates.
• Validation Route: Preserve Sage X3 business validation through the Object or controlled Subprogram rather than letting the external application write tables directly.
• Volume and Timing: Estimate peak record counts, line counts, request sizes, and acceptable response times.
• Error Contract: Decide which errors the client may retry, which require data correction, and what evidence operations staff need.

Create a Publication Register

Keep a register for every exposed service. Include the folder, Object or Subprogram, transaction when applicable, publicName, approved operations, authentication method, mapped X3 identity, pool alias, schema fingerprint, owner, and rollback procedure.

Use a customer or partner naming convention for custom records. A Y or Z prefix is common for customizations, with names such as YWSSOHECM. The name must also be stable, unique in its intended folder, and understandable to administrators.

Step 3: Prepare Syracuse, the Endpoint, and the Classic SOAP Pool

Publication in the Sage X3 folder and execution through Syracuse are separate stages. A valid GESAWE record does not create an available service if the endpoint or pool cannot supply a classic session.

Verify the Sage X3 Endpoint

A Syracuse endpoint maps the web tier to a Sage X3 solution and folder. Confirm that the intended endpoint references the correct server and folder, that the caller's groups allow access to it, and that a test endpoint cannot accidentally resolve to production. Verify the solution and server folder in the endpoint before creating its pool.

Restrict endpoint access through groups. Keep test and production identities, credentials, pool aliases, and activation procedures separate even when service names match.

Enable Dedicated Web Service Processes

Open the Syracuse Hosts administration page for each participating web tier host. Set Number of web services children to a nonzero value on the hosts intended to accept Classic SOAP traffic. The default can be zero, in which case calls fail with HTTP 500 and No Web services accepted.

Each child process receives its own copy of a pool configuration. The product of web service child processes and the pool's maximum size determines the possible channel count across the host. Start conservatively, measure queueing and server behavior, and change one capacity layer at a time.

Create the Classic SOAP Pool

In Syracuse, open Administration > Administration > Web services > Classic SOAP pools configuration and create a pool for the target endpoint. Configure these operational fields:

• Alias: Enter the stable value that callers will send as poolAlias. Treat case and spelling as contract data.
• Endpoint: Select the endpoint that resolves to the intended Sage X3 folder.
• Runtime Tags: Use matching tags when the pool must connect only to selected Sage X3 solution runtimes.
• Locale and User: Set the channel initialization language and user. The call context can change language; the authenticated user's endpoint login map determines the X3 user.
• Initialization Size: Set the number of clients created per Node.js web service process when the pool starts.
• Maximum Size: Set the maximum clients per Node.js web service process. Additional clients can start when all existing clients are busy.
• Timeouts: Set unused, lifetime, and queue timeouts from observed workloads. The defaults include 20 minutes unused and 720 minutes lifetime, but they are only starting points.
• Auto Start: Enable it when the service must return after Syracuse starts or a pool failure. Record any operational reason for manual-only startup.

Initialization and maximum pool sizes apply to each Node.js web service process. License controls do not set the channel count, but Sage X3 can control SOAP data volume. Capacity planning therefore needs server measurements and current license parameters.

Save the pool, select Start/Update, and confirm a ready state on every intended Node.js process. The client sub-grid identifies X3 sessions, users, languages, and access times. Changing the endpoint, user, locale, or sizes can reinitialize clients.

Map the Authenticated User to the X3 Folder Identity

Classic SOAP credentials authenticate at Syracuse. The old SOAP codeUser and password parameters are deprecated. Sage X3 determines the folder user through the authenticated Administration user's endpoint login mapping.

HTTP 401 normally means the login, password, certificate, or bearer token failed at Syracuse. A business authorization failure after HTTP 200 can mean the mapped X3 user lacks access to a function, company, site, transaction, or record.

On-premises deployments can support basic, client-certificate, and OAuth2 authentication. Send Basic credentials only over TLS. Sage X3 Online requires OAuth2 for the Web API. Hosted customers should confirm which administration settings their provider controls.

Step 4A: Publish a Sage X3 Object as a Classic SOAP Web Service

An Object publication exposes a contract derived from a Sage X3 Object and its screens. It is useful when the existing classic transaction provides the right business behavior and field model.

Open GESAWE and Create the Definition

Navigate to Development > Script dictionary > Scripts > Web services, or use function code GESAWE where direct access is allowed. Create a record and enter:

• Publication Name: Supply the external publicName, such as YWSSOHECM for a custom publication.
• Description: State the business operation and owner rather than repeating the Object name.
• Type: Select Object.
• Object: Select the intended Sage X3 Object.
• Transaction: Select the required transaction when that Object uses transactions.

The transaction shapes the exposed fields and behavior. A dedicated transaction can provide a smaller schema, but retain every required input and Sage-managed field.

Review the Generated Field Mapping

Use the Mapping tab to inspect groups, levels, field codes, internal names, parameter types, lengths, dimensions, mandatory indicators, and permitted ranges. GESAWE allows part of a service's fields to be selected. Hidden fields require special care: a publication can choose whether transmissible hidden fields are included, while non-transmitted hidden fields are never published.

Validate the schema with a minimum record, the highest expected line count, and optional values. This reveals missing groups and dimensions.

Publication creates a wrapper and XML structure for an Object or Subprogram. Sage X3 also prevents publishing the same Object-transaction pair twice under different names or varying only the hidden-field choice. If parallel external contracts are required, design distinct supported transactions or operations rather than attempting duplicate aliases for the same pair.

Create, Save, and Publish

Create and save the definition, then select Publication. Confirm that Published on, By, and Program are populated. The generated program uses the WJ plus publication-name convention, and Sage X3 creates XML and XSD descriptions for the service.

Publication makes the definition callable through the generic SOAP service. It does not make every generic operation valid. The Object, transaction, security, and business logic still determine which methods work.

After any change to screens, transaction setup, field selection, or related dictionary elements, republish in a controlled environment and compare the generated description with the previous fingerprint. A schema difference can break a mapping even if the publicName remains unchanged.

Step 4B: Publish a Custom 4GL Subprogram as a Web Service

A Subprogram publication is suitable when a bounded task does not map cleanly to a classic Object operation. Examples include a composite lookup, a controlled batch validation, or a response assembled from several application structures.

Design the Subprogram Contract

Define each parameter's name, data type, direction, length, and dimension. Bound array results and avoid universal routines that accept arbitrary tables, filters, or code fragments.

For retriable commands, define idempotency around a stable external request ID. Data-changing routines should use Sage X3 application logic and transaction handling, never direct table writes that bypass business controls.

Create and Register the 4GL Routine

Create the custom 4GL source in the approved development environment, compile it, and test it in the target development folder. In the Sage X3 Subprogram dictionary, register the source file and exact Subprogram name. Define the parameters in the same order and with the same directions and dimensions as the compiled routine.

Array dimensions must match the supported result size. Use a business limit and pagination or bounded selection for large variable results.

Publish the Registered Subprogram

Open GESAWE, create a custom publication name, select the Subprogram or non-Object service type, and associate the registered process and Subprogram. Review the Mapping tab, create and save the record, then publish it.

Subprogram publications use the generic SOAP run method rather than Object save or read. Verify every parameter through the generated service description before constructing the client payload. A code example copied from another folder is not a safe contract, even when the Subprogram name is identical.

Step 5: Discover the WSDL, Endpoint, and Published Schema

Classic SOAP publications do not create a unique WSDL URL for each publicName. Syracuse provides one generic RPC/encoded WSDL that describes the common methods. Each Object or Subprogram then has a generated description tied to its application code.

Use placeholders until the administrator confirms the externally reachable host and port:

WSDL:https://[SYRACUSE_HOST]:[PORT]/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdlService endpoint:https://[SYRACUSE_HOST]:[PORT]/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC

Import the WSDL into a client that supports SOAP RPC/encoded services. Retrieving it does not prove that the caller can authenticate or execute a publication. The generic Classic SOAP service includes tester operations such as run, save, read, query, and getDescription.

Call getDescription before building a request. Its resultXml describes groups, fields, keys, methods, dimensions, access modes, and the Object transaction. Save it as the integration's baseline contract.

The request uses these context fields and a publication identifier:

• Response Language (codeLang): Set the Sage X3 response language unless the supported HTTP language header supplies it.
• Pool Alias (poolAlias): Send the mandatory alias of the Classic SOAP pool.
• Pool Client (poolId): Leave this optional identifier empty for normal distribution and pin it only for controlled debugging.
• Response Configuration (requestConfig): Select the XML or JSON result format, readable formatting, and any bounded trace output.
• Publication Name (publicName): Pass the mandatory GESAWE publication name separately from callContext to the generic method.

Do not place credentials in deprecated SOAP context fields. Send the deployment's supported authentication at the HTTP layer and verify the user-to-endpoint login mapping.

Step 6: Test the Service from Transport to Business Outcome

Test in a non-production folder with representative configuration and master data. Start with the contract, then move to reads, writes, negative cases, and controlled load.

Run the Tests in This Order

• Transport Test: Retrieve the generic WSDL over the intended TLS route and confirm the certificate chain, hostname, proxy, and firewall path.
• Authentication Test: Call a harmless method and record the authenticated Syracuse identity and mapped X3 identity.
• Description Test: Call getDescription for the exact publicName. Fail the deployment if its schema fingerprint differs unexpectedly.
• Object Query and Read Tests: For an Object publication, query a small list, then read a known key. Verify filtering, limits, visibility, missing keys, and response parsing.
• Object Write Test: For an Object publication, use save only after confirming writable fields. Test a minimum record, duplicate ID, invalid master data, unauthorized site, and maximum expected lines.
• Subprogram Test: For a Subprogram publication, use run with minimum, maximum, empty, and invalid parameters. Verify dimensions and transaction behavior.
• Concurrency Test: Increase parallel requests gradually while watching queues, wait time, execution time, X3 sessions, and database behavior.

Generate request structures from the imported WSDL and the live getDescription output. A structural placeholder can help teams identify the moving parts, but it is not a runnable payload:

<METHOD_NAME> <callContext> <codeLang>[X3_LANGUAGE]</codeLang> <poolAlias>[POOL_ALIAS]</poolAlias> <poolId></poolId> <requestConfig>[CONTROLLED_RETURN_OPTIONS]</requestConfig> </callContext> <publicName>[GESAWE_PUBLICATION_NAME]</publicName> <METHOD_SPECIFIC_PAYLOAD>[GENERATED_FROM_GETDESCRIPTION]</METHOD_SPECIFIC_PAYLOAD></METHOD_NAME>

Object fields come from the selected transaction; Subprogram parameters come from its registered definition. Match every example to the target folder's generated description.

Validate the Complete Response

Classic SOAP returns a CAdxResultXml structure with messages, resultXml, status, and technicalInfos. HTTP and business status are separate:

• HTTP 200 with Body Status 1: The web function completed without a reported error. Validate the returned key and intended business result as well.
• HTTP 200 with Body Status 0: A technical or business error occurred. Parse every message and retain the relevant diagnostic context.
• HTTP 401: Authentication failed before the requested Sage X3 business operation ran.
• HTTP 500 with No Web Services Accepted: Syracuse has no enabled web service child process on the relevant host path.

HTTP status and the SOAP body status report different layers of the result. Store the source identifier, publicName, operation, timestamp, status, messages, and returned X3 key for reconciliation.

Use detailed trace only for bounded diagnosis. It can be large and contain business data. Disable it afterward and protect it like an integration payload.

How to Troubleshoot Common Sage X3 Web Service Failures

Classify failures by layer before changing a publication or pool. Similar symptoms can come from authentication, endpoint mapping, capacity, schema drift, or business validation.

For difficult runtime cases, create a time-bounded X3 session log targeted to the endpoint, service, pool, and user instead of tracing all traffic.

Do not answer queueing by raising every limit. Measure pool wait and execution separately, then fix slow validation, database contention, oversized requests, or long Subprograms at the responsible layer.

Step 7: How to Harden the Service for Production

Production readiness depends on identity, change control, error recovery, and measured capacity.

Apply Least Privilege and Network Controls

Use a dedicated integration identity and map it to an X3 user with only the required function, company, site, and data rights. Never retain a shared administrator identity merely because it eliminated test authorization errors.

Validate TLS certificates, restrict source networks where feasible, and keep secrets in an approved credential store. Rehearse credential rotation.

Control Retries and Duplicate Processing

Retry only failures likely to be temporary, such as a transient network interruption or bounded queue saturation. Business validation failures need correction before replay. Timeouts are ambiguous because the server may have committed the transaction even if the client did not receive the response.

Use a stable external idempotency key with serialized handling or supported uniqueness enforcement. A query-before-create check by itself can race when calls run concurrently. A delayed query can remain inconclusive while the original request is still processing or its result is not yet visible. After a timeout, reconcile the external reference and the Sage X3 result before deciding whether to resend. For Subprogram commands, make idempotency part of the routine contract.

Monitor Capacity and Business Outcomes

Pool Status exposes queues, completed calls, clients, users, and access times. SOAP technicalInfos can show wait and execution duration. Track:

• Technical Health: Track authentication failures, queue timeouts, body status 0 rates, pool wait time, execution time, and channel restarts.
• Business Health: Track requested and accepted records, duplicates, master-data failures, and unreconciled identifiers.
• Contract Health: Detect unexpected getDescription changes after patches, configuration deployments, or republishing.

Change capacity after a repeatable load test, and keep limits below the point where X3 contention reduces throughput.

Make Publication Changes Reversible

Before republishing, retain the definition, generated description, transaction reference, Subprogram version, and tests. Compare the new contract in non-production. Use a coordinated new contract when consumers cannot tolerate a breaking change.

Rollback can restore and republish a prior transaction or Subprogram, revert a mapping, or stop a new consumer. Unpublication alone creates an outage.

How to Connect Published Sage X3 Services with APPSeCONNECT

Once the Sage X3 service contract is stable, APPSeCONNECT can handle the integration workflow around it. APPSeCONNECT supports protocol-based adapters for SOAP and REST. Test the configured SOAP path against Sage X3's RPC/encoded contract and required published operations before relying on it in production.

A production ProcessFlow should make the Sage X3 contract explicit:

• Connection Configuration: Store the Syracuse endpoint, supported authentication, and environment-specific credentials.
• Request Construction: Map source fields only to inputs present in the current Object description or Subprogram parameters.
• Business Rules: Apply lookups and transformations before the SOAP call, while leaving Sage X3 responsible for its own validations and calculated fields.
• Response Handling: Parse HTTP status, body status, messages, and returned keys. Route body status 0 to correction rather than marking it successful.
• Concurrency Control: Keep execution and batches within the tested SOAP pool envelope.
• Reconciliation: Retain source and destination identifiers so operations can prove which records were created and which still need action.

APPSeCONNECT ProcessFlow uses GET, Mapper, and POST nodes to move and transform data. Its Sync Info and Retry capability records failed and unprocessed items for controlled resynchronization. Retry selected temporary failures under configured control; hold business errors for correction.Sync Info and Retry capability records failed and unprocessed items for controlled resynchronization. Retry selected temporary failures under configured control; hold business errors for correction.

Snapshots and node logs help support teams inspect transformations and responses. Protect them because ERP payloads can contain sensitive business data.

Conclusion

A reliable Sage X3 V12 web service has a narrow contract, verified identity path, measured pool, business-aware responses, and reversible release. Schema discovery, negative testing, monitoring, and reconciliation make the endpoint dependable.

If you need to connect a published Sage X3 service to another business application, APPSeCONNECT can map and operate the SOAP or REST workflow around that contract.

Talk to an APPSeCONNECT integration specialist about your Sage X3 service design.

Frequently Asked Questions