Sage X3

Web Services
Level 1
Sage X3 Support to Business
10/20/2016
 Welcome!

• Who am I?
• Who are you?

• Bootcamp prerequisites reminder

• Timing, breaks & rules

Web Services Bootcamp
Agenda
1. What is a Web Service?
2. How to invoke SOAP X3 Web services Hands-on 1 – List of customers
from a web portal in PHP
3. Sage X3 Web Services Architecture Hands-on 2 – Publishing object SOH
4. Setting up Web Services
Hands-on 3 – Execute Web Service
5. Publication and Tests
YOSOH into Soapui
6. Updating the Web Portal PHP & How to add
products
7. Best practices & Performance
8. WS Limitations
9. New Web Services X3 (REST)
10. How to call external REST Web Services from X3

10/21/2016 3
 What you will learn

• A 360° understanding of Web

Services
• How to parameterize and test
Web Services
• How to use an external Web
Service to Sage X3
• To be fully autonomous to develop
a Web Service

10/21/2016 4
 1 - What is a Web
Service?
• Definition
• RESTful in Web Service
• SOAP

10/21/2016 5
Definition

A web service is a collection of open protocols and standards used for exchanging data between
applications or systems.
Software applications written in various programming languages and running on various platforms
can use web services to exchange data over computer networks, like the Internet, in a similar manner
to inter-process communication on a single computer.
Web services are based on protocols allowing standardization of the exchange.
X3 Web services embed several methods:
• Object: to execute a business process
• Sub programs: to run code
• List: to request data
Web services are a major web trend for web and mobile availability.

10/21/2016 6
What is a RESTful Web Service?

The following principles encourage RESTful applications to be simple, lightweight, and fast:
• Resource identification through URI: a RESTful Web Service exposes a set of resources that
identify the targets of the interaction with its clients. Resources are identified by URIs, which
provide a global addressing space for resource and service discovery.
• REST is an architectural style and a design for network-based software architectures.
• REST concepts are referred to as resources. A representation of a resource must be stateless. It
is represented via some media type. Some examples of media types include XML, JSON, and
RDF.
Resources are manipulated by components. Components request and manipulate resources via a
standard uniform interface. In the case of HTTP, this interface consists of standard HTTP ops e.g.
GET, PUT, POST, DELETE.

10/21/2016 7
What is a RESTful Web Service?

Client-Server Communication
Client-server architectures have a very distinct separation of concerns. All applications built in the
RESTful style must also be client-server in principle.

Stateless
Each client request to the server requires that its state be fully represented. The server must be able
to completely understand the client request without using any server context or server session state.
It follows that all state must be kept on the client.

Cacheable
Cache constraints may be used, thus enabling response data to be marked as cacheable or not-
cacheable. Any data marked as cacheable may be reused as the response to the same subsequent
request.

10/21/2016 8
What is a RESTful Web Service?

Uniform Interface
All components must interact through a single uniform interface. Because all component interaction
occurs via this interface, interaction with different services is very simple. The interface is the same!
This also means that implementation changes can be made in isolation. Such changes will not affect
fundamental component interaction because the uniform interface is always unchanged.
One disadvantage is that you are stuck with the interface. If an optimization could be provided to a
specific service by changing the interface, you are out of luck as REST prohibits this. On the bright
side, however, REST is optimized for the web, hence incredible popularity of REST over HTTP!

The above concepts represent defining characteristics of REST and differentiate the REST
architecture from other architectures like web services. It is useful to note that a REST service is a
web service, but a web service is not necessarily a REST service.

10/21/2016 9
What is SOAP?

SOAP (Simple Object Access Protocol) is a messaging protocol that allows programs that run on
disparate operating systems (such as Windows and Linux) to communicate using Hypertext Transfer
Protocol (HTTP) and its Extensible Markup Language (XML).

10/21/2016 10
What is SOAP?

Since Web protocols are installed and available for use by all major operating system platforms,
HTTP and XML provide an at-hand solution that allows programs running under different operating
systems in a network to communicate with each other. SOAP specifies exactly how to encode an
HTTP header and an XML file so that a program in one computer can call a program in another
computer and pass along information. SOAP also specifies how the called program can return a
response. Despite its frequent pairing with HTTP, SOAP supports other transport protocols as well.

SOAP defines the XML-based message format that Web service-enabled applications use to
communicate and inter-operate with each other over the Web. The heterogeneous environment of the
Web demands that applications support a common data encoding protocol and message format.
SOAP is a standard for encoding messages in XML that invoke functions in other applications.

10/21/2016 11
What is SOAP?

The Web Services Description Language (WSDL) is an XML-based interface definition

language that is used for describing the functionality offered by a web service.

10/21/2016 12
REST vs SOAP
The Difference Between Soap and Rest
• SOAP is a protocol. REST is an architectural style.
• SOAP stands for Simple Object Access Protocol. REST stands for REpresentational State Transfer.
• SOAP can't use REST because it is a protocol. REST can use SOAP web services because it is a concept and can
use any protocol like HTTP, SOAP.
• SOAP uses services interfaces to expose the business logic. REST uses URI to expose business logic.
• In Java JAX-WS is the java API for SOAP web services. In Java JAX-RS is the java API for RESTful web services.
• SOAP defines standards to be strictly followed. REST does not define too much standards like SOAP.
• SOAP requires more bandwidth and resource than REST. REST requires less bandwidth and resource than SOAP.
• SOAP defines its own security. RESTful web services inherits security measures from the underlying transport.
• SOAP permits XML data format only. REST permits different data format such as Plain text, HTML, XML, JSON etc.
• SOAP is less preferred than REST. REST more preferred than SOAP.
The X3 Web Services SOAP

With SAFE X3, you may publish Objects, Object Lists and Subprograms through Web Services that will make
them accessible to external applications through the internet:
• Public commercial web site that creates orders in X3
• Enterprise application other than X3
• Commercial sales application on a PDA
• …

The common links between those applications are:

• The need to access X3 in a fully synchronous way
• Maximum security (no data/text files transiting on the servers)

SAFE X3 Web Services fully comply with the public Web Service protocol. They are no longer proprietary as
were the ADAPI tools in the previous version.

X3 publishes a single web service that gives access to all objects and subprograms through the 3 different
methods.

October 16
X3 Web Service Methods
Three Methods
X3 publishes a unique Web Service that contains three types of methods: Objects, Object Lists and
Subprograms.
• Objects: to create, modify or delete an X3 object record and also to execute buttons or menus linked to those
objects under conditions:
- Sales Orders
- Customers
- Products

• Object Lists: A method that queries the main object left list, i.e. provides a list of the records with the same
format as the X3 left browser.

• Subprograms: A method for calling an X3 subprogram (X3 code) declared in the Subprogram Dictionary, for
example:
- Get a price list for a product/customer combination
- Get a product picture
- Get the available stock for a product
- Allocate customer reservations
- (Any X3 subprogram that does not require user interaction or an X3 window)
October 16
 2 – How to invoke SOAP
X3 Web services from a
web portal in PHP
• PHP and Syntax
• Call X3 Web Service
• Eclipse PHP

10/21/2016 16
Context

The portal gives you access to your data in Sage X3 such as orders in real-time. You do not need to
share large files across networks or via email. Because the data stays in X3, not saved out to an
external server, it is more secure. Remote employees like sales professions can not only view data,
but they can also create new data such as sales orders from any computer with internet access via a
browser.

You can create the portal using Sage X3 SOAP web services functionality and WampServer® which
is a Windows web development environment that allows you to create web applications with
Apache2, PHP, and a MySQL database. In addition, PhpMyAdmin allows you to easily manage your
databases. [Source: wampserver.com].

October 16
What is PHP?

PHP is a server-side scripting language designed for web development but also used as a general-
purpose programming language.
PHP code may be embedded into HTML code, or it can be used in combination with various web
template systems, web content management systems and web frameworks. PHP code is usually
processed by a PHP interpreter implemented as a module in the web server or as a Common
Gateway Interface (CGI) executable. The web server combines the results of the interpreted and
executed PHP code, which may be any type of data, including images, with the generated web page.
PHP code may also be executed with a command-line interface (CLI) and can be used to implement
standalone graphical applications.
What is PHP?

The purpose of the delimiting tags is to separate PHP code from non-PHP data (mainly HTML).
Although rare in practice, PHP will execute code embedded in any file passed to its interpreter,
including binary files such as PDF or JPEG files, or in server log files. Everything outside the
delimiters is ignored by the PHP parser and is passed through as output.

These recommended delimiters create correctly formed XHTML and other XML documents. This may
be helpful if the source code documents ever need to be processed in other ways during the life of the
software.

