Changes for page Upgrading Build Numbers

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Title

...	...	@@ -1,1 +1,1 @@
1		-novice-lifecycle-management-cleanup-a-captured-integration
	1	+Upgrading Build Numbers

Content

...	...	@@ -1,73 +1,103 @@
1	1	{{container}}
2	2	{{container layoutStyle="columns"}}
3	3	(((
4		-In this microlearning, we will learn how you can import store items from the eMagiz store in Design after finding the one for you. This microlearning aims to get you acquainted with the various options of importing a store item in the Design phase of eMagiz.
	4	+{{error}}
	5	+Note that the functionality mentioned in this microlearning will become obsolete when migrating to the 3rd generation runtime.
	6	+{{/error}}
5	5
	8	+In this microlearning, we will focus on how you can upgrade your build numbers within eMagiz consistently and easily. Knowing how to upgrade your build numbers will ensure that you will keep your eMagiz solution as up to date as possible and therefore also as stable and secure as possible.
	9	+
6	6	Should you have any questions, please get in touch with [[academy@emagiz.com>>mailto:academy@emagiz.com]].
7	7
8		-* Last update: April 5th, 2021
9		-* Required reading time: 5 minutes
10		-
11	11	== 1. Prerequisites ==
12	12
13	13	* Basic knowledge of the eMagiz platform
	15	+* Basic knowledge of the build number component within the eMagiz Platform
14	14
15	15	== 2. Key concepts ==
16	16
17		-This microlearning centers around importing store items in the Design Phase. With eMagiz Store, we mean A content library available to the community to select re-usable solutions within the eMagiz platform.
	19	+This microlearning centers around upgrading your build numbers.
18	18
19		-* To import a store item in Design, you need to follow the import wizard
20		-* When importing in Design, you can import the system message and accompanying flow fragments
	21	+By upgrading we mean: Ensuring that your eMagiz solution is running on the latest open source and eMagiz software as is possible within the confinements of the customer context
	22	+By build number we mean: An identification that the dependency to other pieces of the solution has changed. Each build number has a unique set of dependencies
21	21
22		-== 3. Importing Store Items - Design Phase ==
	24	+There are three key considerations when updating build numbers:
23	23
24		-In contrast with the Create phase store items (which provide you a set of components to achieve a particular objective), the Design Phase store items give you the additional functionality to import the system message(s). For example, to import a system message from the Store in Design, you must navigate to the system message via the context menu. When doing so for the first time, eMagiz will show you the following options after entering the "Start Editing" mode.
	26	+* Why should I upgrade my build numbers?
	27	+* How do I determine which of my flows can be updated with ease?
	28	+* How should I handle the build number upgrade?
25	25
26		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items-design--import-options-system-message.png]]
	30	+== 3. Upgrading Build Numbers ==
27	27
28		-When you select the option Store, eMagiz will show you all alternatives within the eMagiz store to which a Message Definition is linked. Note that you can search by Name and by Brand in this overview.
	32	+In this microlearning, we will focus on how you can upgrade your build numbers within eMagiz consistently and easily. Knowing how to upgrade your build numbers will ensure that you will keep your eMagiz solution as up to date as possible and therefore also as stable and secure as possible. Within this section of the microlearning we will take a look at the three key consideration when updating build numbers:
29	29
30		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items-design--store-overview-design.png]]
	34	+* Why should I upgrade my build numbers?
	35	+* How do I determine which of my flows can be updated with ease?
	36	+* How should I handle the build number upgrade?
31	31
32		-Once you have found the item of your liking, you can select it by clicking on it. This action will lead you to the details page associated with the store item. Here you will find the relevant information related to this store item. On top of that, we provide you with a Versions & Variants tab that shows you all existing versions you could import.
	38	+=== 3.1 Why should I upgrade my build numbers? ===
33	33
34		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items-design--information-store-item-after-selection.png]]
	40	+Build numbers govern all dependencies to other open-source software and govern the ability to use new functionality on flow level within the portal. Therefore by consistently upgrading your build numbers, you ensure that you keep up to date with all the dependencies. This not only prevents surprises when you did not migrate for a long time but also ensures that you are working on the most secure piece of software that is available. Furthermore, by upgrading your build numbers you will unlock the use of new functionality on flow level and you will prevent that you will run into problems because we have stopped supporting certain build numbers.
