Skip to Content

Wiki source code of Drop Files

Last modified by Danniar Firdausy on 2024/08/21 16:53
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2
3 In the last microlearning, we covered how to retrieve files **from** a local directory. In this microlearning, we will learn the opposite and focus on how to deliver files **to** a local directory.
4
5 If you have any questions along the way, feel free to reach out to us at [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6
7 == 1. Prerequisites ==
8
9 * Basic knowledge of the eMagiz platform
10
11 == 2. Key concepts ==
12
13 This microlearning centers around dropping files to a local directory via eMagiz.
14 * With dropping we mean: Writing the contents of the message to a local directory to be stored as a file
15 * With local directory we mean: A directory that is directly accessible within the network where the eMagiz process is running
16
17 == 3. Drop Files ==
18
19 One of the easiest connectivity methods to implement within eMagiz is sending files to a local directory. With this method, eMagiz will write data to the local directory when data arrives on an exit queue for processing.
20 There are four key considerations you should take into account when picking up files:
21
22 * In which directory should we place the file
23 * Has eMagiz the appropriate rights to read from the directory where the messages are to be retrieved from
24 * If a file with the same name already exists what do we do
25 * How to name the file that you are writing to the directory
26
27 === 3.1 Determine the directory ===
28
29 The key aspect of delivering a message is knowing where to deliver a message to. The same applies to delivering messages as files on a local directory.
30 The external party with whom you are connecting should be able to provide you with the directory where the data should be delivered to.
31
32 The best practice is to work with a property as the directory can change between environments.
33 To ensure that a wrong directory is created by eMagiz the best practice is to **not** let eMagiz auto-create the directory.
34 The basic configuration of the file outbound channel adapter should therefore look as follows:
35
36 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-outbound-channel-adapter.png]]
37
38 === 3.2 Appropriate Rights ===
39
40 To send files to a local directory eMagiz needs to have the appropriate rights to access the directory in question.
41 If the directory in which the files are located is part of a structure of other directories you need to ensure that eMagiz
42 has sufficient rights on all directories above the directory to which you are writing data.
43
44 If this is not the case you will not be able to send data to a local directory via eMagiz.
45
46 === 3.3 What to do when a file already exists ===
47
48 In eMagiz, you can configure what eMagiz should do in case the file you are trying to write to the directory already exists.
49 The default pattern is to replace the original file with the new file ensuring that the newest information is available.
50
51 However, if there are reasons not to replace the original file with the new file considering one of the options below:
52
53 * Append. With this option, you append the new data to the original file
54 * Fail. eMagiz will throw an error when the file already exists
55 * Ignore. eMagiz will silently drop the message when the file already exists
56
57 To choose a specific mode you have to navigate to the Advanced tab and access the Mode drop-down menu.
58
59 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-mode-options.png]]
60
61 === 3.4 Name the file ===
62
63 If you do not name the file eMagiz will use the message ID with the suffix .msg. In general, you do not want that so you should specify how the file should be named.
64
65 There are two methods to do so. The first method is more static and the second one is more dynamic.
66
67 ==== 3.4.1 Format File Name Generator ====
68
69 The first option is the format file name generator. This is a support object in eMagiz
70
71 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-format-file-name-generator.png]]
72
73 This component has several tokens available that can be replaced with values. However, in some cases, some of these tokens are not filled in at all.
74
75 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-format-file-name-generator-tokens.png]]
76
77 Therefore we see that this component is mainly used to combine some static value with one of these tokens. An example of such a construction is shown below.
78
79 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-format-file-name-example.png]]
80
81 This way you control that the message has a certain extension and starts always with the same value. The only dynamic part in this example is the time that is added to the file name
82
83 ==== 3.4.2 File Name Header ====
84
85 Another option that gives you more flexibility is to define the file name header.
86 By adding a standard header enricher component to your exit you can define your file name as follows:
87
88 [[image:Main.Images.Microlearning.WebHome@crashcourse-messaging-drop-files--drop-file-file-name-header-example.png]]
89
90 Do note that the naming of the header matters. Only when you name your header file_name this solution will work. Otherwise, eMagiz will revert to the default so pay attention!
91
92 As you can see from the example we will now dynamically create the file name based on two input variables for which the values can change.
93 Whichever method you choose to create the file name does not matter as long as you have thought about it.
94 Most important thing is that you choose an option to keep control over what is happening.
95
96 == 4. Key takeaways ==
97
98 * Directory Selection: Determine the correct local directory for file delivery and ensure it aligns with the external party’s requirements.
99 * Permissions: Verify that eMagiz has the necessary permissions to write to the specified directory, including all parent directories.
100 * File Overwriting: Decide on the appropriate action when a file with the same name already exists—whether to replace, append, ignore, or fail.
101 * File Naming: Choose a method for naming files to ensure they have meaningful and consistent names. Options include using format file name generators or defining names through file name headers.
102
103 == 5. Suggested Additional Readings ==
104
105 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 link:
106
107 * [[Store (Menu)>>doc:Main.eMagiz Store.WebHome||target="blank"]]
108 ** [[Accelerators (Navigation)>>doc:Main.eMagiz Store.Accelerators.WebHome||target="blank"]]
109 *** [[File Outbound (Store Item)>>doc:Main.eMagiz Store.Accelerators.File Outbound.WebHome||target="blank"]]
110 * [[Drop Files (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=%22drop+files%22||target="blank"]]
111 )))((({{toc/}}))){{/container}}{{/container}}