Wiki source code of Hosting a REST web service

Last modified by Carlijn Kokkeler on 2023/11/03 15:22
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 {{warning}}
3 Please note that this migration path is for the new monitoring stack only.
4 {{/warning}}
5
6 Below you will find a document describing the migration path to migrate your hosted REST web service on the runtime level to the latest generation runtime. For the critical aspects of the new generation compared to the current generation, please read this [[fundamental>>doc:Main.eMagiz Academy.Fundamentals.fundamental-runtime-generation3||target="blank"]].
7
8 Should you have any questions, please get in touch with academy@emagiz.com.
9
10 == 1. Prerequisites ==
11
12 * Advanced knowledge of the eMagiz platform
13 * A thorough understanding of your eMagiz model
14
15 == 2. Key concepts ==
16
17 * This migration path allows you to maintain your hosted REST web service in the 3rd generation runtime
18 * Consequences of this migration are:
19 ** Your all-entry will be split up into separate entries
20 ** HTTP Settings now need to be configured under Deploy -> Architecture
21
22 == 3. Technical Migration Path ==
23
24 As part of the "Transfer Settings from Design" step in the general migration path on migrating to the 3rd generation runtime, you will see an additional option displayed below this option called "Split Combined Entries." After you have migrated your REST web service to the 3rd generation runtime, you will need to split the all-entry directly after the migration is finished.
25
26 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--transfer-settings-from-design-split-combined-entries-rest.png]]
27
28 As a result of this step, all shared resources, such as the security, will be moved to the infra flow, and the all-entry will be split into separate entries. Once this is done, you, as a user, need to execute several steps per entry before deploying your solution to any environment.
29
30 === 3.1. Clean up the entries ===
31
32 The starting point of our solution, which we are going to migrate, is the following REST web service that has two integrations linked to it.
33
34 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--starting-point-migration-rest-web-service-gen-3.png]]
35
36 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--all-entry-config-rest-web-service-before-migration.png]]
37
38 After eMagiz notifies you that the split of the all-entry was successful, you need to execute some manual actions before adding the new flows to your release. The majority of the manual changes should be performed in each split entry. After migration, each entry will contain all functional components present in the all-entry, as we cannot determine which functional components are needed to handle a specific operation. So for each entry, you need to remove all functional components irrelevant to the operation related to the entry you are currently editing. If you do not do this, the all entry is still in the release.
39
40 When opening one of the entries after migration, it looks as follows.
41
42 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--rest-entry-config-directly-after-migration.png]]
43
44 To remove all components that are not relevant anymore in this entry, please enter "Start editing" mode. In this mode, you can remove all irrelevant components from this entry. In this example, all components have something to do with the alpha operation. The result will be something like this.
45
46 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--rest-entry-config-after-removing-the-irrelevant-components.png]]
47
48 {{warning}}Note that you must repeat the above steps per entry created by the split action. For each entry, the irrelevant components need to be removed (which components are irrelevant is different per entry).{{/warning}}
49
50 {{warning}}Please note that the Jetty component remains in every flow that is split. Main reason is that the servlet setting in that Jetty support object is required for the update of the resource path in the inbound gateway component. The resource path is now fully and only configured in that inbound gateway component. Once the resource path is updated, please remove the Jetty support object.{{/warning}}
51
52 === 3.3 Alter the infra flow ===
53
54 To ensure that the HTTP security in the new 3rd generation runtime works as before you need to add a support object of the type "HTTP Security". In this "HTTP Security" support object you only need to define "Disabled" in the Security drop-down.
55
56 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--add-http-security-rest-generation-three.png]]
57
58 === 3.4 Add the split entries to a release ===
59
60 Now that we are finished in Create, it becomes time to deploy our changes to the Test environment. To add the new flows, particularly the new entries, to your release, you must execute the following steps.
61
62 * Create a new release
63 * Access the context menu and press "Details."
64 * In the pop-up that follows search for the infra flow of the runtime you are migrating
65 * Select the latest infra flow of the runtime you are migrating
66 ** As a result, eMagiz will automatically add the split entries to your release and will update the Release overview accordingly
67
68 After successfully completing this, the release overview should display the migrated runtime as follows.
69
70 {{warning}}Note that pressing the "Update flows to latest version" will not work in this scenario and the steps described above need to be executed to the letter.{{/warning}}
71
72 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--release-overview-splitted-entry-rest-web-service.png]]
73
74 === 3.5 Check the Runtime Settings ===
75
76 One last step of the migration is to check the runtime settings of the runtime you are migrating under Deploy -> Architecture. This new functionality allows you to define the port on which the REST web service needs to be running (and optionally SSL settings when running it on-premise). You can access these settings via the context menu on the runtime level.
77
78 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-context-menu.png]]
79
80 Once you have selected this option, a pop-up will appear, showing you, among others, the HTTP settings. The HTTP enabled option needs to be enabled for a REST web service, and when we look at the advanced tab, we need a reference to the port we will use here (which can be a property reference).
81
82 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-default.png]]
83
84 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--http-settings-default-config-rest.png]]
85
86 {{info}}If you want to learn more about the runtime settings options in general please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Runtime Management.intermediate-emagiz-runtime-management-runtime-settings.WebHome||target="blank"]]{{/info}}
87
88 === 3.6 Check your route settings ===
89
90 {{warning}}This step is only relevant when running your solution on-premise{{/warning}}
91
92 For cloud hosted endpoints you are already used to defining a route configuration for your endpoints. With the 3rd generation runtime you also need to do this for your on-premise hosted endpoints. When configuring the route you need to take the following into account:
93
94 * The port configured under the route must match the port defined under the Runtime settings configuration
95 * The DNS left-most label has no effect and can be filled with anything
96 * Make sure to link the correct container to your route
97
98 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--route-config-on-prem.png]]
99
100 === 3.7 Deploy the migrated REST web service to an environment ===
101
102 To deploy this new configuration to your environment, you need to execute step 4.4.2 (Update a subsequent runtime) of the default [[migration path>>doc:Main.eMagiz Support.Migration Paths.migration-path-emagiz-runtime-generation-3||target="blank"]] (or step 4.4.1 should this be your first 3rd generation runtime).
103
104 == 4. Key takeaways ==
105
106 * This migration path allows you to maintain your hosted REST web service in the 3rd generation runtime
107 * Consequences of this migration are:
108 ** Your all-entry will be split up into separate entries
109 ** HTTP Settings now need to be configured under Deploy -> Architecture
110
111 )))((({{toc/}}))){{/container}}{{/container}}