This document describes the installation of Natural for Ajax on application servers and web containers. It does not describe the installation of the additionally required Natural components on a Windows, UNIX or mainframe host, but refers to the corresponding installation documents.

On application servers and web containers (except JBoss Application Server 5), Natural for Ajax consists of a web application (cisnatural.war).

On JBoss Application Server 5, Natural for Ajax consists of an enterprise application (njx<nn>.ear) and a resource adapter (njx<nn>ra.rar).

This document covers the following topics:

• Prerequisites

• License Key File Handling

• Installing Natural for Ajax on JBoss Application Server 5

• Installing Natural for Ajax on JBoss Application Server 6

• Installing Natural for Ajax on JBoss Application Server 7

• Installing Natural for Ajax on Oracle GlassFish Server 3

• Installing Natural for Ajax on IBM WebSphere Application Server

• Installing Natural for Ajax on Apache Tomcat

• Verifying the Installation

For information on how to activate the preconfigured security settings of Natural for Ajax and how to adapt them to your requirements, see Configuring Container-Managed Security in Client Configuration.

You may find additional technical papers dealing with advanced configuration topics in the Knowledge Center at https://empower.softwareag.com/ (for registered users only).

---

Prerequisites

The following topics are covered below:

• Java

• Application Server

• Web Container

• Apache Ant

• Natural for Mainframes

• Natural for UNIX

• Natural for Windows

• Development Servers

• Development Clients

• Browser Prerequisites

Java

Java 6 Update 24 or above is required to run Natural for Ajax.

Application Server

The following application servers are supported. The application servers are not delivered with Natural for Ajax. They can be obtained from the locations indicated below, according to their respective license terms.

