Professional Documents
Culture Documents
Sage X3 Web Services
Sage X3 Web Services
Distribution
Contracts (Purchasing and Sales)
CB 101 – 102 Distribution and Inventory
Loan Orders
Introduction & Packaging & Shipment Preparation Purchasing Subcontracts
Functional Overview Purchasing Signature Management
Pre-Allocations (Pegging Function)
(3 days) Sales and Purchasing Prepayments
TEC102 Sales Reps and Commissions Radio Terminals
Development Sourcing: RFQs, Responses
(4 days) Carrier Management
Inter-Site and Intercompany Transactions Manufacturing (5 days)
Invoice Elements (Purchasing & Sales) Configurator
Kits, Options & Variants
Weighing
Price List Management (Advanced)
TEC103 Manufacturing (4 days) Optimisation ILOG
Installation Advanced Global Manufacturing
(4 days) Production Costing Finance
Finance Multi-Legislation Set Up
Bank Communication & Reconciliation Operating Budgets
FIN201 - Budget Control/ Analytical Budget
Analytical Allocations
Finance Financial Data Extraction
(4 days) Statements & Reminders Factoring
Automatic Journals & Dimension Defaults
Advanced Payment Transactions
Month and Year End Processes Tools & Development
OPE201 - TEC101 - Fixed Assets Using BI in Sage ERP X3
Distribution Common Tools Inventory (3 days) Java Bridge Serveur Components
(3 days) (3 days) Allocation Rules (Advanced)
EDM – Version One
Stock Counts
Serial Number Management Web Services
Reodering Replenishment Storage Plan Crystal Reports
You
Valuation Methods and Price Adjustments
and cost calculations Are
OPE202 - OPE203 - Quality Control & Sampling Here
Inventory Manufacturing
Tools & Development
(2 days) (3 days) Advanced Common Tools
Advanced Development
Course Map
SAFE X3 Web Services
Course Contents
The set of network protocols Web Services are based on is called SOAP
(Simple Object Access Protocol). It defines XML message transportation over a
network, usually through http. Web Services are hence mainly based on http and
XML.
A Web Service has a set of methods that may be invoked or called by the client
application. Each method represents a functionality of the Web Service. It is
called by sending the parameters to it in XML format, and returns a set of
results, also in XML format.
Web Services are the ideal tool for integration of business applications and
B2B/B2C commerce.
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.
Objects: A set of methods to create, modify or delete an X3 object record and also
to execute buttons or menus linked to those objects, with certain 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.
Object methods
read(context, object, key)
context: Connection parameters and other options (trace, debug etc.)
object: The object Web Service name
key: Key(s) element(s) for the record to be read
This reads an object record and returns all the field values. It is equivalent to accessing the record in X3, but the record is not
locked.
This creates an object record based on the data transmitted to the method, at least all the values for mandatory screen fields.
It is equivalent to populating the screens and pressing the Create button in X3. All application controls are performed.
X3 responds by returning all the screen data (All fields) and eventual X3 error or warning messages.
This modifies an existing record in the object. The key is specified, as well as field values to be modified.
This is equivalent to populating the fields and pressing the Save button in X3.
This deletes an object record after performing necessary data integrity checks. It is equivalent to pressing the
Cancel button in X3.
This triggers the action linked to an object button or menu item, for example the V action attached to Sales Orders
that will calculate the SO Value without creating the order.
X3 responds by returning all the screen data (All fields) and eventual X3 error or warning messages.
This runs an X3 subprogram identified by its Web Service name, using the parameters in the input XML data.
Return values are in XML format.
To be published as a Web Service, a subprogram must not require any user interaction (X3 window), the only
data it will run with being in the input parameters.
This queries the object’s main left browser and returns the column values for a maximum of nblines records, in XML
format.
getDescription(context, webService)
webService: A Web Service public name (Object or Subprogram)
Verify that an object, subprogram or object list has been published in X3 as a Web Service.
Load the latest version of that Web Service in the X3 web server cache.
Obtain a description of the data required or returned by the Web Service, i.e. the following information:
• For an object list, the names and types of the columns defined in the object
• For an object, the names and types of the screen fields for that object
• For a subprogram, the name and types of the subprogram arguments.
X3 solution architecture
Database Process X3 application
Server Server Server
Windows
Client
LAN
IE Client (Web)
http
Third-Party
Web
Application
Server
(Web Services)
http / SOAP / XML
X3 Web Server
X3 Application
Servlet Container (Tomcat) Server
Cache Server
Session Server
Connection Server n simultaneous
Web Service Server permanent
connexions
WS Connection Pool
Third-Party
Applications
(Java, .NET,
HTTP Server (Apache) JavaScript, PHP etc.)
1. User action: User requests info, presses web site button etc.
2. Web site calls X3 web service URL with proper parameters (http/SOAP)
3. X3 web server contacts application server and triggers process (X3 protocol) 2 6
4. X3 process is run by the application server (Subprogram call, object action etc.)
Users
1 1
Internet / Intranet
7
Web Site
X3 Web Server
N Permanent Connexions
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 parameters (Console) and is limited by the maximum number of
Web Service connections allowed by the X3 licence.
Application Connection
Server Pool
1 Connexion Request 1
3 simultaneous requests
Request 2
Request 3
Request 4
Waiting
Queue
Request 5
Argument
s
X3 Object
(Customers, Sales Orders,
Products, specific object…)
“Wrapper”
Methods: Program
read() +
save() Test
delete() Program
…
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.
SAFE X3 Web Services
2.5 – Publishing Web Services In X3
The 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:
V5:
WJ[OBJ][TRS] for objects, where [OBJ] is the object code and [TRS] the entry
transaction code selected (If any).
WR[WS_NAME] for subprograms, where [WS_NAME] is the subprogram public
name (Web Service name).
V6:
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.
SAFE X3 Web Services
3 – Setting Up Web Services
You must install the web server to be able to use X3 Web Services.
Once the web server is installed, you must publish the folder you will access, using the
normal procedure (Console – c.f. Installation course).
The Web Service connection pool is set up using the console (Web Servers panel)
A pool is identified by a unique name in the X3 solution, and by the following parameters:
Default startup language (X3)
Default startup X3 user code and password
System account / password
MaxSize (maximum number of connections)
Initial size (number of connections at startup)
REMARK : The maxSize and InitSize MUST NOT be greater than the number of WS
licences.
If so, the pool will be automatically stopped, and will not be started unless you put
proper values.
When configured, the pool may be started manually from the Console.
The web server technical page also contains a Web Service tester.
SAFE X3 Web Services
Exercise 1
SAFE X3 Web Services
4 – Publishing Subprograms
Introduction
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.
Dictionary information
Subprograms that may be called as Web Services have the Web Service flag
enabled.
The Length column defines a maximum size for character, clob and blob
variables. This allows the client application to implement additional controls.
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:
Messages are transmitted in the XML response data and may be used by the
client application.
50 arguments maximum for a subprogram (But all arguments may have dimensions).
The subprogram dictionary is a system table, i.e. it is the same for all the folders in the
solution.
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 if server email is
wanted.
Reports may be generated using the Report instruction. Always use an X3 Report Server.
SAFE X3 Web Services
4.2 – Publishing A Subprogram
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.
</GRP>
The subprogram web service wrapper program acts as an interface between the
web server and X3code. It manages:
Header arguments
Information / Error / Warning messages
The subprogram arguments and return values.
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.
Contents
X3 objects (Products, Sales Orders, Suppliers etc.) are stored in a dictionary that describes:
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
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.
Field types
Invisible and technical fields are available in the [M] classes. Not transmitting
them to the clients simply reduces network traffic.
Field Actions
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.
In standard, the only objects that have been verified are Sale Orders (SOH),
Customers (BPC)
and Products (ITM).
</GRP>
</GRP>
MOD="Display"
TYP="Char"
LEN="30"
C_BRI="Order Num." /> Column title
</GRP>
</ADXKEY>
<ADXMEN>
</ADXSER>
</ADXREAD>
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 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.
The Web Server includes a Web Service Tester, accessible in the web server
technical page.
It is a simple web service client that implements the three types of methods X3
may publish: Subprograms, object methods and the object list.
It works by sending the raw XML data provided by the user to the web service
and simply displaying the results as raw XML data in corresponding text fields.
Pool Entry Group: Public name of the web service pool to use (As defined in
the console).
Adonix User / Password: X3 user name and password to use for connection.
The Save Context button will save the above parameters for future use.
The Web Service section holds the public name and generic parameters for executing the
web service.
The Action section contains the methods for the web service type to be tested:
Execute for subprograms
Read, Create, Modify etc. for objects
List for object lists
A common Description action for all web service types that gets the web service
XML description.
A Subprogram Data section allows users to enter raw XML input data (see subsequent
sections in this course)
Four output sections will display web service result data (all available within the XML output
stream)
Reply Description is a verbose description of the final processing status.
XML Reply shows the response part where actual X3 data is contained.
Data Process Log is a detailed account of how the input XML data was
processed.
Request Trace is the detailed log of the whole process.
An XML data stream starts with a header or declaration in the following format:
<?xml version="1.0" encoding="UTF-8"?>
XML data is enclosed into elements with the following format: <TAG
Property="Value">Content</TAG>.
Start and end delimiters are called tags. The element's content (Or value) is
anything that appears between the tags.
Elements may be nested into other elements, in which case they are called
child elements. <PARAM>
<FLD NAME="SOHNUM">SO000052</FLD>
<FLD NAME="BPCORD">C001</FLD>
<FLD NAME="ORDDAT">20061124</FLD>
...
</PARAM>
Elements have properties that are identified inside the start tag
(Property="Value").
For X3 web services, the body of the input data is enclosed in a <PARAM>
element (Input parameters), and individual fields or arguments are in a <FLD>
child element:
<PARAM>
<FLD NAME="ITMREF">CD100</FLD>
</PARAM>
<PARAM>
<FLD NAME="SOHNUM">SO000052</FLD>
<FLD NAME="ITMREF">CD100</FLD>
</PARAM>
For other object actions, no input XML data is necessary. The tester interface provides the
necessary fields:
Read, Delete: Only the object's key (Index fields) is required. Corresponding
values are populated in the Key(s) section.
List: Left list criteria are entered in the Criteria section. No input XML stream is
required.
The key is also required for the Modify action in addition to XML data, since the system
needs to know which record is being modified.
SAFE X3 Web Services
6.2 – XML Data Streams
XML input data for table screens
</PARAM>
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>
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 (See chapter 5.2 – The XML
Description File for more details).
The data is contained in the <RESULT> element in the returned XML
stream.
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")
Table/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 table 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 table 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.
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.
Sage developers have designed a basic Java web service test application that
automatically generates a graphical interface based on the web service
description. It allows the user to avoid the work involved in constructing a correct
XML stream.
Load testing
Load testing will show you the total CPU and memory usage on the web server,
which may be used as an estimation of future needs for the live system.
The Java Tester provides a load testing section that may be used to simulate
important web service activity according to a specified scenario, and for a
specified number of simultaneous connexions.
The web service protocols include a description standard (different from the one generated
directly by X3) integrated in an XML structure. It is called the WSDL (Web Service
Description Language).
Normally, each field or argument to be transmitted to a web service must be described in the
WSDL structure. In X3 however, a single web service is used for all objects.
In order not to have a large number of WSDL descriptions, the "internal" structure (screen
fields, subprogram arguments etc.) is described as a variable XML flux included as raw XML
in single "generic" WSDL, where only methods (read, create, query etc.) are fixed.
This also avoids having to change your client application each time a field is modified or
added in an X3 screen.
As a consequence, the client application has the responsibility of constructing the input XML
stream and parsing the response XML stream.
The WSDL file includes detailed information about the web service's methods
and how to implement them in the form of complex data types and functions.
The X3 web service WSDL file is published by the web server and may be
accessed through the following URL:
http://[WebServer]/adxwsvc/services/CAdxWebServiceXmlCC?wsdl
Stub classes are also shipped ready to use with the X3 Web Server and may be
downloaded from the Web Service Server section on the technical page.
X3 Web Server
http://[WebServer]/adxwsvc/services/CAdxWebServiceXmlCC?wsdl
X3 Web Server
Download Eclipse 3.1 Workspace
Download Visual Studio 2005 Solution
Example:
requestConfig =
"adxwss.trace.on=off&adxwss.trace.size=16384
&adonixx.trace.on=off&adonix.trace.level=1&adonix.trace.siz
e=8
&adonix.debug.on=off&adonix.debug.host=localhost&adonix.deb
ug.port=1789"
CAdxResultXml: This class contains the actual results in an XML clob, along
with the status, messages and technical information.
int status Response status (1 = OK, 0 = Not OK)
CAdxMessage[] messages An array of X3 messages (See below)
string resultXml The XML output or return string (Raw XML format)
CAdxTechnicalInfos technicalInfos
Technical information regarding request processing (See below).
poolExecDuration
poolRequestDuration
totalDuration
Calling the service via the stub classes (Using the CAdxWebServiceXmlCC
class)
Most of the code in your application will usually be dedicated to managing the
interface and building or parsing Xml streams.
SAFE X3 Web Services
7.3 – .NET Development
Preparing the solution
Examples in this section are developed in the C# language using Microsoft® Visual Studio®
2005.
In order to prepare a .NET solution for web services, you must add to it a web reference,
which is the name of a web service WSDL in the .NET environment.
Once the web reference is imported, you must use the main class in your
project:
using CAdxWebServiceXmlCC;
using System.Text;
using System.Xml;
using System.IO;
The first step in calling a web service is preparing the call context structure,
which will be passed as a parameter to all the web service's methods (See
section 7.2):
The next step is to create an instance of the web service, and to prepare a
variable of type CAdxResultXml, the class that will hold the results:
// XmlResult instance
CAdxResultXml result = new CAdxResultXml();
Most of the X3 web service methods take an XML input stream as an argument
(amongst others).
The XML input stream may be built as a simple string, or using available .NET
XML utilities and builders. The run method accepts strings as the third
argument.
// Run subprogram
// run method: run(CAdxCallContext <Context>, String <WebServiceName>, String <XML Input>)
// XML Input:
// XML header + <PARAM><FLD NAME="field1">value1</FLD><FLD NAME="field2">value2...</PARAM>
result = wsvc.run( cc, "GETITMPRI", xmlInput );
read does not take any XML input stream. Instead, you must use an array of
instances of the CAdxParamKeyValue class to indicate which record is to be
read. Each instance contains one key element. For simple objects, there will be
only one element in the array:
query returns data corresponding to the object's left browser columns. It also
takes an array of CAdxParamKeyValue instances as an argument, but this time
it represents quick select criteria for each of the left browser's columns.
// Read object
CAdxParamKeyValue[] objKey = new CAdxParamKeyValue[3];
The result XML stream is contained in the CAdxResultXml instance. This class
contains:
The process of preparing the Java project to generate and use the stub classes
is the same as in a .NET environment. The best tool to use in a Java
environment is the Axis Ant task and wsdl2java, that convert a WSDL files to
Java stub classes.
You can also download the stub classes directly from the X3 web server's Web
Service Server / Axis Stubs section.
Once the stub classes have been generated, they must be included in your
project's directory / build path and must be imported into your project:
Other Java SDK classes will also be necessary (A few of them are listed here):
import java.io.StringReader; // String reading/building classes
import javax.xml.parsers.DocumentBuilder; // DOM builder
import javax.xml.parsers.DocumentBuilderFactory;
import org.xml.sax.InputSource;
[...]
SAFE X3 Web Services
7.4 – Java Development
The web service locator
As with .NET, the first step in calling a web service is preparing the call context
structure (See section 7.2):
Most of the X3 web service methods take an XML input stream as an argument
(amongst others).
The XML input stream may be built as a simple string, or using available Java
StringBuffer or XML utilities and builders. The run method accepts strings as the
third argument.
// Prepare XML
StringBuffer xmlBuilder = new StringBuffer(1000);
// Run subprogram
// run method: run(CAdxCallContext <Context>, String <WebServiceName>, String <XML Input>)
// XML Input:
// XML header + <PARAM><FLD NAME="field1">value1</FLD><FLD NAME="field2">value2...</PARAM>
result = wsvc.run( cc, "GETITMPRI", xmlInput );
read does not take any XML input stream. Instead, you must use an array of
instances of the CAdxParamKeyValue class to indicate which record is to be
read. Each instance contains one key element. For simple objects, there will be
only one element in the array:
Notice the CAdxParamKeyValue element with index 1 has been built in one shot
this time, using the CAdxParamKeyValue constructor with two arguments (The
key field and its value). Also notice the field name has been used rather than its
position in the index.
Both methods are valid in .NET and in Java.
query returns data corresponding to the object's left browser columns. It also
takes an array of CAdxParamKeyValue instances as an argument, but this time
it represents quick select criteria for each of the left browser's columns.
// Read object
CAdxParamKeyValue[] objKey = new CAdxParamKeyValue[3];
objKey[0] = new CAdxParamKeyValue("1","C*"); // Searching for cust.codes that start with "C"
objKey[1] = new CAdxParamKeyValue("2","*");
objKey[2] = new CAdxParamKeyValue("3","*");
Definition
In a web page context, PHP runs on the web server, taking PHP code as its
input and creating web pages as output. The actual code may be embedded into
html pages and vice-versa (PHP pages may include html elements).
<?php
The next step in calling the web service is building the Calling Context structure.
It is a string structure that must conform to the wsdl definition published for the
web service:
$CContext["codeLang"] = "BRI";
$CContext["codeUser"] = "ADMIN";
$CContext["password"] = "";
$CContext["poolAlias"] = "WS_DEMOBRI";
$CContext["requestConfig"] = "adxwss.trace.on=on&adxwss.trace.size=16384
&adonix.trace.on=on&adonix.trace.level=3&adonix.trace.size=8";
Most of the code for running a subprogram will be dedicated to constructing the
XML input:
// Run the subprogram using the SoapClient variable and Calling Context defined earlier
$result = $client->run($CContext,"GETITMPRI",$xmlInput);
As described in earlier sections, the save method takes the calling context, the
public web service name and the XML input as arguments:
The result XML stream returned by the web service contains the usual
structures, as described in the wsdl definition:
} else {
// Return array of messages
$messages = $result->messages;
$parse_error = True;
$err_text = "ERROR: ($type) $message \n";
$err_mesg .= " 1. $err_text<br />";
…
If the debugger is opened, when a web service is run the system will halt in
process AWEB (before execution), and at any dbgaff instruction encountered
in the X3 code.
[...]
cc.requestConfig = "…&adonix.debug.on=on&adonix.debug.host=localhost&adonix.debug.port=1789";
AIRFRANCE
80000 users
30 orders per minutes, ~ 1 order every 2 seconds
300 WS calls per minute
40 licenses WS spread on 2 web servers
A load balancer working on the 2 web servers
~ 40 Web Services