35	35
36		-In cases where you want the latest version use the button titled "Use latest version" on the Information tab. Once you have selected a version, eMagiz will show the following step of the process. Here you can choose whether you want to import the message definition(s), and it will ask you whether you wish to select accompanying flow fragments which are of use later on in Create. Since it is a GET operation, we only have a response definition to import. On top of that, we have two flow fragments. One that handles the authentication and one that holds the logic of the store item.
	42	+All in all enough reasons to keep a regular pace to upgrade your build numbers.
37	37
38		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items-design--making-choices-on-the-store-item.png]]
	44	+=== 3.2 How do I determine which of my flows can be updated with ease? ===
39	39
40		-It is up to you what you exactly want to import. Maybe only the definition is enough for you, or perhaps you want the whole package. So here you have the choice to do so. Once you are satisfied with your selection, press "Use message(s)." This will start the import process. As a result, eMagiz will import the model on the canvas and define the system message(s) in the right panel.
	46	+The first trigger will be in the release notes in eMagiz [[Buildnumber release notes>>doc:Main.Release Information.Build numbers.WebHome||target="blank"]] and the release blog that is written with every release. Here you can read why a new build number is introduced. Is it because of new functionality, did we update some of the underlying (open source) software or a combination of multiple factors? By reading the release notes you can also easily determine what the possible impact is on your eMagiz solution. For example, if the only change in build number is that a specific component is added or changed and you do not use that (or only limited) the impact is also limited.
41	41
42		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items-design--import-result-in-design.png]]
	48	+As you can already imagine, this judgment call becomes much tougher when you are 10 versions behind compared to when you are 1 or 2 versions behind. Simply because there is less of a gap to identify and analyze. So keep your eye on the release notes and release blog.
43	43
44		-Now you should create the mapping from your data model to the system message(s) yourself, and when you are finished, you can transfer the solution to Create just as you are used to doing.
	50	+Now that you know that there is a new build number and what is exactly changed you can start comparing your current release state to the desired release state (i.e. all flows on the latest build number). You can do this with relative ease with the help of the compare functionality in Deploy -> Releases. As the help infographic on this page tells us you can determine what is changed with the help of how eMagiz color codes the various flows:
45	45
46		-=== 3.1 Importing Design Store Item - Effect in Create ===
	52	+[[image:Main.Images.Microlearning.WebHome@novice-lifecycle-management-upgrading-build-numbers--release-compare-legend.png]]
47	47
48		-Once you have transferred the solution to the Create phase and open the relevant flow for which you have imported the store item, you will see a "Pending configuration" button on the bottom of your canvas.
	54	+As you can see, when a flow indicates a blue dotted line it means the only change between your Create flow and the flow within your release is the build number. These flows are excellent candidates to upgrade as there are no functional changes to consider.
49	49
50		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items--pending-configuration.png]]
	56	+[[image:Main.Images.Microlearning.WebHome@novice-lifecycle-management-upgrading-build-numbers--release-comparison.png]]
51	51
52		-After pressing this button, you will see a pop-up showing all flow fragments to import. You can select each flow fragment separately by pressing the Setup button. Note that if you want to configure this at a later moment, you can choose the option "Do this later" and come back later to finish the job. On top of that, you can press Cancel if you change your mind and don't want to import the flow fragments.
	58	+Note that when you are dealing with a functional change in a flow you should consider what the impact would be if you upgrade the flow to the latest build number. Simply because upgrading to the latest build number automatically means upgrading to the latest flow version (regardless of whether functional changes have occurred). If the flow is still in development and not part of a Production (or Acceptance) release there is nothing to worry about as you will use the latest flow version anyway to test your functionality and move it to Production (or Acceptance) at a later stage.
53	53
54		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items--importing-flow-fragments.png]]
	60	+However, when a functional change has occurred and the older flow is running on Production (or Acceptance) you should make a deliberate choice whether or not to move that flow to the latest build number. Once again the decision will become far more complicated when you are a lot of build numbers behind as that might mean that other flows on the same runtime are also not eligible to be upgraded. So once again keep your build numbers updated.
