Overview

Before the GWA application starts, the file system emulation is populated with data provided by gwabuildtool. For example, the "/app" directory is populated with the data from the gwabuildtool --program-dir option.

The /home directory is excluded from the pre-population of the file system; all data which can be bundled lands in /app directory.

Home directory

The /home directory is the "persistent" directory of the GWA, where the application state can be stored even if the application is restarted or the browser is restarted. Data in the /home directory is stored in the browser cache, or to be more precise, in IndexedDB (external link) caches. Therefore, if you want to store data, you must put your files in the /home directory using explicit channel operations such as os.Path.copy commands as shown in the next section.

Database persistence

Database persistence is managed via a SQLite database file, which must be placed in the /home directory.

If an SQLite database file needs to be created at application startup, you must write some 4GL code to create the file before calling the CONNECT instruction.

# check for database
VAR home_db="/home/mydatabase.db"
#...
IF NOT os.Path.exists(home_db) THEN --Copy to home directory first time
  --the initial mydatabase.db is bundled by gwabuildtool into /app
  IF NOT os.Path.copy("/app/mydatabase.db", home_db) THEN
    DISPLAY "Can't copy initial db"
    EXIT PROGRAM 1
  END IF
END IF
# connect to database

Accidental clearing of the cache

Explicitly cleaning the browser cache for the site hosting a GWA application will remove all stored data of a GWA application.

As there is always the danger that an end user may clear browser cache and thus delete the contents of a GWA application /home directory unintentionally, your GWA application should be prepared to send the data to a REST server via REST API, or synchronise data with the server by other combinations of GWS calls.

The manifest has some parameters that allows you to change icons, add screenshots, change application title, and so on, according to the Web Application Manifest (external link) specification.

When you call the gwabuildtool tool to build the GWA, it looks for a dedicated manifest in the programdir/gwa of your program directory.

In the manifest file, the path to icons and screenshots are set by the "src" property. "src" does not refer to a web server path, instead gwabuildtool searches for those images in the absolute path or a path that is relative to your programdir/gwa path.

So an image named "src" : "foo.png" will be found in programdir/gwa/foo.png. This is the recommended default directory for those kind of images.

The directory programdir/webcomponents is the default location for web components in your program directory. All components located there will be automatically packaged.

Furthermore, the gwabuildtool has a --webcomponent switch to bundle a web component from another location in the file system other than programdir/webcomponents. The switch can be used multiple times in the build command.

Including built-in web components

A call to ui.Interface.filenameToURI(asset_in_filesystem) can be used to produce URLs to make a web component visible.

The gwa_webcos demo is a good source to check the various asset paths.

When a GWA application ends, an application ended page is displayed similar to GBC. (This page can be customized). By default a "Reload page" button is shown on this page, which enables a restart of the application.

If the application has been updated server side in the meantime, clicking the Reload page button will start the updated version of the application.

Automatic application updates

As the GWA uses JavaScript service workers, the application can even be updated when the program is not active; the browser automatically checks the server side for a new version and downloads the new version if there is one.

By default the application is also updated automatically when it is reloaded. This can happen when the user clicks the Reload page button on the application ended page, by using the browser reload menu action (F5 usually), or by reopening the browser with the same application URL.

To keep track of application updates, the gwabuildtool has an --app-version switch to set the application version. This version can be queried by using methods in the gwa.app package module.

User-driven update

The gwa.app package module has a function to query the up-to-date status of the application and perform a user-driven update immediately if a version difference is detected.

If a network connection is not available, the current installed version in the browser is used. Internally, the GWA tries first to contact the server for an update, if this fails, after 500ms the cached application version is used.

It is recommended that you code to check for updates after your application starts by calling the gwa.app.getServerVersionAndBuild() method.

For an example performing a user-driven update, explore the GWA "update" demo in your GWA installation directory. If installed in FGLDIR, you will find the demo in $FGLDIR/demo/gwa/update or if installed in a separate directory, you will find it in gwa-install-dir/demo/gwa/update.

