Import and export of applications

1. General information

• Import and export of applications in NET Genium are used to transfer applications between different installations of the system, to deploy new versions of applications, and to create backup copies.
• The functions for importing a new application, updating an existing application, and exporting an application are available only to users with the highest permission level — the Administrator with database ID 1. This permission is required primarily due to the possibility of modifying the structure, permissions, and dependencies of an application.
• Import of a new application is available through the “Import application” icon in the navigation area, or on the main page in administrator mode by selecting “Import application” in the “Create new application” wizard.
• Updating an existing application is performed in the “Edit application” dialog on the “Administration” tab, which contains a separate “Import application” section intended exclusively for update imports.
• Export of an application is available in the navigation area through the “Export application” icon, and allows generating a file with the “nga” extension. This file contains the complete definition of the application, and optionally also data or file attachments, depending on the selected options in the “Export application” dialog.
• Importing a new application and updating an application represent two distinct processes:
  • Importing a new application creates an entirely new instance of the application.
  • Updating an application replaces the existing application and modifies its structure and configuration according to the imported file.
• In NET Genium Online the import of a new application from an “nga” file is not available – the “Import a new application” dialog offers the “Templates” tab only. Updating an existing application from an “nga” file in the application settings is available. Exporting an application is not restricted.
• Exporting applications and application groups can be disabled in the given installation even for the Administrator user by the “DenyExport.txt” file in the “Config” directory (its content does not matter).
• The “nga” file is encrypted with a fixed NET Genium key, which is not secret. An export containing data must therefore be handled as unprotected data.

2. Import a new application

• The options described in this chapter apply exclusively to the import of a completely new application.
• Importing a new application creates a separate instance of the application in NET Genium and does not perform any update of an existing application. The procedure for updating an existing application is described separately in the chapter Update an existing application.
• Importing a new application is available only to users with the highest permission level, specifically the Administrator with database ID 1.
• Importing a new application is available via the “Import application” icon in the navigation area, or on the main page in Administrator mode by selecting “Import application” in the “Create new application” wizard.
• The “Import application” dialog allows import from a file with the “nga”, “xlsx”, or “xls” extension, or from a template listed on the “Templates” tab.

2.1. “From file” tab

2.1.1. Options

• I am the owner of the imported data
  • Checking this box determines whether the import overwrites the owner of all database records in all imported database tables. The owner of records in the change history tables does not change.
  • If the box is unchecked, the records keep the owner IDs from the source NET Genium – in the target NET Genium they may belong to a different user, or may not exist.
  • A detailed description of ownership and co-ownership of records is provided in the separate guide Edit form.
• Import history of records
  • Checking this box determines whether the record history of all imported database tables should be imported.
  • The prerequisite for this function is that the file with the exported application contains the history records. An export with data always contains the record history.
• Import rights
  • Checked – When importing rights, user and user group IDs will be used exactly according to the rights settings in the source (exported) application and in all its child objects. This form of import can cause a data inconsistency between the rights in the source and destination applications. The same IDs can indicate different users or user groups in two different NET Genium. At the same time, some IDs may not exist in the target NET Genium. In the rights settings of the imported application, only ID numbers will be displayed instead of the name of users or user groups.
  • Unchecked – The imported application and all its child objects that had at least one right set in the source application will have the rights to the user group “Users” set. Objects without rights remain without rights, i.e. accessible only to administrators.
  • The same applies to co-owners of edit form records: if an edit form in the source application had at least one co-owner set, after an import with the box unchecked all users of the “Users” group become co-owners and can thus modify the records of other users. It is therefore advisable to check the co-owners of the edit forms after the import.
• Keep bindings to other applications
  • Checked – References to objects of other applications (edit forms, controls, view pages, queries) are taken over with the IDs from the source NET Genium without any check. The import is stopped with an error message about data consistency violation only where the reference is guarded by a database foreign key. Elsewhere, a reference to a non-existent object remains invalid, and if another object with the same ID exists in the target NET Genium, the reference will point to it.
  • Unchecked – Links to other applications and their children will not be linked. Queries over edit forms of other applications and the controls that use them will not be created. If there are links to other applications, it is necessary to go through and adjust these links.

2.1.2. Select file

• “Browse...” button to upload the file of the imported application with the extension “nga”, “xlsx”, “xlsm” or “xls”.
• The “nga” file format is the standard export and import format for NET Genium applications, which contains the complete definition of the application, including its structure, controls, bindings and possibly data.
• The “xlsx”, “xlsm” and “xls” formats are used to automatically create a new application based on data from Microsoft Excel.
  • For each non-empty sheet of the workbook, a separate edit form, a view page with a view table and a button for creating a new record are created.
  • The row with the column headers is selected for each sheet separately (rows 1 to 10). Columns are read from the left up to the first empty header cell.
  • For each column, a Textbox control with the data type String is automatically created.
  • All data from the rows below the header is automatically imported into the created database table during import. Column names and values longer than 50 characters are truncated.