If proper XML validation is not an issue, and a file contains only PHP code, it is preferable to omit the
PHP closing (?>) tag at the end of the file.
Syntax and examples
Body
<!DOCTYPE html>
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<?php echo '<p>Hello SAGE X3 World</p>'; ?>
</body>
</html>

The PHP processor only parses code within its delimiters. Anything outside its delimiters is sent
directly to the output and not parsed by PHP. The only open/close delimiters allowed by PSR-1[3] are
"<?php" and "?>" or <?= and ?>. In files containing only PHP, the closing tag should be omitted.
Syntax and examples
Variables
Variables in PHP are represented by a dollar sign followed by the name of the variable. The variable
name is case-sensitive.
Variable names follow the same rules as other labels in PHP. A valid variable name starts with a letter
or underscore, followed by any number of letters, numbers, or underscores. As a regular expression,
it would be expressed thus: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'

<?php
$var_tic = ‘Tic';
$var_tac = ‘ et Tac';
echo "$var_tic, $Var_tac"; // outputs « Tic et Tac »

$4site = 'not yet'; // invalid; starts with a number

$_4site = 'not yet'; // valid; starts with an underscore
$täyte = 'mansikka'; // valid; 'ä' is (Extended) ASCII 228.
?>
Syntax and examples
Conditional statements
If ... else[edit]
The syntax of a PHP If ... else statement is as follows:

<?php
if (condition) {
// statements;
} elseif (condition2) {
// statements;
} else {
// statements;
}
?>
PHP code to call Web Service X3
Reading Customers list and Single Order

Reading the list of customers (left list object Reading a single order:
Sales orders):
<?php
<?php …
… $order = new Order ();
$order = new Order (); echo ($order->showOne ( $sohnum ));
echo ($order->showListe ()); …
… ?>
?>
Calling Web Service in PHP
Create an order
Creating an order ($WS input parameters for the web service):
<?php
…
$WS = "<PARAM><GRP ID=\"SOH0_1\" >";
$WS .= "<FLD NAME=\"SALFCY\">$formsalfcy</FLD>";
$WS .= "<FLD NAME=\"SOHTYP\">$formsohtyp</FLD>";
$newDate = date ( "Ymd", strtotime ( $formorddat ) );
…
$WS .= "<FLD NAME=\"BPCORD\">$formbpcord</FLD>";
$WS .= "</GRP>";
$WS.="<TAB ID=\"SOH4_1\">";
for($i = 0; $i < count ( $formtabitmref ); $i ++) {
$WS .= "<LIN>";
$WS .= "<FLD NAME=\"ITMREF\">$formtabitmref[$i]</FLD>";
$WS .= "<FLD NAME=\"QTY\">$formtabqty[$i]</FLD>";
$WS .= "</LIN>";
}
$WS .= "</TAB></PARAM>";
Calling Web Service in PHP
Create an order
Creating an order (Executing web service):

$order = new Order ();

echo ($order->create ( $WS ));
…
?>
Sage Resources

To install the website, everything is on the site:

https://github.com/Sage-ERP-X3/sample-x3-ws-php-webportal

The documentation is available either in pdf or directly online

Install and configure the Web Portal

Recommendation:
Follow the How-to
guide step by step
Demonstration of The PHP Web portal

Enter the URL for your portal in your default browser. In this example the URL is
http://x3pu9trainvm:8125/sagex3/
This is the name of X3 Syracuse server and the number was configured in httpd.conf.
This is an example of what your portal could look like.
Warning

• This portal is a demonstration portal based on Wampserver.

• WampServer is a development tool.

• You might like this PHP portal but in this case the web server must be a real production server.

• The PHP code is only an example for developers. Don’t re-use for a production portal. The PHP
code of this portal was not written by a PHP specialist.
How to (re)start the Wamp server

Start Wampserver

Restart Wampserver
Eclipse PHP for the development
Installation

Download the
Eclipse for PHP
64 bit
Eclipse PHP for the development
Installation

• Open Eclipse

• New PHP project

Eclipse PHP for the development
Installation

• Project name sagex3

• Create project at existing
location
• Click Finish
• View PHP explorer
3 – Sage X3 Web Service
Architecture
• X3 solution
• Web server
• Connection Pool
• Publishing Web services

40
© 2016 Sage Software, Inc. All rights reserved
Sage X3 solution
What you must know
Web Services are linked to an X3 solution.
A solution is a unique, identified Sage X3 installation that contains:
• A technology platform (Runtime, Database Server, Web Server etc.)
• A number of folders arranged in a hierarchy (Reference folder  Child folders)
• Database elements that belong to each folder
• Directories on the application server
An X3 installation (Solution) is identified by a name and a code, defined in the Console and stored in
the solution.xml file in the parent directory of the reference folder directory (Typically the …/Folders
directory).
Different X3 solutions, on different machines or on the same machine, may have folders with the
same name published through the same Web Servers. The solution name acts as the differentiator in
that case.
41
Sage X3 solution

SAGE X3 solution architecture

HTTP/HTTPS Web Client

(SOAP/REST)

Database Web
Server Server
Process Apps
server

Application
Server

42
Sage X3 Web server

The Sage X3 web server publishes Web Services

X3 Web Server X3 Application

NODEJS Server
n simultaneous
permanent
connexions
X3 instruction

JSON WS Connection Pool

Third-Party
XML (SOAP) Interpretation Applications
Apps (Java, .NET,
JavaScript, PHP etc.)

43
 Web Service Request Processing

1. User action: User requests info, X3 Application Server

presses web site button etc. 4 3
2. Web site calls X3 web service URL WEB Server
with proper parameters (http/SOAP) Sage Protocol
3. X3 web server contacts application
server and triggers process (X3 5
protocol)
4. X3 process is run by the application
server (Subprogram call, object
action etc.)
2 6
5. X3 application server returns results
to X3 web server (X3 protocol)
6. Web server returns data to web site
(http/SOAP)

Users
1 1

Internet / Intranet
7
Web Site
44
The Connection Pool

What is the connection pool?

• A set of permanent X3 connexions with the application server, used when needed by the web server:
Channel
• The tools and mechanisms to manage waiting queues for Web Service requests and the way available
connections are used to process the requests.

The connection pool is started with a predefined number of connections

Connexion Pool
X3 Connection Manager Request 1
Server
Request 2
> Start automatically when the X3 web server starts

> Start manually from the administration page

X3 Web Server
N Permanent Connexions
45
Connection Pool
How it works
• Requests may arrive simultaneously on the web site.
• Requests are piled in a waiting queue until a connection is available.
• When a connection is available, the web server uses that connection to process the top request in
the waiting queue (in FIFO order)
• The pool distribution algorithm optimises the use of available connexions depending on the
user, language, folder etc. specified.
• The total number of connections is specified in the Web Server.

PROCESS WS POOL
Request 1
SERVER Connection #0 (Channel)
Request 2

Request 3

Waiting Request 4

Queue Request 5

46
Connection Pool
How it works
E.G: requests with same user and 3 languages.
• The channels will adapt to the requests in order to remain open without switching context.

PROCESS WS POOL
SERVER Connection #0 (Channel)
ADMIN Request 1- ENG

ENG

Connection #1 (Channel)
ADMIN Request 2- ENG

ENG

Connection #2 (Channel)
ADMIN Request 3- ENG

ENG

47
Connection Pool
How it works
E.G: requests with same user and 3 languages.
• The channels will adapt to the requests in order to remain open without switching context.

PROCESS WS POOL
SERVER Connection #0 (Channel)
ADMIN Request 1- FRA

ENG

Connection #1 (Channel)
ADMIN Request 2- FRA

FRA

Connection #2 (Channel)
ADMIN Request 3- FRA

ENG

48
Connection Pool
How it works
E.G: requests with same user and 3 languages.
• The channels will adapt to the requests in order to remain open without switching context.

PROCESS WS POOL
SERVER Connection #0 (Channel)
ADMIN Request 1- FRA

ENG

Connection #1 (Channel)
ADMIN Request 2- FRA

FRA

Connection #2 (Channel)
ADMIN Request 3- FRA

FRA

49
Connection Pool
How it works
E.G: requests with same user and 3 languages.
• The channels will adapt to the requests in order to remain open without switching context.

PROCESS WS POOL
SERVER Connection #0 (Channel)
ADMIN Request 1- ENG

ENG

Connection #1 (Channel)
ADMIN Request 2- FRA

FRA

Connection #2 (Channel)
ADMIN Request 3- ENG

ENG

50
Connection Pool
What are Child processes?
What are child processes?
A node process that manages channels
• At least 1 child on the Syracuse host: W0

51
Connection Pool
What are Child processes?
Default configuration for a given pool

Channel #1
WS Pool Child
WSLIVE1 Process W0
Channel #2

52
Connection Pool
What are Child processes?
Enable load balancing (based on Wn process availability)

