Bots 3.0.0

  • Bots 3.0.0 was released 2013-02-04
  • Bigger changes, and a database migration is needed.

Migration Notes


Version 3.0 is a bigger update for bots, view all changes in next section. Overview:

  1. Django 1.1 and 1.2 are not supported anymore. Supported are django 1.3 and 1.4.
  2. is changed. Advised: use the new, and do your customization in the new (eg for error reports, maybe database and timezone).
  3. The database has changed. A script is included to change the database. I had no database issues while testing this migration.
  4. lots of changes in bots.ini. The ‘old’ bots.ini is OK, but it is advised to use new bots.ini, and do your customizations there.
  5. Excel input: does work; but is now an incoming messagetype and not via ‘preprocessing’.
  6. Most user scripts will work; many user scripts are not needed anymore because the functionality is provided by bots now.
  7. Some functions that may be used in user scripting have changed:
    • botslib.change() -> botslib.changeq(). This function is used to in processing incoming 997’s and CONTRL
    • botsengine routescripts: for ‘new’ runs in routescript called function postnewrun(routestorun) -> postnew(routestorun)
    •,idroute) ->,command,idroute). Command is one of: ‘new’,’automaticretrycommunication’,’resend’,’rereceive’.
    •,idroute) ->,command,idroute). Command is one of: ‘new’,’automaticretrycommunication’,’resend’,’rereceive’.


My experiences: after changing and database migration, all works (except for and issues mentioned above).

Summary of procedure

  1. make a backup!
  2. rename existing installation.
  3. do a fresh install.
  4. copy old data to new installation.
  5. change settings
  6. update the database.


  • It is critical to change the settings before updating the database. Bots finds the right database via the settings.
  • If you use MySQL or PostGreSQL: same procedure. The bots-updatedb script also updates MySQL or PostGreSQL.
  • Tested this for migration from bots2.2.1 -> 3.0.0, but works for all bots2.* installations.

Windows procedure

  1. make a backup!
  2. rename existing installation
    • existing bots-installation is in C:\Python27\Lib\site-packages
    • renamed bots directory to bots221
    • also renamed existing directories for cherrypy, django, genshi.
  3. do a fresh install of bots3.0.0 installer (bots-3.0.0.win32.exe)
  4. copy old data to new installation.
    • in C:\Python27\Lib\site-packages new directories have been installed (bots, django, cherrypy, genshi)
    • copy directories botssys and usersys from bots221-directory to bots directories. Everything can be overwritten.
  5. change settings
    • use new config/bots.ini, adapt for your own values.
    • use new config/, adapt for your own values. Especially the database settings are important; the format is slightly different (but similar enough to give no problem); critical is using the ‘ENGINE’-value of the new
  6. update the database.
    • use command-prompt/dos-box
    • goto directory C:\Python27\Scripts
    • command-line: C:\Python27\python
    • should report that database is successful changed.


If you use a 64-bits version of windows another option is to use the 64-bits versions of python and bots.

Linux procedure

  1. make a backup!
  2. rename existing installation
    • existing bots-installation is in /usr/local/lib/python2.7/dist-packages
    • renamed bots directory to bots221
    • for libraries: check you use at least django 1.3
  3. do a fresh install: see installation procedure
  4. copy old data to new installation.
    • in /usr/local/lib/python2.7/dist-packages new bots-directory is installed.
    • copy directories botssys and usersys from bots221 directory to bots directories. Everything can be overwritten.
    • mind your rights.
  5. change settings
    • use new config/bots.ini, adapt for your own values.
    • use new config/, adapt for your own values. Especially the database settings are important; the format is slightly different (but similar enough to give no problem); critical is using the ‘ENGINE’-value of the new
  6. update the database.
    • command-line:
    • should report that database is successful changed.


Changes in database format since version 3.0.0rc

Alas; the database as used in the 3.0.0rc version has changed. Changed is:

  • table channel: field ‘testpath’ is added
  • table report: field ‘acceptance’ is added
  • tabel ccode: field ‘rightcode’->70pos
  • tabel ccode: field ‘attr1’->70pos

Wrapping of user script functionality into GUI

  1. For outgoing filenames: can include partnerID, messagetype, botskey, data/time, etc in channel.
  2. Pass-through is option in route.
  3. Zip and unzip files as option in channel.
  4. SSL keyfile and certificate as options in channel.
  5. Excel as incoming messagetype (instead of via preprocessing).
  6. Option in channel to indicate edi file in email should be in body.
  7. Add: communication-out type ‘trash’ to discard of edi files.

