eMagiz Runtime Generation 3

Below you will find a document describing the migration path to migrate a single runtime (i.e., connector or container) to the latest generation runtime. Note that this functionality is not yet generally available and can only be executed after consulting your partner manager. For the key aspects of the new generation compared to the current generation, please read this fundamental.

Should you have any questions, please get in touch with academy@emagiz.com.

1. Prerequisites

• Advanced knowledge of the eMagiz platform
• A thorough understanding of your eMagiz model

2. Key concepts

• This migration path allows you to migrate a specific runtime to Generation 3
• All flows of the runtime are updated, so plan your migration
• The JMS needs to be migrated to Generation 3 as the last runtime of your model
• When executing the first migration of a runtime, additional steps are necessary to update your cloud configuration
• In case you want to use the new EDI functionality in messaging, both the connector and the process container need to be migrated to Generation 3

3. Migration Scenarios

As migrating to the latest generation runtime impacts your model, it is advisable to consider various scenarios when migrating. In broad terms, there are two scenarios with which you can migrate. The first scenario is a scenario we will call "Big Bang." In this scenario, you will migrate your complete model at once. The second scenario we will discuss is called "Gradual Improvement." In this scenario, you will migrate parts of your model in a larger time frame.

Before diving into both scenarios and outlining the pros and cons, let us first look at the current limitations of the new generation runtime that might impact your choice regarding which method to choose.

3.1 Known Limitations

The list below shows functionality not yet tested or migrated to work on the Generation 3 runtime. Take this list into account when determining when and how to migrate.

• Message redelivery
• Code Mappings
• Smooks components
• XSL-FO (PDF Generation)
• WS-Security
• eMagiz Mendix Connector
• Dynamic Alerting
• Using "Batch" components (i.e., Data Pipeline)
• Hosting a SOAP web service
• Hosting a REST web service
• Hosting an ODATA web service

3.2 "Big Bang"

As the name of the scenario suggests, this scenario is designed to migrate your complete model at once. As a result, you can (quickly) execute the steps outlined in Chapter four in one go.

3.2.1 Advantages

• The migration path can be executed efficiently as you migrate all runtimes in one iteration
• Your user experience won't be clouded by the fact that part of your solution runs the 'old' architecture and the other part runs in the 'new' architecture
• The duration of the complete migration path from start to finish is limited as you migrate everything at once, and therefore you can move through the environments at a faster pace

3.2.2 Disadvantages

• As you migrate everything at once, you need a period of roughly 2-3 weeks in which no functional changes can happen on your model
• Everything needs to be tested at once
• If part of your model cannot yet be migrated, you need to wait until the complete model can be migrated before you can execute this scenario barring you from unlocking other new features that are only available on the new runtime architecture.

3.3 "Gradual Improvement"

As the name of the scenario suggests, this scenario is designed to migrate your model gradually. As a result, you can (efficiently) execute the steps outlined in Chapter four in a phased manner.

3.3.1 Advantages

• By migrating gradually, you can migrate parts of your model earlier, unlocking new features of the runtime architecture but still keeping others in the current runtime until functional changes are done or limitations removed.
• You can incrementally test only those static parts of your solution that you want to migrate.
• Only the part you want to migrate cannot contain functional changes.

3.3.2 Disadvantages

• You need to migrate parts of your model over a more considerable amount of time (i.e., 2-3 months), meaning that you continuously need to be aware of how to migrate from the old to the new situation.
• During the time you run on both architectures, your user experience will be dual in nature, especially in Manage. This means that part of your metrics, logging, and error messages are shown differently per runtime.
• By dragging out the migration over a long period, you risk that the migration takes such a long time that you are forced to migrate in a hurry at some point in time
• You continuously need to be aware of the order via which you need to migrate (especially surrounding the JMS migration).

4. Technical Migration Path

Below you will find a document describing the migration path to migrate a single runtime (i.e., connector or container) to the latest generation runtime. Note that this functionality is not yet generally available and can only be executed after consulting your partner manager. For the key aspects of the new generation compared to the current generation please read this fundamental.