Channel #1
Child
Process W0
Channel #2
WS Pool
WSLIVE1
Channel #1
Child
Process W1
Channel #2

53
Connection Pool
What are Child processes?

A node process that manages channels

• Multiply processing power
EG: 2 channels 2 channels
x 1 child process x 2 child processes
________________ ________________
= 2 channels = 4 channels

• Requests load balanced (Round Robin)

54
Publishing Web Services in X3

The publication utility (Development / Processes / Processes/ Web Services)

• It is a very simple function that transforms a subprogram or object into a web service with a
public name, and generates its XML description, stored in the
X3_PUB/<FolderName>/GEN/ALL/WEBS directory on the application server.
• It is also possible to list published web services (for the folder), to unpublish existing web
services, or to generate all the web services defined for the folder (Global Publication).
• Generated web services are time-stamped, and the web server will always check if the version in
its cache is the latest version. If not, it will reload the latest version from the application server.

56
Publishing Web Services in X3
Wrapper program
The publication utility also generates a wrapper program in X3 code, which is the interface between
X3 and the web server. The wrapper program is called:
• WJ[WS_NAME] for objects, where [WS_NAME] is the object public name (Web Services).
• WJ[WS_NAME] for subprograms, where [WS_NAME] is the subprogram public name (Web
Service name).
The wrapper program manages:
• Header arguments (Technical data, timestamps etc.)
• Messages
• Data streams, both incoming and outgoing.
The wrapper program contains an automatic test subprogram that allows the developer to “run” the
web service in X3 before using it in a third-party application.

57
4 – Setting up Web
Services
• X3 server configuration
• Pool web service configuration
• Web server Licenses

58
© 2016 Sage Software, Inc. All rights reserved
Configure the X3 server

Open Administration > Administration > Servers > Hosts.

Click the edit icon next to your host name.
On the next screen, in the Number of Web service child processes field, enter a value (1 minimum)

59
Configure the Pool of X3 Web Service

Open Classic SOAP pools configuration from Administration > Administration > Web Services.
Click Create soapClassicPool.
Complete the following fields:
- Alias: Enter the name of the pool to be used in the web service call.
- Initialization size: Enter 1 ( minimum).
Represents the number of clients (per node.js process) that are initialized during the pool
startup.
- Maximum size: Enter 1 ( minimum).
Represents the maximum number of clients (per node.js process) that can be started on this
pool.

60
Configure the Pool of X3 Web Service

Auto start: Leave unchecked.  if checked, the pool starts when the Syracuse server starts.
X3 server TAGS: Leave blank.  This field is best used by Developers with classic SOAP pool
configuration.
Endpoint: Enter the endpoint (folder) to be used for web service requests.
Locale: Enter your language and location. (In this example, English.)
User: Enter the user name, Admin for example. It is better to enter a user dedicated to web services
only.

61
Configure the Pool of X3 Web Service

62
Web Server Licenses
Installation
Based on data volume consumed
Administration > Administration > Licences > License data
• WSSIZELIMIT: defines the size (in Megabytes) of data that can be exchanged in incoming web services.
• WSPERIOD: defines the period on which the size limitation applies.( a string that can be DAY,MONTH or
YEAR).
• WSGRACELIMIT: (as a percentage) defines the oversize percentage allowed (typically 10%; this means that if
the maximum size is defined as 1Mb / day, 1.1 Mb per day will be possible without blocking the web services.
• WSGRACESLOWDOWN: describes the rate used to decrease the speed of the web services between the size
limit and the size limit plus the grace limit. If for instance the value of this parameter is 5, it means that once the
1 Mb limit has been reached on a given day, the speed will be divided by 5 until the limit of 1.1 Mb is reached
within the end of the day (if this limit is reached, the web services will stop).

63
Web Server Licenses
Installation
Example:
• WSSIZELIMIT : 1 Mb
• WSPERIOD : DAY
• WSGRACELIMIT : 10 % = 0,1 Mb
• WSGRACESLOWDOWN : 5

• [0Mb ; 1Mb]  Normal speed

• ]1Mb ; 1,1Mb]  Speed degraded. Speed / 5
• >1,1Mb  Web service stopped

64
Web Server Licenses
Installation

WEB SERVICES
USAGE IS FREE
UNTIL FURTHER NOTICE
65
 5 – Publication and Test

• Publish subprograms
• Hands-on 1 “List of customers”
• Test supprograms
• Publish Object
• Hands-on 2 “Publishing Object SOH”
• Test object WS for the PHP Portal
• Hands-on-3 – Web service YOSOH
• Log web service

10/21/2016 66
Publish subprograms
Subprogram
Dictionary
Introduction
• A subprogram must be declared in the Subprogram Dictionary (Development / Script Dictionary /
Scripts / Subprograms) in order to be used as a Web Service.

• The dictionary lists the subprogram’s arguments (automatically detected from the code).

• A subprogram called as a Web Service may return values to the calling entity via some of its
arguments, passed by address rather than by value.

68
Subprogram
Dictionary
Message generation in a subprogram

Messages may be generated and sent to the Web Server during the execution of a subprogram. To
make sure messages are correctly generated, you should always use the following calls:

• Information message: Call MESSAGE(MESSAGE) From GESECRAN

• Warning message: Call ADDMESSWARN(MESSAGE) From AWEB
• Error message: Call ERREUR(MESSAGE) From GESECRAN

Messages are transmitted in the XML response data and may be used by the client application.

Up to 50 messages may be generated by a single subprogram.

69
Publishing in Subprogram

Publication utility
• In order to publish a subprogram, you must simply define the Web Service public name.
• The publication utility will generate the XML description file in the
X3_PUB/<FolderName>/GEN/ALL/WEBS directory on the application server.
• The wrapper program is also created, with the following name:
WJ[WS] where [WS] is the web service public name.

70
 Hands-on 1
“List of customers”
Our example subprogram will get a list of customer codes and names along with their credit limit from
the X3 customer table (BPCUSTOMER).
A range of customer codes and a maximum number of customers may be sent as input arguments.

71
 Hands-on 1
• Get the script XLISTBPC.src
• Compile it and save it under XLISTBPC
• Create the dictionary description of this subprogram:
• Development > Script Dictionary > Scripts > Subprograms (GESASU)
- Process: XLISTBPC
- Subprograms: LISTBPC
• The list of parameters is automatically loaded.
• Description: List of customers
• Web Services
• The dimension column for BPCNUM, BPCNAM and OSTAUZ needs to be the same number as the number of
clients you want to display (NBBPC).

72
•
 Hands-on 1
• Tab Definition, Publication name: WSLISTBPC
• Check the mapping tab. What do you see on the group and level columns?
• On the tab Definition, note the wrapper program name on the Information block.
• Open the wrapper program and execute it

73
©
 Hands-on 1
Script XLISTBPC
#**
#* BPCLIST: List of customers designed for Web Services
#* @param BPCSTR Start range
#* @param BPCEND End range
#* @param NBBPC Number of customers in the list (dimension)
#* @param BPCNUM Customer code
#* @param BPCNAM Customer name
#* @param OSTAUZ Customer credit
#*!
Subprog LISTBPC(BPCSTR,BPCEND,NBBPC, BPCNUM, BPCNAM, OSTAUZ)
…
End

74
 Hands-on 1
Are you ready to practice?
 Hands-on 1
► Compile it and save it under XLISTBPC
► Create the dictionary description of this subprogram
► Create the web service WSLISTBPC
► Publish the web service
► Open the wrapper program and execute it

76
 Hands-on 1
► Compile it and save it under XLISTBPC in Eclipse

Compile

77
 Hands-on 1
► Create the dictionary description of this subprogram 1/2

The activity code was

created before

Don’t forget this

check box

78
 Hands-on 1
► Create the dictionary description of this subprogram 2/2
► Do not forget to put a dimension value >1 for tables of values in return

79
 Hands-on 1
► Create the web service WSLISTBPC

80
 Hands-on 1
► Publish the web service

Publish

81
©
 Hands-on 1
► Open the wrapper program and execute it in X3

82
©
 Hands-on 1
► Open the wrapper program and execute it in X3 – log file

83
©
Test subprograms – X3 Tool
Tests Subprograms – Tool X3
Test the Web Service List of customers
X3 Tool– Administration / Web Services / Classic SOAP Web services

85
Test the Web Service List of customers
X3 Tool
X3 Tool – Administration / Web Services / Classic SOAP Web services

86
Test the Web Service List of customers
X3 Tool - Run
X3 Tool– Administration / Web Services / Classic SOAP Web
Services
Click Run
• Language code: language (FRA, ENG, BRI...)
• Pool alias: Pool code (ex : SEED)
• Pool ID: it allows you to force a specific client through a
pool definition
• Request configuration :
adxwss.beautify=true&adxwss.optreturn=JSON
• Public name: Name of web service

