Prerequisites

1. GitHub account created and account part of a FOLIO organization and ThunderJet team.
2. Clone ThunderJet modules and set workspace in the IDEA
3. Create branch from "onboarding_<release_name>" with name "<EPAM_login>" for acq-models, mod-invoice and mod-invoice-storage. Example : "onboarding_morning_glory" → "Andrei_Makaranka"
4. You able to replace instances of the mod-invoice and mod-invoice-storage modules by your instance which run from IDEA.

Overview

The purpose of practical tasks in the implementation of CRUD API to insert/updating/obtaining the order line number with which the invoice line is associated.

Useful links and information

Full flow - Onboarding.postman_collection.json - Download this collection that allows you to create an order with an order line as well as an invoice and an invoice line based on the order line.

Apply last update from sub-module.PNG - How to set your sub module on specific commit or branch

Tasks

1. Create/Update schema → mod-invoice-storage

First of all we need to define JSON schema "po_line_vs_invoice_line.json" for model which should contain next fields :

On the FOLIO project JSON schema is used to define models which will be used as REST request/response and also save in the PostgreSQL : https://json-schema.org/

https://github.com/folio-org/acq-models → This is the central repository for the models of the various acquisition modules.

1.1 Please create schema "po_line_vs_invoice_line.json" in the mod-invoice-storage/schemas of the acq-models. Also add example mod-invoice-storage/examples.

1.2 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>"

Note : Don't merge your PR and just provide for review

2. Define storage CRUD API → mod-invoice-storage

Storage modules in the FOLIO should contain logic for working only with the database.

2.1 Check out on branch "onboarding/<EPAM_login>" in the GIT sub-module : mod-invoice-storage\ramls\acq-models. Use Apply last update from sub-module.PNG replace branch "master" with your branch  "<EPAM_login>"

2.2 Create new RAML file "mod-invoice-storage\ramls\po-line-invoice-line-connection.raml", where you should define new CRUD API.

In the definition you should use created schema and examples from step (1 Create/Update schema). Build project and then go to "target/generated-sources/raml-jaxrs/org/folio/rest/jaxrs/resource" and find new generated REST interface.

2.3 Implement generated interface from step above. As example you can use InvoiceStorageImpl.java

2.4 We also need to declare a new API in the module descriptor "descriptors/ModuleDescriptor-template.json", which will then be loaded into the Okapi and will allow us to route requests to the appropriate microservices in the future.

Note : Module descriptor documentation -> https://github.com/folio-org/okapi/blob/master/doc/guide.md#example-4-complete-moduledescriptor

2.5 To be able store new data in the PostgreSQL we need to define table "po_line_vs_invoice_line" in the "templates/db_scripts/schema.json". Also add indexes for fields : "poLineNumber" and "invoiceLineNumber".

2.6 Deploy module with new REST API and module descriptor. Check that API works through Postman collection.

2.7 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>". In the PR attach screen that API works

Note : Don't merge your PR and just provide for review

! 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);
  }

3. Define business GET APIs → mod-invoice

Business modules in the FOLIO should contain business logic, calls to his storage module (mod-invoice → mod-invoice-storage) and should call third modules by using business APIs of this module.

3.1 Check out on branch "onboarding/<EPAM_login>" in the GIT sub-module : mod-invoice\ramls\acq-models

3.2 Create new RAML file "mod-invoice\ramls\po-line-invoice-line-connection.raml", where you should define only GET by id and GET by query API (don't define POST, PUT, DELETE)

In the definition you should use created schema and examples from step (1 Create/Update schema). Build project and then go to "target/generated-sources/raml-jaxrs/org/folio/rest/jaxrs/resource" and find new generated REST interface.

3.3 Implement generated interface from step above. Please create business service and invoke methods of this service from controller.

3.4 We also need to declare a new API in the module descriptor "descriptors/ModuleDescriptor-template.json".

3.5 Deploy module with new REST API and module descriptor. Check that API works through Postman collection.

3.6 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>". In the PR attach screen that API works

Note : Don't merge your PR and just provide for review

4. Add business logic to connect invoice line and order line → mod-invoice

Connection should be stored in the DB if invoice line created based on order line.

4.1 Business API for creating invoice line → POST /invoice/invoice-lines}. Please find controller and service method which responsible for creating invoice line.

4.2 Add logic to the method founded in 4.1, which should create connection between order line and invoice line in the DB. Please use Storage API from Task 2

4.3 Deploy module mod-invoice with your updates. Check that connection is created using Postman collection.

4.4 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>". In the PR attach screen that API works

Note : Don't merge your PR and just provide for review

5. Add DB transaction support → mod-invoice-storage

If we delete the invoice line, then we need to delete the links between the order line and the invoice line (delete record of "po_line_vs_invoice_line").

To ensure data consistency, this operation must be atomic and performed within a single database transaction.

5.1 Business API for deleting invoice line → DELETE /invoices/invoice-lines/{id} and finally Storage API will be invoked → DELETE /invoices-storage/invoice-lines/{id}.

5.2 Go to mod-invoice-storage and find method which responsible for deleting invoice line from database.

5.3 Update logic of the method which you found in 5.2 by adding method, which should delete record of  "po_line_vs_invoice_line". Learn org.folio.rest.persist.DBClient implementation.

5.4 Deploy module mod-invoice-storage with your updates. Check that invoice line will be deleted with "po_line_vs_invoice_line" using Postman collection.

5.5 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>". In the PR attach screen that API works

Note : Don't merge your PR and just provide for review

6. Add validation business logic → mod-orders

Should not be possible delete order line (DELETED /orders/order-line/{id}) if there is connection between order line and invoice line.

6.1 Business API for deleting order line → DELETE /orders/order-line/{id}. Please find controller and service method which responsible for deleting order line.

6.2 Add logic to the method founded in 6.1, which  should block deletion order line and return error to user.

6.3 Deploy module mod-invoice-storage with your updates. Check that is not possible delete order line if there is connection to invoice line using Postman collection.

6.4 Commit and push new schema in the branch "onboarding/<EPAM_login>" and create PR in the "onboarding_<release_name>". In the PR attach screen that API works

Note : Don't merge your PR and just provide for review

7. Prepare cross module migration