Deploying the Application

This document covers the following topics:


Components of a Natural for Ajax Application

A Natural for Ajax application consists of two parts that are usually installed on two different machines.

On one hand, there are Natural modules (adapters, programs, subprograms and other Natural objects) that are installed on a Natural server. On the other hand, there are page layouts of rich GUI pages and related files that are installed in a Natural for Ajax environment on an application server.

Unloading the Natural Modules

The Natural modules that belong to your application are contained in one or several Natural libraries in your Natural development environment. Unload them into a file, using the Object Handler.

Installing the Natural Modules

In order to install the Natural modules in the production environment, load them with the Object Handler.

Packaging the User Interface Components

Your web application might contain one or more user interface components.

In production environments it is deeply recommended to always deploy/refresh the whole web application for consistency.

In development or test environments you sometimes might want to deploy single user interface components into an already deployed web application. To deploy global files such as custom controls, which are used by several user interface components or configuration files like the cisconfig.xml file (which is used for the whole web application), you have to use web application deployment/refreshment as described in the following sections.

User interface components are stored in subdirectories of your web application.

You only need to package those files of your user interface component which are not generation results. All files which are generation results will be generated by the Natural for Ajax runtime during deployment. If you also package files which are generation results, the Natural for Ajax runtime system will ignore these files.

If you are using NaturalONE, use the ant war deployment wizard to create an ant file which will package your user interface component(s). To package a user interface component for deployment without NaturalONE, add all files and subdirectories to an archive using an archiving tool like WinZip or tar. Do not include the following files and folders:

File Description
<use interfacedir>/*.html Generated HTML pages.
<use interfacedir>/wsdl/*.* Generated data schemas.
<use interfacedir>/nat Generated Natural code
<use interfacedir>/protocol Generated protocol files
<use interfacedir>/styles/<mystylesheet>.css Style sheet files that are generated from a Natural for Ajax *.info file

Provide a unique name for the created zip file. This can for example be done by appending date or timestamp to the file name. Example: <myui>20170501.zip.

Deploying the User Interface Components

In order to deploy the user interface components, simply copy the zip file which you created as described previously into the _uiupdates folder of your web application, for example: <tomcatfolder>/webapps/<mywebapp>/_uiupdates/<myui>20170501.zip.

By default the Natural Ajax runtime system will pick up the file every 5 seconds. This value can be customized with the monitoringthreadinterval parameter. It will deploy it and refresh all internal caches of the Natural Ajax runtime system. For the example above, deployment and refreshing is finished when a file with the name <tomcatfolder>/webapps/<mywebapp>/_uiupdates/<myui>20170501/update.result exists. It is important to check the update.result file for errors: Open the file and look for "Update finished Successfully". If you cannot find this, check the *.protocol files in the protocol sub folder for errors and/or exceptions.

In case you cannot solve the generation problems via the Layout Painter error marking, you can switch on the creation of additional log files. See the htmlgeneratorlog attribute in the Ajax Configuration section.

Packaging and Deployment as a Web Application

Natural for Ajax is delivered as a web application (.war file). This allows for packaging and deploying also your own applications (more exactly: the user interface components thereof) as self-contained web applications. The preferred way to create a *.war for your application is to use the ant war deployment wizard of NaturalONE.

If you are not using NaturalONE:

Start of instruction setTo package your application as a web application

  1. Invoke the Application Designer development workplace.

  2. In the Development Tools node of the navigation frame (which is visible when the Tools & Documentation button has previously been chosen), choose WAR Packager.

  3. In the resulting dialog, make sure that the Deployment Scenario tab is selected.

  4. Define the generation type by selecting one of the following option buttons: with file system reference or fully clusterable. See the Application Designer documentation for detailed information on these generation types.

    Note:
    The option fully clusterable applies only for web applications written in Java, not for those written in Natural. This is because a Natural-written application runs on a Natural server and therefore needs to keep a TCP/IP connection to the server, while Java applications are executed on the web container itself.

  5. If you selected with file system reference, enable the Switch off Design Time check box.

  6. Select the Project Selection tab.

  7. Select the project directories that you want to include in your web archive. These must be at least the following:

    Directory Description
    cis Application Designer configuration files.
    cisnatural Natural for Ajax logon page and related pages.
    HTMLBasedGUI HTML user interface.
    images Application Designer image files.
    META-INF Standard directory in a web application.
    resources Natural Web I/O Interface style sheets and related files.
    scripts Natural Web I/O Interface JavaScript files.
    WEB-INF Standard directory in a web application.

    In addition, you have to select your own project directories.

  8. In the text box WAR File to be created, specify a path and name for the web application to be created.

  9. Choose the Create WAR button.

    The web application (.war file) is created.

Start of instruction setTo deploy your application

  1. You deploy your web application in the same way as you deployed Natural for Ajax itself (see Installation).

  2. After you have deployed your web application, you can use the configuration tool to specify the configuration for this specific application. For further information, see Using the Configuration Tool.

    Start the configuration tool with the following URL:

    http://<host>:<port>/<webcontext>/conf_index.jsp

    The logon page of the application can be found here:

    http:// <host>:<port>/<webcontext>/servlet/StartCISPage?PAGEURL=/cisnatural/NatLogon.html

    Note:
    <webcontext> denotes the web context of your application. On Apache Tomcat, this is the name of the .war file, without the extension .war. On IBM WebSphere, this is the value you specified as the web context during the deployment.

Generating HTML Pages Using the Command Line

You can generate HTML pages using the command line (either single pages or entire projects). If you do this, you have to reload your web application afterwards or - in a development environment - use the monitoring tool to refresh the internal caches.

An Ant file named generate.xml is available for this purpose. After the installation, you can find it in the support/ant directory.

The Ant file has the following major targets:

  • info
    Shows the syntax of this Ant task.

  • project
    Generates all HTML pages for a given project.

  • page
    Generates a single HTML file for a given page in a project.

  • pages
    Generates HTML files for given pages in a project.

  • style
    Generates CSS files for info files in a project

The following call explains the targets with their mandatory and optional parameters:

ant -f generate.xml info

By default, the following log files are written during the HTML generation:

<layout>.protocol files

For a layout named mylayout.xml a file named mylayout.protocol is created in the protocol subdirectory of the user interface component. It contains the error messages, warning messages and information messages for the controls in the layout. Open the layout with the Layout Painter Editor to position at the erroneous controls.

Example

<?xml version="1.0" encoding="utf-8"?>
<pro:protocol xmlns:pro="http://www.softwareag.com/cis/protocol">
<pro:lineitem>
	<pro:id>6</pro:id>
	<pro:tag>field</pro:tag>
	<pro:message>
		<pro:severity>Error</pro:severity>
		<pro:mtext>Property VALUEPROP is not set</pro:mtext>
	</pro:message>
	<pro:message>
		<pro:severity>Warning</pro:severity>
		<pro:mtext>One of the properties LENGTH or WIDTH should be set</pro:mtext>
	</pro:message>
</pro:lineitem>
<pro:summary errors='1' warnings='1' infos='0' ></pro:summary>
</pro:protocol>

HTMLGeneratorWholeDirectory.log

When generating all layouts of a user interface component, additionally a file named HTMLGeneratorWholeDirectory.log is created in the log subdirectory of the user interface component. It contains the names of the generated layouts and the information, whether an error occurred.

Example

...
Starting generation of wpworkplacelan1.xml...
...finished 
Starting generation of wpworkplacelan2.xml...
...finished 
Starting generation of xmldatamode.xml...
...finished 
Starting generation of xmldatamode2.xml...
...finished 
=========================================
 227 layouts generated
 1 layouts with ERROR

<layout>.log files

In addition to the above, you can activate the creation of an individual .log file for each layout. This file contains generation details.

To switch on the log file creation, set htmlgeneratorlog="true" in the cisconfig.xml file. Only activate this option, if you need to analyze generation problems, as it reduces generation performance. The additional .log files are created in the log subdirectory of the user interface component. The htmlgeneratorlog option is described in General cisconfig.xml Parameters of the Ajax Configuration section.