• JBoss Application Server 5.1, 6.1 and 7.1 (see http://www.jboss.org/).

• Oracle GlassFish Server 3.1 (see http://glassfish.java.net/public/downloadsindex.html).

• IBM WebSphere Application Server 7, 8.0 and 8.5 (see http://www.ibm.com/).

Web Container

The following web container is supported. The web container is not delivered with Natural for Ajax. It can be obtained from the location indicated below, according to its license terms.

• Apache Tomcat 6 and 7 (see http://tomcat.apache.org/).

Apache Ant

Apache Ant 1.8.1 or above is required to perform the deployment on JBoss Application Server. This tool is freely available on http://ant.apache.org/.

Natural for Mainframes

If you want to use Natural for Ajax with Natural for Mainframes, the following must be installed:

• Natural for Mainframes Version 8.2.2 or above, and

• the Natural Web I/O Interface server.

For detailed information, see:

• the Installation documentation which is provided with Natural for Mainframes;

• the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for Mainframes.

Natural for UNIX

If you want to use Natural for Ajax with Natural for UNIX, the following must be installed:

• Natural for UNIX Version 6.3.7 or above, and

• the Natural Web I/O Interface server and daemon.

For detailed information, see:

• the Installation documentation which is provided for Natural for UNIX;

• the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for UNIX.

Natural for Windows

If you want to use Natural for Ajax with Natural for Windows, the following must be installed:

• Natural for Windows Version 6.3.7 or above, and

• the Natural Web I/O Interface server and service.

For detailed information, see:

• the Installation documentation which is provided for Natural for Windows;

• the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for Windows.

Development Servers

The following development servers support the remote development of Natural for Ajax applications:

• Natural Development Server for Mainframes Version 2.2.3 or above.

• Natural Development Server for UNIX Version 2.2.3 or above.

• Natural Development Server for Windows Version 2.2.4 or above.

Development Clients

The following development clients support the remote development of Natural for Ajax applications:

• Natural for Windows (Natural Studio) Version 6.3.7 or above.

• NaturalONE Version 8.2 or above.

Browser Prerequisites

Supported browsers in this version are:

• Internet Explorer 8, 9 and 10

• Mozilla Firefox Extended Support Release 10 and 17

  Note:
  Only the Extended Support Releases of Mozilla Firefox are explicitly supported.

• Safari 5.1 on Windows and Mac OS X

• Google Chrome

  Note:
  The Google Chrome support is based on Google Chrome Version 19. Due to frequent version upgrades of Google Chrome, compatibility of Natural for Ajax with future versions of Google Chrome cannot be fully guaranteed. Possible incompatibilities will be removed during the regular maintenance process of Natural for Ajax.

Important:
Cookies and JavaScript must be enabled in the browser.

License Key File Handling

A valid license key file is required during the installation. The license key file is an XML file which is usually supplied along with the product. Alternatively, you can obtain a license key file from Software AG via your local distributor.

For the runtime version, you need a license key for Natural for Ajax Runtime.

For the development version, you need a license key for Natural for Ajax Developer.

Make sure to copy only one license key file to the appropriate location during installation.

Installing Natural for Ajax on JBoss Application Server 5

The distributables for JBoss Application Server 5 are contained in the directory JBoss5.

Only one version of the Natural Web I/O Interface client or one version of Natural for Ajax can be installed on the same JBoss Application Server.

You can either install the Natural Web I/O Interface client or Natural for Ajax on the same JBoss Application Server, not both.

It is assumed that <jboss> is the directory of your JBoss Application Server installation.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax

1. Install Apache Ant (you need Apache Ant to deploy Natural for Ajax to the JBoss Application Server; see the Prerequisites above for the required version number):

   1. Download and unzip Apache Ant (from http://ant.apache.org/) into an installation directory of your choice. Avoid a directory name that contains blanks.

   2. Let the environment variable ANT_HOME point to the directory <ant> (where <ant> is the directory of your Ant installation).

   3. Add <ant>/bin to your PATH environment variable.

2. Deploy Natural for Ajax to JBoss Application Server:

   1. Copy the Natural for Ajax distributables to a directory on a disk drive.

   2. In the directory that contains the Natural for Ajax distributables, there is an Ant script named jbossdeploy.xml. Edit this script and change the setting

      <property name="jbosshome" value=""/>

      to

      <property name="jbosshome" value="<jboss>"/>

      where <jboss> is your JBoss Application Server installation directory.

      Important:
      Take care to use forward slashes (also on Windows) when specifying the directory path.

   3. Execute the script jbossdeploy.xml by entering the following command:

      ant -f jbossdeploy.xml

      Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.

3. Copy the license file into the directory <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/cis/licensekey.

4. Go to the directory <jboss>/server/default/deploy.

   Edit the file jca-jboss-beans.xml and change the setting

   <!-- Whether to track unclosed connections and close them -->
   <property name="debug">true</property>

   to

   <!-- Whether to track unclosed connections and close them -->
   <property name="debug">false</property>

5. Start JBoss Application Server.

Update Installation

To update Natural for Ajax

1. Shut down JBoss Application Server.

2. Deploy Natural for Ajax to JBoss Application Server:

   1. Copy the Natural for Ajax distributables to a directory on a disk drive.

   2. In the directory that contains the Natural for Ajax distributables, there is an Ant script named jbossdeploy.xml. Edit this script and change the setting

      <property name="jbosshome" value=""/>

      to

      <property name="jbosshome" value="<jboss>"/>

      where <jboss> is your JBoss Application Server installation directory.

      Important:
      Take care to use forward slashes (also on Windows) when specifying the directory path.

   3. In order to upgrade an existing Natural for Ajax 8.2.<n> installation to version 8.3<m>, execute the script jbossdeploy.xml by entering the following command:

      ant -f jbossdeploy.xml upgrade

      Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.

   4. In order to update an existing Natural for Ajax 8.3.<n> installation to the newest update package (8.3<m>), execute the script jbossdeploy.xml by entering the following command:

      ant -f jbossdeploy.xml redeploy

      Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.

      Copy the Natural for Ajax 8.3 license file into the directory <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/cis/licensekey. Remove the license file from the previous version.

   5. The update installation creates two backup directories, backup and backupsys, in the JBoss Application Server installation directory. These directories contain a backup of the user project directories and some configuration files. Should the update installation fail for some reason, these directories can be used to restore the the backed up user data in a fresh installation. After a successful update installation, these directories can be removed.

3. In the directory <jboss>/server/default/deploy, make sure that the file jca-jboss-beans.xml contains the same settings as described for a first-time installation.

4. Regenerate the HTML pages of the projects that you have created with an earlier release of Natural for Ajax. You can do this either with the development workplace or using a script, as described below.

   Development workplace:

   1. Start a web browser and enter the following URL:

      http://<host>:<port>/cisnatural/index.html

   2. Open the development workplace.

   3. In the Development Tools node of the navigation frame, choose Layout Manager.

   4. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

   Script:

   1. Execute the script jbossdeploy.xml by entering the following command:

      ant -f jbossdeploy.xml regenerate -Dnjxproj=<projectname>

   2. Wait for the message "BUILD SUCCESSFUL". This indicates that the generation was successful.

5. Start JBoss Application Server.

Installing Natural for Ajax on JBoss Application Server 6

The distributables for JBoss Application Server 6 are contained in the directory JBoss6.

The following is assumed:

• <host> is the name of the machine on which JBoss is installed.

• <port> is the name of the port where JBoss is installed. In a default installation, this is port 8080.

• <jboss_home> is the path to the directory in which JBoss is installed.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax

1. Shut down JBoss Application Server.

2. Extract the contents of the file cisnatural.war into a new directory <jboss_home>/server/default/deploy/cisnatural.war.

3. Add your license file to the directory <jboss_home>/server/default/deploy /cisnatural.war/cis/licensekey.

4. Start JBoss Application Server.

Update Installation

To update Natural for Ajax

1. Shut down JBoss Application Server.

2. Create a backup copy of your sessions.xml file, which is located in <jboss_home>/server/default/deploy/cisnatural.war/WEB-INF.

3. Create a backup copy of your license file, which is located in <jboss_home>/server/default/deploy/cisnatural.war/cis/licensekey.

4. Create backup copies of all modified configuration files, which are located in <jboss_home>/server/default/deploy/cisnatural.war/cis/config.

5. Create backup copies of previously created projects, which are located in <jboss_home>/server/default/deploy/cisnatural.war.

6. Delete the directory <jboss_home>/server/default/deploy/cisnatural.war.

7. Deploy the cisnatural.war file for the new version of Natural for Ajax as in a first-time installation.

8. Restore the files that you have backed up in steps 2, 3, 4 and 5.

9. Start JBoss Application Server.

10. Open your web browser and enter the following URL:

    http://<host>:<port>/cisnatural/index.html

11. Open the development workplace.

12. In the Development Tools node of the navigation frame, choose Layout Manager.

13. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

Installing Natural for Ajax on JBoss Application Server 7

The distributables for JBoss Application Server 7 are contained in the directory JBoss7.

The following is assumed:

• <host> is the name of the machine on which JBoss is installed.

• <port> is the name of the port where JBoss is installed. In a default installation, this is port 8080.

• <adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 9990.

• <jboss_home> is the path to the directory in which JBoss is installed.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax

1. Start JBoss Application Server.

2. Extract the contents of the file cisnatural.war into a new directory <jboss_home>/standalone/deployments/cisnatural.war.

3. Add your license file to the directory <jboss_home>/standalone/deployments/cisnatural.war/cis/licensekey.

4. Add the following security domain definition in the file standalone.xml, under <security-domains>. This file is contained in <application-server-install-dir>/standalone/configuration.

   <security-domain name="NaturalWebIOAndAjaxRealm" cache-type="default">
   </security-domain> 

5. To trigger the actual deployment, create a file named cisnatural.war.dodeploy in <jboss_home>/standalone/deployments.

Update Installation

To update Natural for Ajax

1. Start JBoss Application Server.

2. Create a backup copy of your sessions.xml file, which is located in <jboss_home>/standalone/deployments/cisnatural.war/WEB-INF.

3. Create a backup copy of your license file, which is located in <jboss_home>/standalone/deployments/cisnatural.war/cis/licensekey.

4. Create backup copies of all modified configuration files, which are located in <jboss_home>/standalone/deployments/cisnatural.war/cis/config.

5. Create backup copies of previously created projects, which are located in <jboss_home>/standalone/deployments/cisnatural.war.

6. Open your web browser and enter the following URL:

   http://<host>:<adminport>/console

   This opens the Administration Console.

7. Select cisnatural.war in the list of installed applications.

8. Choose Remove.

9. Deploy the cisnatural.war file for the new version of Natural for Ajax as in a first-time installation.

10. Restore the files that you have backed up in steps 2, 3, 4 and 5.

11. Open your web browser and enter the following URL:

    http://<host>:<port>/cisnatural/index.html

12. Open the development workplace.

13. In the Development Tools node of the navigation frame, choose Layout Manager.

14. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

Installing Natural for Ajax on Oracle GlassFish Server 3

Natural for Ajax consists of a web application (cisnatural.war).

The distributables for Oracle GlassFish Server are contained in the directory GlassFish.

Natural for Ajax is installed using the Administration Console of the Oracle GlassFish Server. It can also be installed automatically (autodeploy).

The following is assumed:

• <host> is the name of the machine on which the application server is installed.

• <port> is the name of the port where the application server is installed. In a default installation, this is port 8080.

• <adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 4848.

• <glassfish> is the path to the directory in which the application server is installed. In a default installation on Windows, this is C:\glassfish3\glassfish.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax using the Administration Console

1. Start the application server.

2. Open your web browser and enter the following URL:

   http://<host>:<adminport>

   This opens the Administration Console.

3. Deploy the web application:

   1. Open the tree node Applications.

   2. Choose Deploy.

   3. Choose Browse.

   4. Go to the directory containing the web application cisnatural.war and select the web application.

   5. Choose OK.

To install Natural for Ajax automatically

1. Start the application server.

2. Copy the web application cisnatural.war into the directory <glassfish>\domains\domain1\autodeploy.

Update Installation

To update Natural for Ajax

1. Shut down the application server.

2. Create a backup copy of your sessions.xml file, which is located in <glassfish>/domains/domain1/applications/cisnatural/WEB-INF/lib.

3. Create a backup copy of your license file, which is located in <glassfish>/domains/domain1/applications/cisnatural/cis/licensekey.

4. Create backup copies of all modified configuration files, which are located in <glassfish>/domains/domain1/applications/cisnatural/cis/config.

5. Create backup copies of previously created projects, which are located in <glassfish>/domains/domain1/applications/cisnatural.

6. Start the application server.

7. Start a web browser and enter the following URL:

   http://<host>:<adminport>

   This opens the Administration Console.

8. Select the tree node Applications and undeploy the cisnatural application.

9. Deploy the new version of the web application cisnatural.war as in a first-time installation.

10. Shut down the application server.

11. Restore the files that you have backed up in steps 2, 3, 4 and 5.

12. Start the application server.

13. Start a web browser and enter the following URL:

    http://<host>:<port>/cisnatural/index.html

14. Open the development workplace.

15. In the Development Tools node of the navigation frame, choose Layout Manager.

16. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

Installing Natural for Ajax on IBM WebSphere Application Server

The distributables for IBM WebSphere Application Server are contained in the directory WebSphere.

Natural for Ajax is installed using the Administration Console of IBM WebSphere Application Server.

The following is assumed:

• <host> is the name of the machine on which the application server is installed.

• <port> is the name of the port where the application server is installed. In a default installation, this is port 9080.

• <adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 9060.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax

1. Make sure the application server is running.

2. Open your web browser and enter the following URL:

   http://<host>:<adminport>/ibm/console

   This opens the Administration Console.

3. Deploy the web application cisnatural.war.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. On the Enterprise applications page, choose Install.

   3. Select WebSphere/cisnatural.war as the path to the new application. Then choose Next.

   4. Choose Next. If additional information is required, you will be prompted.

   5. On the Select installation options page, choose Next. You will then install with the default options.

   6. On the Map modules to servers page, select a cluster and server, select Natural for Ajax and choose Apply. Then choose Next.

   7. On the Map virtual hosts for Web modules page, select a virtual host, select Natural for Ajax and choose Next.

   8. On the Map context roots for Web modules page, enter "cisnatural" as context root and choose Next.

   9. On the Summary page, choose Finish.

   10. On the next page, choose Save.

4. Configure the application.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. Select cisnatural.war.

   3. On the Configuration page, select Class loading and update detection.

   4. On the General Properties page, enter a value for Polling interval for updated files (for example, 300 seconds).

   5. On the General Properties page under Class loader order, select Classes loaded with local class loader first (parent last).

   6. Choose OK.

   7. On the next page, choose Save.

   8. Back on the Enterprise applications page, select cisnatural.war.

   9. On the Configuration page under Modules, select Manage Modules.

   10. On the Manage Modules page, click the Natural for Ajax link.

   11. On the General properties page under Class loader order, select Classes loaded with local class loader first (parent last).

   12. Choose OK.

   13. On the next page, choose Save.

5. Deploy the license file.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. On the Enterprise applications page, select cisnatural.war and choose Update.

   3. On the Preparing for the application update page, choose Replace or add a single file.

   4. In the Specify the path beginning… field, enter "cisnatural.war/cis/licensekey/<licensekeyfilename>".

   5. In the Specify the path to the file field, browse for your license key file.

   6. Choose Next.

   7. On the Updating application page, choose OK.

   8. On the next page, choose Save.

6. Start the application.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. On the Enterprise applications page, select cisnatural.war and choose Start.

Update Installation

To update Natural for Ajax

1. Create a backup copy of the Natural for Ajax application and the contained user projects.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. On the Enterprise applications page, select cisnatural.war and choose Export. The application is exported as the file cisnatural_war.ear.

   3. On the Export Application EAR files page, choose cisnatural_war.ear to download it from the application server.

   4. Extract the web application cisnatural.war from the exported archive.

2. Copy user projects and modified configuration files from the exported old version of cisnatural.war to the new version.

   1. Unpack the exported old cisnatural.war using a zip tool.

   2. Unpack the new cisnatural.war using a zip tool.

   3. Copy the sessions.xml file, which is located in cisnatural.war/WEB-INF, from the old version to the new version.

   4. Copy the license file, which is located in cisnatural.war/cis/licensekey, from the old cisnatural.war to the new cisnatural.war.

   5. Copy all modified configuration files, which are located in cisnatural.war/cis/config, from the old cisnatural.war to the new cisnatural.war.

   6. Copy all user projects, which are located in cisnatural.war, from the old cisnatural.war to the new cisnatural.war.

   7. Repack the new cisnatural.war to a web application using a zip tool.

3. Uninstall the old version of Natural for Ajax.

   1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

   2. On the Enterprise applications page, select cisnatural.war and choose Uninstall.

   3. On the Uninstall Application page, choose OK.

   4. On the next page, choose Save.

4. Install the new version of Natural for Ajax as in a first installation.

Installing Natural for Ajax on Apache Tomcat

The distributables for Apache Tomcat are contained in the directory Tomcat.

Natural for Ajax is installed using the Tomcat Manager.

The following is assumed:

• <host> is the name of the machine on which Apache Tomcat is installed.

• <port> is the name of the port where Apache Tomcat is installed. In a default installation, this is port 8080.

• <tomcat> is the path to the directory in which Apache Tomcat is installed.

The following topics are covered below:

• First-time Installation

• Update Installation

First-time Installation

To install Natural for Ajax

1. Start Apache Tomcat.

2. Open your web browser and enter the following URL:

   http://<host>:<port>/manager/html

   This opens the Tomcat Manager.

3. Deploy the web application file cisnatural.war:

   • Under Select WAR file to upload select the path to the file cisnatural.war.

   • Choose Deploy.

4. Copy the license file into the directory <tomcat>/webapps/cisnatural/cis/licensekey (you have to create the directory if it does not yet exist).

5. In the Tomcat Manager, look for the application Natural for Ajax and choose Reload.

Update Installation

To update Natural for Ajax

1. Shut down Apache Tomcat.

2. Create a backup copy of your sessions.xml file, which is located in <tomcat>/webapps/cisnatural/WEB-INF.

3. Create a backup copy of your license file, which is located in <tomcat>/webapps/cisnatural/cis/licensekey.

4. Create backup copies of all modified configuration files, which are located in <tomcat>/webapps/cisnatural/cis/config.

5. Create backup copies of previously created projects, which are located in <tomcat>/webapps/cisnatural.

6. Start Apache Tomcat.

7. Open your web browser and enter the following URL:

   http://<host>:<port>/manager/html

   This opens the Tomcat Manager.

8. Select cisnatural.war in the list of installed applications.

9. Choose Undeploy.

10. Deploy the new version of Natural for Ajax as in a first-time installation.

11. Shut down Apache Tomcat.

12. Restore the files that you have backed up in steps 2, 3, 4 and 5.

13. Start Apache Tomcat.

14. Open your web browser and enter the following URL:

    http://<host>:<port>/cisnatural/index.html

15. Open the development workplace.

16. In the Development Tools node of the navigation frame, choose Layout Manager.

17. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

Verifying the Installation

It is assumed that http://<host>:<port> is the URL of your application server or web container.

To verify the installation

1. Enter the following URL in your web browser:

   http://<host>:<port>/cisnatural/index.html

   This opens a page from where you can access the logon page, the development workplace and the configuration tool.

2. Click on the link for the logon page.

   This opens the Natural logon page. The installation is now complete.