Natural for Ajax Runtime Tools

Natural for Ajax provides tools to configure sessions and the runtime of Natural clients.

The following sections cover the features and functionalies.


Invoking the Natural for Ajax Runtime Tools

The runtime tool are automatically installed when you install Natural for Ajax.

They can be accessed from the default index page. You can also access them via the following URL:

http(s)://<host>:<port>/cisnatural/servlet/StartCISPage?PAGEURL=/njxruntimetools/njxruntimetoolsmain.html&POPUPTITLE=Natural%20for%20Ajax%20RuntimeTools

Note
You may wish to protect the configuration tool against unauthorized access. See section Configuring Container-Managed Security for information on how to restrict the access to sensitive areas of the application server environment. In NaturalONE you can access the Runtime Tools via the Ajax Developer context menu on any Ajax enabled Natural project.

Session Configuration

The following configuration settings and procedures are discussed below:

Invoking the Session Configuration Tool

To invoke this the Session Configuration tool, click link in the left frame.

The Session Configuration tool appears in the right frame. It shows the global settings and lists all sessions and users that are currently defined.

Global Settings

The global settings apply to all defined sessions. The settings are grouped.

Each group has individual settings as listed below:

Server Trace
Trace directory

Optional. Location of a different trace directory.

When a different trace directory is not defined, the trace files are written to the default trace directory. By default, the trace files are written to the directory which has been set by the Java property java.io.tmpdir . On Windows, this is normally the environment variable TMP for the user who started the application server. On Linux, this is normally /tmp or /var/tmp .

You can also set this property in the start script for the application server. The following examples apply to Wildfly.

  • Example for Windows ( run.bat ):

    set JAVA_OPTS=%JAVA_OPTS% -Djava.io.tmpdir=C:\temp
  • Example for Linux ( run.sh ):

    set JAVA_OPTS="$JAVA_OPTS -Djava.io.tmpdir=/tmp

Tracing can be enabled individually for each session (see Overview of Session Options below). However, it should only be enabled when requested by Software AG support.

Session Timeout
Last activity timeout (n seconds)

The number of seconds that the client waits for the next user activity. When the defined number of seconds has been reached without user activity, the session is closed. The default is 3600 seconds.

SSL/TLS
Truststore path

Optional. The path to your trust file. See Configuring SSL for further information.

Truststore password

If your trust file is password-protected, you have to specify the appropriate password.

When you do not specify the password for a password-protected trust file, the trust file cannot be opened and it is thus not possible to open an SSL session.

When your trust file is not password-protected, you should not specify a password.

OpenID Connect
Client id The client identifier of your client at your OpenID Provider. This identifier is assigned to you when you register your client with your OpenID Provider.
Client secret The client secret only known to your client and your OpenID Provider.
Natural user claim The name of the claim in the token, which provides the value of the Natural username.
Natural user – remove email suffix If email is specified as Natural user claim then the e-mail suffix is removed and only the remaining part is used as username for Natural.
Request claims using scope Additional claims are requested from the provider via the scope parameter and integrated into the token.
Request claims using the claims request parameter Additional custom claims are requested from the provider via the claims request parameter and integrated into the token.
Authorization endpoint The OpenID Provider server endpoint where the user is asked to authenticate and grant the client access.
Token endpoint The client exchanges the code received from the authorisation endpoint for a token.
Logout endpoint A client can use the logout endpoint to clear the provider-side session and cookies for a web browser. If used, you will need to log in at the OpenID Provider again.
JAAS
Use secure logon page

If selected, users are authenticated before they access the Natural for Ajax logon page. See also Configuring Application-Managed Authentication .

If Use SAML for JAAS-based authentication is also selected, the secure logon page is only shown in the case of an error in the SAML artifact validation.

Adding a New Session

You can add a new session to the configuration file.

Start of instruction setTo add a new session

  1. Choose the Create button in the Sessions panel.

    The Edit Session page appears.

  2. Specify all required information as described below in the section Overview of Session Options.

  3. Choose the SAVE button.

    The new session is written to the configuration file, and you are returned to the Session Configuration page.

Editing a Session

You can edit any existing session in the configuration file.

Start of instruction setTo edit a session

  1. Choose the Edit icon for the session that you want to edit in the session table.

    The Edit Session page appears.

  2. Specify all required information as described below in the section Overview of Session Options.

  3. Choose the SAVE button.

    The new session is written to the configuration file, and you are returned to the Session Configuration page.

Overview of Session Options

The Edit Session page appears when you

  • add a new session, or

  • edit an existing session.

The individual options are grouped under tabs. The following options are provided:

General
Session ID Mandatory. A session name of your choice. On the logon page, the session name is provided in a drop-down list box.
Application name