87
Test the Web Service List of customers
X3 Tool - Run
• Input XML/JSON:

{ "GRP1" : {
"BPCSTR": "",
"BPCEND": "",
"NBBPC": "0"
}

88
Test the Web Service List of customers
X3 Tool - Run
Result of the Web Service
• Status : 0 = NOK, =1=OK for executing the Web Service

89
Test the Web Service: List of customers
X3 Tool - Run Result XML/JSON:
Result of the Web Service {
"GRP1": {
"BPCSTR": "",
"BPCEND": "",
"NBBPC": "0"
},
"GRP2": [
{
"BPCNUM": "",
"BPCNAM": "",
"OSTAUZ": "0"
}
]
} 90
Test the Web Service List of customers
X3 Tool - Run
Request configuration:
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.

91
The Wrapper program

Using the wrapper program

• The wrapper program contains test code that may be used to make sure the subprogram behaves
as wanted, simply by running the wrapper program.

• The test code generates a generic trace file with the results.

• Two sections, $INITWS and $RESULTWS, may be inserted into the original subprogram, in which
you can initialise argument values and print additional statements in the trace file. They are called
if they exist in the original subprogram.

• It is recommended to implement your testing code and modifications in a separate process, since
the wrapper program is re-generated each time the Web Service is published again.

92
Tests subprograms – Tool Soapui
Test the Web Service List of customers - Tool Soapui

You can use the open source tool Soapui.

Download and install it :https://www.soapui.org

95
Test the Web Service List of customers - Tool Soapui

Get the description file wsdl in x3

96
Test the Web Service List of customers - Tool Soapui

Get the description file wsdl in x3

Copy the url

97
Test the Web Service List of customers - Tool Soapui

Get the description file wsdl in x3

The url is for example: http://x3pu9trainvm/soap-
wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl

98
Test the Web Service List of customers - Tool Soapui

Create a new SOAP project

Wsdl file

99
Test the Web Service List of customers - Tool Soapui-Run

Rename the request for the web service Request_List_of_customers.

Double-click to open this request

100
Test the Web Service List of customers - Tool Soapui - Run
Modify the input xml flow
<soapenv:Envelope
…
<codeLang xsi:type="xsd:string"> ENG </codeLang>
<poolAlias xsi:type="xsd:string"> SEED </poolAlias>
<poolId xsi:type="xsd:string"></poolId>
<requestConfig xsi:type="xsd:string"></requestConfig>
</callContext>
<publicName xsi:type="xsd:string"> WSLISTBPC </publicName>
<inputXml xsi:type="xsd:string"> … </inputXml>
…

101
Test the Web Service List of customers - Tool Soapui - Run
Modify the input xml tag <inputXml>
<inputXml xsi:type="xsd:string">
<![CDATA[
{ "GRP1" : {

"BPCSTR": "AO01",

"BPCEND": "ES001",
you must surround json
"NBBPC": "5" with
} <![CDATA[ … ]]>
}

]]>
</inputXml>

102
Test the Web Service List of customers - Tool Soapui - Run

Mandatory to connect to X3.

Username : user X3
Password : pwd X3
Pre-emptive auth : Authenticate
pre-emptively
Test the Web Service List of customers - Tool Soapui - Run

Result of the web service

Result XML/JSON
{<resultXml xsi:type="xsd:string">{
"GRP1": {
…} Status of web service :
1 = OK
</resultXml>
0 = NOK
<status xsi:type="xsd:int">1</status>

104
Test the Web Service List of customers - Tool Soapui - Run

Result NOK of Web Service

• Input <inputXml> is empty

• Result XML/JSON is empty

• Status is 0

105
Test the web service List of customers - Tool Soapui - Run

Result NOK of Web Service

• Message of error

106
Test the Web Service List of customers - Tool Soapui -
GetDescription

XLM input

XML Output

107
Test the Web Service List of customers - Tool Soapui -
GetDescription
Output XML description. No JSON description in the tag <resultXml>:
<ADXDOC …>
<ADXDATA>
<GRP PNA="GRP1" NAM="GRP1" DIM="1">
<FLD NAM=“BPCSTR“ IDX=“1“ TYP=“Char“ PAR=“Value“ MOD=“Input“ LEN=“250“ C_ENG=“Start range“ >
<FLD NAM=“BPCEND“ IDX=“2“ TYP=“Char“ PAR=“Value“ MOD=“Input“ LEN=“250“ C_ENG=“End range“ >
<FLD NAM=“NBBPC“ IDX=“3“ TYP=“Integer“ PAR=“Value“ MOD=“Input“C_ENG=“Number of customer“ >
</GRP>
<GRP PNA="GRP2" NAM="GRP2" DIM="100">
<FLD NAM=“BPCNUM“ IDX=“4“ TYP=“Char“ PAR=“Adr“ MOD=“Input“ LEN=“250“ C_ENG=“Customer code“ >
<FLD NAM=“BPCNAM“ IDX=“5“ TYP=“Char“ PAR=“Adr“ MOD=“Input“ LEN=“250“ C_ENG=“Customer name“ >
<FLD NAM=“OSTAUZ“ IDX=“6“ TYP=“Decimal“ PAR=“Adr“ MOD=“Input“C_ENG=“Customer credit“ >
</GRP>
</ADXDATA>
<ADXMEN> ... </ADXMEN>
</ADXDOC>

108
Test the Web Service List of customers - Tool Soapui -
GetDescription
{
"GRP1": {
Input-Output JSON "BPCSTR": "AO01",
"BPCEND": "ES001",
"NBBPC": "5"
},
"GRP2": [
{
"BPCNUM": "AO021",
"BPCNAM": "Agro Alimentar do Namibe",
"OSTAUZ": "0"
},
{
"BPCNUM": "AO151",
"BPCNAM": "Luanda Bikes",
"OSTAUZ": "0"
},
{
"BPCNUM": "AO152",
"BPCNAM": "SoftCenter - Informatica ",
"OSTAUZ": "0"
}
]
}

109
Test the Web Service List of customers - Tool Soapui -
GetDescription
Input-Output XML
<ADXDATA>
<GRP NAM="GRP1"> For Input XML For Output XML
<FLD NAM=“BPCSTR“ TYPE=“Char“/>
<ADXDATA>  <PARAM> <ADXDATA>  <RESULT>
<FLD NAM=“BPCEND“ TYPE=“Char“/> </ADXDATA>  </PARAM> </ADXDATA>  </RESULT>
<FLD NAM=“NBBPC“ TYPE=“Integer“/>
</GRP>
<GRP DIM="100“ NAM="GRP2" SIZE=“5">
<LIN NUM="1”>
<FLD NAM=“BPCNUM“ TYPE=“Char“ />
<FLD NAM=“BPCNAM“ TYPE=“Char“ />
<FLD NAM=“OSTAUZ“ TYPE=“Decimal“ />
</LIN>
<LIN NUM=“2”>
<FLD NAM=“BPCNUM“ TYPE=“Char“ />
<FLD NAM=“BPCNAM“ TYPE=“Char“ />
<FLD NAM=“OSTAUZ“ TYPE=“Decimal“ />
</LIN>
</GRP>
</ADXDATA>

110
Test the Web Service List of customers - Tool X3
What is a JSON format?
What is a JSON format?
JSON: JavaScript Object Notation.
JSON is a syntax for storing and exchanging data.
JSON is an easier-to-use alternative to XML.
JSON Example
{"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter", "lastName":"Jones"}
]}

111
Test the Web Service List of customers - Tool X3
What is a JSON format?
JSON Syntax Rules
JSON syntax is derived from JavaScript object notation syntax:
• Data is in name/value pairs
• Data is separated by commas
• Curly braces hold objects
• Square brackets hold arrays

JSON Data - A Name and a Value

JSON data is written as name/value pairs.
A name/value pair consists of a field name (in double quotes), Example
followed by a colon, followed by a value. "firstName":"John"

JSON names require double quotes.

JavaScript names don't.

112
Test the Web Service List of customers - Tool X3
What is a JSON format?

JSON Values JSON Objects

JSON values can be: JSON objects are written inside curly braces.
• A number (integer or floating point) Just like JavaScript, JSON objects can contain multiple
• A string (in double quotes) name/values pairs:
• A Boolean (true or false) Example:
• An array (in square brackets) {"firstName":"John", "lastName":"Doe"}
• An object (in curly braces)
• null
JSON Arrays
JSON arrays are written inside square brackets.
Just like JavaScript, a JSON array can contain multiple objects:
Example:
"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter","lastName":"Jones"}
]
113
JSON description
Input / Output for X3 subprogs
The group GRPn has dimension 1 The group GRPm has dimension > 1
[ ] is a table.

