Importing a Joget App

Joget Apps are packaged files that contain Form, List, UI, Process definitions, custom plugin, and or app data. Apps can be exported from another Joget installation, or downloaded from the Joget Marketplace. Importing a new app into an environment with an existing App ID will result in the creation of a new App Version. You may also choose to retain or override environment variables and plugin default properties by checking on the checkboxes.


Example:-

  1. App with Id "leaveSystem" with App Version 2 (Process Version 10) exists in the environment.
  2. Importing an App with the same App Id will result in the creation of an App with the ID "leaveSystem" with App Version 3 (and Process Version 11).


To import an app, log in to the App Center as an admin or a user with an "admin role" (See Managing Users for more information).

  1. Click on the Import App button (see Figure 1).


    Figure 1: App Center buttons

  2. You can also import apps from the Design App dashboard (the URL is http://localhost:8080/jw/web/userview/appcenter/home/_/home).


    Figure 2: Import the app via the Design App page

  3. In the Import App popup window, select the app ".jwa" file from your hard disk folder and click on the Upload button.
    Click on the Show Advanced Options hyperlink to manage the import options, as follows:

    • Override environment variables.
    • Override plugin default properties.
    • Do not import participant mapping for existing participants.
    • Do not import tool mapping for existing tools.
    • Do not import plugins.

    • Do not import Form Data.


      Figure 3: Advance options for app import

      Import plugins & import form data are new features in Joget DX. These import options are only applicable to apps that has been exported from Joget DX only.


      If the target environment has an existing version of the app and:

      • If override app variables are checked, app variables such as counters (such as the running number created by use of ID Generator Field) will be overridden.
      • If override app variables are not checked,  app variables that are intended to be overwritten will not carry over. 


  4. Publish the app after importing if you want to run the app.

    1. At the top left, click on the Versions button.
    2. A window will pop up the App Configuration Management. Click on the app version radio button and then click on Publish button.


    Figure 4: Publish an app

    You can also manage the following app import options:

    • New Version: Clone this app into the next version number.
    • Publish: Publish for users to run the app.
    • Unpublish: Unpublish to hide the app.
    • View: Jump to this version to view the app elements.
    • Delete: Permanently delete this app. App data and process data related to this app will not be deleted. 
      You cannot undo or reverse an app deletion. You can import your app which you have previously exported or restore from a database backup (caution, a restore may affect other apps and Joget data).

  5. Click the Launch button to run the published app. The app will open in a new browser tab.

    Figure 5: Run a published app


New feature

New Import Feature in Joget DX 8 version 8.1 onwards.

  • Joget DX 8 version 8.1 onwards support zipping folder like `crm_1` from app_src folder and use it to import app.
  • This feature will support the use of zipped files from app_src folder to be imported into Joget DX.
    • Steps to use this feature  
      • Go to installation folder/wflow/app_src/<app name> eg: crm
      • Zip one of the app's version folder eg: crm_1


      • Import the zip 


      • A new app version for the crm app should be created. (Version 2) (new app if does not exist) 

Import App Troubleshooting

There will be cases where you will get an error when importing an app to a new Joget DX Environment.

Figure 6: Import Error

These are potential errors that could cause the error and how to fix it.

  1. java.sql.SQLException: Column 'id' cannot be null in Joget log. 
    • The error was caused by a missing id in the appDefinition.xml of the exported app.
    • To fix this, go to the exported app .jwa file and open appDefinition.xml, this requires you to search id one-by-one to check if there's an id with no value.
    • In the figure above, in line 1441, an Environment Variable id's value is not set. In this sample case, we will set the id with "test".
    • Replace the "<id>test</id>" with the correctly declared one from your original app to avoid possible conflict / mismatch, save it in your .jwa file and test the app import again.
    • The error should not re-occur.

App Configuration Management

The App Configuration Management popup window has the following additional management tabs:

Exporting a Joget App

The Export option allows one to export the entire app design into a single file. This is useful when one is performing a backup or transferring the app to another server.

  1. To export an app, the first login to any UI in the current app as an administrator.
  2. In the App Composer of the Application click on the Export Button on the top left.


  3. A file .jwa extension will be generated. This is a zip file you can open in any zip or compression utility. You can now take this .jwa file and import it into another Joget platform.



New Export Feature in Joget DX

New Feature

This is a new Joget DX feature for Enterprise and Professional editions.

Joget DX has a new feature where you can select to include the following data or plugins when exporting apps:

  1. The app's transaction data records.
  2. The custom plugins used in your app (This option is not available if you are running on Joget Cloud).

When the "Export plugins" property is checked:

If Joget App Git is enabled (default behavior), Joget will search the "wflow/app_src/[appId]/[appVersion]/plugins" folder for any custom plugins used in the app to include it in the exported app file.

If Joget App Git is disabled, Joget will search the app's component definitions for matching classpaths instead.

Reference: Git Configuration - Disabling Git In Joget DX


The above-selected elements will be compressed and added to the "appname.jwa" file. When you import this app into a new Joget platform, the data records will be added to the database and any custom plugins added to Joget's ".\wflow\app_plugins\" folder.

Caution: If the app's transaction records are huge, export and import of the app could take a long time and may cause a performance issue for other Joget users. If you have a lot of data records, it is better to use a database utility to perform a database SQLdump.

Figure 7: Exporting An App

Related Documentation



  • No labels