55	55
56		-When pressing this, eMagiz will show you the import wizard. This configuration wizard finishes the import process.
	62	+When you can upgrade all flow versions to the latest version eMagiz provides you with a button that will automatically do this for you. This prevents you from clicking through the release several hundred times. If you access the context menu of your release you will see the option called Update flows to the latest version. Pressing this button will automatically upgrade all flows that are part of the release to the latest version.
57	57
58		-[[image:Main.Images.Microlearning.WebHome@novice-emagiz-store-importing-store-items--configuration-wizard.png]]
	64	+[[image:Main.Images.Microlearning.WebHome@novice-lifecycle-management-upgrading-build-numbers--update-flows-to-latest-version.png]]
59	59
60		-For all the details on this wizard, please check out the following [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Novice Level.eMagiz Store.novice-emagiz-store-configuring-store-items.WebHome||target="blank"]].
	66	+After you are satisfied with how the release looks you should make it active via the option called Set Release as Active.
61	61
	68	+[[image:Main.Images.Microlearning.WebHome@novice-lifecycle-management-upgrading-build-numbers--release-comparison-after-update.png]]
	69	+
	70	+=== 3.3 How should I handle the build number upgrade? ===
	71	+
	72	+The reason why you should set your release as Active instead of deploying instantaneously is two-fold:
	73	+
	74	+* As this will impact the complete environment you should communicate and plan a correct date and time to execute the upgrade
	75	+* Using the deploy functionality to upgrade your complete project is not considered best practice
	76	+
	77	+Now that you have made the release active you can upgrade your complete project in the following way:
	78	+
	79	+* Stop all entries to ensure that no data is flowing to your project in the midst of upgrading your complete project
	80	+* Ensure that you have disabled all alerting
	81	+* Upgrade the JMS by installing the new deployment package and starting the new flow.
	82	+* Ensure that all other runtimes get stopped, data folder removed (excluding the h2 part), and get started again
	83	+
	84	+By using that logic eMagiz will forget which flows were running on the runtime and the start-up will ask the portal which flows should run. Because you have made the new release active this means that automatically the new and correct flows will be installed and started by eMagiz.
	85	+
	86	+Note that for cloud runtimes you can combine this with a cloud template upgrade or by using the Reset functionality offered by eMagiz in Deploy -> Architecture. Note that for on-premise runtimes you will have to do these steps manually.
	87	+
	88	+When you are finished with all runtimes navigate back to the Releases overview in Deploy and press the Deploy icon to activate your deployment plan. This is a great way to ensure that you did not accidentally miss one or more flows and will automatically ensure that the eMagiz alerting is activated again (assuming you make use of the best practices of eMagiz).
	89	+
62	62	== 4. Assignment ==
63	63
64		-Import a Store item in Design to import the system message(s) and subsequently transfer it to Create to see how to import the pending configurations. This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
	92	+Read up on the release notes of the build numbers and determine for the projects in which you operate what the status is of your eMagiz solution on the eMagiz platform.
65	65
66	66	== 5. Key takeaways ==
67	67
68		-* To import a store item in Design, you need to follow the import wizard
69		-* When importing in Design, you can import the system message and accompanying flow fragments
70		-* After importing the system message in Design, you can configure the flow fragments in Create with the help of the button called "Pending configurations."
	96	+* Make your life easier by keeping up to date with regards to the build numbers that eMagiz releases
	97	+* Determine the impact of the build number upgrade based on the release notes and the comparison functionality
	98	+* Communicate before executing the upgrade
	99	+* Ensure that data traffic is limited (or even better halted) during the upgrade
	100	+* Verify your work by running the deployment plan
71	71
72	72	== 6. Suggested Additional Readings ==
73	73
...	...	@@ -75,7 +75,7 @@
75	75
76	76	== 7. Silent demonstration video ==
77	77
78		-{{video attachment="novice-emagiz-store-importing-store-items-design.mp4" reference="Main.Videos.Microlearning.WebHome"/}})))
	108	+As this is a more theoretical microlearning we have no video for this)))
79	79
80	80	((({{toc/}}))){{/container}}
81	81	{{/container}}