GAS 3.10 upgrade guide

These topics describe product changes you must be aware of when upgrading to version 3.10.

Important:

This incremental upgrade guide covers only topics related to the Genero Application Server (GAS) version specified in the page title. Check prior upgrade guides if you migrate from an earlier version, and complete the migration tasks for all versions between your existing version and the target version, in order. Make sure to also read about the new features for this version.

Corresponding new features page: GAS 3.10 new features.

Previous upgrade guide: GAS 3.00 upgrade guide.

Delegation and environment variables

Starting with GAS version 3.10, all environment variables defined via X-FourJs-Environment- HTTP headers are forced to uppercase. If you use delegation in your applications or web services, make sure that you are not relying on case (for example title or camel case, "MyEnvVar") in the naming of parameters as there is no guarantee that it will be preserved.

Some web servers convert all header names to lowercase, which is outside your control. To provide a consistency in use across platforms (Windows® and UNIX® ), proxies parse the HTTP headers and convert all environment variables to uppercase.

Delegation and URLs

To avoid query decoding issues, the delegate mechanism has been changed to follow URL RFCs by passing the delegate URL as a standard QueryString.

See How to implement delegation for more information.

OpenID Single sign-on (SSO) protocol not supported

The OpenID authentication mechanism for Single Sign-on authentication is deprecated. If you have previously used OpenID to authenticate users launching applications, you must now use an alternate method, such as OpenID Connect or SAML. Any new development requiring Single Sign-on should plan to use OpenID Connect, or SAML. See the Single Sign-On User Guide. For alternative solutions, please contact your Four Js support center.

Sample SSO implementation (simplesso) located on GitHub

The sample implementation of Single Sign On (SSO) for Genero is no longer provided in the FGLGWS installation at $FGLDIR/web_utilities/services/simplesso, instead it can now be found under the Four Js Genero GitHub repository. See https://github.com/FourjsGenero/ex_simplesso.

What does this mean for your upgrade to 3.10? If you had previously used the simplesso mechanism for your SSO service, you will need to download it from GitHub. For complete implementation instructions and its use, please see the README file in the download. For more information, see Delegation use cases and SSO custom sample (simplesso) page in Single Sign-On User Guide.

Parent application for a web Service must start with "ws."

To support Genero Archive packaging, all parent applications defined in the configuration of web services applications must now start with "ws." See Configure applications for web service.

Desupported GAS configuration elements

The following elements are no longer allowed or used:
  • The DVM_PINGTIMEOUT, child element of the TIMEOUT (for an application), is not supported. The GAS no longer sends a ping event when the DVM is running with GAS. No action needs to be taken.

    If you have set the gui.protocol.pingTimeout in your FGLPROFILE, this setting is not used when the DVM runs with the GAS. For applications running on Genero Desktop Client (GDC) in direct mode ( without GAS), the ping event is still part of the protocol and the GDC keeps sending it as usual.

  • The FILE_TRANSFER element and its child element, TIMEOUT, are not supported.
  • The OUTPUT element which specified the parameters for rendering GWC for HTML5 web applications is no longer supported. Starting with Genero 3.10, all UI applications should use the UA proxy instead, which is configured by the UA_OUTPUT element.

Desupported proxies

The following proxies are no longer supported:
  • The gdcproxy proxy used for GDC is no longer supported. The uaproxy proxy is now used for GDC.
  • The html5proxy proxy for Genero Web Client for HTML5 (GWC-HTML5) is no longer supported. This version of the Genero web client is no longer supported and has been replaced by the Genero Browser Client (GBC) instead. The uaproxy proxy is used for GBC.

Desupported session variables

Session variables are no longer managed in the GAS when using UAProxy. If before you used session variables to maintain states between runs of an application by means of configuring the HTTP_COOKIES element in the as.xcf file, this is no longer utilized and you will need to remove those entries.

In your 4GL code session state is set through "localStorage" front calls. Starting with version 3.10, you must use the new localStorage front calls, supported by all Genero front-ends, to dynamically set and get session state from within your Genero application. For example:
ui.Interface.frontCall("localStorage", "setItem",
   [key,value], [])

Deprecated session front calls

The session module front calls setVar and getVar are deprecated. You will need to replace these calls with calls to "localstorage". For more information, see the Local storage front calls section in Genero Business Development Language User Guide.

Alias GAS configuration elements: GWC-JS and GBC

The latest GAS version configuration file shows the following element changes:
  • GBC is now the preferred element for Genero Browser Client customization. GWC-JS is deprecated.
  • GBC_LOOKUP_PATH is now the preferred element for GBC customization look up. GWC_JS_LOOKUP_PATH is deprecated.
Whilst GWC-JS and GWC_JS_LOOKUP_PATH elements continue to be supported, we recommend you take the opportunity at this time to replace the deprecated elements (GWC-JS, GWC_JS_LOOKUP_PATH) in your application configuration files with their replacements, GBC, and GBC_LOOKUP_PATH respectively.

Apply fix for mod_proxy_fcgi URL decoding in Apache 2.4

The Apache bug 55329 preventing mod_proxy_fcgi decoding application URLs with spaces or special characters correctly has been fixed for Apache 2.4.11. This bug prevented, for example, applications with URLs like "http://server/gas/wa/r/test/220%2012", from working.

If you are using Apache 2.4.11 or later you must apply the following fix in the Apache configuration to avoid this issue:
SetEnvIf Request_URI . proxy-fcgi-pathinfo=unescape
For more details, see Configure FastCGI for Apache 2.4.

If you are using a version of Apache prior to 2.4.11, as the 4GL developer you need to be aware that you can get spaces encoded in URLs and need to handle these in your program code. It is recommended that you decode URLs before using them.

SESSION_COOKIE definition

Starting with GAS version 3.10.16, the SESSION_COOKIE element includes the SameSite attribute.

If you are migrating SESSION_COOKIE elements, you may need to set the SameSite attribute.

For more information see SESSION_COOKIE.

SameSite attribute is now recommended when setting HTTP cookies

If you use cookies on the server side, make sure that the cookies you use to secure your web services are set with sameSite as "Strict". Setting SameSite="Strict" on the secure cookie ensures that only the exact URL the cookie has been set with will return the cookie to the server. If not set, the Genero Web Server sets each cookie's sameSite attribute as "Lax".

To have SameSite available, you must recompile your sources with fglcomp 3.10.24 or greater.

For more information, see the com.HTTPServiceRequest.setResponseCookies topic in the Genero Business Development Language User Guide.

Changes in earlier versions

Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases.

For more details, see GAS 3.00 upgrade guide.

Notable changes introduced in maintenance releases:

  • The change in use of the default HTTP header "X-Content-Type-Options", which needs to be set to the value "nosniff", also available since GAS 3.10 (GA version).
  • How the USER_AGENT timeout value is halved when sent to the Genero Browser Client, also available since GAS 3.10.14.
  • The change in the default value for REQUEST_RESULT from 60 seconds to 45 seconds, also available since GAS 3.10.16.
  • The removal of the Alias directive in Apache 2.4 Web server and other changes introduced in the configuration.