ASYRWEBSER API

Origen fuente: http://online-help.sageerpx3.com/erp/12/wp-static-content/static-pages/en_US/v7dev/api-guide_api-asyrwebser.html

A standard API is available in X3 scripts to perform calls to the platform's javascript published functions. It works on code executed from classic pages as well as on V7 (and later) code.

General Web server javascript call

The function is located in the ASYRWEBSER library, and its definition is the following:

Funprog EXEC_JS(MODULE, FUNCTION_NAME, MODE, ARGUMENTS, ENCODINGS, CALLB, RETURNS, RETURNS_ENC, RESHEAD, RESBODY)
Value Char MODULE()         : # The name of the published node.js javascript module
Value Char FUNCTION_NAME()  : # The name of the javascript function to be called
Value Char MODE()           : # A mode to determine if the call is synchronous or asynchronous ('sync' or 'wait')
                            : # This mode depends on the signature of the function
Value Clbfile ARGUMENTS()   : # Multiple arguments delimited by ',' ; It can be JSON format or every types.
Value Char ENCODINGS()      : # Specify if arguments must be base64 encoded or not. A list of '0' or '1' separated by ','
                              # Can be empty if no base64 encoding is needed for any argument
                              # Important: when it is not an empty string, it must match exactly the number of arguments
Value Integer CALLB         : # Specify the location of callback function. This is needed only for 'wait' mode.
                            : # The value depends on the function
                              # -1 is the value to say that the callback location is the last parameter.
Value Char RETURNS()        : # Used to filter JSON Objects if you don't want all object properties
                            : # or if the object contains circular references.
Value Char RETURNS_ENC      : # Specify the needs to encode the response to base64 or not. Can be '0' or '1'
Variable Clbfile RESHEAD    : # The http response header.
Variable Clbfile RESBODY    : # The Response body.

Integer STATUSCODE          : # The status code returned by the javascript runner module.

The execution of functions is performed on node.js in javascript. A function can be synchronous or asynchronous. When a function is asynchronous, a parameter of the function defines the callback function; i.e., the function that is called when the execution of the asynchronous function is finished. We use the package streamline.js to make the use of asynchronous functions simple, by adding an "_" parameter that is preprocessed to handle the callback.

This means that if the function has been defined as asynchronous, you have to use the 'wait' value for MODE, and to indicate the place of the callback parameter as it is declared in the function. The values of these parameters will be mentioned in the function definition.

The function fills RESBODY and RESHEAD, and returns the HTTP status (200 if successful).

The complete JSON structure returned is stored in RESBODY as a stringified JSON. If you want to get only one element in the structure, you have to give its name (if it is a property at the first level of the hierarchy) or the path (if it is a nested property). If the property is a single one, it will be returned in a string, otherwise you will get the JSON description of the requested sub-element.

For example, if the function returns a JSON like the following one:

{
  "elt1" : "val1",
  "elt2" : { "sub21": true, "sub22" : 3.14, "sub23" : "Hello","sub24" : { "a" : 2.718, "b" : 1.732 } },
  "elt3" : [ {"x":1, "y":2}, {"x":3, "y":4}, {"x":5, "y":6}]
 }

The result will be the following, according to the value sent in RETURNS:

RETURNS value given	RESBODY returned
""	{ "elt1":"val1", "elt2":{"sub21":true,"sub22":3.14,"sub23":"Hello","sub24":{"a":2.718,"b":1.732}}, "elt3" : [{"x":1, "y":2}, {"x":3, "y":4}, {"x":5, "y":6}]}
"elt1"	val1
"elt2"	{"sub21":true,"sub22":3.14,"sub23":"Hello","sub24":{"a":2.718,"b":1.732}}
"elt1.sub22"	3.14
"elt1.sub24"	{"a":2.718,"b":1.732}
"elt1.sub24.b"	1.732
"elt3"	[{"x":1, "y":2}, {"x":3, "y":4}, {"x":5, "y":6}]
"elt3[0]"	{"x":1, "y":2}
"elt3[1].y"	4

The RESHEAD structure contains a typical HTTP header returned on GET with the following values:

{
  "statusCode"     : 200,
  "message"        : "OK",
  "content-type"   : "application/json",
  "content-length" :  123
}

The important information is the HTTP status, it has the value 200 if no error occurred (see above).

Functions available

The list of published functions available is given here:

• Access to the user profile as it is defined by the connection conditions
• Access to the document database
• XML signature
• PDF signature

Execution of an http request from Web server

This function also located in the ASYRWEBSER library performs an http request from web server on an URL. It works on code executed from classic pages as well as on the V7 (and later) code, and its definition is the following:

 Funprog EXEC_HTTP(HEADERCOD, HEADERVAL, DATA, RESHEAD, RESBODY)
 Value Char HEADERCOD()(1..) : # An array that is contain header's keys.
 Value Char HEADERVAL()(1..) : # An array that is contain header's value.
 Value Clbfile DATA()        : # Http body that you want to send (for methods 'POST' and 'PUT' only).
 Variable Clbfile RESHEAD()  : # The Http response header.
 Variable Clbfile RESBODY()  : # The Http Response body.
 ...
 Local Integer STATUSCODE    : # The status code corresponding to the Http response.
 ...
 End STATUSCODE

An example of the use of this function is the following:

Funprog HTTP_GET(RESHEAD, RESBODY)
 Variable Clbfile RESHEAD()
 Variable Clbfile RESBODY()

 Local Char HEADERCOD(64)(3)
 Local Char HEADERVAL(255)(3)
 HEADERCOD(0) = "url"
 HEADERVAL(0) = "http://footballpool.dataaccess.eu/data/info.wso?wsdl"
 HEADERCOD(1) = "method"
 HEADERVAL(1) = "GET"
 Local Clbfile BODY(0)
 BODY = '{}'
 Local Integer STATUSCODE
 STATUSCODE = func ASYRWEBSER.EXEC_HTTP(HEADERCOD, HEADERVAL, BODY, RESHEAD, RESBODY)
 If STATUSCODE <> 200
   Goto END_HTTP_GET
 Endif

 $END_HTTP_GET
 End STATUSCODE