4.1 Update Design Architecture

The first step of this migration path is to update a part of your Design Architecture. In this update step, you will define on runtime level (i.e., connector or container) whether a runtime is a generation 3 runtime or not.

Note that we have provided an extensive help text to support you in your choice of whether to migrate to Generation 3 or not. You can read the help text by pressing the information icon on the popup and selecting the Gen3 option.

4.2 Transfer Settings from Design

Now that we have indicated that a certain runtime needs to be migrated to Generation three, the next step is Create. In Create navigate to Settings -> Transfer Settings From Design -> Container. Here you will see all runtimes designed to be generation 3 in Design but are still configured as generation 2 in Create.

When you press the button "Transfer Gen3 state from Design", eMagiz will automatically migrate your environment to the latest generation and update all your flows accordingly. This means that each flow will get a new version number which we need to deploy in a later phase.

On top of that eMagiz will change the default behavior of how the error handling is done within eMagiz flows. When migrating you will have the option to select for which flows you want to keep your custom error handling.

For more information on migrating your custom error handling towards the 3rd generation runtime please see this migration path

4.3 Create a new release

After the migration is finished, eMagiz will have created new versions of all flows on the runtime you just migrated. The next step would be to include these changes in a new release so they can be deployed. After adding the new flow versions to the release, ensure the release is "set as active."

4.4 Update Deploy Architecture

4.4.1 Update Cloud Template - One Time Action

For the first runtime, you migrate to Generation 3; you need to ensure that the correct cloud template is selected on which the Generation 3 runtimes can function. This is the latest Docker template available at the moment of your migration. Note that upgrades of new cloud templates will be automated after this moment, just as you are used to within eMagiz. As an alternative, you can also execute the updates manually if needed.

To update your cloud architecture, press "Apply to Environment" in Deploy Architecture.

4.4.2 Update A Subsequent Runtime

Apart from updating the cloud template itself, you also need to update each runtime so it will run on Generation 3. To apply the changes from Design Architecture to Deploy Architecture, you need to press the button "Apply to Environment" just as you would now if you add or change a runtime in the current architecture.

4.5 Verify whether runtime started

There are two mechanisms to verify whether the runtime started up correctly. Below you can find more information on these mechanisms.

4.5.1 Verification in Deploy Architecture

The first check can be done in Deploy Architecture itself. Here you can access the context menu on the runtime level and open the Details page of the runtime.

Once you have opened the Details overview, you will see a second tab called "Status". On this tab, you can see the "Status" of the runtime and execute several commands on the runtime level when in "Start Editing" mode.

You can also define which release version is running on this runtime by looking at the last part of the image name. This part holds a reference to the release version. In this example, the release version is 7.2.1

4.5.2 Verification in Manage

On top of this verification, you can check the Log Entries in Manage to see whether your runtime successfully started up. Here you can search for the key phrase "Started eMagiz" to see which runtimes have been started (or you can filter on a specific runtime).

4.6 Update Deployment Plan

Note that the way each runtime is deployed is changed in Generation 3. This also means that your deployment plan changes as well. For example, instead of deploying on a flow-by-flow basis, we will package the whole runtime in one image and deploy that to the machine. Therefore new steps have been added to the deployment plan to deploy changes on your machine. For example, the first time you introduce a Generation 3 runtime on a machine, you need to add a Deploy Machine step to the deployment plan and remove all actions referencing the runtime you just migrated. An example of what this looks like can be seen below.

5. Key takeaways

• This migration path allows you to migrate a specific runtime to Generation 3
• All flows of the runtime are updated, so plan your migration
• The JMS needs to be migrated to Generation 3 as the last runtime of your model
• When executing the first migration of a runtime, additional steps are necessary to update your cloud configuration
• In case you want to use the new EDI functionality in messaging, both the connector and the process container need to be migrated to Generation 3