The X3 web services
Prerequisites
The XTEND server only accesses the X3 back-office via the X3 web services call to access the data or the user actions processing.
The XTEND developer must have a good knowledge on how to implement X3 web services before creating a XTEND application (architecture, connection pools, tests...).
However, any skills in development is required to program the web services call via the stub/proxy classes.
The server of web services
It is necessary to have at least on server of web services on which will be published the X3 sub-programs or objects used by the XTEND applications.
It is possible to select, for example, the same X3WEB server as the one that hosts the XTEND server.
The first step consists in ensuring that the server is correctly set up.
Identification of server
The server of web service is identified by a hostname and a tcp port. From now on, let's use the following hostname address: 28880.
SOAP/HTTP
Simple Object Access Protocol and Hypertext Transfer Protocol are the protocols used to call X3 web services
The server of web service must be accessible
Make sure the hostname:port address can be accessed from the XTEND server.
port is the port of the front web server. the default value is 28880
To do this, it is only necessary to check that the http://hostname:28880/root/ address displays the home page of the administration server after having entered the default password (sage/sage).
If the page is not displayed
- make sure that the Apache/Tomcat services are correctly launched
- make sure the 'ping hostname' order returns a response
The X3 solutions/folders must be published
All the X3 solutions/folders to which the XTEND applications access must be published on the X3WEB server which hosts the server of web services.
This operation is carried out by the administrator via the X3 console during the X3WEB server setup.
The list of published applications, accessible via the 'Home/Administration' menu
The connection pools must be started
Connection pools
The server of web services offers third-party applications, a group of X3 connections (X3 client of web service type) grouped by 'entry group' or 'pool'.
The connection pools are created and set up via the X3 console. The console is used, among others, to setup the number of connections of the pool.
The number of connections allocated to the pool determines the number of requests (SOAP) that can be simultaneously processed by this pool. When all the connections are occupied, the requests are put on hold.
Server configuration
The server of web service must have at least one connection pool (entry group) by solution/folder that publishes web services to the XTEND applications.
These connection pools must have the 'started' status and must have at least one free connection (<poolentry>) .
The list of connection pools is accessible via the 'Server of web services/Connection pools'function.
Response type
The response time of a XTEND application and so, the 'fluidity' of the web site highly depend on the response times obtained when calling the web services. We advise to control on a regular basis:
- The availability of the web services pool connections.
- Size correctly the number of pool connections (license web services)
- the charge rate of the X3 server
- Beware of the batch processings
Web service publication
The publication of web services is carried out by the function X3/
'Development/Processing dictionary/Processings./Web services'.
X3 Object web services
To publish an object web service, it is only necessary to create a web service record specifying the publication name (also called alias) and the object code (plus the transaction code).
Publishing a X3 object gives asset to all the actions of the object (read, create, record, delete by default) and to the left list.
The action button 'Delete' is used to 'unpublish' the web service.
Sub-program web services
To publish a sub-program web service, it is first and foremost necessary to create a sub-program record which is used to declare the publication parameters and groups via the function :
'Development>Processing dictionary>Processing>Sub-program'
Then, publish this web service (publication button) and assign an alias to it just like the object web service.
Publication groups
The publication groups are used to logically associate parameters (of identical size) to create distinct entities.
Each group (or entity) can be considered as a table recording or as a record or structure type.
They are used when setting up XTEND to carry out 'mappings' between the web services parameters and the XTEND entities.
For the sub-programs
Example for a sub-program that returns 6 parameters which represent a list of ship-to addresses (shipaddr, shipcity, shipzip) and also a list of invoicing addresses (invaddr, invcity, invzip). These parameters can be grouped in 2 entities or logical groups SHIPADDR and INVADDR.
For the objects
The names of publication groups are generated by X3. They correspond to the codes of the screen blocks.
Web services test
It is highly recommended to test the X3 objects or sub-program web services via the 'Web services tester' function from the X3WEB server before using them in a XTEND application.
Location of web services in XTEND
XTEND locates a web service by a unique identifier valid for all the XTEND sites of the X3 file.
This identifier refers to the web service location record which contains, among others, the destination of the web service server (hostname and port) et the alias of the connection pool.
Function
'Development>Utility>Miscellaneous>Pools Web services'