docs/installation/edi_setup.txt

   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 Admin > Server Administration > Acquisitions > 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 Admin > Server Administration > Acquisitions > 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 Admin > Server Settings > 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