LP#1739803 Webstaff: Replace Grunt with Webpack
[working/Evergreen.git] / docs / installation / edi_setup.adoc
1 Setting Up EDI Acquisitions
2 ---------------------------
3
4 Introduction
5 ~~~~~~~~~~~~
6
7 Electronic Data Interchange (EDI) is used to exchange information between 
8 participating vendors and Evergreen. This chapter contains technical 
9 information for installation and configuration of the components necessary 
10 to run EDI Acquisitions for Evergreen.
11
12 Installation
13 ~~~~~~~~~~~~
14
15 Install EDI Translator
16 ^^^^^^^^^^^^^^^^^^^^^^
17
18 The EDI Translator is used to convert data into EDI format. It runs
19 on localhost and listens on port 9191 by default. This is controlled via 
20 the edi_webrick.cnf file located in the edi_translator directory. It should
21 not be necessary to edit this configuration if you install EDI Translator 
22 on the same server used for running Action/Triggers events.
23
24 [NOTE]
25 If you are running Evergreen with a multi-server configuration, make sure
26 to install EDI Translator on the same server used for Action/Trigger event
27 generation.
28
29 .Steps for Installing
30
31 1. As the *opensrf* user, copy the EDI Translator code found in 
32    Open-ILS/src/edi_translator to somewhere accessible 
33    (for example, /openils/var/edi):
34 +
35 [source, bash]
36 --------------------------------------------------
37 cp -r Open-ILS/src/edi_translator /openils/var/edi
38 --------------------------------------------------
39 2. Navigate to where you have saved the code to begin next step:
40 +
41 [source, bash]
42 -------------------
43 cd /openils/var/edi
44 -------------------
45 3. Next, as the *root* user (or a user with sudo rights), install the 
46    dependencies, via "install.sh". This will perform some apt-get routines 
47    to install the code needed for the EDI translator to function. 
48    (Note: subversion must be installed first)
49 +
50 [source, bash]
51 -----------
52 ./install.sh
53 -----------
54 4. Now, we're ready to start "edi_webrick.bash" which is the script that calls 
55    the "Ruby" code to translate EDI. This script needs to be started in 
56    order for EDI to function so please take appropriate measures to ensure this 
57    starts following reboots/upgrades/etc. As the *opensrf* user:
58 +
59 [source, bash]
60 -----------------
61 ./edi_webrick.bash
62 -----------------
63 5. You can check to see if EDI translator is running.
64    * Using the command "ps aux | grep edi" should show you something similar 
65      if the script is running properly:
66 +
67 [source, bash]
68 ------------------------------------------------------------------------------------------
69 root    30349  0.8  0.1  52620 10824 pts/0      S       13:04   0:00 ruby ./edi_webrick.rb
70 ------------------------------------------------------------------------------------------
71    * To shutdown EDI Translator you can use something like pkill (assuming 
72      no other ruby processes are running on that server):
73 +
74 [source, bash]
75 -----------------------
76 kill -INT $(pgrep ruby)
77 -----------------------
78
79 Install EDI Scripts
80 ^^^^^^^^^^^^^^^^^^^
81
82 The EDI scripts are "edi_pusher.pl" and "edi_fetcher.pl" and are used to
83 "push" and "fetch" EDI messages for configured EDI accounts.
84
85 1. As the *opensrf* user, copy edi_pusher.pl and edi_fetcher.pl from
86    Open-ILS/src/support-scripts into /openils/bin:
87 +
88 [source, bash]
89 --------------------------------------------------
90 cp Open-ILS/src/support-scripts/edi_pusher.pl /openils/bin
91 cp Open-ILS/src/support-scripts/edi_fetcher.pl /openils/bin
92 --------------------------------------------------
93 2. Setup the edi_pusher.pl and edi_fetcher.pl scripts to run as cron jobs
94    in order to regularly push and receive EDI messages.
95    * Add to the opensrf user's crontab the following entries:
96 +
97 [source, bash]
98 -----------------------------------------------------------------------
99 10 * * * * cd /openils/bin && /usr/bin/perl ./edi_pusher.pl > /dev/null
100 0 1 * * * cd /openils/bin && /usr/bin/perl ./edi_fetcher.pl > /dev/null
101 -----------------------------------------------------------------------
102    * The example for edi_pusher.pl sets the script to run at 
103      10 minutes past the hour, every hour.
104    * The example for edi_fetcher.pl sets the script to run at
105      1 AM every night.
106
107 [NOTE]
108 You may choose to run the EDI scripts more or less frequently based on the 
109 necessary response times from your vendors.
110
111 Configuration
112 ~~~~~~~~~~~~~
113
114 Configuring Providers
115 ^^^^^^^^^^^^^^^^^^^^^
116
117 Look in Administration -> Acquisitions Administration ->  Providers
118
119 [options="header"]
120 |======================================================================================
121 |Column              |Description/Notes
122 |Provider Name       |A unique name to identify the provider
123 |Code                |A unique code to identify the provider
124 |Owner               |The org unit who will "own" the provider.
125 |Currency            |The currency format the provider accepts
126 |Active              |Whether or not the Provider is "active" for use
127 |Default Claim Policy|??
128 |EDI Default         |The default "EDI Account" to use (see EDI Accounts Configuration)
129 |Email               |The email address for the provider
130 |Fax Phone           |A fax number for the provider
131 |Holdings Tag        |The holdings tag to be utilized (usually 852, for Evergreen)
132 |Phone               |A phone number for the provider
133 |Prepayment Required |Whether or not prepayment is required
134 |SAN                 |The vendor provided, org unit specific SAN code
135 |URL                 |The vendor website
136 |======================================================================================
137
138 Configuring EDI Accounts
139 ^^^^^^^^^^^^^^^^^^^^^^^^
140
141 Look in Administration -> Acquisitions Administration ->  EDI Accounts
142
143 [options="header"]
144 |===============================================================================================================
145 |Column               |Description/Notes
146 |Label                |A unique name to identify the provider
147 |Host                 |FTP/SFTP/SSH hostname - vendor assigned
148 |Username             |FTP/SFTP/SSH username - vendor assigned
149 |Password             |FTP/SFTP/SSH password - vendor assigned
150 |Account              |Vendor assigned account number associated with your organization
151 |Owner                |The organizational unit who owns the EDI account
152 |Last Activity        |The date of last activity for the account
153 |Provider             |This is a link to one of the "codes" in the "Providers" interface
154 |Path                 |The path on the vendor's server where Evergreen will send it's outgoing .epo files
155 |Incoming Directory   |The path on the vendor's server where "incoming" .epo files are stored
156 |Vendor Account Number|Vendor assigned account number.
157 |Vendor Assigned Code |Usually a sub-account designation. Can be used with or without the Vendor Account Number.
158 |===============================================================================================================
159
160 Configuring Organizational Unit SAN code
161 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
162
163 Look in Administration -> Server Administration -> Organizational Units
164
165 This interface allows a library to configure their SAN, alongside 
166 their address, phone, etc.
167
168 Troubleshooting
169 ~~~~~~~~~~~~~~~
170
171 PO JEDI Template Issues
172 ^^^^^^^^^^^^^^^^^^^^^^^
173
174 Some libraries may run into issues with the action/trigger (PO JEDI). 
175 The template has to be modified to handle different vendor codes that 
176 may be used. For instance, if you use "ingra" instead of INGRAM this 
177 may cause a problem because they are hardcoded in the template. The 
178 following is an example of one modification that seems to work.
179
180 .Original template has:
181
182 [source, bash]
183 ----------------------------------------------------------------------------------------------------------------------------------------------
184 "buyer":[
185     [%   IF   target.provider.edi_default.vendcode && (target.provider.code == 'BT' || target.provider.name.match('(?i)^BAKER & TAYLOR'))  -%]
186         {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
187     [%- ELSIF target.provider.edi_default.vendcode && target.provider.code == 'INGRAM' -%]
188         {"id":"[% target.ordering_agency.mailing_address.san %]"},
189         {"id-qualifier": 91, "id":"[% target.provider.edi_default.vendcode %]"}
190     [%- ELSE -%]
191         {"id":"[% target.ordering_agency.mailing_address.san %]"}
192     [%- END -%]
193 ],
194 ----------------------------------------------------------------------------------------------------------------------------------------------
195
196 .Modified template has the following where it matches on provider SAN instead of code:
197
198 [source, bash]
199 ------------------------------------------------------------------------------------------------------------------------------------------
200 "buyer":[
201     [%   IF   target.provider.edi_default.vendcode && (target.provider.san == '1556150')  -%]
202         {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
203         {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
204     [%- ELSIF target.provider.edi_default.vendcode && (target.provider.san == '1697978')  -%]
205         {"id":"[% target.ordering_agency.mailing_address.san %]"},
206         {"id-qualifier": 91, "id":"[% target.provider.edi_default.vendcode %]"}
207     [%- ELSE -%]
208         {"id":"[% target.ordering_agency.mailing_address.san %]"}
209     [%- END -%]
210 ],
211 ------------------------------------------------------------------------------------------------------------------------------------------
212