Upgrade Netgrif Platform

Netgrif publishes release notes and the required migration tasks for individual upgrade paths. If you are updating a deployed Platform instance, select the version you are upgrading from and the target version. The result is an exact list of tasks in the order in which they must be run.

Netgrif prepares these migrations; they are not created from the recipes for a custom Petriflow process. To update existing cases after changing your own process, see the case migration procedure.

Upgrading fromNetgrif Platform 1.0.0→To versionNetgrif Platform 1.0.1

1 release stepRun them in the listed order.

Netgrif Platform 1.0.0 → Netgrif Platform 1.0.1

1. 1

   Netgrif Platform 1.0.0 → Netgrif Platform 1.0.1

   1 migration task

   Relevant release notes

   • Process resource IDs use a stable prefix derived from processIdentifier instead of the PetriNet ObjectId.
   • Existing databases with legacy IDs require a conversion of the stored IDs and the references to them.

   Migration tasks

   1. 01

      Process resource identifier migration

      Performs a one-time conversion of the old process resource ID format to the format derived from the stable processIdentifier.

      When to run

      When upgrading a database from Platform 1.0.0, if preflight finds legacy process-resource IDs. It does not run on a fresh 1.0.1 installation or after the migration has already completed.

      Before production

      The available script is a working draft and is not yet production-ready. Before deployment, it must have its blocking findings fixed and pass a successful test on representative data.

      1. Migration scriptmigration_platform_1_0_0_1_0_1.groovy
         Download ↓
      What the task changes6 areas

      Process roles

      Changes the IDs of all non-global roles and the stored references to those IDs.

      PetriNet models

      Updates role keys, permissions, and negative view roles at both the net and transition level.

      Users and groups

      Preserves the assigned business roles and rewrites their old IDs to the new ones.

      Cases

      Changes case IDs, roles and permissions, task references, and CASE_REF values.

      Tasks

      Changes task IDs, caseId, processIdentifier, and role permissions.

      Elasticsearch

      After the MongoDB phase succeeds, creates documents under the new IDs and removes the old ones.

      What the task does not change3 items

      • the petriNetObjectId and the Petriflow process version of existing cases
      • activePlaces and ordinary business values
      • file content in storage

      Before execution4 items

      • Create and verify a restorable MongoDB backup and an Elasticsearch snapshot.
      • Test the migration on an up-to-date copy of production data.
      • Schedule downtime or block concurrent writes to the affected data.
      • Record the expected counts of cases, tasks, roles, users, and groups.

      Procedure5 steps

      1. Run preflight without writes and confirm that every old ID has an unambiguous new mapping with no collisions.
      2. In Admin, open Cluster → Migrations and select the designated worker.
      3. Run the MongoDB phase and check the counts and errors of every batch.
      4. Start the Elasticsearch phase only after the MongoDB phase has been verified successfully.
      5. Wait for the indexing queues to drain and perform all postflight checks.

      Verification after migration5 items

      • No legacy ID remains in cases, tasks, or non-global process roles.
      • The counts of cases, tasks, and non-global roles match before and after the migration.
      • Permissions, role assignments, and CASE_REF values contain no null or unresolved IDs.
      • Users and groups have the same business roles as before the migration.
      • Cases and tasks can be loaded by their new IDs and found in Elasticsearch.

      Rollback3 items

      • Restore MongoDB from the pre-migration backup.
      • Restore the Elasticsearch snapshot or rebuild the indexes from scratch.
      • Storage is not restored, because this task does not change its content.