NaturalONE Version 8.3.7
 —  Using NaturalONE  —

Deploying Natural Applications

This document covers the following topics:


General Information

You can deploy a Natural application from a version control system to a Natural server. The Natural sources and any other resources may reside in a versioning repository on one machine, and the ready-to-use application may be deployed to a different machine via a Natural server connection.

NaturalONE offers a deployment wizard which collects all required information (such as the access information for the versioning repository and the Natural server) and writes it to an Ant script which is used to start the deployment process. This Ant script makes the deployment task highly configurable and repeatable, and allows you to run the deployment process unattended.

The deployment process can either be started from within the NaturalONE Eclipse environment or via the Ant command line utility. It performs the following steps:

Top of page

Using the Deployment Wizard for Natural Applications

The deployment wizard creates a Natural deployment file in your project root. This is an Ant script. You can create one or more Natural deployment files for a project, and you can also load an existing Natural deployment file and modify the current settings.

The deployment file contains information on whether it has been created for a secured or unsecured environment, that is, whether the environment is protected by Natural Security or not. This setting cannot be changed after the deployment file has been created. Thus, if you change a project from secured to unsecured (or vice versa), you have to create a new deployment file.

Start of instruction setTo use the deployment wizard

  1. In the Navigator view or in the Natural Navigator view, select the Natural project for which you want to create the deployment file.

    Or:
    If you want to load the settings of an existing Natural deployment file, select this file in the Navigator view or in the Natural Navigator view.

  2. From the File menu or from the context menu, choose New > Other.

  3. In the resulting New dialog box, expand the Natural node, select Deploy Natural Ant and then choose the Next button.

    The first page of the wizard appears (see below).

  4. Specify all required information as described in the topics below. Use the Next button repeatedly to proceed from the first page of the wizard to the last page.

  5. When all required information has been provided, choose the Finish button.

The different pages of the deployment wizard are described in the following topics:

General Settings

On the first page of the wizard, you define general settings for the deployment.

Deploy

Deployment file

The default name for the Natural deployment file is deploy.xml. This name is shown in this text box when an existing Natural deployment file was not selected while invoking the wizard. However, when an existing Natural deployment file was selected, the name of the selected file is shown and the settings from this file are automatically loaded.

You can enter any other name for your new deployment file. It is recommended that your new deployment file also has the extension ".xml".

Note:
If you keep the name deploy.xml, the settings from an existing Natural deployment file with the same name are loaded the next time you select the project and invoke the wizard.

If you want to load an existing Natural deployment file, choose the Browse button. A dialog appears, providing for selection all Natural deployment files in the current project. Next, you have to choose the Load from File button. Otherwise, the settings in this file are not shown in the wizard and may thus be overwritten unintentionally.

If you want to return to the default settings of the deployment wizard (this also includes the information that can be specified on the other pages of the wizard), choose the Load Defaults button.

Deployment mode

Select one of the following option buttons:

See also Controlling the Scope of Files to be Processed.

Note:
You can run more than one incremental deployment inside a single Natural project. Each of the incremental deployments maintains its own state of changed files. This is helpful, if you want to deploy your application into different environments, for example, into a testing environment and later into a production environment.

Upload

When enabled, the sources and resources are uploaded to the Natural server.

Use exclude list from project if available

When enabled, an exclude list is used. The files specified in the exclude list will not be used for the deployment. See also Excluding Objects from Processing in the Natural Environment.

Retain sources of unchanged files

When enabled, only the sources of changed files are updated on the Natural server. The sources of unchanged files are neither uploaded nor stowed on the server. In case Stow is also selected, the sources of unchanged files are cataloged instead. See also Controlling the Scope of Files to be Processed.

Note:
This option only has an effect when an incremental deployment mode is selected. In full deployment mode, all files in the project are assumed to be changed files.

Check time stamp on server

When enabled, the time stamps of the sources to be uploaded are checked against the time stamps of the sources on the Natural server. If the sources on the server have been changed since the last deployment run, a time stamp conflict is detected and the corresponding sources on the server are not overwritten. For further information, see Checking the Time Stamps in the Natural Environment.

Catalog / Stow / None

When Catalog is selected, the uploaded sources are cataloged on the Natural server. When Stow is selected, the uploaded sources are saved and cataloged on the Natural server (the time stamps of the sources and cataloged objects are then identical). When None is selected, the uploaded sources are neither cataloged nor stowed on the Natural server.

Retries if catalog is not successful

