Development > Safe X3 WAS > SAFE X3 link > Interface 

SEEWARNING Before creating your site, it is advised to read the documentation:Before beginning.


The main function of the setup record 'Interface' is to identify and locate an X3 Web service by supplying:

  • its publication name or alias,
  • the data of the Web service server providing the service.

The interactions between an XTEND Web application and the X3 back office includes two service categories:

  • the services of type 'Access' describing the access to data,
  • the services of type 'Action'describing the User actions.

SEEWARNING The number of setups of Web services of type 'Access' or 'Sub-program access' is limited to 50.

In Web service mode, the X3 global variable GUSER contains the X3 User code set as a setup at the moment of the Web service call.

XTEND values the X3 User code depending on whether the User is logged in or not:

  • The XTEND User not logged in uses the X3 User code defined by default in the Web service pool,
  • The logged in XTEND User uses the X3 User code returned by the login function.

Interfaces of type 'Access'

The XTEND server does not have a direct access to the X3 database via a a database connector, but by calling up specialized Web services of type sub-program or left list.

The interfaces of type 'Access' make it possible to define these Web services working as data providers.

The Web services are called up by the tokens of type block.

Generated access to Table

Is used to generate automatically a Web service to access the recordings of a table of the X3 database:

1. Generation of a 4GL processing,

2. Creation of a record in the sub-program table,

3. Publication of the Web service.

The generated Web service can immediately be used on all Web service servers loading the folder.

Generated access to View

Same thing as for 'Generated access to Table', but concerns X3 views.

Left list access

Makes it possible to use the 'Left list' Web service of an X3 object as data source.

'Sub-program' access

The type 'Sub-program access' is generally used to add calculated fields to the fields of the table/view you want to access.

Example: add the availability and the product prices in a catalog.

In order to calculate the values of the 'calculated' fields, a 4GL processing must be run on the context setups coming in addition to those submitted to a standard processing by the XTEND server. For that purpose, setups AXPARCOD and AXPARVAL are used (see User actions).

Example: a Customer code or a quantity/date entered by the User.

Parameter grid 'Sub-program access'

This grid makes it possible to define the list of additional setups.
The value of setups of type 'Entry' is entered in the record of the token dynamic link or block.

SEEWARNING Unlike the User actions, the sub-program access does not make it possible to anter the mapping of setups.

The setup grid can be considered as a mapping on the list of setups AXPARCOD/AXPARVAL.

Optimizations

As for the Generated access to Table, calling Web services must sometimes be optimized to improve response times.

  • This grid is used by the developer to define (enter) his own optimization types.

  • The XTEND server values setup $OPTIMZE when calling the Web service.

  • The 4GL developer is responsible for the optimization processing taking into account the setup value.

Interfaces of type 'Action'

The interfaces of type 'User Action' make it possible to define Web services (4LG processings) having an effect on the X3 back-office data.

The interface 'Action' is associated with a record Web action is used to describe the setup mapping.

The Web actions are associated with the tokens of type dynamic link to be inserted in the graphical interface elements such as buttons (<input type="button" onClick="">) or anchors(<a href="button" onClick="">).

User action

An EXTEND User action always triggers the following: calling of an X3 Web service being either a sub-program or an action associated with an X3 object.

An XTEND action calls on setups on entry, carries out a processing and values a certain number of parameterson return such as calling a sub-program in 4GL.

In the case of an XTEND application, the setups 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 setups for other actions.

Sub-program action

The 4GL processing must have been previously programed, and the sub-program record must have been created.

Once the interface has been created, the button 'Generate access' makes it possible to load the Web service.

X3 Object Action.

The code of the X3 action (Action button of the object) is entered in the Web action record.

