X3 SOAP Web Services

X3 SOAP Web Services

Skill for creating, deploying, and calling Classic SOAP sub-program web services on a Sage X3 install. Use when:

• Writing or editing a .src 4GL subprog that will be exposed via SOAP
• Building or fixing a SOAP envelope to call an X3 web service
• Diagnosing why a SOAP call returns empty / no output
• Deploying changes to a service (publication, pool restart)
• Creating a new web service publication entry

Architecture

A working X3 Classic SOAP web service has four parts:

1. 4GL source file (.src) containing a Subprog <NAME>(...) declaration in TRT directory.
2. Subprograms dictionary entry registering the subprog (Subprograms record with Web services ticked).
3. Publication in GESAWE (Classic SOAP web services) with a parameter Mapping.
4. Pool worker (Classic SOAP pool, e.g. WSBUILD) that loads and runs the compiled wrapper WJ<NAME>.

A SOAP call hits Syracuse → assigns to a pool worker → optional CHGUSR → reads HORDAT → loads wrapper WJ<NAME> → calls subprog → returns.

Naming

• Service codes are limited to 10 characters (X3 internal limit; longer names truncate silently and break dictionary lookups).
• Custom services use a Z prefix by Ramsden convention (e.g. ZWEMSTAGE = Z + Write + EMStage).
• The Subprog declaration name, the File/Subprograms fields in the dict, and the GESAWE publication name all match.

4GL syntax gotchas (Adonix)

• Line continuation is & (not _). Trailing underscore = Illegal character compile error.
• Use Return (not End) to exit a Subprog early. End halts the entire Adonix process.
• Files: declare with the table code, alias the abbreviation:

  Local File BPCUSTOMER [BPC]
  

  Then use Read [BPC]BPC0 = ... and [F:BPC]field = .... Without the declaration, file ops silently no-op at runtime.
• String concat: +. No +=.
• Trace keyword isn't reliably available — don't depend on it for diagnostics. Set O_RETCODE to numeric breadcrumbs (10, 20, …) instead.
• For/Next: explicit loop variable on Next (Next WI) on stricter parsers.

SOAP envelope — boilerplate

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wss="http://www.adonix.com/WSS"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header/>
  <soapenv:Body>
    <wss:run soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <callContext xsi:type="wss:CAdxCallContext">
        <codeLang xsi:type="xsd:string">ENG</codeLang>
        <poolAlias xsi:type="xsd:string">WSBUILD</poolAlias>
        <requestConfig xsi:type="xsd:string">adxwss.optiontype=adxwss.optiontype.multi&amp;adxwss.trace.on=on&amp;adxwss.beautify=true</requestConfig>
      </callContext>
      <publicName xsi:type="xsd:string">YOURSERVICE</publicName>
      <inputXml xsi:type="xsd:string"><![CDATA[<PARAM>
... see input format below ...
</PARAM>]]></inputXml>
    </wss:run>
  </soapenv:Body>
</soapenv:Envelope>

requestConfig flags

• Separator is & (XML-escape as &), not |.
• adxwss.trace.on=on — essential while debugging; without it the response trace is empty.
• adxwss.optiontype=adxwss.optiontype.multi — forces per-call session reset; gives per-worker CHGUSR rather than once-per-pool-cycle.
• adxwss.beautify=true — pretty-prints the response.

inputXml — by Dimension

The publication groups parameters into screen-style groups (GRP1, GRP2, …). The Mapping tab in GESAWE shows the layout; the XML view button gives the canonical schema (saved as <service>.xml).

Scalar group (Dimension = 1) — use <GRP>

<GRP ID="GRP2">
  <FLD NAM="I_NEW_STAGE">6</FLD>
  <FLD NAM="I_OTHER_PARAM">value</FLD>
</GRP>

Array group (Dimension > 1) — use <TAB> with <LIN> rows

<TAB ID="GRP1">
  <LIN><FLD NAM="I_BPCNUM">425073</FLD></LIN>
  <LIN><FLD NAM="I_BPCNUM">400044</FLD></LIN>
  <LIN><FLD NAM="I_BPCNUM">425099</FLD></LIN>
</TAB>

Mixing both works — group your scalars, TAB your arrays:

<PARAM>
  <TAB ID="GRP1">
    <LIN><FLD NAM="I_BPCNUM">425073</FLD></LIN>
    <LIN><FLD NAM="I_BPCNUM">400044</FLD></LIN>
  </TAB>
  <GRP ID="GRP2">
    <FLD NAM="I_NEW_STAGE">6</FLD>
  </GRP>