When Catalog or Stow is selected, you can specify the number of retries for cataloging. This is helpful since it will not always be possible to catalog all sources in the proper order in one pass. When you specify a number greater than 1, the erroneous sources are recataloged until either no more errors occur or the specified number of retries has been reached. Default: 1.

Delete sources on server after upload

When enabled, the sources are deleted on the Natural server after they have been uploaded and (if Catalog or Stow is selected) cataloged.

Enable password encryption

When enabled, all passwords that are used in the deployment file are stored in an encrypted format.

Enable fail-on-error for Ant script

When enabled, the Ant script reports errors and terminates in the case of a build failure.

When disabled, the Ant script still reports errors but build failures are only triggered in severe situations (see also Status Code Handling).

Root directory

This path should only be changed when you intend to start the deployment from the command line (that is, when the deployment is not to be started from Eclipse).

Specify the directory in which the selected project is to be checked out and where the processing takes place. When the deployment is supposed to run on a different machine, you can insert the desired root path via copy-and-paste.

Source Types

On the second page of the wizard, you can specify the source types that are to be processed.

When the Process all source types check box is not selected, you can deselect any sources types which are not to be processed. For example, if you deselect the GDA check box, global data areas are not processed (that is, they are not uploaded and cataloged) during the deployment.

Deploy

Select the Support old internal data area format check box only, if you require data areas in the old format that are to be used with Natural Version 5.1 or below. See also Natural in Changing the Project Properties.

Repository

On the third page of the wizard, you define all settings related to the versioning repository. This can be either Subversion (SVN), GIT or CVS.

Deploy

From the Type drop-down list box, select the type of versioning repository that you are using, and then specify all required information. The names of the text boxes and their availability changes according to the selected type.

The wizard usually collects a set of default information as given for the selected project. In most cases, only minor corrections have to be made to the defaults, for example, user ID and password may have to be provided.

Server Environment

The fourth page of the wizard shows information which applies to the Natural server to which the selected project belongs (such as host name and port number). You can change the settings according to your requirements. For information on the options on this page, see Mapping a Natural Environment.

Deploy

Steplibs

The fifth page of the wizard shows the steplib settings for the current project, depending on whether the current environment is protected by Natural Security or not.

The following page is shown for an unsecured environment. In this case, project steplibs can be defined.

Deploy

The following page is shown for a secured environment. In this case, library steplibs can be defined.

Deploy

In many cases, the given settings are sufficient. For information on the steplib options on this page, see the description of the property page Steplibs in Changing the Project Properties.

Mappings

On the sixth (and last) page of the wizard, you can enable the mapping of library names.

Deploy

When the Enable mapping check box is selected, you can change the mapping information for all required libraries. The workspace name is the library name that is used in the versioning repository and in the current Eclipse workspace. The target name can be a different library name that is to be used on the Natural server.

To add a new mapping, choose the Add button and specify both the workspace name and the target name.

Top of page

Controlling the Scope of Files to be Processed

When you deploy a Natural application, you can control the scope of the files that are to be processed in the Ant workspace. This is done by choosing one of the following deployment modes on the first page of the deployment wizard for Natural applications:

Important:
With both deployment modes, the files to be processed must reside within a single Natural project. The Ant deployment script cannot process files which reside in a different Natural project. In the latter case, however, you can create a separate deployment script within the other project which processes the files in that project accordingly.

Top of page

Starting the Deployment from Eclipse

When you start the deployment process from Eclipse, it is not possible to execute the checkout and update targets of the deployment file since these targets would access the versioning repository, and this is not feasible from within an Eclipse environment. If you want to check out a specific revision from the versioning repository or if you want to update your project with sources from the versioning repository, you have to start the deployment from the command line as described below.

For testing purposes, for example, it is helpful to start the deployment process from Eclipse. Since the Natural deployment file is an Ant script, the built-in Eclipse functionality of starting Ant scripts is used here. The build target of the Ant script will then be executed.

Start of instruction setTo start the deployment from Eclipse

Top of page

Starting the Deployment from the Command Line

You can start the deployment process from a Windows command line such as the Command Prompt (cmd.exe) or from a shell command line on a Linux system. When you start the deployment from the command line, special requirements must be met.

The following topics are covered below:

Prerequisites

The following must be installed and accessible:

You have to copy the following JAR files, which contain the necessary processing code, from the NaturalONE Eclipse installation to the new directory (when using a master deployment file, it is not required to manually copy the files mentioned below):

You have to copy your deployment file, which has been created by the deployment wizard, into the directory which has been specified in the wizard as the root directory (this is the base directory for processing).

Starting the Deployment