Improved ‘run’ options

  1. Run options in GUI are simpler: new, rereceive, resend. (Automatic recommunication is possible via bots-engine).
  2. Communication errors are visible in outgoing-screen and can be ‘resend’ manually.
  3. Add ‘resend all’ and ‘rereceive all’ in incoming/outgoing screen; espc. useful in combination with selections.
  4. Indicate in screens a file has been resend; Keep track of number of resends of an outgoing file. Filer works ‘over’ resends now.
  5. Dropped ‘retry’ option. This was not useful and confusing. Use ‘rereceive’.
  6. Dropped ‘retry communication’. Use ‘resend’, easier and more consistent.
  7. Add: use ‘channel’ in selects (eg useful for resend selects).

Configuration change management :doc:`see wiki <../deployment/change-management>`

  1. Use tools to push changes test-> production
    1. Via GUI: write database configuration to usersys in order to compare environments.
    2. Via GUI: read the changed database configuration in usersys after pushing changes
  2. Isolated acceptation tests: run an acceptance test set without changes.
    1. option in bots.ini to active ‘acceptance test’
    2. bots prevents communication to ‘outside
    3. use seperate path to read/write (‘testpath’)
    4. do not change counters etc
    5. results of acceptance tests can be deleted/removed
    6. etc

Many improvements in GUI, eg:

  1. ‘Detail’ screen has a better layout.
  2. Improve: show name partner in selectlist (in configuration).
  3. Improve: show channel-type in selectlist and routes (in configuration). I find this very convenient.
  4. Improve: better sorting in configuration for in django 1.4, eg for routes, codelists, trasnlations.
  5. References in a configuration are better guarded. Eg: when deleting partner that is used in partner-specific translation: user is warned, has to confirm.
  6. Improve: removed charset from channel. This was not needed.
  7. Improve: selections in screens not only for partners but also for partner groups
  8. Fix: download an edi-file via filer could give not-correct file.
  9. Add: keep track of file-size of incoming/outgoing files.

Extended partner functionality

  1. Add: function ‘partnerlookup’ for use in mapping scripts to look-up/convert partner related functions.
  2. Add: extra partner fields: address, user-defined fields.
  3. Add: send a message to any bots partner from mapping script (use partners as the email address book).
  4. Improve: multiple email addresses in cc field.


  1. Fix: bug in confirmation logic for frompartner/topartner (I had them reversed…).
  2. Better CONTRL-message.
  3. Option to run user exit either to generate CONTRL message or change the generated CONTRL message.
  4. messagetype (for incoming) is now similar to other uses of message-type; edi-type is removed (is not needed)
  5. Fix: better indexing for reference/botskey. This improves performance for confirmations.


  1. Always make configuration backup when reading new plugin.
  2. Dropped the date-indication for files that are overwritten.
  3. Index file in plugin always starts with type of plugin and layout is sorted/predictable.
  4. Fix for performance problem when generating plugin for big plugins.
  5. Fixed bug for relations in database. Bug only occurs when reading ‘hand-changed’-plugins.

Better handling of ‘database is locked’/crash recovery

  1. First of all: use the jobqueue-server for more complicated scheduling (prevents running multiple engine)
  2. Different way of detecting another instance of engine is running via locking of port.
  3. If bots-engine finds no other engine is running, but the database is locked this indicates the previous run was ended unexpectedly (eg computer crash).
  4. In this case bots will do an automatic ‘crash recovery’. A warning is still given in logs or via email. Only ONE email is send.


  1. An 64-bits installer for windows is available.
  2. Runs with django 1.4 now ; dropped support for django 1.1, 1.2
  3. Database has changed. A script is added to upgrade the database.

Other changes

  1. Add: startup script for bots-webserver using apache. Multiple bots-environments can run over one apache server.
  2. Add: user exit for cleanup.
  3. Improve: use external file name in archive.
  4. Add: archive as zip-files.
  5. Fix: port was not used in initializing PostgreSQL.
  6. Less statuses in processing (simpler, faster).
  7. Improve: use unlimited text fields in database for errortext and persist.
  8. Improve: if message in incoming edi file has error in mapping script and/or writing outgoing file: process rest of edi file (there is a compatibility option in bots.ini).
  9. Reworked errors for edi files (parsing, generating). All errors have numbers now (for referencing).
  10. Always read incoming files sorted by name. Reason: predictability. Formerly the read order was not predicable.
  11. Fix: better handling of import errors for user scripts. This could lead to confusing errors/situations.
  12. Add: access to whole envelope in mapping.
  13. Fix: nr of messages was not used correctly when writing multiple UNH in one mapping script.
  14. Fix: bug for numerical fields with more than 4 decimal positions.
  15. Add: counter(s) per bots-run in mapping script; eg useful for UNH/ST counter per interchange.
  16. Fix: enveloping for edifact with keca-character-set.
  17. Add: concatenate function for usage in mapping scripts.
  18. Improve: updated grammar-handling to allow for UNS-UNS construction.
  19. Improve: set explicit namespace when generating xml.
  20. Add: determine translation via user scripting.
  21. Add: user scripts can easy detect what type of run is done via routedict[‘command’]
  22. Dropped: intercommit connector.