Optional. An application name of your choice. This name is used to provide more individual disconnect messages. The name entered here will replace the term "Application" in the standard disconnect message of Natural for Ajax applications.

For example, if the field Application name contains the word "Calculator" the disconnect message "Application finished successfully" would instead be "Calculator finished successfully" .

Similar custom messages will be displayed if the application ends with an error.

Disconnect behavior

Defines whether the default disconnect page is to be shown when a Natural program ends, or whether the current browser tab is to be closed. You can select the required setting from the drop-down list box.

  • Display disconnect page
    Default. The disconnect page is always displayed.

  • Always close browser
    The current browser tab is closed. When the last tab in the browser is closed, the entire browser is closed.

  • Close browser, but display disconnect page on error
    The current browser tab is closed. When the last tab in the browser is closed, the entire browser is closed. However, in the case of an unexpected error, the disconnect page is shown.

Internet Explorer allows closing the browser with JavaScript by default. For Firefox, however, this has to activated as follows:

  1. In the Firefox address bar, type the following:

    about:config

    A warning message appears, saying that changing the advanced settings can be harmful and that you should only continue if you are sure of what you are doing.

  2. Choose the I'll be careful, I promise! button.

  3. In the Filter text box, type the following:

    dom.allow_scripts_to_close_windows
  4. Set this value to "true" by double-clicking on the entry (default: "false" ).

Trace Should only be set to Yes when requested by Software AG support.
Timeout (in seconds) The number of seconds that the client waits for a response after an updated page was sent to the Natural session. When the defined number of seconds has been reached without response, the session is closed. The default is 60 seconds. Normally, you need not change this value.
Natural Connection
Host name The name or TCP/IP address of the server on which Natural and the Natural Web I/O Interface server are running. When this is specified, the corresponding field does not appear on the logon page.
Port number The TCP/IP port number on which the Natural Web I/O Interface server is listening. When this is specified, the corresponding field does not appear on the logon page.
Use SSL If set to Yes , a secure connection is established between Natural for Ajax on the application server and the Natural Web I/O Interface server.

Important
If you want to use SSL with Natural for Mainframes, one of the corresponding mainframe types must be selected; the type must not be Undefined or Natural for Windows or Linux . The other way around, if you want to use SSL with Natural for Windows or Linux, you must not select one of the mainframe types; the type may also be Undefined in this case.

Authentication
Natural Server Type The platform on which user ID and password are authenticated. You can select the required setting from the drop-down list box.
  • Undefined
    Default. User ID and password can have a maximum of 32 characters. See also the description for Natural for Windows or Linux below.

  • Natural for Mainframes
    User ID and password can have a maximum of 8 characters.

  • Natural for Mainframes with Natural Security
    User ID and password can have a maximum of 8 characters. The user ID must comply with the Natural naming conventions for library names .

  • Natural for Windows or Linux
    User ID and password can have a maximum of 32 characters. When a domain is required, you have to specify it together with the user ID (in the form " domain \ user-ID " ).

OpenID Connect (OIDC)

Use OIDC for authentication to Natural. Be sure that you have filled in the mandatory OIDC settings of the global session settings.

JAAS-based authentication

If selected, application-managed authentication is used. This setting implies that Forward credentials is also selected. See also Configuring Application Managed Authentication .

If Use SAML for JAAS-based authentication is also selected in the global settings, the user name and password are not visible in the Natural for Ajax logon page. See also Using Software AG Security Infrastructure .

Forward credentials

If selected, the security credentials from the application server are forwarded to the Natural Web I/O Interface server, thus sparing the user a second logon. See also Forwarding the User Credentials to Natural .

User name Optional. A valid user ID for the current machine. When this is specified, the corresponding field does not appear on the logon page.
User name in upper case If selected, the input field for the user ID is in upper-case mode.
Password

Optional. A valid password for the above user ID.

Under Windows and Linux, this is always the operating system password of the user, even if Natural Security is active.

On the mainframe, this is different: When Natural Security is not active, this is the operating system password of the user. When Natural Security is active, this is the Natural Security password.

When a password is specified, the corresponding field does not appear on the logon page. The configuration tool saves the password in encrypted form.

Save user credentials

Applies only to applications that are designed as Application Designer workplaces.

If set to Yes (default), the default behavior of the option Share session user applies.

If set to No , the user credentials (user ID and password) are not saved in the Application Designer session and are therefore not available for an Application Designer subsession.

An example for a workplace application is available under the following URL:

http:// <host> : <port> /cisnatural/servlet/StartCISPage?PAGEURL=/njxdemos/wpworkplace.html

where <host> and <port> are the host name and port number of your application server.

Share session user

Applies only to applications that are designed as Application Designer workplaces.

