Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents


App Considerations

English
If you are looking into migrating all the apps, please look at Backup, Restore and Disaster Recovery.

In order to migrate a single Joget app from one server to another, we will need to assess the current footprint of the app to determine the best way to migrate.

...

For example, in the screenshot below. The "Expenses Claim" app is making use of "j_expense" as the prefix in its forms' table naming.

Image Modified

Figure 1: Form tables

Migrating app form data out would be quite straightforward since it resides in its own set of tables. Depending on the database systems that you are using, you can make use the appropriate tools/clients to export the data out. 

Image Modified

Figure 2: Export App

...

Referring to Figure 1 above, we can make use of the form Form builder > Advanced Tools > Table > Table Usage In Other Apps to check if tables are being shared with other apps.

...

This is because data of process instances are stored in set of tables shared by all other apps in the same Joget server. Process data contains not just instances from the latest version of the app that we are migrating out, it may also contain all the process instance data of the same app but from earlier versions. The current server and target server may also contain different set of versions . Migrating of the same app too. Therefore, migrating the data out in parts may will likely to affect the normal functionality of the workflow engine.

We would recommend to leave the process instances' data behind. For process instances that are still in transit (open.running), here's the approach that we recommend.

...

In case you find it important to preserve the audit trail of the part / completed process data, you can enable Process Data Collector at the app level. Process related data of the app would be written into set of tables (app_report_* tables) that can be easily digested for analytical use such as by using SLA Report Menu. However, this plugin would only work on new process data as they are being executed after it is enabled, and not retrospectively on past process data.

Plugins

This section is applicable to you if your app is making use plugins, otherwise, you can move on to the next section.

...

Make a list of all external touch points that your app is using.

Image Modified

Figure 3: Service Calls in App's Performance

...

Otherwise, you may need to duplicate the existing user directory date (tables with prefix of dir_ in the database) to the new server.

Migration of Running Process Instances

Before We Begin

Before attempting anything, always perform a backup in any (app or database) servers that you will be working on. This is so that there's always something to fallback on, just in case!

...

  1. Make a list of process instances that are still running.
  2. Copy these data over to the target server.
    1. Form Data from the database
    2. File Upload from wflow/app_formuploads
  3. Now that form data and its uploaded files are available in the target server, we can migrate process instances over to the target server.

To verify the data that you have copied them over, make use of CRUD Menu or List Menu in the app to browse through the data imported in.

Migrate Process Instances

Then, perform the following steps, starting with just 1 process instance. The steps below can be performed using the utility app available for download in this article.

  1. Based on the list compiled in step 1, start new process instance in the new server using the same user with reference to the form record ID. Here's a sample of a process instance that is still running.
    Image Modified
    Figure 4: Process Instance View

    In Figure 4 above, there are 3 vital information we need, and use them to call JSON API in the target server by using JSON API#web/json/workflow/process/start/(*:processDefId). We will also need to copy any workflow variable data over to the new instance too. We can pass on var_* parameters to set the workflow variables' values accordingly.

    At this point of time, the new process instance would be waiting at its very first activity.

    IMPORTANT NOTE: If you have tools that run right at the start of the process flow, this may cause manipulation of form data state. Take note of potential changes that may occur and devise a way to preserve original data/state.
  2. Once a new process instance is started, note down the process instance ID generated, and we will then need to make use of JSON API#web/json/monitoring/activity/start/(*:processId)/(*:activityDefId) to resume the activity where it supposed to be, in the original server.

    Image Modified
    Figure 5: Process Instance View Highligting Open Activity Instances

    NOTE: Depending on how many pending activities that we may have in the specific process instance, we may need to make multiple calls to this JSON API. Take note that in the first of such call, we will need to set the "abortCurrent" parameter value to "true" so that it aborts the first default pending activity instance. Subsequently, set "abortCurrent" parameter to "false".

    IMPORTANT NOTE: The assignee of the resumed activity instance may not be correct if its participant mapping relies on performer of past activities. This is because past activities' data is NOT available in the target server.
  3. In the target server, attempt to continue with the process assignment, as usual, through Datalist Inbox Menu or Inbox Menu in your app, ideally, to the very end, to validate that it is working as expected.

Once we have validated and refined the steps to migrate a process instance, we can then move on to migrate more process instances over.

Utility App for Migration of Running Process Instances

We have created an utility app to perform the 3 steps listed above. It has been tested using MySQL database and on Joget DX 7.

Please refer to the diagram below to understand on how to use it.

Image Modified

Figure 6: Utility App to Migrate Process Instances

  1. Install this app in the current server. Publish the app.
  2. Go to setup menu to key in parameters required of the target server.
    Image Added
    Figure 7: Utility App Setup Screen

  3. At the target server, login as admin, navigate to System Settings > General Settings > API Domain / IP Whitelist and key in the domain / IP of the current / old server. This is so that the target server can accept JSON API calls from current server. We have set up the app.
  4. Go to List of Running Process to see the list of running process instances. Select and click Migrate to start migration.
    IMPORTANT NOTE: If your app has User Notification Plugin or similar notification plugin enabled, or other process tool that will immediately run after process starts, it may be a good idea not to have them enabled while migration is taking place.
  5. Observe current server log files and target server's Running Processes to verify its execution status / result.
    An entry will be added to Logs menu if it is successful.
    Image Added

    Figure 8: Utility App Logs

    In the List of Running Process menu, the status will change to "Migrated" with process instance ID furnished based on the data from logs.
    Image Added
    Figure 9: Utility App List of Running Process with New Process Instance Information

View file
nameAPP_migrateProcess-12-2021050622400720210518184056.jwa
height250

Note: This migration utility app is tested on Joget v6 Enterprise 6.0.31 and Joget DX Enterprise 7.0.16 and with process migrated into a Joget server runing Joget DX 7.0.16.