Skip to end of metadata
Go to start of metadata


  • All the backed modules contain a Vagrantfile
    • this is for convenience, but it's really important to note that you only ever run 1 vagrant image - and that will coordinate all the modules you want to run
    • so if you want to run mod-agreements and mod-licenses together, you will need to use only one of the Vagrantfile images - usually use the mod-agreements one
    • check the version of the folio/testing-backend being used by the Vagrantfile before running looking for uncommented lines like:
      • config.vm.box_version = "5.0.0-20190612.2294"
    • Comment out this line from the Vagrantfile if you want to just run the latest version
  • Once you have done a vagrant up you have a folio running with a base collection of modules
  • We then need to start up our backend modules - mod-agreements and mod-licenses -
    • Both modules have a scripts directory with a script which you probably want to use.
    • The process is usually cd <module>/service; grails war; ../scripts/  
    • NOTE: the script uses a jar file in ../build/libs.   The script may need to be modified to use the correct version of the jar file.
    • This is enough to build the module and start it up.
  • At this point you have a running folio and your running modules, but the running OKAPI does not know that it should route requests for the diku tenant to your running modules.
    • In order to do that we provide a  script in the scripts directory
    • NOTE: This script uses the "jq" command, which may be installed on a MAC using "brew".
    • Running this script (one for each backend module you want to enable for the diku tenant) will connect the okapi running in the vagrant image to the running modules.
  • This gets you a backend system.
    • Both modules have test scripts that you can use to exercise the backend as a whole by talking to the OKAPI on port 9130.
    • You will see a script called okapi-cmd in both scripts directory - you can use this to trigger a URL directly - for example ./okapi-cmd /licenses/licenses  will trigger the index action on the licenses controller in the licenses module.
  • If you need to drop the database you can use a one-liners like (substituting the correct username/password):
    • vagrant ssh -c 'export SCHEMA=diku_mod_licenses;PGHOST= PGDATABASE=okapi_modules PGUSER=<username> PGPASSWORD=<password> psql -c "DROP SCHEMA IF EXISTS $SCHEMA CASCADE;"'
    • vagrant ssh -c 'export SCHEMA=diku_mod_agreements;PGHOST= PGDATABASE=okapi_modules PGUSER=<username> PGPASSWORD=<password> psql -c "DROP SCHEMA IF EXISTS $SCHEMA CASCADE;"'
    • then stop and restart the backend (re-run ../scripts/ )
    • then re-register the module (e.g. by re-running the ../scripts/

Backend troubleshooting

  • If you need to update the version of the backend you are running with Vagrant, update the config.vm.box_version setting in the Vagrantfile to the appropriate version (or remove this restriction completely to get the latest version), then try:
vagrant halt
vagrant destroy
vagrant box update
vagrant up
  • If you get errors such as "Access requires permission: <permission name>" check you are running the latest version of folio/testing-backend (see above)
  • On macOS the default sed install recognize the -r option, which causes the okapi-cmd script to fail

    • Use "brew install gnu-sed" to install the Gnu version of sed as gsed

    • Update the okapi-cmd and okapi-login scripts to use gsed instead of sed

SQL Logging

If you want to see what SQL statements are being created in the application log you can make the following changes:

  • In /service/grails-app/conf/application.yml uncomment the following lines

# format_sql: true
  • In /service/grails-app/conf/application.yml uncomment the following lines
# logSql: true
  • In /service/grails-app/conf/logback.groovy uncomment the following lines
//logger("org.hibernate.SQL", DEBUG)
//logger("org.hibernate.type.descriptor.sql.BasicBinder", TRACE)

Avoid GOKb harvesting

If you do not need/wish to harvest GOKb data in your test instance, before you run the  script in Agreements, edit the file /service/src/main/okapi/tenant/sample_data/diku-data.groovy

Find the code block starting:

RemoteKB gokb_test = RemoteKB.findByName('GOKb_TEST') ?: new RemoteKB(

And change:

active:Boolean.true → active:Boolean.FALSE,

Trigger GOKb harvest (and clear database)

If you are in a position where you need to trigger a fresh harvest to check against your code changes, then you can run the following from within your mod-agreements directory while mod-agreements is running.

curl -H 'X-OKAPI-TENANT: diku' -XDELETE http://localhost:8080/_/tenant
curl -XPOST -H 'Content-Type: application/json' -H 'X-OKAPI-TENANT: diku' http://localhost:8080/_/tenant -d '{ "parameters": [{"key": "loadSample", "value": true}, {"key": "loadReference", "value": true}]}'

This will drop the currently initialised tenant, clearing the database and essentially acting as if you had started a fresh vagrant image and run the `register_and_enable` script. This will trigger a fresh GoKB harvest.

Setup eHoldings

To work with eHoldings requires a customer ID and API key for the EBSCO EKB Sandbox. These can be obtained from Khalilah Gambrell or Carole Godfrey  at EBSCO

Once obtained these can be entered via the UI via:

 Settings → eHoldings → Knowledge base

To prevent  KB API Credentials are invalid error with ensured valid credentials with the sandbox API one should at least use 
which you find in vagrant box folio/testing-backend version v5.0.0-20200427.4130 and newer.


  • The front-end can easily be deployed by using the platform-erm Stripes platform.
  • To use local copies of applications with checked-out repositories, following the instructions in the Developing and Contributing section

Frontend troubleshooting

  • No labels

1 Comment

  1. When running on a mac, the (it's actually called okapi-cmd, without the extension) in mod-agreements and mod-licenses fails with an error which indicates that sed doesn't recognize the -r option.  The version of sed which runs on a mac does not support the -r (regexp) option, and including it causes the sec command to fail as well.

    Workaround:  Use "brew install gnu-sed" to install the Gnu version of sed which supports regular expressions.  This will install as gsed into /usr/local/bin.  The okapi-cmd and okapi-login scripts should be modified to invoked the appropriate version of sed.