“GRPn” : { "GRPm": [
“Field1” : “value string”, {
“Field2” : number “Field1” : “value string 1”,
} “Field2” : number 1
},
{
“Field1” : “value string 2”,
“Field2” : number 2
}
]

114
XML description
Input / Output for X3 subprogs
The group GRPn has dimension 1

<GRP ID="GRPn" DIM="1">

<FLD NAME="STOCK“ TYPE="Decimal">
Value of field
</FLD>
</GRP>

<GRP ID="GRPn">
<FLD NAME="STOCK“>
Value of field simplified format input
</FLD>
</GRP>

115
XML description
Input / Output for X3 subprogs

<TAB DIM=“1000“ ID=“GRP2“ SIZE=“5“>

Group GRP2 has dimension
<LIN NUM=“1"
> 1 ( dim = 1000)
<FLD NAME="STOCK“ TYPE="Decimal">Value of field 1</FLD>
</LIN>
<LIN NUM=“2"
<FLD NAME="STOCK“ TYPE="Decimal">Value of field 2</FLD>
</LIN>
</TAB>

<TAB ID=“GRP2“>
<LIN NUM=“1"
<FLD NAME="STOCK“>Value of field 1</FLD>
</LIN>
<LIN NUM=“2"
simplified format input
<FLD NAME="STOCK“>Value of field 2</FLD>
</LIN>
</TAB>
116
XML/JSON description
Input / Output for X3 subprogs

For XML input For JSON input

<![CDATA[ <![CDATA[
<PARAM> {
… …
</PARAM> }
]]> ]]>

For XML output For JSON output

<![CDATA[ <![CDATA[
<RESULT> {
… …
</RESULT> }
]]> ]]>

117
Publishing Objects
Publishing objects
The Object Dictionary
X3 objects (Products, Sales Orders, Suppliers etc.) are stored in a dictionary describing:
• The left browser (Selection parameters)
• The object's screens (Fields, blocks etc.)
• Special options / buttons / menus
• The main object table
• X3 processes linked to the object

To publish an object, no dictionary change is usually necessary. If the object is available in TP mode, it should
also be available through Web Services.

However, slight modifications may be necessary to access additional entry screens, such as addresses screens
in Sales Orders. These are done via the Additional Screens option in the object dictionary.

The object template is the most widely used function type in X3. Other functions that do not belong to that
template (e.g. std process functions such as Automatic Invoice Validation) may usually be encapsulated into
subprograms that may be called via Web Services.

119
Publishing object
Field types
Object fields can be:
• Entered: The field is used and transmitted in both Web Services and traditional clients.
• Displayed: The field is transmitted in both Web Services and traditional clients.
• Invisible: Invisible fields are never transmitted to the client for traditional clients. For Web Services
you have the choice of publishing those fields or not.
• Technical: Those fields are never transmitted to either clients or Web Service applications.

Invisible and technical fields are available in the [M] classes  Not transmitting them to the clients
simply reduces network traffic.

120
Publishing object
Field Actions
An execution type is attached to each field action in the screen dictionary (Execution field):
• Interactive: Action is executed only in traditional clients.
• Always: Action is executed in traditional clients and in web service mode.
• Import / Web Service: Only executed in import and web service mode (non-interactive).

-The following actions are never executed in web service mode:

• Init Button
• ButtonN
• Selection
• Click (Icons)

121
Publishing object
Web Service Generator
The web service publication utility published X3 objects, with the choice of:
• Transaction entry code (if available). Usually simple entry transactions are built for web
services.
• Including invisible fields: Invisible fields may or may not be included in the object web service
(Technical fields are never published).

The publication utility will generate the XML description file in the
X3_PUB/<FolderName>/GEN/ALL/WEBS directory on the application server.

The wrapper program is also created, with the following name:

WJ[WS_NAME] where [WS_NAME] is the publication name of the web service.

122
 Hands-on 2
“Publishing object SOH”
This example will publish the object SOH with the transaction WEB.

123
 Hands-on 2
Function Development > Script Dictionary > Scripts > Web Services

Publication name: WSORDER

Description: Sales order
Object: SOH
Transaction: WEB
• On the tab Definition, note the wrapper program name on the Information block.
• Open the wrapper program WJWSORDER and execute it.
Note: If you get an error message "Too many field published”, reduce the number of lines for
grid SOH4

124
 Hands-on 2
Are you ready to do it yourself?
 Hands-on 2

► Create the web service WSORDER

► Publish the web service
► Open the wrapper and execute it

126
 Hands-on 2
► Create the web service WSORDER

127
 Hands-on 2

Publish the web service

► Create

► Save

► Publish

128
 Hands-on 2
► Publish the web service
► If you have this error,

you must Unselect fields into the entry Transaction WEB.

129
 Hands-on 2

► Open the wrapper program and execute it.

130
 Hands-on 2
► Open the wrapper program
and execute it in X3 – log file

► It is the left list.

131
Test Objects – X3 Tool
Test the Web Service: Object SOH – X3 Tool - Query

X3 Tool:
Administration / Web Services / Classic SOAP Web services.
Click Query
It is le left list of the object SOH ( Orders)
List size: Max number of records of the left list.

133
Test the Web Service Object SOH - Tool X3 - Query

Result of the web service

• Status : 0 = NOK, =1=OK for executing the web service

134
Test the Web Service Object SOH - Tool X3 – Query
Web Service result

• Result XML/JSON
[
{
"SOHNUM": "SOWFR0120001",
"BPCORD": "FR001",
"ORDDAT": "07/09/2016",
…
},
{
"SOHNUM": "SOWFR0110005",
"BPCORD": "FR001",
"ORDDAT": "07/09/2016",
…
}
]
135
Test the web service Object SOH - Tool X3 – Read

Click Read.
It is for reading a unique
record of object SOH.
Click ‘+’ for adding the key
of object SOH.

136
Test the web service Object SOH - Tool X3 – Read
Web Service result

Status : 0 = NOK, =1=OK

for executing the web service.

