Skip to Content
Version 10.1 by eMagiz on 2022/05/10 11:16
Show last authors
1 {{html wiki="true"}}
2 <div class="ez-academy">
3 <div class="ez-academy_body">
4
5 <div class="doc">
6
7
8
9 = Pick up Files =
10
11 In this microlearning, we will explain the basics of retrieving files from a local directory (i.e. a directory that is directly accessible within the network where the eMagiz process is running)
12
13 Should you have any questions, please contact academy@emagiz.com.
14
15 * Last update: February 25th, 2021
16 * Required reading time: 8 minutes
17
18 == 1. Prerequisites ==
19
20 * Basic knowledge of the eMagiz platform
21
22 == 2. Key concepts ==
23
24 This microlearning centers around retrieving files from a local directory via eMagiz.
25 By retrieving we mean: Checking with a certain interval if new files are ready to be pulled from the directory by emagiz
26 By local directory we mean: A directory that is directly accessible within the network where the eMagiz process is running
27
28 Key considerations when picking up files are:
29
30 * What are the determining criteria to define when a file is "ready" to be picked up (age, pattern, size, etc.)
31 * With what frequency is eMagiz going to check for new files
32 * Has eMagiz the appropriate rights to read from the directory where the messages are to be retrieved from
33 * What is the format (i.e. XML, JSON, EDI, TXT, CSV, etc.) of the files that eMagiz needs to retrieve
34
35
36
37 == 3. Pick up Files ==
38
39 One of the easiest connectivity methods to implement within eMagiz is the retrieval of files from a local directory.
40 With this method, eMagiz will periodically look whether (new) files are ready for consumption. There are four key considerations you should take into account when picking up files:
41
42 * What are the determining criteria to define when a file is "ready" to be picked up (age, pattern, size, etc.)
43 * With what frequency is eMagiz going to check for new files
44 * Has eMagiz the appropriate rights to read from the directory where the messages are to be retrieved from
45 * What is the format (i.e. XML, JSON, EDI, TXT, CSV, etc.) of the files that eMagiz needs to retrieve
46
47 === 3.1 Determining Criteria ===
48
49 By default, eMagiz has a filter that will only accept each file once. This option is called prevent duplicates
50
51 <p align="center">[[image:crashcourse-messaging-pick-up-files--prevent-duplicates.png||]]</p>
52
53 As the eMagiz help text clearly states this option will ensure that eMagiz will keep a list in memory and files are only to be passed once.
54 This check is done before any other filtering is done. So be aware when mixing these settings.
55
56 For example, if you combine this setting with an age list filter (i.e. specifying how old a message must be before picking it up) but you pick up messages
57 at a higher frequency compared to the setting of your age list filter you run the risk of never picking the message up as the message
58 will be blocked by the age list filter the first time and the second time by the prevent duplicates setting
59
60 Another downside of only using the prevent duplicates option is that when you do not delete messages properly and you do restart the flow eMagiz will start picking up those messages again.
61
62 So, as you can see determining the proper set of criteria can be quite challenging.
63 Luckily there is a store component available in the public eMagiz Store that is build based on a set of best practices including the best practice when it comes to filtering.
64
65 To filter which messages need to be retrieved from a local directory we use a composite file list filter.
66
67 <p align="center">[[image:crashcourse-messaging-pick-up-files--composite-file-list-filter-component.png||]]</p>
68
69 In this filter, we use the following four criteria to filter our messages:
70
71 * Regular files only
72 * Size list filter (minimum 1 bytes, maximum 1048575)
73 * Age file list filter (minimum 10000)
74 * Simple pattern file list filter (${file.pickup.pattern})
75
76 The result of this configuration should be:
77
78 <p align="center">[[image:crashcourse-messaging-pick-up-files--composite-file-list-filter.png||]]</p>
79
80 The next step would be to link this support object to the file inbound channel adapter (the starting point of our flow). To do so open the component and navigate to the Advanced tab.
81 Here you need to select the correct filter to reference your support object.
82
83 <p align="center">[[image:crashcourse-messaging-pick-up-files--composite-file-list-filter-linked.png||]]</p>
84
85 === 3.2 Frequency ===
86
87 Now that we have established the criteria that govern which messages can and which messages cannot pass the next thing
88 we need to consider is with what frequency we are going to let eMagiz check for new files.
89
90 There are three options from which you can choose:
91
92 * Fixed Delay
93 * Fixed-Rate
94 * Cron Trigger
95
96 <p align="center">[[image:crashcourse-messaging-pick-up-files--frequency-options.png||]]</p>
97
98 Both the Fixed Delay and the Fixed Rate are static. This means that when you want to change the frequency with which you look you will have to make a new version of the flow.
99
100 The cron trigger can be filled in with the help of a property and can therefore be changed over time without having to change the flow itself.
101
102 The best practice is to use the cron trigger in cases where you already expect that the frequency will change over time. If a static value is sufficient the Fixed Delay would be your best option.
103 The main benefit of the fixed delay above the fixed rate is that it waits before the previous process was finished.
104 That way you ensure that eMagiz will have to process a huge amount of data in a small amount of time.
105
106 === 3.3 Appropriate Rights ===
107
108 To retrieve files from a local directory eMagiz needs to have the appropriate rights to access the directory in question.
109 If the directory in which the files are located is part of a structure of other directories you need to ensure that eMagiz
110 has sufficient rights on all directories above the directory from which you want to retrieve files.
111
112 If this is not the case you will not be able to retrieve the files from a local directory via eMagiz.
113
114 === 3.4 Message Format ===
115
116 Files come in many different forms, shapes, and sizes. Due to the wide variety of options, you will need to ensure that the data is processed correctly.
117 How to process each message format (i.e. XML, JSON, EDI, CSV, etc.) correctly is explained in other microlearnings where we zoom in on each of the message formats.
118
119 For learning about picking up files we need to know that in other for eMagiz to
120 process the content of the file in the onramp and further downstream the contents of the file need to be transformed to string.
121
122 There is a component in eMagiz called the file to string transformer. You should place this directly after receiving the file from the external source
123
124 <p align="center">[[image:crashcourse-messaging-pick-up-files--file-to-string-component.png||]]</p>
125
126 Configuration wise you need to select the option Delete files to ensure that the files are deleted
127
128 <p align="center">[[image:crashcourse-messaging-pick-up-files--file-to-string-configuration.png||]]</p>
129
130 The result of linking the components together will lead to the following solution
131
132 <p align="center">[[image:crashcourse-messaging-pick-up-files--simple-solution.png||]]</p>
133
134 With all this in mind, you have successfully learned how to set up your first connectivity via a messaging flow in eMagiz!
135
136 ===== Practice =====
137
138 == 4. Assignment ==
139
140 Build an entry that retrieves files from an external source and ensures that the data is delivered on the onramp queue.
141 This assignment can be completed with the help of your (Academy) project you have created/used in the previous assignment.
142
143 == 5. Key takeaways ==
144
145 * Key considerations when picking up files are:
146 * What are the determining criteria to define when a file is "ready" to be picked up (age, pattern, size, etc.)
147 * With what frequency is eMagiz going to check for new files
148 * Has eMagiz the appropriate rights to read from the directory where the messages are to be retrieved from
149 * What is the format (i.e. XML, JSON, EDI, TXT, CSV, etc.) of the files that eMagiz needs to retrieve
150
151
152
153 == 6. Suggested Additional Readings ==
154
155 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
156
157 == 7. Silent demonstration video ==
158
159 This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned.
160
161 <iframe width="1280" height="720" src="../../vid/microlearning/crashcourse-messaging-pick-up-files.mp4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
162
163 </div>
164 </div>
165 </div>
166
167 {{/html}}