Once the interface has been created, the button 'Generate access' makes it possible to load the Web service.

    Prerequisites

    SEEREFERTTO Refer to documentation Implementation

    Screen management

    Header

    Fields

    The following fields are present on this tab :

    Interface code.

    • Site (field FCYLIB)

    Current Web site

    • Description (field INTIT)

    [object Object]

    Close

     

    Tab General

    Presentation

    Interface general setups
    The setups to enter depend on the interface type selected.

    Close

     

    Fields

    The following fields are present on this tab :

    Interface type

    • Type (field TYP)

    The interfaces of type 'Access to data':

    • Generated access to Table : is used to generate automatically a Web service to access the recordings of a table of the X3 database:

    • Generated access to View : same thing as for 'Generated access to Table', but concerns X3 views.

    • Left list access : makes it possible to use the 'Left list' Web service of an X3 object as data source.

    • Sub-program User access : is used to customize a sub-program of type 'Access to data' and to add calculated fields.

    The interfaces of type 'Action':

    • Sub-program User action : calls a Web service of type sub-program.

    • Object User action : calls a Web service of type Action of an X3 object.

    Table/view

    Table code for a 'Generated access to Table'.

    View code for a 'Generated access to View'.

    Object

    Object code for the interfaces of type 'Object User action' and 'Left list access'.

    • Transaction (field VARIANTE)

    Code of the transaction for the interfaces of type 'Left list access' and 'Object User action'

    • Invisible fields (field INVISIBLE)

    This field is used to take into account the invisible fields for the Object Web service in the case of interfaces 'Left list access' and 'Object User action'.

    • field LIBVAR

     

    Sub-program

    • Processing (field PRG)

    Name of the processing called by the Web service.

    This field is to be entered only for interfaces 'Sub-program access' and 'Sub-program User action'.

    SEEWARNING It is necessary to create the processing and the sub-program record.

    • Sub-program (field SUBPRG)

    Name of the sub-program called by the Web service.

    This field is to be entered only for interfaces 'Sub-program access' and 'Sub-program User action'.

    SEEWARNING It is necessary to create the processing and the sub-program record.

    Publication

    • Publication name (field WEBSRCCOD)

    Publication name of the Web service.

    • Max. no. of lines (field RESMAX)

    Maximum number of recordings returned by the Web service, can be modified via button 'Generate access'.

    • Generate access (field IGEN)

    SEEREFERTTO In order to access the field help of the screen displayed, see documentation on button [Generate access].

    • field WWSLIB

     

    Close

     

    Tab Advanced

    Fields

    The following fields are present on this tab :

    Display messages by type

    • Information (field DSYINF)

    An X3 Web service can return messages of type:

    • Information
    • Warning,
    • Error.

    Checking a type of message indicates to the XTEND server that it must take into account this particular type of message on return of the Web service call and display it via the Field token of name AMSGUSER.

    • Warning (field DSYWRN)

     

    • Error (field DSYERR)

     

    Table number 1

    • Optimizations (field OPTIMI)

    The interfaces of type 'Access' are the most used by the XTEND engine, the Web site fluidity relies heavily on the respective response times of the called Web services.

    This grid displays for each access type the list of possible optimizations selected when calling in the block token.

    Pool

    • Pool by default (field LNKADSDEF)

    The Web service pool is used to locate a Web service:

    • Yes: indicates that the XTEND server will use the Web service defined at site level to call up the Web service associated with this interface.

    • No: used so that the interface uses a specific Web service pool whose code is given by the parameter 'Web service pool'.
    • Web service pool (field LNKADS)

    Code of the XTEND pool if it is different from the default pool entered at the level of parameter 'Web site'.

    Using a specific XTEND pool for a given interface makes it possible to distribute the load between different connection pools when few Web service licences are available.

    For instance:

    The default pool can be used for calling interactive Web services having short response times.
    However a specific pool can be used for calling Web services triggering longer processings (such as passing of an order) so that the other Users are not blocked.
    This pool can possibly be connected to a dedicated processing server.

    Access

    • Protected access (field ACSMOD)

    This parameter is used to control access to Web services via profiles:

    • Yes: indicates that only logged in Users can access this Web service.

    This parameter is generally used by applications using the AJAX libraries of XTEND.

    • field W1

     

    Grid Param sub-routine access

    Parameter code

    • Value (field VALTYP40)

    Type of value for the parameter:

    • Entry: the value of parameters of type Entry is entered in the record of the token dynamic link or block.
    • Constant : fixed value entered in the column 'Constant'.
    • Constant (field VALEUR40)

    Value of a parameter of type 'Constant'.

    Close

     

    Tab Description

    Presentation

    [Development screen]

    Close

     

    Fields

    The following fields are present on this tab :

    Table number 1

    • Group (field DSCGRP)

     

    • Code (field DSCCOD)

     

    • Dim. (field DSCOCC)

     

    • Type (field DSCADR)

     

    • Description (field DSCDES)

     

    Grid Object action

    • Key code (field DSCKEY)

     

    • field DSCKEYDES

     

    Close

     

    Reports

    By default, the following reports are associated with this function :

     PRTSCR : Screen print

    This can be changed using a different setup.

    Specific Buttons

    This button is used to update the XTEND dictionary in XML format.

    The X3WEB server takes into account only the dictionary with this format.

    There is one XML file per dictionary.

    For instance, the ACT.xml file corresponds to all the web actions for the current web site.

    This button is used to copy an interface.

    The following fields are included on the window opened through this button :

    Block number 1

    • Data type (field TYP)

    The interfaces of type 'Access to data':

    • Generated access to Table : is used to generate automatically a Web service to access the recordings of a table of the X3 database:

    • Generated access to View : same thing as for 'Generated access to Table', but concerns X3 views.

    • Left list access : makes it possible to use the 'Left list' Web service of an X3 object as data source.

    • Sub-program User access : is used to customize a sub-program of type 'Access to data' and to add calculated fields.

    The interfaces of type 'Action':

    • Sub-program User action : calls a Web service of type sub-program.

    • Object action : calls a Web service of type Action of an X3 object.
    • Code (field OBJCOD)

    • field ZDES

     

    • Publication name (field WEBSRCCOD)

    • Max. no. of lines (field RESMAX)

    Maximum number of recordings returned by the Web service, can be modified via button 'Generate access'.

    • Processing (field PRG)

    Name of the 4GL processing called by the Web service.

    • Subprograms (field SUBPRG)

    Name of the sub-program called by the Web service.

    • Module (field MODULE)

    • field WA

     

    • field WB

     

    • field WC

     

    • Type (field TYPASU)

    Grid Interface

    • field WSEL

     

    • Code (field CODXTD)

    • Group (field GRP)

    • Dimension (field DIME)

    • Description (field INTITCOURT)

     

    • Length (field CODLNG)

    Close

    This documentation describes icon button [Generate access].

    This button is used to generate automatically the Web service whose publication name is defined in the interface.

    The generated Web service can immediately be used on all Web service servers loading the folder. 

    SEEINFO This button is active once the record has been created.

    The button 'Generate access' triggers following operations:

    • Offers the possibility to enter the maximum number of recordings read upon calling of the Web service ('Max. nb of lines'),
    • Activity code, Module and Web service type,
    • Requests to select useful fields,
    • Generates the 4GL processing called by the Web service having 'W + Publication name' as name
    • Loads the Web service with the Publication name entered previously.

    For interfaces of type:

    Generated access to Table, Generated access to View

    The processing and sub-program record are generated automatically.

    Sub-program access, Sub-program User action

    The processing and the sub-program record must be created manually prior to access generation.

    Object User action, Left list action

    There are neither processings nor sub-program records to be created.

    Menu Bar

    Tools / Copy Web Service

    The tool 'Copy Web service' is used to select one or several interfaces (interface field empty) of an XTEND site belonging to the current X3 folder, and to copy/load the associated Web services to another folder.

    In order to activate the copy, select at least an interface from the list.

    Copy a sub-program:

    • Copy of a 4GL processing Web service,
    • Creation of the 'sub-program' record,
    • Publication of the Web service.

    Copy of an X3 Object Web service,

    • Publication of the Web service.

    Origin/Folder: Current folder

    Origin/Web site : Code of the XTEND site used to display the interface list (Default current site)

    Origin/Interface : Code of the interface to display only the Web service of this interface.

    Destination/Folder: Destination folder for the copy.

    Tools / Create field token

    This tool is used to create the field tokens from:

    • the field list of an X3 Table,
    • the field list of an X3 View,
    • the setups of the Web service associated with an interface.

     Column

    Description

    Parameter

    Code of the field of the Table or the Web service setup

    Title

    Field title

    Field Token

    XTEND code for the setup (same code by default)
    Can be entered if it is required to create a field with a name differing from that of the setup (mapping).

    Present

    Checked if this field is already present in the dictionary

    Type

    Field type (XTEND)
    Can be entered upon creation

    Menu

    Menu identifier for the type Local Menu
    Can be entered if it is required to create a field with a name differing from that of the setup

    Dimension

    Maximum number of setup or field values

    Generation

    For fields of dimension superior to 1, indicates if it is necessary to generate an index (FIELDNAME + INDEX):
    None: creates a field without index,
    All: creates as many indexed fields as possible values for this field,
    One: creates only one field with the index indicated in the index column.
    Can be entered upon creation.

    Index

    Field index for name calculation
    Can be entered upon creation if Generation=One

    Validate the fields after generation so that the XTEND server takes them into account.

    The validation generates a new XML dictionary of XTEND setups.

    The new dictionary is automatically taken into account on reload/F5 of the HTML page in the browser provided the option of the site setup record 'Technique\Verify updates\Web dictionary' is checked.

    If it is not checked, it is necessary to reload the dictionary by means of the url:
    'http://hostname:port/xtend/svc/SolutionX3/DossierX3/SiteXtend/admin/reposit/reload'

    Error messages

    The only error messages are the generic ones.

    Tables used

    SEEREFERTTO Refer to documentation Implementation