Skip to Content
Last modified by Danniar Firdausy on 2024/09/18 14:37
From version 2.1
edited by Erik Bakker
on 2022/06/10 08:38
Change comment: Imported from XAR
To version 11.6
edited by Danniar Firdausy
on 2024/09/18 14:37
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Making clear what you changed (auditability)
Parent
... ... @@ -1,0 +1,1 @@
1 +WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ebakker
1 +XWiki.dfirdausy
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,13 +1,8 @@
1 1  {{container}}{{container layoutStyle="columns"}}(((
2 -= Making clear what you changed (auditability) =
2 +In the world of software tooling, it's crucial to understand what changes have been made to effectively evaluate their impact. This microlearning will guide you through the process of clarifying changes within the eMagiz platform, focusing on the importance of clear and detailed descriptions for auditability. By the end of this microlearning, you will know how to properly document and version your changes to maintain a clear history and facilitate better integration management.
3 3  
4 -As you can imagine, there is a need to know what has changed when working with software tooling. By knowing you can assess the impact of your planned changes within the context of the integration data model. In this microlearning, we will look at what you can do to clarify what you changed within the eMagiz platform.
5 -
6 6  Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
7 7  
8 -* Last update: August 4th, 2021
9 -* Required reading time: 6 minutes
10 -
11 11  == 1. Prerequisites ==
12 12  
13 13  * Basic knowledge of the eMagiz platform
... ... @@ -15,28 +15,18 @@
15 15  == 2. Key concepts ==
16 16  
17 17  This microlearning centers on making clear what you changed (auditability).
13 +* By auditability, we mean: A history trail that depicts who changed what at which moment in time containing an explanation of what has been changed
18 18  
19 -Auditability is defined as follows: A history trail that depicts who changed what at which moment in time containing an explanation of what has been changed
20 -
21 -* The key aspects are:
22 - * The description is your way of communicating the history of the flow
23 - * Using vague descriptions (or placing a dot as description) hurts the auditability
24 - * For all things versioned in eMagiz it is crucial that you supply the correct description
25 - * eMagiz provides audit trails on Architectural overviews (Design and Deploy architecture) including a description
26 - * eMagiz provides audit trails on message definitions and transformations including a description
27 -
28 -
29 -
30 30  == 3. Making clear what you changed (auditability) ==
31 31  
32 32  As you can imagine, there is a need to know what has changed when working with software tooling. By knowing you can assess the impact of your planned changes within the context of the integration data model. In this microlearning, we will look at what you can do to clarify what you changed within the eMagiz platform.
33 33  
34 34  * The key aspects are:
35 - * The description is your way of communicating the history of the flow
36 - * Using vague descriptions (or placing a dot as description) hurts the auditability
37 - * For all things versioned in eMagiz it is crucial that you supply the correct description
38 - * eMagiz provides audit trails on Architectural overviews (Design and Deploy architecture) including a description
39 - * eMagiz provides audit trails on message definitions and transformations including a description
20 + ** The description is your way of communicating the history of the flow
21 + ** Using vague descriptions (or placing a dot as description) hurts the auditability
22 + ** For all things versioned in eMagiz it is crucial that you supply the correct description
23 + ** eMagiz provides audit trails on Architectural overviews (Design and Deploy architecture) including a description
24 + ** eMagiz provides audit trails on message definitions and transformations including a description
40 40  
41 41  === 3.1 Versioning by users ===
42 42  
... ... @@ -48,15 +48,15 @@
48 48  
49 49  ==== 3.1.1 eMagiz Data Model ====
50 50  
51 -On the eMagiz data model level in Design, you can version your eMagiz Data model. By doing this you can register per the eMagiz data model what you have changed. If you want practical help in learning how you can version your eMagiz data model please check out this [microlearning](intermediate-defining-your-message-structures-audit-emagiz-data-models.md). Doing so is crucial in telling others now (and in the future) what you have changed and why you have changed that portion of the eMagiz data model.
36 +On the eMagiz data model level in Design, you can version your eMagiz Data model. By doing this you can register per the eMagiz data model what you have changed. If you want practical help in learning how you can version your eMagiz data model please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Defining message structures.intermediate-defining-your-message-structures-audit-emagiz-data-models||target="blank"]]. Doing so is crucial in telling others now (and in the future) what you have changed and why you have changed that portion of the eMagiz data model.
52 52  
53 53  ==== 3.1.2 eMagiz Flows ====
54 54  
55 -On the eMagiz flow level in Create, you need to create a new flow version when you are satisfied with your changes (if any are needed). Note that eMagiz allows the ability to use temporary versions while developing. When using these do note that you need to create a definitive version at some point to prevent confusion now (and in the future). If you want practical help in learning how you can version your eMagiz flows please check out this [microlearning](crashcourse-platform-create-promote-flows-to-deploy.md). On the flow level, it must become clear to anyone what you have changed. That will determine whether a certain flow version is ready to be released much easier.
40 +On the eMagiz flow level in Create, you need to create a new flow version when you are satisfied with your changes (if any are needed). Note that eMagiz allows the ability to use temporary versions while developing. When using these do note that you need to create a definitive version at some point to prevent confusion now (and in the future). If you want practical help in learning how you can version your eMagiz flows please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-create-promote-flows-to-deploy||target="blank"]]. On the flow level, it must become clear to anyone what you have changed. That will determine whether a certain flow version is ready to be released much easier.
56 56  
57 57  ==== 3.1.3 eMagiz Releases ====
58 58  
59 -On the eMagiz release level, you need to create a new version whenever you want to include new versions of flows in a release. There is one exception to this rule and that is when someone else has already created a new release that is not yet deployed or made active. In that scenario, you can both combine all changes that need to de deployed to create a more efficient deployment. With eMagiz releases, you have two ways of notifying others what the release is all about. The first one is the name of the release and the second one is the description of a release. If you want to learn how to create a release please check out this [microlearning](crashcourse-platform-deploy-create-new-release.md). If you want to learn more about managing releases please check out this [microlearning](intermediate-release-management-managing-releases-best-practice.md)
44 +On the eMagiz release level, you need to create a new version whenever you want to include new versions of flows in a release. There is one exception to this rule and that is when someone else has already created a new release that is not yet deployed or made active. In that scenario, you can both combine all changes that need to de deployed to create a more efficient deployment. With eMagiz releases, you have two ways of notifying others what the release is all about. The first one is the name of the release and the second one is the description of a release. If you want to learn how to create a release please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-deploy-create-new-release||target="blank"]]. If you want to learn more about managing releases please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Release Management.intermediate-release-management-autoclean-releases||target="blank"]].
60 60  
61 61  === 3.2 Versioning by eMagiz ===
62 62  
... ... @@ -67,29 +67,25 @@
67 67  
68 68  In all cases, you will find a History button on the page in question that will guide you to the history (audit trail) of what has changed by whom at which point in time.
69 69  
55 +== 4. Key takeaways ==
70 70  
57 +* Ensure that all descriptions are detailed and specific to effectively communicate the history of changes.
58 +* For all versioned elements within the eMagiz platform, including data models, flows, and releases, providing precise descriptions helps in tracking modifications and understanding their impact.
59 +* Utilize the audit trails provided by eMagiz for Architectural overviews, message definitions, and transformations to keep a comprehensive history of changes. This feature is vital for maintaining transparency and accountability in your integration processes.
60 +* By maintaining clear and accurate documentation of changes, you improve the ability to assess impacts and manage integration data models more effectively, ensuring smoother operations and fewer misunderstandings.
71 71  
72 -== 4. Assignment ==
62 +== 5. Suggested Additional Readings ==
73 73  
74 -Check out the history of (one of) your eMagiz data models, one of your flows, and your releases to see if you can determine how they have changed over time.
64 +If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following links:
75 75  
76 -== 5. Key takeaways ==
77 -
78 -* The key aspects are:
79 - * The description is your way of communicating the history of the flow
80 - * Using vague descriptions (or placing a dot as description) hurts the auditability
81 - * For all things versioned in eMagiz it is crucial that you supply the correct description
82 - * eMagiz provides audit trails on Architectural overviews (Design and Deploy architecture) including a description
83 - * eMagiz provides audit trails on message definitions and transformations including a description
84 -
85 -
86 -
87 -== 6. Suggested Additional Readings ==
88 -
89 -If you are interested in this topic and want more information please check out the help texts provided by eMagiz.
90 -
91 -== 7. Silent demonstration video ==
92 -
93 -As this is a more theoretical microlearning we have no video for this.
94 -
66 +* [[Crash Courses (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-design-defining-a-message-format||target="blank"]]
67 +** [[Crash Course Platform (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.WebHome||target="blank"]]
68 +*** [[Promote flows to deploy (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-create-promote-flows-to-deploy||target="blank"]]
69 +*** [[Creating a new Release (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-deploy-create-new-release||target="blank"]]
70 +* [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]
71 +** [[Defining message structures (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Defining message structures.WebHome||target="blank"]]
72 +*** [[Audit eMagiz Data Models (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Defining message structures.intermediate-defining-your-message-structures-audit-emagiz-data-models||target="blank"]]
73 +** [[Release Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Release Management.WebHome||target="blank"]]
74 +*** [[Autoclean releases (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Release Management.intermediate-release-management-autoclean-releases||target="blank"]]
75 +* [[Making clear what you changed (Search Results)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22making+clear+what+you+changed%22||target="blank"]]
95 95  )))((({{toc/}}))){{/container}}{{/container}}