If set to No (default), the user credentials of the main Application Designer session are automatically used in an Application Designer subsession if the server and port of the subsession is the same as in the main session. If the server and port are not the same, the user has to specify the user ID and password in a logon dialog.

If set to Yes , the user credentials of the Application Designer main session are always used for all Application Designer subsessions on all involved servers - even if the server and port are different.

Natural Application
Application
  • Natural for Mainframes
    The name of the Natural program or a command sequence that starts your application as you would enter it on the NEXT prompt. Example:

    TEST01 data1,data2

  • Natural for Linux
    The name of the Linux shell script for starting the Natural application (a file similar to nwo.sh ).

  • Natural for Windows
    The name of the Windows command file ( .bat ) for starting the Natural application.

When this is specified, the corresponding field does not appear on the logon page.

Natural parameters

Optional. Parameters for starting the Natural application. This can be stack parameters, a parameter file/module or other Natural-specific information.

  • Natural for Mainframes
    Used to pass dynamic Natural profile parameters to the session, for example:

    SYSPARM=(MYPARMS) STACK=(LOGON MYAPPL)

    Note
    It is recommended to specify the Natural program that starts the application with the option Application instead of passing it with the profile parameter STACK .

  • Natural for Linux and Natural for Windows
    Used when the above shell script (Linux) or command file (Windows) uses the parameter $5 after "natural" , for example:

    PARM=MYPARM STACK=(LOGON MYLIB;MENU)

Web I/O Pages
Language

You can select the required language from the drop-down list box.

It is also possible to select Set in workplace from the drop-down list box. When selected, the language that is currently used in the workplace will also be used for the next start of Natural.

See also Multi-Language Management . Default: English.

Show style sheet selector

With Natural for Ajax, the users can switch to another style sheet during a running session. If set to No , the users are no longer able to select another style sheet.

Style sheet

The name of the style sheet which determines the colors, fonts and PF key button style of the current session. See Using Style Sheets . When this element is specified, a fixed style sheet is used. In this case, the corresponding field does not appear on the logon page and the user is thus not able to select a different style sheet.

Double-click behavior

Applies only to Natural maps, not to rich GUI pages.

The key that is to be simulated when double-clicking an output field. By default, this is the ENTER key.

It is possible to disable the double-click behavior, or to define a function key ( PF1 through PF12 ).

You can select the required setting from the drop-down list box.

Tip
When context-sensitive help has been defined for the output fields, it may be useful to define PF1 . The help function will then be invoked when the user double-clicks an output field.

PF keys display style

Applies only to Natural maps, not to rich GUI pages.

By default, only the named function keys are shown as buttons.

It is also possible to show buttons for all function keys, including those which do not have names. You can specify whether to display buttons for 12, 24, 36 or 48 function keys. Each line always contains 12 function key buttons. The first line also contains a button for the ENTER key. Each function key button is always displayed at the same position.

You can select the required setting from the drop-down list box.

Screen rows

Applies only to Natural maps, not to rich GUI pages.

The number of rows in the output window. Possible values: minimum 24, no upper limit. Default: 24.

Not used by Natural for Mainframes which uses the profile parameter TMODEL instead.

Screen columns

Applies only to Natural maps, not to rich GUI pages.

The number of columns in the output window. Possible values: minimum 80, no upper limit. Default: 80.

Not used by Natural for Mainframes which uses the profile parameter TMODEL instead.

Show function key numbers

Applies only to Natural maps, not to rich GUI pages.

If set to Yes , the PF key numbers are shown next to the PF keys.

Check for numeric input

If set to Yes (default), numeric input fields are validated. In this case, only the following characters are allowed in numeric input fields (in addition to the numbers "0" through "9" ):