</PARAM>

ID matches the group code from the Mapping tab. Attributes use NAM (3 chars), not NAME.

Pool / auth quirks

• Each pool worker has multiple X3 sessions. Only the first session in a worker to receive a CHGUSR for a given user gets that user; subsequent sessions stay as the pool's default user (admin).
• Result: without multi mode, ~1 successful call per pool restart. With multi, ~1 successful call per worker per cycle (≈2 with the default 2-channel install).
• Design services as batch (array input + 4GL loop) to sidestep the cap entirely. A single SOAP call can update N records.
• Pool config (Classic SOAP pools configuration in Syracuse admin):
  • Lifetime (mn) controls auto-respawn. Set to 5 in dev for fast cycling, 720+ in prod.
  • Maximum size doesn't reduce worker count below 2 on the Ramsden install — channels are architectural.
  • Stop/Start does NOT change worker PIDs; only Lifetime auto-respawn truly recycles processes.

Deploy pipeline

Each change requires:

1. Update .src source — paste into Scripts editor (Folder=BUILD, Directory=TRT, Type=SRC), Compile (silent on success).
2. Update Subprograms dictionary entry if signature/dimensions changed.
3. Click Publication on the GESAWE Web Services record. Watch the Published the timestamp tick — if it doesn't, Publication didn't take. Re-clicking is sometimes needed.
4. Stop / Start the pool workers (Classic SOAP pools → Actions). Reminder: this doesn't actually replace processes; for a clean reload, wait for Lifetime auto-respawn.
5. In the next call's trace, confirm WW_HORDAT matches the new Published the.

Direct URL navigation (when search is broken or menus are bare)

Pattern:

https://<host>/syracuse-main/html/main.html?url=%2Ftrans%2Fx3%2Ferp%2F<ENDPOINT>%2F%24sessions%3Ff%3D<FUNC>%252F2%252F%252FM%252F%26profile%3D~(loc~%27en-GB~role~%27<ROLE_GUID>~ep~%27<EP_GUID>~appConn~())

Fastest way to extract the right profile=... tail: open any working X3 function tab and copy its URL — everything except the f%3D... segment is reusable.

Common function codes:

• GESAWE — Classic SOAP web services / publication editor
• ADOTRT — Scripts editor (compile/edit .src)
• GESAUS — X3 user maintenance
• GESADS — Folders maintenance

Diagnostics — reading the trace

In the response's traceRequest CDATA, look for:

• Call X3 subprogram 'CHGUSR:CHGLOGINXTEND' — present means user-switch fired.
• Call X3 subprogram 'WJ<NAME>:<NAME>' — present means the wrapper ran.
• Result parameters: [...] — populated O_* values come back here as {"num":N, "resu":..., "descr":"...", "grp":"..."} entries.
• processReport [err] lines — explicit error messages from the dispatcher.
• Result (0) with empty Technical parameters: [] and poolExecDuration ≈ 1ms — wrapper short-circuited before subprog body ran (auth/cache/empty-input issue).

Common error decoder

Reference: scalar subprog

##############################################################################
# Set ZEMSTAGE on a single BP Customer.
##############################################################################

Subprog ZWEMSTAGE(I_BPCNUM, I_NEW_STAGE, O_RETCODE, O_ERRMSG)
Value   Char    I_BPCNUM()
Value   Integer I_NEW_STAGE
Variable Integer O_RETCODE
Variable Char    O_ERRMSG()

Local File BPCUSTOMER [BPC]

Trbegin [BPC]
Read [BPC]BPC0 = I_BPCNUM
If fstat
  O_RETCODE = 1
  O_ERRMSG  = "Customer not found"
  Rollback : Return
Endif
[F:BPC]ZEMSTAGE = I_NEW_STAGE
Rewrite [F:BPC]
If fstat
  O_RETCODE = 4
  O_ERRMSG  = "Write failed"
  Rollback : Return
Endif
Commit
O_RETCODE = 0
O_ERRMSG  = "OK"
Return

End

Reference: batch subprog with array input (the ZWEMSTAGE shape)

##############################################################################
# ZWEMSTAGE - Set ZEMSTAGE on a batch of BP Customer records.
#
# Inputs  : I_BPCNUM     array of customer codes (up to 100)
#           I_NEW_STAGE  target stage applied to every customer in the batch
# Outputs : O_COUNT      number of records successfully updated
#           O_FAIL_LIST  comma-separated list of customer codes that failed
#           O_ERRMSG     human-readable summary
#
# Empty slots in I_BPCNUM stop the loop, so caller can leave trailing
# elements blank without padding.
##############################################################################

