docs-antora/modules/installation/pages/edi_setup.adoc

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