When all prerequisites are in place, the deployment can be started by issuing specific Ant calls. This section just provides some examples (where the default name deploy.xml is used).

Top of page

Status Code Handling

The Ant deployment script can run in two status code modes. The mode can be toggled by specifying the command line parameter -Dnatural.ant.failonerror as described in the following table.

Command Line Option Description
-Dnatural.ant.failonerror=no Only severe errors such as missing project directories will lead to a build failure with a status code other than 0. Other errors such as catalog or stow errors will be reported but will not trigger a status code other than 0 and hence will not lead to a build failure. This is the default mode.
-Dnatural.ant.failonerror=yes In addition to the severe errors described above, errors occurring during checkout, update, catalog, stow and delete will also lead to a status code other than 0 and hence will lead to a build failure.

Note:
The default mode can also be changed on the first page of the deployment wizard.

When the additional status code handling has been enabled, the Ant tool as well as the internally used tools such as SVN, GIT or CVS clients may issue specific status codes. In case the status codes are unclear, refer to the documentation of these tools.

In addition, the following NaturalONE-specific status codes may be issued:

Status Code Description
0 No build errors occurred.
11 An error occurred while reading or writing the Natural Development Server configuration data. Check whether the Natural Development Server is accessible.
12 It is not possible to connect to the Natural Development Server. Check whether the Natural Development Server is running and accessible.
13 An error occurred while uploading Natural objects. Check whether the Natural Development Server allows uploading and saving of Natural objects in the affected libraries.
14 An error occurred while cataloging Natural objects. Check the affected objects and correct the errors.
15 An error occurred while deleting Natural objects. Check whether the affected objects are available on the server

Note:
Under Windows, Ant currently maps all error codes other than 0 to 1. Thus, %ERRORLEVEL% is either 1 for errors or 0 for no errors.

Top of page

Checking the Time Stamps in the Natural Environment

When deploying Natural applications in the usual way, the sources on the Natural server are exclusively updated by the Ant deployment scripts. In this case, the sources in the Ant workspace and the sources on the Natural server are always identical. If the sources in the Ant workspace are updated with newer revisions from a version control system, the Ant script can easily detect the new sources and directly transfer them to the Natural server without conflicts.

In special cases where the sources on the Natural server are not exclusively controlled by the Ant deployment scripts but, for example, are directly edited on the server, the deployment process would simply overwrite the modified sources when they have also been changed in the versioning repository.

To avoid overwriting of sources that have been modified directly on the server, it is possible to enable time stamp checking in the deployment wizard for Natural applications (see General Settings under Using the Deployment Wizard for Natural Applications).

The following topics are covered below:

Prerequisites

Time stamp checking works as of the following versions:

General Information on Time Stamp Checking

When time stamp checking has been enabled in the deployment wizard for Natural applications, the following happens during the deployment process:

Maintaining Time Stamps in the Ant Workspace

The time stamps in the Ant workspace are stored in the file timestamp_<project-name>.properties. When time stamp checking is enabled in the deployment wizard, this file is created during the deployment process. The time stamps in this file are updated each time an upload is successful.

If time stamp checking is disabled, an existing time stamp file in the Ant workspace will be deleted during the next deployment run. This is necessary because the time stamps in this file must be most accurate, and this is not the case when an in-between deployment is run without time stamp checking.

Detecting Time Stamp Conflicts with checkts

The checkts target of the Ant deployment script simulates the next run of the script without making any changes. It just reports the time stamp conflicts so that you are able to resolve these conflicts before starting the usual deployment process.

The following is an example of starting the Ant script with the checkts target:

ant -lib path-to-mylib -f deploy.xml checkts

Resolving Time Stamp Conflicts

Generally, resolving time stamp conflicts is a task left to the user of the deployment process because the reason for a time stamp conflict may be very specific and cannot be solved with a general rule or processing method.

When the time stamp conflicts have been resolved, you can synchronize the time stamps of the sources that were in conflict. To do so, you start the Ant script with the checkts target and the additional option -Dnatural.ant.resolve.time.stamp.conflicts=yes. For example:

ant -lib path-to-mylib -f deploy.xml checkts -Dnatural.ant.resolve.time.stamp.conflicts=yes

If the Ant script is started like this, it updates the time stamps in the Ant workspace that were in conflict with the current time stamps from the server. When the next usual deployment run is then started using the build target, the sources that previously caused the time stamp conflicts are also uploaded.

Keep in mind that the above Ant call only updates the time stamps in the Ant workspace for the sources that previously had time stamp conflicts. It does not perform the upload itself and it does not resolve the reason for the conflict, for example, by merging sources.

Top of page