Subprog ZWEMSTAGE(I_BPCNUM, I_NEW_STAGE, O_COUNT, O_FAIL_LIST, O_ERRMSG)
Value   Char    I_BPCNUM()(0..100)
Value   Integer I_NEW_STAGE
Variable Integer O_COUNT
Variable Char    O_FAIL_LIST()
Variable Char    O_ERRMSG()

Local File BPCUSTOMER [BPC]
Local Integer WI, WTRIED

O_COUNT     = 0
O_FAIL_LIST = ""
WTRIED      = 0

For WI = 0 To 99
  If I_BPCNUM(WI) = "" : Break : Endif
  WTRIED = WTRIED + 1

  Trbegin [BPC]
  Read [BPC]BPC0 = I_BPCNUM(WI)
  If fstat
    Rollback
    O_FAIL_LIST = O_FAIL_LIST + I_BPCNUM(WI) + ","
  Else
    [F:BPC]ZEMSTAGE = I_NEW_STAGE
    Rewrite [F:BPC]
    If fstat
      Rollback
      O_FAIL_LIST = O_FAIL_LIST + I_BPCNUM(WI) + ","
    Else
      Commit
      O_COUNT = O_COUNT + 1
    Endif
  Endif
Next

O_ERRMSG = "Updated " + num$(O_COUNT) + " of " + num$(WTRIED) + " to stage " + num$(I_NEW_STAGE)
Return

End

Reference: matching SOAP envelope (batch with TAB array)

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wss="http://www.adonix.com/WSS"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header/>
  <soapenv:Body>
    <wss:run soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <callContext xsi:type="wss:CAdxCallContext">
        <codeLang xsi:type="xsd:string">ENG</codeLang>
        <poolAlias xsi:type="xsd:string">WSBUILD</poolAlias>
        <requestConfig xsi:type="xsd:string">adxwss.optiontype=adxwss.optiontype.multi&amp;adxwss.trace.on=on&amp;adxwss.beautify=true</requestConfig>
      </callContext>
      <publicName xsi:type="xsd:string">ZWEMSTAGE</publicName>
      <inputXml xsi:type="xsd:string"><![CDATA[<PARAM>
  <TAB ID="GRP1">
    <LIN><FLD NAM="I_BPCNUM">425073</FLD></LIN>
    <LIN><FLD NAM="I_BPCNUM">400044</FLD></LIN>
    <LIN><FLD NAM="I_BPCNUM">425099</FLD></LIN>
  </TAB>
  <GRP ID="GRP2">
    <FLD NAM="I_NEW_STAGE">6</FLD>
  </GRP>
</PARAM>]]></inputXml>
    </wss:run>
  </soapenv:Body>
</soapenv:Envelope>

Reference: caller bat

@echo off
set X3_USER=MHE
set X3_PASS="<password>"
set X3_URL=https://x3.ramsden-international.com/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC

curl -o response.txt -k -s -X POST ^
  -H "Content-Type: text/xml; charset=utf-8" ^
  -H "SOAPAction: \"\"" ^
  -u %X3_USER%:%X3_PASS% ^
  --data-binary "@envelope.xml" ^
  "%X3_URL%"

Ramsden install specifics

• Folders: X3 (reference), SEED, BUILD (development, full prod-like), RAMDATA, RAMLIVE (production financial system — off-limits for direct edits).
• Develop in BUILD. Pool used during dev: WSBUILD.
• The BUILD folder has BPCUSTOMER available via inheritance, but BPC.fde doesn't exist as a separate file — BPC is just the abbreviation for table BPCUSTOMER.
• Standard X3 BP table → abbreviation:
  • BPCUSTOMER → BPC
  • BPSUPPLIER → BPS
  • BPARTNER → BPR
• SOAP endpoint URL: https://x3.ramsden-international.com/soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC
• HTTP Basic Auth using the integration user's Syracuse credentials.
• Read EMStage back via the existing REST proxy:

  curl -s -H "APIKEY: <key>" "https://api.ramsden-international.com:8443/X3RestApiUAT/api/sagex3/customer?CustomerCode=425073" | jq -r ".responseData[0].customer.EMStage"
  

• Syracuse search server (Elasticsearch) intermittently unavailable on this install; use direct URLs (above) when search-by-function-code doesn't work.