• An import from an “nga” file creates new edit forms with the identifiers from the source application. If a table with the same identifier already exists in the target NET Genium, the new table gets a numeric suffix (for example “ng_table0”). The new identifier is automatically reflected only in print templates in the Excel format; query conditions written directly in SQL, other print templates, JavaScript and external functions must be adjusted manually.

2.1.3. “Templates” tab

• Each NET Genium has a “Store” directory on the disk with subdirectories by language, and sample applications stored in them, which can be imported in this way.
• The options from the “From file” tab apply to the import of a template. Data in date columns is shifted during the import so that it corresponds to the current month.

3. Update an existing application

• This chapter describes exclusively the process of updating an already existing application. Importing a new application, which creates an entirely new instance of the application in NET Genium, is described separately in the chapter Import a new application.
• Updating an existing application is available only to users with the highest permission level, specifically the Administrator with database ID 1.
• The update of an existing application is performed in the “Modify application” dialog on the “Administration” tab, where the “Import application” section is available.

• Updating is carried out by importing a file with the “nga” extension, which replaces the structure and configuration of the application according to the contents of the imported file. The file must contain exactly one application; NET Genium does not check whether it is the same application.
• The update first deletes the existing application and then recreates it from the file. This implies:
  • All edit forms, controls, view pages and queries of the application get new IDs. Saved links containing the ID of a form or a view page and IDs written in JavaScript, HTML controls and external functions therefore stop working.
  • References from other applications to the updated application (queries over its edit forms and the controls that use them, references in scripts and e-mails) are removed during the deletion and are not restored by the import.
  • The user settings of all users – favorite items, portlets, view table settings and filters – and the synchronization settings of the edit forms of the application are deleted as well.
  • The deletion of the application and its recreation do not take place in a single transaction. If the import ends with an error, the original application no longer exists. It is therefore advisable to export the application including data before the update.
• The data of existing tables is preserved through a backup that NET Genium saves to the “Backup” directory when deleting the application (the “ng_table.xml” and “ng_table_history.xml” files). Tables are paired by identifier, columns within a table also by identifier. New columns remain empty, the data of columns missing in the new version is lost. A backup older than 1 hour is not used. New tables get data from the “nga” file.
• Print templates bound to buttons are saved to the “Templates” directory as new copies with each update and the buttons are switched to them; modifications of the templates made in the target NET Genium are thus no longer used.

3.1. “Modify application” dialog, “Administration” tab

3.1.1. Import application

3.1.1.1. Options

• Update and preserve existing data
  • Checking this box displays the "Browse..." button, which is used to update the application while preserving existing data in all database tables of the application. No other way of updating is available.
  • Preservation of existing data is based on a comparison of the identifiers of tables and columns – see the chapter Update an existing application.
  • The record history is always restored during the update and the owners of records do not change.
• Import rights
  • Checked – When importing rights, user and user group IDs will be used exactly according to the rights settings in the source (exported) application and in all its child objects. This form of import can cause a data inconsistency between the rights in the source and destination application. The same IDs can indicate different users or user groups in two different NET Genium. At the same time, some IDs may not exist in the target NET Genium. In the rights settings of the imported application, only ID numbers will be displayed instead of the user or user group name.
  • Unchecked – The behavior is the same as for the import of a new application, see the chapter Import a new application. The rights set in the target NET Genium are not preserved in either case.
• Keep bindings to other applications
  • The behavior is the same as for the import of a new application, see the chapter Import a new application.

3.1.1.2. Select file

• “Browse...” button to upload the imported application file with the "nga" extension.
• Displayed after checking the “Update and preserve existing data” option.

4. Export the application

• Exporting an application is available through the “Export application” icon and is intended exclusively for users with the highest permission level — the Administrator with database ID 1.

• After clicking the “Export application” icon, an export file with the “nga” extension is generated. This file contains the complete definition of the application. The export includes the structure of the application, controls, relations, and, depending on the selected options, also data or file attachments.
• Exporting an application serves to transfer it to another NET Genium environment or to create a backup copy. The process is performed as a single step without requiring further user actions. After selecting the export options, the system generates the file and offers it for download.

4.1. Options

• Including data
  • Checking this box determines whether the database records of all exported database tables, including the record history, should be included in the resulting export.
• Including attachments (files/images)
  • Checking this box determines whether file attachments of all exported database tables should be included in the resulting export. Attachments are exported only together with data; an export of data without attachments leaves the columns of the “File” and “Image” type empty.

Images inserted into “RichText” controls and the background image of the application group are always part of the export. Of the print templates, only those bound to a button are exported.

The export does not contain users and user groups, synchronization settings, user settings (favorite items, portlets, view table settings) or external functions.

4.2. “Export” and “Close” buttons

• “Export” button – Starts the application export and creates an export file with the “nga” extension, which contains the selected application including all settings and optionally also data or attachments, if these options are selected.
• “Close” button – Closes the application export dialog without performing the export.