Page Comparison

(this is a draft)

This documentation provides some help for backend developers to get started. It is most likely incomplete, so please don't hesitate to ask and add information here as needed.

See also: Overview for a new developer and Newcomer's first steps

FOLIO Design & Architecture

• Okapi : Gateway/Discovery service and Security model - https://folio-org.atlassian.net/wiki/display/~vijay/FOLIO+-+Developer+Onboarding+Guide#FOLIODeveloperOnboardingGuide-Design&Architecture
• RMB framework : Core module for all Vertx based modules - https://github.com/folio-org/raml-module-builder#overview

Introduction to FOLIO Acquisitions

Some demo videos are useful to understand FOLIO acquisition apps (these are using old versions):

• Orders
• Finance
• Organizations
• Receiving

See also: Thunderjet - Guidelines for backend code organization, unit tests and Karate tests

Running in IDEA

Installation

1. Install Java JDK 1117

2. Install IDEA as IDE : https://www.jetbrains.com/idea/

3. Install last version of Vagrant : https://www.vagrantup.com/
4. Install VirtualBox : https://www.virtualbox.org/
5. Alternative to vagrant/virtualBox using less memory: BusyBee
6. Install Postman: https://www.postman.com/
7. Clone from git modules and add all of them in one IDEA project
   
   • ThunderJet back-end modules : mod-orders, mod-orders-storage, mod-invoice, mod-invoice-storage, mod-finance, mod-finance-storage, mod-organizations, mod-organizations-storage, mod-gobi, edge-orders, edge-common, mod-ebsconet, acq-models
   • Modules with integration tests: folio-integration-tests(Karate), folio-api-tests(Postman)
8. Up FOLIO platform by using one of the box  :
   • Back-end + UI : https://app.vagrantup.com/folio/boxes/testingOnly Back-End : snapshot
   • See build times at https://appdev.vagrantupfolio.comorg/folioguides/boxesautomation/testing#reference-backendenvironments
9. Configure VitualBox and IDEA for running FOLIO microservice from IDEA : How to run folio backend modules with IntelliJ Idea and interact with Vagrant box environment

...

The mod-invoice and mod-invoice-storage modules are not included in the testing VagrantBox VMs, so it's easier to practice deployment with these modules:

1. Download Postman collection collections with all necessary requests or create it by yourself. The storage module should be deployed before the business one: mod-invoice-storage and then mod-invoice.

Deployment collections

Here is a zip with all the Postman collections to deploy modules.

• "FOLIO VAGRANT local.postman_environment.json" → All request in the Postman collections use variables from Environment configuration.

Please import this environment configuration with predefined values of variables : {{protocol}}, {url}}, {{okapiport}}

• "Add okapi permission to diku_admin.postman_collection.json" →  After you started VagrantBox, then you should add "okapi.all" permission to give ability to deploy modules by "diku_admin" user. 

• "Redeploy-invoice-storage-module.postman_collection.json" → Please use this collection to deploy mod-invoice-storage

Deployment Steps

1. On Linux, use this first:
   sudo ifconfig lo:1 10.0.2.15 up
sudo ifconfig lo:0 10.0.2.2 up

2. Assign “okapi.all” permission for diku_admin
   

3. Login
   

4. Build mod-invoice-storage module : mvn clean install. As a result target/ModuleDescriptor.json is created, which will be used as deployment descriptor for your microservice.

5. Copy ModuleDescriptor.json into body of “POST Module Descriptor” and run request
   

6. Run module from IDEA
   

7. Let OKAPI (Api Getway and discovery server) know were is your microservice by send request
   
   Important:

   • “srvcId” and “id” from deployment descriptor must be the same

   • Port in “url” must be the same with port from IDEA configuration “-Dhttp.port=8097”

8. Make the microservice accessible from the outside and allow access to it
   

9. If everythigs fine – start using APIs

If a module was already deployed and a new version needs to be tested for integration tests, it is not necessary to remove the old version: simply add .xxx to the id in the descriptor, with a number higher than the currently deployed one, and the karate tests will automatically use the latest version.

Debugging

TODO! Important (issue with module upgrade and load sample and reference)

{{okapiprotocol}}://{{okapiurl}}:{{okapiport}}/_/proxy/tenants/{{xokapitenant}}/install?tenantParameters=loadSample=false,loadReference=false
12:49
  @Override
  public Future<Integer> loadData(TenantAttributes attributes, String tenantId, Map<String, String> headers, Context vertxContext) {
//    log.info("postTenant");
//    Vertx vertx = vertxContext.owner();
//    Parameter parameter = new Parameter().withKey(PARAMETER_LOAD_SYSTEM).withValue("true");
//    attributes.getParameters().add(parameter);
//
//    TenantLoading tl = new TenantLoading();
//    buildDataLoadingParameters(attributes, tl);
//
//    DBClient client = new DBClient(vertxContext, headers);
//
//    return Future.succeededFuture()
//      .compose(v -> migration(attributes, "mod-invoice-storage-5.2.0",
//        () -> migrationService.syncOrderPoNumbersWithInvoicePoNumbers(headers, vertxContext)))
//      .compose(v -> {
//
//        Promise<Integer> promise = Promise.promise();
//
//        tl.perform(attributes, headers, vertx, res -> {
//          if (res.failed()) {
//            promise.fail(res.cause());
//          } else {
//            promise.complete(res.result());
//          }
//        });
//        return promise.future();
//      })
//      .onFailure(throwable -> Future.failedFuture(throwable.getCause()));
    return Future.succeededFuture(0);
  }

Debugging

Modules can be executed in debug mode in IDEA, they just need to be deployed as described above.. Unit tests can also be debugged in the same way.

change log level for mod-invoice-storage:
http://localhost:8097/admin/loglevel?level=INFO&java_package=org.folio.rest.persist.PostgresClient

...