SOAP Web services implementation

The SOAP Web service implementation process is exactly the same as what was available through the GESAWE function in V6.

Syracuse Web services definition

IMPORTANT

Generic SOAP Web services are based on the use of classic clients. That means calling Web services will consume legacy X3 objets and subprograms exactly like in V6.

A soapGeneric entity provides a description of the generic Web service.

Pool definition

The pools are defined in the SOAP classic pool administration function, managed by the Syracuse administration framework.

The size of each pool (number of channels) is no longer controlled by the license. This means customers can create as many channels as they want. Of course, server sizing considerations need to be taken into account to size the pool. The license controls only the size of data exchanges. (See Licensing control chapter).

Load balancer

Web services can work with the Syracuse load balancer mode.

A new property in the host definition entity allows you to define how many Web services dedicated processes should be set on a Syracuse environment (Number of Web service child). By default this property is set to 0, so it is necessary to configure it. Otherwise, each Web service call will generate the HTTP 500 error with the specific message No Web services accepted.

As explained in , the pool definition document, each pool configuration is duplicated for each host Web services child process.

Licensing control

The licensing system does not limit the number of clients defined on pool configuration. The SOAP Web service implementation performed in the administration platform controls the data volume consumed by third party application consumers (in and out).

The license parameter is defined in the following document.

Four variables are defined through the license: WSSIZELIMIT, WSPERIOD, WSGRACELIMIT and WSGRACESLOWDOWN:

• WSSIZELIMIT: indicates the size (in Megabytes) of data that can be exchanged in incoming SOAP Web services (in and out)
• WSPERIOD: (a string that can be DAY, MONTH or YEAR) determines the period on which the size limitation applies
• WSGRACELIMIT: (as a percentage) defines the oversize percentage allowed (typically 10%); this means that if the maximum size is fixed at 1 MB / day, this means that:
  • 1 MB per day is possible without decreasing the speed of the Web services
  • The next 10% (100Kb) is possible at a lower speed
  • The service does not respond when the 1.1 MB limit is reached
• WSGRACESLOWDOWN: indicates the rate used to decrease the speed of the Web services when the grace limit is reached. Taking into account the value of the above variables 'WSSIZELIMIT' and 'WSGRACELIMIT', if, for example, 'WSPERIOD' is equal to 'DAY' and the value of WSGRACESLOWDOWN is 5, it means that:
  • When the 1 MB limit has been reached on a given day, the speed is divided by 5 until the end of the day
  • Speed slowdown continues until the 1.1 MB is reached
  • After that, the service stops

Web services calls

Requests

All the operations listed (in Tester forms section of the generic SOAP Web service documentation) take several parameters.

Common SOAP parameters

• callContext: this is a group of parameters where consumer need to define the following:
  • codeLang (can be optional if HTTP header accept-language is used, otherwise, it is mandatory): this parameter can take X3 language format (FRA, ENG, BRI...). If the consumer decides to use accept-language HTTP header, the ISO format is necessary (fr-FR, en-US, en-GB...).
  • codeUser is deprecated and no longer used !: The X3 user is determined by the Administration user endpoint login map.
  • password is deprecated as well.
  • poolAlias is mandatory, it corresponds to the Alias defined in the pool configuration.
  • poolId is optional; it allows you to force a specific client through a pool definition list. If no 'poolId' is set here, the client selection is done with an intelligent pool distributor algorithm (See Client selection algorithm).
• requestConfig: A set of configurations separated by '&' character:
  • adxwss.trace.on: value 'on' to be activated.
  • adonix.trace.on: value 'on' to be activated.
  • adonix.trace.level: Integer that defines runtime traces level.
  • adonix.trace.size: Integer that defines the CLOB size on runtime side.
  • adxwss.optreturn: Can be 'XML' or 'JSON'. Default value is 'XML'.
  • adxwss.beautify: Can be 'true' or 'false'. Set to true, response flow is formatted to be more readable.

CODECODE CODExml<callContext xsi:type="wss:CAdxCallContext"><codeLang xsi:type="xsd:string">FRA</codeLang><codeUser xsi:type="xsd:string"></codeUser><password xsi:type="xsd:string"></password><poolAlias xsi:type="xsd:string">SEED</poolAlias><poolId xsi:type="xsd:string"></poolId><requestConfig xsi:type="xsd:string"><![CDATA[adxwss.trace.on=on&adonix.trace.on=on&adonix.trace.level=3&adonix.trace.size=8&adxwss.optreturn=JSON&adxwss.beautify=true]]></requestConfig></callContext>

• publicName (mandatory) corresponds to the public name declaration done in GESAWE X3 function.

CODECODE CODExml<publicName xsi:type="xsd:string">WSBPC</publicName>

Specific SOAP parameters

They are the same as for V6. Please refer to V6 documentation.

Client selection algorithm

As explained in Common SOAP parameters section, the poolId parameter allows you to force a specific client usage (this can be really useful when a developer wants to debug 4GL code putting breakpoints into Eclipse after he attached to a specific process ID --> the same as poolId).

If no poolId parameter is provided (OR the required client is not free, OR the required process ID doesn't exist), an algorithm selects consumers with free clients to be served following these rules:

Are there free clients ?y --> Are there clients with same language and same user ?y --> Select (set busy) and use one of these clients as is.n --> Are there clients with the same user only ?y --> Select (set busy) and use one of these clients, then change language set.n --> Are there clients with the same language only ?y --> Select (set busy) and use one of these clients, then change user set.n --> Select the first client from those available and change context (language and user).n --> wait for next free client (no context preferences (language and user) will be taken into account.Context change applies)