BYRD - Administrator’s and Developer’s Guide

Ruby

BYRD's customization scripts for data models, workflows or transformations, are written in the Ruby language. So if you are about to write or customize any of these scripts, a basic knowledge about programming in general and Ruby in particular is strongly recommended.

Compared to other programming languages like Java or C, Ruby is a rather easy to learn. The internet provides many web sites dealing with teaching Ruby. The most comprehensive one may be found on the "official" web site for the Ruby language (https://www.ruby-lang.org/). You may as well have a look at an alternative web site which offers a more interactive way of teaching ruby (http://tryruby.org/).

When writing customization scripts for BYRD, you can take full advantage of almost all Ruby features. Also depending on the type of script (data model, workflow, transformation) BYRD automatically provides a set of API modules and method you can use. Please keep in mind that due to the nature of "in-server" scripting a couple of limitations apply:

• The script engine runs your script with Ruby version 1.9.3. Thus you can only use features of that version.
• The default encoding for all strings is 'UTF-8', in contrast to 'US-ASCII', which is the default for Ruby version 1.9.3.
• Only standard Ruby libraries can be used with 'require'. You cannot 'require' non standard libraries.
• It is not possible to access files from the file system.

Also keep in mind, that many system provided methods are designed to take a Ruby block parameter, which is expected to "return" a value. But due to the nature of Ruby blocks, you should NEVER use the "return" to do that! Instead either use "next VALUE" or "if"-statements to assign the return value and the single value variable on the last line.

Example:

category_calculation do |values|

    # Don't use "return" in a block!
    #return BasicItem if not values['packages']

    # Use next, if necessary
    next BasicItem if not values['packages']

    # Or use "if"-statements
    if values['pallet_type']
      category = PalletItem
    elsif values['package_type']
      category = PackageItem
    else
      category = BasicItem
    end
    category # The "return" value

end