Prerequisites
- GitHub account created and account part of a FOLIO organization and ThunderJet team.
- Clone ThunderJet modules and set workspace in the IDEA
- Create branch from "onboarding_<release_name>" with name "onboarding/<EPAM_login>" for acq-models, mod-invoice and mod-invoice-storage. Example : "onboarding_morning_glory" → "Andrei_Makaranka"
- 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.
Tasks
1. Create/Update schema
First of all we need to define JSON schema "po_line_vs_invoice_line.json" for model which should contain next fields :
| Name | Type | Mandatory | Description | Note |
|---|---|---|---|---|
| id | UUID | Y | Unique identifier. | This field is mandatory for RMB |
| poLineId | UUID | Y | Reference on order line | |
| poLineNumber | Pattern | Y | Number of the order line | The same pattern as in the po_line.json |
| invoiceLineId | UUID | Y | Reference on invoice line | |
| invoiceLineNumber | String | Y | Number of the invoice line |
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
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
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
3. Define business GET APIs
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 DB transaction support
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.
4.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}.
4.2 Go to mod-invoice-storage and find method which responsible for deleting invoice line from database.
4.3 Update logic of the method which you found in 4.2 by adding method, which should delete record of "po_line_vs_invoice_line". Learn org.folio.rest.persist.DBClient implementation.
4.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.
4.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