137
Test the web service Object SOH - Tool X3 – Read
Web Service result
Result XML/JSON
{
"SOH0_1": {
"SALFCY": "FR011",
"ZSALFCY": "Comptech SA",
"SOHTYP": "WEB",
…
"WSOHCAT": ""
},
"SOH1_1": {
"BPCINV": "FR001",
"BPINAM": "Urban Cycle",
…

138
Test the web service Object SOH - Tool X3 – Save

Click Save.
It is for creation of
an SOH record.

Object Xml: the same description (in

Xml or JSON) of the result for the Read
operation.

SOHNUM field must be empty when

creating.

139
Test the web service Object SOH - Tool X3 – Save
Web Service result

Status : 0 = NOK, =1=OK

for executing the web service.

140
Test the web service Object SOH - Tool X3 – Save
Web Service result

The SOHNUM field has the new value of the order.

Result XML/JSON
{
"SOH0_1": {
"SALFCY": "FR011",
"ZSALFCY": "Comptech SA",
"SOHTYP": "WEB",
…
"WSOHCAT": ""
},
"SOH1_1": {
"BPCINV": "FR001",
"BPINAM": "Urban Cycle",
…
141
Tests Objects – Soapui Tool
Test the Web Service: Object SOH – Soapui Tool

Create the requests for the web service for the next operations :
• Query
• Read
• Save

143
Test the Web Service: Object SOH – Soapui Tool - Query

Rename the request for the object SOH

Double-click to open this request

144
Test the Web Service : Object SOH – Soapui Tool - Query
Modify the input xml flow
<soapenv:Envelope …
<codeLang xsi:type="xsd:string">ENG
ENG </codeLang>
SE
<poolAlias xsi:type="xsd:string">SEED
SEED </poolAlias>
ED
<poolId xsi:type="xsd:string"></poolId>
<requestConfigxsi:type="xsd:string">
<![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
ON]]>
</requestConfig>
</callContext>
<publicName xsi:type="xsd:string">WSORDER
WSORDER </publicName>
…

145
Test the Web Service: Object SOH – Soapui Tool - Query

Modify the input xml tag <listSize>

<listSize xsi:type=“xsd:int”>
10

</listSize>

Don’t forget the Authentication.

146
Test the web service: Object SOH – Soapui Tool – Query
Web Service result

Result XML/JSON
{<resultXml xsi:type="xsd:string>

"SOHNUM": "SOWFR0120001",

"BPCORD": "FR001",</resultXml>

<status xsi:type="xsd:int">1</status> Status of Web Service :

1 = OK
0 = NOK

147
Test the web service : Object SOH – Soapui Tool - Read

Rename the request for the SOH object

Double-click to open this request

©
Test the web service : Object SOH – Soapui Tool - Read

Modify the input xml flow

<soapenv:Envelope
…
<codeLang xsi:type="xsd:string">ENG</codeLang>
<poolAlias xsi:type="xsd:string">SEED</poolAlias>
<poolId xsi:type="xsd:string"></poolId>
<requestConfigxsi:type="xsd:string">
ON]]> <![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
</requestConfig>
</callContext>
WSORDER
<publicName xsi:type="xsd:string">WSORDER </publicName>
… 149
Test the web service : Object SOH – Soapui Tool - Read

Modify the input xml tag <objectKeys>

<objectKeys
xsi:type="wss:ArrayOfCAdxParamKeyValue"
soapenc:arrayType="wss:CAdxParamKeyValue[]
">
<keys>
<key> SOHNUM </key>
<value> SOWFR0110006 </value>
</keys>
</objectKeys>

150
©2016
Test the web service : Object SOH – Soapui Tool – Read
Web service result

Result XML/JSON
{<resultXml xsi:type="xsd:string>

"SOH0_1": {

"SALFCY": "FR011",

"ZSALFCY": "Comptech SA",

"SOHTYP": "WEB",

…
Status of web service :
<status xsi:type="xsd:int">1</status> 1 = OK
0 = NOK

151
Test the web service : Object SOH – Soapui Tool - Save

Rename the request for the object SOH

Double-click to open this request

152
Test the web service : Object SOH – Soapui Tool - Save

Modify the input xml flow

<soapenv:Envelope
…
<codeLang xsi:type="xsd:string">ENG</codeLang>
<poolAlias xsi:type="xsd:string">SEED</poolAlias>
<poolId xsi:type="xsd:string"></poolId>
<requestConfigxsi:type="xsd:string">
<![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
ON]]>
</requestConfig>
</callContext>
WSORDER
<publicName xsi:type="xsd:string">WSORDER </publicName>
… 153
Test the web service : Object SOH – Soapui Tool - Save

Modify the input xml tag <objectXml>

<objectXml xsi:type=“xsd:string”>
<![CDATA[

For this part of JSON, you can: a) get the result of the operation Read, b) init the field SOHNUM
]]>
</objectXml>

154
Test the web service : Object SOH - Soapui Tool - Save
Modify the input xml tag <objectXml>
<objectXml xsi:type=“xsd:string”>
<![CDATA[
{
"SOH0_1": {
"SALFCY": "FR011",
"ZSALFCY": "Comptech SA",
"SOHTYP": "WEB",
"ZSOHTYP": "WEB",

"SOHNUM": "",
…
]]>
</objectXml>

155
Test the web service : Object SOH - Soapui Tool – Save
Web Service result
The field SOHNUM contains the key of the new order.
Result XML/JSON
{<resultXml xsi:type="xsd:string>

"SOH0_1": {

"ZSOHTYP": "WEB",
Status of web service :
"SOHNUM": "SOWFR0110007", 1 = OK
"REVNUM": "0",… 0 = NOK

<status xsi:type="xsd:int">1</status>

156
JSON description : Input / Output for X3 objects

The group matches the abbreviation screen + bloc number for a list block

Screen code and block number

"SOH0_1“ : {
"SOHNUM": “SOW001“,
“REVNUM": “0“,
“SOHTYP": “WEB“,
“SALFCY": “FR011“,
“ORDDAT": “20160907“,
“BPCORD": “FR001“,
“BPCNAM": “Urban Cycle“
}

157
JSON description : Input / Output for X3 objects

Group for a grid block

Screen code and block number

"SOH4_1“: [
{
"NUMLIG“: “0”,
"ITMREF“: “DIS010”,
"QTY“: “2”
},
{
"NUMLIG“: “0”,
"ITMREF“: “DIS010”,
"QTY“: “2”
}

158
XML description : Input / Output for X3 objects

The group matches the abbreviation screen + bloc number for a list block
Screen code and block number

<GRP ID="SOH0_1">
<FLD NAME="SOHNUM" TYPE="Char">SOWFR01100006</FLD>
<FLD NAME=“REVNUM" TYPE="Char">0</FLD>
<FLD NAME=“SOHTYP" TYPE="Char">WEB</FLD>
<FLD NAME=“SALFCY" TYPE="Char">FR011</FLD>
<FLD NAME=“ORDDAT" TYPE="Char">20160907</FLD>
<FLD NAME=“BPCORD" TYPE="Char">FR001</FLD>
<FLD NAME=“BPCNAM" TYPE="Char">Urban Cycle</FLD>
</GRP>

159
XML description : Input / Output for X3 objects

The group for a grid block

Screen code and block number

<TAB DIM=“1002“ ID="SOH0_1“ SIZE=“2">

<LIN NUM=“1">
<FLD NAME=“NUMLIG" TYPE=“Integer">0</FLD>
<FLD NAME=“ITMREF" TYPE="Char">ITM1</FLD>
<FLD NAME=“QTY" TYPE=“Decimal">2</FLD>
</LIN>
<LIN NUM=“2">
<FLD NAME=“NUMLIG" TYPE=“Integer">0</FLD>
<FLD NAME=“ITMREF" TYPE="Char">ITM2</FLD>
<FLD NAME=“QTY" TYPE=“Decimal">3</FLD>
</LIN>
</TAB>

160
XML description : Input / Output for X3 objects

XML input data for arrayed fields inside list blocks

• Array fields inside list blocks (e.g. Company Name in BPs) are represented inside a <LST>
element with the NAME property containing the field name.

• The <LST> element contains nested <ITM> elements with individual values for each index.

<PARAM>
<FLD NAME="BPRNUM">C0001</FLD>
<FLD NAME="BPRSHO">B&J Toys</FLD>

<LST NAME="BPRNAM">
<ITM>B&J Toys</ITM> BPRNAM(0)
<ITM>(Harrods Group)</ITM> BPRNAM(1)
</LST>

</PARAM>
161
XML/JSON description : Input / Output for X3 objects

For XML input For JSON input

<![CDATA[ <![CDATA[
<PARAM> {
… …
</PARAM> }
]]> ]]>

For XML output For JSON output

<![CDATA[ <![CDATA[
<RESULT> {
… …
</RESULT> }
]]> ]]>

162
SOAP XML Data streams
Return XML data streams

Status and messages

• The returned XML stream contains a section that indicates the status of the request and possible
information, warning or error messages.

Technical information
• It also contains a technical section that contains the detailed processing log (If logging has been
enabled) and timing information.

Data
• For all web service methods (object, list, subprogram), the system returns an XML stream that
corresponds to the <ADXDATA> element in the XML web service description with values
populated.
• The data is contained in the <RESULT> element in the returned XML stream.

163
XML Data streams
Data integrity checks
In X3, data integrity and contention management is carried out using symbolic locks. Only a single user is
allowed to modify an object at any point in time, and the record is locked as soon as the user accesses it.

In Web Services, the Read and Modify methods are separated. The read method does not lock the object
(there is no point in locking the object when it is read in web service mode).

To check that an object has not been modified between the time when the data has been read and the time
when it is modified, the following procedure must be followed:

• The Read method returns two technical fields enclosed in the <ADXTEC> element in the returned XML
stream:
- WW_MODSTAMP Time stamp of latest object update
- WW_MODUSER Modification user

• If the WW_MODSTAMP field is included in the input XML for the Modify method, the system checks that the
object has not been modified since that time.

• If the object has been modified, an error message is returned  ("Record modified since last read")
164
XML Data streams
Grid/detail screens
Grid/detail screens require special care when they are accessed in web service mode. The most
frequent example is the Addresses screen in BPs, Customers, Suppliers etc.

To be accessed through Web Services, those screens must comply with the following standards:
• Entered field code (right part) = Constant character + invisible field code
(E.g. XBPACRY = X + BPACRY).
• The last invisible numeric (C) field in the block is the line number control variable. It is
initialised by the wrapper program for each line when the screen is used.

Only the fields in the grid block (left part) are transmitted through Web Services and need to be
populated when creating or modifying. All invisible fields are automatically included in the web
service description.

When modifying records in those screens, the end of grid variable (NBLIG, NBADR etc.) must
be set to the correct number. If it is not, then the last line in the input XML stream is taken as the
last line in the screen.
165
XML Data streams
Additional screens (object dictionary)

It is possible to add to an object up to 8 additional screens with their respective abbreviation.

The system will:

• Include those screens in the XML structure generated when the object is published.
• Open the screens in the window's automatic process, and declare them as window tabs.
• Load the screen with the input XML stream (If any).
• Include the screens in the response XML stream.

The application (X3 code) must ensure those screens are used correctly in web service mode
(GWEBSERV=1).

The standard SOH object has been modified to illustrate the use of additional screens.

166
The Wrapper program
Header arguments
The object wrapper program acts as an interface between the web server and the X3 object.
It manages:
• Header arguments
• Information / Error / Warning messages
• The object fields as arguments and return values.

The following header arguments are included in the wrapper program:

• WW_OK Integer Return status: 1 (OK), 0 (Error)
• WW_ZONE Character Error field if there was an error
• WW_STAT Integer Number of messages
• WW_GRAVE Integer(1..50) Message level ( 1 (Info), 2 (Warning), 3 (Error) )
• WW_MESS Character(1..50) Message text
• WW_ACTION Character Action/Method code (Action to execute):
READ / CREATE / MODIFY / DELETE / SUPLIG
• WW_IDENT Character Identifier (Key1~Key2~Key3… or start value or left list quick select criteria)
• WW_NB Integer Number of records to read (Left list) or number of records returned
• WW_HORDAT Character Web service timestamp
• WW_TAB Character For line deletion actions
• WW_PAR Character For line deletion actions
• WW_TRACE Clbfile Trace parameters for activity logging
167
Using the Wrapper program

The wrapper program contains test code that may be used to make sure the object behaves as
wanted, simply by running the wrapper program with the proper parameters for each object
action/method.
The test code generates a generic trace file with the results.
A number of sections may be inserted into a separate program called ZZWS[OBJ] where [OBJ]
is the object code. They will be called if they exist:
• $INITMAJ: Initialisation of parameters for object actions/methods (Read, Modify, Create,
Delete and special object actions).
• $RESMAJ: Analysis of results and additional trace file statements for object actions/methods.
• $INITLG: Initialisation of parameters for left list method.
• $RESLG: Analysis of results and additional trace file statements for left list method.

168
Web Service for the PHP portal
PHP Web Site Example
Web Service for PHP portal

The Web Service used for the portal is YOSOH.

Open C:\Sage\wamp\www\sagex3\config\Config.php

Name of the web service

170
 Hands-on 3
“Execute web service YOSOH
into Soapui”

171
 Hands-on 3
• Duplicate requests Request_WSORDER to Request_YOSOH for Query, Read and Save
• Execute the requests below

172
Using logs X3 for web services
Host traces - Setup

Administration / Logs / Host traces

Select the fist Auto record alterable.

174
Host traces - Setup
• Edit

• Select Soap-generic

175
Host traces - Setup

• Select Soap-generic
• Update the level for debug
• Save

All the X3 sessions Syracuse are logged, the X3 soap web service too.

176
Host traces - Setup

Several types of events are traced and identified in the Configuration grid.
For every type of event traced, it is possible to have different trace levels:
* Error only traces the errors found.
* Warning also traces the warnings found.
* Info adds the information log to the next events.
* Debug is the most verbose trace that returns a lot more information.

177
Host traces
Get the process number of the Web Service session
Administration > Web client sessions

Node W0

178
Host traces – Execute the web service

The session Node for the web service is 1156

Execute the web service YOSOH.Query. Click List of orders

179
Host traces – Execute the web service

Into the alterable record (your session) you must Flush.

Go to Web Service session 1156.

180
Host traces – Get the log

181
Host traces – Get the log

• Get the file .gz

• Unzip with the tool 7zip
• Open with nodpad++
• The format is json
• You can use the plugin JSTool for
viewing it.

182
Host traces – Go back to the initial setup

Change the debug level to Error.

183
 6 – Updating the Web
Portal PHP & How to add
products

10/21/2016 184
 PHP - List of products
The corrections are in C:\Sage\wamp\www\sagex3\EXERCISES\1
PHP – List of products

• Create the web service YOITM

• Save
• Publish

186
PHP – List of products

• Copy C:\Sage\wamp\www\sagex3 to C:\Sage\wamp\www\sagex3-svg1

• Modify C:\Sage\wamp\www\sagex3\config\Config.php.
- …
public static $WS_ORDER = "YOSOH";
Add
public static $WS_PRODUCT = "YOITM";
…
• Modify C:\Sage\wamp\www\sagex3\includes\menu_home.php

187
PHP – List of products

• Add the new code below

New code
<li class="dropdown"><a href="#" class="dropdown-toggle"
data-toggle="dropdown" role="button" aria-expanded="false">Products X3
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li><a href="page_itm_list.php">List of products</a></li>
</ul>
</li>

188
PHP – List of products

• Copy C:\Sage\wamp\www\sagex3\page_soh_list.php to
C:\Sage\wamp\www\sagex3\page_itm_list.php
• Update file page_itm_list.php

• Copy C:\Sage\wamp\www\sagex3\WebService\models\Order.php to
C:\Sage\wamp\www\sagex3\WebService\models\Product.php
• Update file Product.php
- Rename class Order  product
- Update function showListe
- $WS_ORDER  $WS_PRODUCT
- Titles of columns, names of fields

189
PHP – List of products - Demo

190
PHP - Details of products
The corrections are in C:\Sage\wamp\www\sagex3\EXERCISES\2
PHP – Details of products

• Modify C:\Sage\wamp\www\sagex3\WebService\models\Product.php
• Modify function showList()
• Modify function showOne()
• Copy C:\Sage\wamp\www\sagex3\page_soh_read.php to
C:\Sage\wamp\www\sagex3\page_itm_read.php
• Modify file page_itm_read.php

192
PHP – Details of products - Demo

Click to
visualize
product
detail

193
7 – Best practices &
Performance

194
© 2016 Sage Software, Inc. All rights reserved
Publication
Entry Transaction

• It is highly recommended to customize the transaction used for publishing the WS

• Reduce the number of X3 data integrity controls (less time in Application server)

• Reduce the number of publishable fields (65000 max.)

• Simplify and reduce size of XML/JSON stream

195
Measure execution time : Web service ‘Order’

• It is easy to measure execution time of a web service with Soapui.

• Web service WSORDERS : Normal transaction

• Web service YOSOH : WSORDERS : simplified transaction

• Result : time is divided by 2

196
Web Services Pools
Pool Configuration
• Pool size and configuration adapted to your set of data
• Several Pools (Separate contexts: slow/fast requests, etc.)
• Several channels per pools.

• The web application will need to know the pool configuration to distribute requests into the
matching pools.
• Switching language is not the most costly. Switching user is more costly
• Have enough channels per pool:
. users*language recommended
. 1 channel per user at least
OR
. 3 channels minimum for a LIVE folder

197
Debug and logs

Analysis and customization of X3 code

• Use debug eclipse in a web service session
• Use log Host traces (already seen)
- Administration > Usage > Logs > Host traces
• Use log in a classic session

198
Log in a classic session

Use the function ‘Classic Client sessions’

Administration > Usage > Classic Client sessions
• Activate X3 Log
• Execute a Web service
• In the function Web client sessions:
• choose session type: Soap
• Visualisation of CPU Graph + log

199
 8 – Limitations of Web
Services

10/21/2016 200
The Subprogram Dictionary
Possibilities and Limitations
• Subprograms must not open any X3 window for user interaction. They must run independently
using their arguments only.

• All display instructions (Affzo, Diszo etc.) are forbidden. All database instructions are allowed, of
course.

• The infbox instruction does not stop the web service, but will not send any message to the client
application.

• Emails may be sent via the Send instruction, or using the meladx utility (smtp server needed).

• Reports may be generated using the Report instruction. Always use an X3 Print Server.

201
Publishing an Object
Tuning and Limitations
• Once an object has been published, it must be tuned to make sure it is compatible with Web
Services.
• In standard, the only objects that have been verified are:
Sale Orders (SOH), Customers (BPC) and Products (ITM).
• Other objects must be verified: Depending on parameters and user actions, additional windows
may be displayed, which is not compatible with web services.
• Main limitations are linked to display problems (Infbox instruction, opening additional windows
(stock detail, Left list picking,…)
• Only 65000 fields are publishable for both objects and subprograms (Nb of fields x Dimension)
 Important to use a dedicated, customized entry transaction (if available).

202
 9 – New X3 Web
Services (REST)

10/21/2016 203
Introduction – New Web Services X3

Sage X3 Version 7 technology introduced a new type of Web Service: REST Web Services.
There 3 types of facets that can be used:
• Query
• Detail
• Edit

For the following examples, we will consider that the V7 server name is X3PU9TRAINVM.

10/21/2016 204
Tools for testing REST web services

• Internet browser ( IE, Firefox, Chrome,…)

• Chrome Extension : Postman Interceptor
• Apps Chrome Postman
• Soapui (For SOAP and REST Web services)

Please use Chrome application

10/21/2016 205
JSON format

• REST Web Services platform is

based on JSON format.
• It is recommended to use a proper
JSON viewer application
(nodepad++) in order to parse
easily and automatically JSON
input/output.
Dedicated libraries are available to
manage JSON for all development
platform like .Net or PHP.

10/21/2016 206
HTTP methods for RESTFul Web Services

The HTTP protocol contains several methods we can use with RESTful Web Services. Those methods
will allow CRUD operations.
GET: is used to retrieve (read) the representation of a resource. For instance a list of sales orders,
or a sales order
POST: is used to create a new resource.
PUT: is used to update an existing resource. It is possible to create a new resource by passing the
key as an input parameter, but it is not recommended.
DELETE: is used to delete a resource.
Data operation RESTful methods

Create POST

Read GET

Update PUT

Delete DELETE

10/21/2016 207
URL: structures and parameters

• In order to use REST Web Services, it is critical to understand the structure of the URLs used in
Version 7. Version 7 is implementing the SDATA protocol. As such, you can describe the URL in 3
mains parts.
• URL=ENDPOINT WS+Resource+Parameters
• Example:
http://X3PU9TRAINVM:8124/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER?represen
tation=SORDER.$query&count=20

10/21/2016 208
URL: structures and parameters

ENDPOINT WS RESOURCE PARAMETERS

http:// X3PU9TRAINVM:8124 or http:// /sdata/x3/erp/X3PU9TRAIN_SEED_LOCAL
?representation=SORDER.$query&count=20
X3PU9TRAINVM DOC/SORDER
Parameters start with the ? character. You
This is the path to the class in your X3 folder:
need to specify the representation linked to
the class declared in the resource:
/sdata = name of the dispatcher representation=SORDER
/x3 = name of the application
You also need to specify which facet
This is the Syracuse Server you want to /erp = name of the contract (method) you want to use. The facet needs to
connect to with the port. start with a $ sign:
/ X3PU9TRAIN_SEED_LOCALDOC = name
representation=SORDER.$query
of the dataset (Endpoint X3 )
/SORDER= name of the class/entity
If there are several parameters, use the &
sign to add them :
representation=SORDER.$query&count=20

10/21/2016 209
 URL: structures and parameters

• Each facet of the representations can have

their own parameters.
• In order to use a facet in Web Services:
• it needs to be activated in the
representation

10/21/2016 210
How to get the properties for a facet?

• In version 7, we have access to the resource’s protocols. This feature defines the facets
requirements like the key to read, the URL to use, the properties, etc.
• The URL structure is the following:
http://.../$prototypes(‘MY_REPRESENTATION.$MY_FACET')
• For instance to get the prototype of the query facet of SORDER representation:
http://X3PU9TRAINVM:8124/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/$prototypes(‘SORD
ER.$query')

10/21/2016 211
Build URL for the facet Query

The result should look like this

• For instance properties $url and
$baseUrl is giving the URL to use to
execute the query facet:

• The final url being: $baseUrl+$url

All facets have a prototype.

10/21/2016 212
Buid URL for the several facets

Facets for a representation The prototypes are :

• $prototypes('SORDER.$details') . The ‘s’ is mandatory.
• $prototypes('SORDER.$edit’)
• $prototypes('SORDER.$query')
• $prototypes('SORDER.$lookup')
• $prototypes('SORDER.$summary')

213
URL for query – List of orders

Query – SORDER.$query
http://x3pu9trainvm:8124/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER?representation=SORDER.$query

10/21/2016 214
URL for detail(s)– Detail of order

Detail(s) – SORDER(‘key’).$details
http://x3pu9trainvm:8124/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER('QTEFR0110040')?representation=
SORDER.$details

10/21/2016 215
Tests for the several facets
Query Facet

Testing with interactive mode

• Connect to X3 with the browser
(Firefox, Chrome…)
• Connect to the Products menu
(Read-only-pages)
• You can see the list of products

Testing with Postman (use prototype)

• http://x3pu9trainvm/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER?representation=ITMM
ASTER.$query
The result is :

217
Query Facet

The web service use the representation ITMMASTER

and the entity (class) ITMMASTER.

Testing with Soapui

10/21/2016 218
Query Facet

Testing with Soapui

Type this URL:

http://x3pu9trainvm/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER?representation
=ITMMASTER.$query&count=20

We must give the user and password to access Syracuse

server. See to setup authentication http basic.

You must add the header Accept

The value is :
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

It is the HTTP method GET.

10/21/2016 219
Facet Details

Testing with interactive mode

• Click on the order number
• You can see the detail of an order

Testing with the browser

• Type in the browser:
http://x3pu9trainvm/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER(‘APPLEWATCHSP
‘)?representation=ITMMASTER.$details

The result is:

10/21/2016 220
Facet Details

Testing with Soapui

http://x3pu9trainvm/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER(‘APPLEWATCHSP’')?r
epresentation=ITMMASTER.$details

10/21/2016 221
 10 – How to call external
Web Service REST from X3

10/21/2016 222
Web services for testing
Installing Web Service into PHP server

• Get the file php-ws-x3_YYYYMMDD.zip

• Unzip it
• Copy php-ws-x3 into C:\Sage\wamp\www and rename to sagex3-ws
• Connect to http://x3pu9trainvm:8125/sagex3-ws/web
• You have this REST web services you can test.
- clicrdv
- creeraffaire
- eurostat
- hello
- stock

10/21/2016 224
Test the Web Service hello into X3
Test the web service hello
Connect with your browser to
http://x3pu9trainvm:8125/sagex3-ws/web/hello/
The result is : “Hello Everybody”

Connect to http://x3pu9trainvm:8125/sagex3-
ws/web/hello/?name=Olivier
The result is : “Hello Olivier”

10/21/2016 226
Configure and test this web services in X3

• Connect to X3
• Administration > Rest Web Services
• Name of Web Service: “hello”
• Base url has the real name of machine and the last
character must be /.
• You can test with the button ‘Test GET’
• It is OK.

10/21/2016 227
Call the web service with a script X3
http://.../hello

• Get the script ZCALLWSHELLO.src

• Execute this script

O_HTTP_COD = func EXEC_REST_WS("hello", "GET", "", PARAMS_COD, PARAMS_VAL,

HEADERS_COD, HEADERS_VAL, "{}", 0, "", O_RESHEAD, O_RESBODY)

Infbox "STATUS_HTTP-->"-num$([L]O_HTTP_COD)
Infbox "BODY-->"-num$([L]O_RESBODY)

The results of web services are

10/21/2016 228
Call the web service with a script X3 suite
http://.../hello?name=Olivier

• Get the script ZCALLWSHELLO2.src

The results are

• We use the X3 param :

PARAMS_COD(1)= "name" : PARAMS_VAL(1)= '"Olivier"'

10/21/2016 229
Call the web service with a script X3 suite
http://.../hello?name=Olivier&formatreturn=JSON

• Get the script ZCALLWSHELLO3.src

The results are

• We use the X3 param :

RETURNS="message.name"

10/21/2016 230
Test the Web Service clicrdv into X3
Test the web service clicrdv – Authentication http basic
• Connect to
http://x3pu9trainvm:8125/sagex3ws/web/clicrdv/api/v1/grou
ps/127723/

• User : sage1
• Password : sage2
/
The result is :

10/21/2016 232
Configure and test this web services in X3

• Connect to X3
• Administration > Rest Web Services
• Name of Web Service: “clicrdv
• Base url has the real name of machine and the last
character must be /.
• You can test with the button ‘Test GET’
• It is OK.

10/21/2016 233
Call the web service with a script X3 - GET
http://.../clicrdv/api/v1/groups/127723/

• Get the script ZWSEXT_TST_CLICRDV_GET.src

• Execute this script

The results of web services are

10/21/2016 234
Call the web service with a script X3 - POST
http://.../clicrdv/api/v1/groups/127723/

• Get the script ZWSEXT_TST_CLICRDV_POST.src

• Execute this script

The results of web services are

10/21/2016 235
 Q&A
Ask all your questions!
 Conclusion

In this Workshop “Level 1”:

• You have been given a reusable PHP tool
• You have been given a methodology to be
autonomous to call a WS X3 such as:
- Sub-program
- Object
- X3 Version 7
• You have practiced an example of an
external X3 WS

10/21/2016 237
 Thank you

© 2015, The Sage Group plc or its licensors. Sage, Sage logos, Sage product and service names mentioned herein are the trademarks of The Sage Group plc or its
licensors. All other trademarks are the property of their respective owners.
 Annexes

10/21/2016 240
Public Resources GitHub

• https://github.com/orgs/Sage-ERP-X3
• sample-x3-ws-php-webportal : Example of this documentation
• soap-tester-client : This repository contains .Net code for Sage ERP X3 Soap Web Service
tester

10/21/2016 241
How to calling web services X3
See folder CALL_WS_X3\
• PHP : See CALL_WS_X3\PHP\howto_PHP.txt
• C# : See CALL_WS_X3\CSHARP\howto_CSHARP.txt

10/21/2016 242