Genero provides SSO based on the OpenID Connect (OIDC) protocol via its Genero Identity Provider (GIP). For more information on GIP and SSO, refer to the Single Sign-On User Guide. Any identity provider that supports OIDC will work with GWA and can manage the creation of user accounts as well as authentication and authorization during sign-in.

Overview

When your GWA application is registered with an IdP for SSO, the end-user enters credentials once in a login form on the browser to get authorization to use the application. If your application performs further request to REST services, an access token is required. Your application must perform a request via a password-credential flow to the IdP in order to receive an authorization and an access token for this purpose.

CORS constraints

Access-Control-Allow-Origin:"https://cube:6394"

#...
<SERVICE>
    <HEADER Name="Access-Control-Allow-Origin">https://cube:6394</HEADER>
</SERVICE>
#...

OAuth API

In your GWA application, you must call functions of the OAuthAPI library in order to authenticate and retrieve an access token to call additional REST services. See the example in Typical BDL OAuth initialization.

Of course, you can also use fglrestful --auth yes to generate the stubs to connect using OAuth protocol to any REST services. However, as GWA has a limited number of GWS functions available at this time, you must use option --legacyJSONApi of the fglrestful tool, and only requests with JSON or plain text are supported. XML is not supported.

Typical BDL OAuth initialization

IMPORT FGL OAuthAPI

-- IDP constants
CONSTANT idp_issuer = "https://host:port/gas/ws/r/services/GeneroIdentityProvider"
CONSTANT client_id = "XXXXX" -- OAuth client id as registered in your IdP
CONSTANT private_id = "ZZZZZ" -- OAuth private id as registered in your IdP

-- OAuthAPI
DEFINE metadata OAuthAPI.OpenIDMetadataType
DEFINE tokens OAuthAPI.OpenIdCResponseType
DEFINE user_login, user_pswd STRING
DEFINE s INTEGER
DEFINE r BOOLEAN

MAIN
  -- Initialize user_login and user_pswd (from a login dialog for example)
  -- CALL AskForLoginAndPassword() RETURNING s, user_login, user_pswd
  IF s<0 THEN EXIT PROGRAM 0 END IF

  -- Fetch IDP metadata
  CALL OAuthAPI.FetchOpenIDMetadata(5, idp_issuer)
     RETURNING metadata
  IF metadata.issuer IS NULL THEN
    DISPLAY "ERROR: Could not fetch OAuthAPI.OpenIDMetadataType"
    EXIT PROGRAM 1
  END IF

  -- Perform password credential flow 
  CALL OAuthAPI.RetrievePasswordTokenForNativeApp(5, metadata.token_endpoint,
                                                user_login, user_pswd,
                                                client_id,
                                                private_id,
                                                NULL)
     RETURNING tokens 
  -- Initialize OAuthAPI via returned tokens
  LET r = OAuthAPI.InitNativeApp(5, tokens,
                               client_id,
                               private_id,
                               metadata.token_endpoint)
  IF NOT r THEN
    DISPLAY "ERROR: Could not initialize native app with OAuthAPI.InitNativeApp"
    EXIT PROGRAM 1
  END IF
  -- Use any GWS client stub generated with fglrestful --oauth yes --legacyJSONApi
END MAIN

A runOnServer call is basically implemented as described for Genero Mobile for iOS (GMI) and Genero Mobile for Android (GMA) applications in mobile.runOnServer; however, there are two notable differences or things to consider when implementing runOnServer calls in a Genero Web application:

1. In GWA, unlike for GMI/GMA, both RUN and RUN ... WITHOUT WAITING can be used in any combination.

   If we wanted to limit it to a RUN, the GBC would need to know if it is in a runOnServer state.

   The runOnServer application finishes when the GBC loaded with the remote application detects application termination (meaning the session ended).

2. In the GWA, you can omit the full origin (http://host:port) in the GAS URL argument, because the origin of the starting GWA application and the GAS application must be the same. (A Cross-Origin Resource Sharing (CORS) issue could arise, but this would require a modification in the GBC.) Therefore, the call for the GAS URL argument can be reduced to a simple path like /ua/r/simple. In GMI/GMA, this is not possible because the native application always runs on another origin.