User action
Introduction
A XTEND User action triggers either an action carried out directly by the XTEND server, or a call to a X3 Web service being either a sub-program or an action associated to an X3 object.
The action calls on X3 Web services when associated to an interface.
A Web action calls on parameters on entry, carries out a processing and values a certain number of parameters on return such as calling a sub-program in 4GL.
In the case of an XTEND application, the parameters on entry are generally entered by the User in an HTML form, and the values returned by the sub-programs are stored in memory in the User session (mapping) with the purpose of being displayed in an HTML page or used as parameters for other actions.
This document specifies the method to follow to create new user actions.
Programming and test in X3
The first step consists in programming and TESTING in X3 client mode the L4G processing or the X3 object which will be called by the XTEND action.
Case of the X3 objects
Before using a X3 object in a XTEND application, it is necessary to make sure that this X3 object can be used through web service.
It is especially necessary to make sure that the processing of the actions does not require the presence of a user (individual) in front of a screen to answer the potential questions or messages the X3 server returns.
User messages
The AWEB processing contains utility sub-programs to manage the user messages.
Sending of an information, warning or error message:
- Subprog ADDMESSINF(MESSAGE)
- Subprog ADDMESSWARN(MESSAGE)
- Subprog ADDMESSERR(MESSAGE)
In test mode
- Subprog INITABMES
- Subprog VISUALLMES
A user action is considered validated if no error messagewas sent by the Web service call..
The error messages are sent in 4GL via sub-program ADDMESSERR (Call ADDMESSERR("Message") From AWEB)
X3 messages are displayed via the token AXUSERMSG.
Ex.:<span id="userMsg" class="userMsg" adx="aMsgUser"></span>
Sub-program case
It is important to remember that calling a X3 processing via a web service is "w/o report", i.e., the context of the X3 session (global) used to process a web service is only valid during the service processing. This context is lost after the execution of the processing. It is reinitialized at each call.
All the contextual data must be transported in the parameters of the web service call.
When calling the web service of sub-program type, the XTEND server add the contextual parameters to this sub-program call by valuing the AXPARCOD and AXPARVAL parameters of the AX_PAR publication group, if the AX_PAR group has been defined when publishing the sub-program.
The parameters, included the default contextual parameters, are the following:
|
Code |
Description |
|
SITCOD |
XTEND site code |
|
USRCOD |
XTEND user code if the user is identified |
|
USRPRF |
XTEND user profile code if the user is identified |
|
USRLANG |
XTEND language code (site language) |
Web service publication and test
This step makes sure that the web services are available and work correctly.
See the web services page.
Creation of an action
-1- Setup of the interface
Create an interface record via the Development/Safe X3 WAS/Link SAFE X3/Interface function.
-2- Creation of the fields
Calling a web service of Action type returns data which are either sub-program parameters or fields of a X3 object.
All the fields used to display or pass parameters of web or XTEND type must be declared in the fields dictionary.
After having created the interface, it is recommended to create all the fields returned by web service via the 'Tools/Creation token field' menu of the interface record.
-3- Creation of the entities
The parameters in issue, returned by web services, are grouped by publication groups.
This step consists in creating a XTEND entity by publication group.
In order to create the entities the utility function creation of entities accessible via the 'Tools\Entry help'' menu of the entity record.
-4- Creation of the Web action
This step consists in creating the web action to define the mapping between the web service parameters and the XTEND entities.
The mapping concerns:
- The parameters (in entry) that needs to be valued when calling the web service
- The parameters (in issue) returned by web service, that need to be recorded and from which the XTEND entities of session type will be created
-5- Creation of the dynamic link
This step consists in creating the dynamic link token which will be inserted in the html page either in a button or in a anchor to make sure that the user can trigger the action with a click.
the dynamic link is also used to specify how the web action call parameters will be valued either from data entered by the user (web fields) or from the data stored in the memory (XTEND fields).
Login action
XTEND login principle
XTEND takes into account 2 user types, which are:
- the anonymous users
- the identified users
The user is identified with the XTEND server via the login page by entering a user code and a password.
The action of the XTEND login calls on a L4G sub-program (web service) used to check if the user exists and if the password is valid. An error is posted (ADDMESSERR) to make the login invalid.
A 'protected' XTEND page will be only visible by the identified users.
It is also possible to protect the access to the XTEND pages according to the XTEND profile, which code is returned by the login program (optional).
See ASAMPLE login site.
Interface of the login L4G sub-program
XTEND can call on any L4G sub-program which first 12 parameters are the following:
Subprog ACTION (AXPARCOD, AXPARVAL, AXUSERCODE, AXPWD, AXUSERPROF, AX3SOL,
AX3FLDR, AX3LANG, AX3USER, AX3PWD, AXLOGCOD ,AXLOGVAL ...)
Variable Char AXPARCOD()()
Variable Char AXPARVAL()()
Variable Char AXUSERCODE()
Value Char AXPWD()
Variable Char AXUSERPROF()
Variable Char AX3SOL()()
Variable Char AX3FLDR()()
Variable Char AX3LANG()()
Variable Char AX3USER()()
Variable Char AX3PWD()()
Variable Char AXLOGCOD()()
Variable Char AXLOGVAL()()
...
|
Parameter |
Type |
Description |
|
AXPARCOD |
Valued by the XTEND engine |
Key/value contextual parameters valued by the XTEND server when calling on the sub-program. |
|
AXUSERCODE |
Entered by the user |
XTEND user code entered by the user |
|
AXPWD |
Entered by the user |
Password entered by the user |
|
AXUSERPROF |
Returned by X3 |
XTEND profile code used to manage the access to the pages |
|
AX3SOL |
Returned by X3 |
X3 solution code |
|
AX3FLDR |
Returned by X3 |
X3 file code |
|
AX3LANG |
Returned by X3 |
X3 language code for the AX3SOL/AX3FLDR login |
|
AX3USER |
Returned by X3 |
X3 user code for the AX3SOL/AX3FLDR login |
|
AX3PWD |
Returned by X3 |
X3 password for the AX3SOL/AX3FLDR login |
|
AXLOGCOD |
Returned by X3 |
Additional information on the user, of type key/value, which are stored in the XTEND session (ASESSION section). |
|
.... |
|
The login sub-program can return other information that will be "mapped" on XTEND entities. |
Sub-program record
Description record of the login sub-program.
The names of the publication groups of the AX* parameters must be respected.
|
Code |
Type |
Dim |
Argument type |
Publication group |
|
AXPARCOD |
Char |
20. |
By address |
AX_PAR |
|
AXPARVAL |
Char |
20. |
By address |
AX_PAR |
|
AXUSERCODE |
Char |
1. |
By value |
AXLOG_PAR |
|
AXPWD |
Char |
1. |
By value |
AXLOG_PAR |
|
AXUSERPROF |
Char |
1. |
By address |
AXLOG_PAR |
|
AX3SOL |
Char |
10. |
By address |
AXLOG_X3 |
|
AX3FLDR |
Char |
10. |
By address |
AXLOG_X3 |
|
AX3LANG |
Char |
10. |
By address |
AXLOG_X3 |
|
AX3USER |
Char |
10. |
By address |
AXLOG_X3 |
|
AX3PWD |
Char |
10. |
By address |
AXLOG_X3 |
|
AXLOGCOD |
Char |
50. |
By address |
AXLOG_RES |
|
AXLOGVAL |
Char |
50. |
By address |
AXLOG_RES |
The following parameters are given for information purposes and managed by the XTEND developer.
A list of ship-to addresses and a list of invoicing addresses (10 lines max) which will be 'mapped' on the SHIPADDR and INVADDR entities
|
SHIPADDR |
Char |
10. |
By address |
SHIPADDR |
|
SHIPCITY |
Char |
10. |
By address |
SHIPADDR |
|
SHIPZIP |
Char |
10. |
By address |
SHIPADDR |
|
INVADDR |
Car |
10. |
By address |
SHIPADDR |
|
INVCITY |
Char |
10. |
By address |
SHIPADDR |
|
INVZIP |
Char |
10. |
By address |
SHIPADDR |