blank
+ (plus)
- (minus)
_ (underscore)
, (comma
. (period)
? (question mark)

If set to No , numeric input fields are not validated.

Auto skip

Applies only to Natural maps, not to rich GUI pages.

If set to Yes , the cursor is automatically placed in the next input field when the last possible character has been entered in the current input field.

If set to No (default), the cursor remains in the current input field.

Translate characters from / Translate characters to

Applies only to Natural maps, not to rich GUI pages.

Optional. Used to translate characters that are sent from the host or entered by the user into different characters to be shown on the screen.

You enter the characters to be translated in the Translate characters from text box and the characters to be used instead in the Translate characters to text box (in the same order as in the first text box). Both text boxes must contain the same amount of characters.

The following example shows how to translate all lower-case characters to upper-case characters:

Translate

The following example shows how to translate the so-called "European numerals" to "Arabic-Indic numerals" :

Translate

Filler character

Applies only to Natural maps, not to rich GUI pages.

Optional. The filler character that is to be removed from the input fields. An application can define, for example, an underscore (_) as the filler character. Trailing filler characters will be removed from the input fields, and leading filler characters will be replaced with blanks.

Duplicating a Session

You can add a copy of any existing session to the configuration file.

Start of instruction setTo duplicate a session

  1. Choose the Duplicate icon that is shown next to the session that you want to duplicate.

    A new entry bearing the name Copy of session-ID appears at the bottom of the list of sessions. However, this duplicate session is not yet available in the configuration file.

  2. Edit and save the duplicated session as described above.

Deleting a Session

You can delete any existing session from the configuration file.

Start of instruction setTo delete a session

  1. Choose the Delete icon that is shown next to the session that you want to delete.

    The session is deleted from the list of sessions. However, it is not yet deleted in the configuration file.

  2. Choose the Save button to delete the session from the configuration file.

Adding a New User

You can add predefined Natural users and their passwords in the configuration file.

When a Natural page is opened with a URL that specifies a user in the URL parameter natuser, the specified user is matched against the list of users in the configuration file. If the specified user is defined in the configuration file, the corresponding password is used to authenticate the user when the Natural session is started. See also Starting a Natural Application with a URL.

Example

The following URL applies the password as defined for user1:

http://myhost:8080/cisnatural/servlet/StartCISPage?PAGEURL=/cisnatural/NatLogon.html&xciParameters.natuser=user1 ...

Start of instruction setTo add a new user

  1. Choose the Create button in the Users panel

    The Create User dialog appears.

  2. Specify a username and password.

    Choose the SAVE button to write the new user to the configuration file.

Note
You edit, duplicate and delete a user in the same way as a session (see the corresponding descriptions above).

Saving the Configuration

When you choose the Save button, all of your changes are written to the configuration file. The server picks up the new settings automatically the next time it reads data from the configuration file.

Caution
The new settings are NOT written to the configuration file if you do not select Save before you log out or leave the configuration tool for another URL.

Natural Client Logging Configuration

Logging is managed from the Logging Configuration page.

On this page, you can determine the settings recorded in the configuration file for logging, natlogger.xml.

Ajax Configuration

Opens the Ajax Configuration Editor.

The Ajax Configuration settings are described in Ajax Configuration.

Monitoring Tool

This section covers the following topics:

About the Monitoring Tool

The monitoring tool is used to monitor the sessions that are currently running in the deployed web application.

You refresh internally used cached sessions or delete sessions, which are no longer required. This way you can free memory. For more information on sessions, see Details on Session Management.

Invoking the Monitoring Tool

The monitoring tool is part of the Runtime Tools. When you invoke the monitoring tool, the following editor appears:

Monitoring tool

The information and functions are grouped in the following way:

Using the Refresh button at the very top, you can reload the information in the editor and show the most recent information.

Start of instruction setTo invoke the monitoring tool in a deployed web application

  • Click the button Runtime Tools of the default index page. This opens the Runtime Tools.

Start of instruction setTo invoke the monitoring tool in NaturalONE

  1. In the ProjectExplorer view, select the project for which you want to invoke the monitoring tool.

  2. Invoke the context menu and from the Ajax Developer menu, choose Ajax Runtime Administration. This opens the Runtime Tools.

Java Memory

The top of the editor provides the following information:

Option Description
Used memory This text box indicates the currently used memory.
Process memory This text box indicates the available memory.
Collect garbage When you choose this command button, memory which is no longer used on the server is set free.

JavaScript

You can use this section to dynamically switch on or off the writing of JavaScript logging to the browser console.

Ajax Server Log File

The server log file contains a protocol of all interactions with the application server/web container. You switch Debug Mode on or off. In debug mode, the log contains more detailed information.

When you choose the Open Today's Log File command button, a dialog appears showing the content of the log file.

System Management (Caches)

You can use this section to clear or refresh specific internal caches.

Option Description
Class Loader When you choose the Use latest Version of Applications for new Sessions command button, a new class loader instance is generated. The most recent versions of your applications are then loaded. For example, when an adapter class has been modified, the modified class is loaded and any changes are immediately in effect.

See also Class Loader Concepts.

Text Buffer When you choose the Refresh Text Buffer command button, the most recent versions of your language files are loaded and any changes are immediately in effect.

When you choose the Refresh Layout Repository Buffer command button, the most recent versions of your layouts are loaded and any changes are immediately in effect.

Active Ajax Sessions

This section provides a list with all sessions, which are currently active.

The monitoring process itself is also considered as a session. When no other sessions are active, the monitoring process is the only session that is listed in the editor.

The following command buttons and icons are available:

Command Button/Icon Description
Remove The trashcan icon next to each active session. When you click this icon, the selected session is removed from the list of active sessions.
Remove temporary sessions When you click this button, all temporary sessions, for instance Layout Painter Preview sessions, are removed from the list of active sessions. Temporary sessions start with “TEMP”.