Module 4 - The backend

The backend logic #

As a business problem, the app should be able to manage the library’s book history, including tracking book availability, borrowing, returns, as well as the tax calculations related to overdue books.

As a technical problem, the app should have implemented workflows for reading and writing data across multiple entities. These workflows must support operations like tracking borrowed books (book instances) and updating the stock based on borrow/return actions.

Event listeners #

Event listeners are used to automate and respond to key business processes in real-time. The event listeners need to be created for the entities that require validations. For more information about event listeners see Documentation → Develop App→ Event listeners. Here you can add validations such as the book cannot be borrowed if it is not available, displaying an error message in the interface. For more details about validations, see Documentation → Workflow packages → Package: validation.

Step 8: Creating the event listeners #

To create an Event listener follow the steps presented in Lesson 3 inventory management. Additionally, you can see more details about event listeners in Documentation → Develop App → Event listeners.

The minimum event listeners that are required for this app to function properly are the following:

Optionally, you can also create them for the rest of the entities if you want to complete the application implementation.

Example of an Event listener #

First step is to create an event listener for book. We go to Event Listeners → Add. At entity we will choose book, and we will check “Before Insert” and “Before Insert Update” boxes.

After that, three workflows will be created. One with the name “BookBI”, one with the name “BookBIU”, and another one with “BookOperations”. We will open the"BookOperations" one.

The workflow will be the following:

workflow BookOperations;

method atomic onBI(e as ENTITY book) {
    //When we create a book, and only on create, we need to initialize stock with 0
    e.stock = 0;
}

method atomic onBIU(e as ENTITY book) {
    //A book must have a title
	validation->failIf(e.title == null or e.title == "", "A book must have a title!");
    validation->failIf(e.id_author == null, "A book must have an author!");
}

 //A book must have a category
  var book_categories =  FETCH book_category(key)
                         FILTER AND (id_book == ${e.key}) 
                         LIMIT 1**;

  if(book_categories.key == null){
    validation->failIf("The book must have a category!");
  }

As you can see, to check a n:n (many-to-many) relationship, we fetch book categories filtered by current book. It must have at least one category, and that’s why we put “LIMIT 1”. If we didn’t put “LIMIT 1”, the variable “book_categories” would’ve been an array, and it would have been harder to check.

You still need to add event listeners for the “book_instance” and “customer” entities for this application to work properly.

Step 9: Creating the entity actions #

Entity actions in the library system help automate tasks, keep things consistent, and improve efficiency. Actions like “Borrow book” or “Return book” help track book status, manage inventory, and improve customer service.

The entity action is shown on an edit view screen, enabling the user to execute code with a simple button click.

For more information about entity actions see Documentation → Develop App → Entity actions.

The “ActionBorrowBook” entity action #

We need to create an entity action for borrowing books (borrowing an instance of the original book). We will go to Develop → Entity actions, and we will press Add button, then we will complete the following:

1. Name = Borrow book
2. Entity = book

Click the Inputs tab, and enter the following:

Momentarly, we will save. We will come back to it later.

After that, we need to create an workflow to integrate the logic of the Entity action. You should already be familiar with creating the workflows from the previous lessons. The workflow will be the following:

workflow ActionBorrowBook;

method atomic main(s as selection, date as datetime, tax as decimal, customerKey as int) {
    //Firstly, we could use datetime->now() for dates
    //But this is a demonstatrive application
	foreach k in ui->getKeys(s){
        //validation if customer wasn't selected
        validation->failIf(customerKey == null, "A customer must be selected!");
        //Try to see if respective book is available
        var book = GET book(k);
        validation->failIf(book.stock == 0, "The book is not available at this time!");
		//We try to see if this client has books to return
        //So firstly, we will need all book history types
        var borrowType = 
        	FETCH book_history_type(key)
			FILTER AND (label == "borrow")
            LIMIT 1 **;
        var returnType = 
        	FETCH book_history_type(key)
			FILTER AND (label == "return")
            LIMIT 1 **;
		//1 method would be to see all book histories of this client,
        //and to see if nr of borrow > nr of return, if yes that means this client didnt bring back book
        
		//2 method would be to see if the number of book histories on 
		//this client is odd or even (odd means that he borrowed a book, but not returned yet)
        //even means he returned all books he borrowed
        var bookHistoriesOfClient =
        	FETCH book_history(COUNT(key) AS nr)
            FILTER AND (id_customer == ${customerKey})
            LIMIT 1 **;
        validation->failIf((bookHistoriesOfClient.nr % 2) != 0, "This customer borrowed a book and didn't return it");
        
        //After validations, we create the borrowing process
    	var book_history = CREATE book_history;
        book_history.date = date;
        book_history.tax = tax;
        book_history.id_book_history_type = borrowType.key;
        book_history.id_customer = customerKey;

        //We search one available book instance
        //We know there is one, because we validate book stock earlier
        var bookInstance = FETCH book_instance(key)
        	               FILTER AND(id_book == ${k})
                           LIMIT 1 **;

        //We need to modify book instance after we found it
        var bi = GET book_instance(bookInstance.key);
        bi.in_stock = false;
        PUT bi;

        //so book history instance will be this instace
        book_history.id_book_instance = bi.key;

        PUT book_history;
    }    
}

After the workflow is created, we go back to “Borrow book” entity action, and we will complete the Start workflow field with “ActionBorrowBook”. Now you can click the save button.

After we created the entity action, we need to add it to the book edit view. Go to the book edit view and go to Actions tab. You will add a new input with Action: “Borrow book”.

The “ActionReturnBook” entity action #

Now, we need to create an action for the return of the book (the instance of the original book that was borrowed). The steps are the same as for the “Borrow book” action. Then we create the workflow:

workflow ActionReturnBook;

method atomic main(s as selection, date as datetime) {
    //Firstly, we could use datetime->now() for dates
    //But this is a demonstatrive application
    
	foreach k in ui->getKeys(s){
        //Same as Borrow, we see if the client has something to return
        var bookHistoriesOfClient = FETCH book_history(COUNT(key) AS nr)
                                    FILTER AND (id_customer == ${k})
                                    LIMIT 1 **;

        validation->failIf((bookHistoriesOfClient.nr % 2) == 0, "This customer doesn't have a book to return");

        //If he has, we need to get the latest book history, to get all info
        
        var borrowType = FETCH book_history_type(key)
                         FILTER AND (label == "borrow")
                         LIMIT 1 **;

        var returnType = FETCH book_history_type(key)
        	             FILTER AND (label == "return")
                         LIMIT 1 **;

        var bookHistory = FETCH book_history(key)
        	              FILTER AND(id_customer == ${k})
                          ORDER BY date_created DESC
                          LIMIT 1 **;

        var bh = GET book_history(bookHistory.key);

        //We will tax the client if he didn't pay in last 7 days
        var c = GET customer(bh.id_customer);
        if(datetime->daysBetween(bh.date, date) > 7)
        c.total_tax = decimal->coalesce(c.total_tax, 0) + decimal->coalesce(bh.tax, 0);

        PUT c;

        //Book instance in stock to be true, basically we revert borrow action
        var bookInstance = GET book_instance(bh.id_book_instance);
        bookInstance.in_stock = true;
        PUT bookInstance;

        //And we create history, with return
        var bookHistoryCreate = CREATE book_history;

		bookHistoryCreate.date = date;
        bookHistoryCreate.tax = 0;
        bookHistoryCreate.id_book_instance = bookInstance.key;
        bookHistoryCreate.id_book_history_type = returnType.key;
        bookHistoryCreate.id_customer = k;

		PUT bookHistoryCreate;
    }    
}

After the workflow is created, we go back to “Return book” entity action, and we will complete the Start workflow field with the workflow name “ActionReturnBook” and save.

After we created the entity action, you need to add it to customer edit view. Go to the customer edit view and go to Actions tab. You will add a new input with Action: “Return book”.

Now you should be able to create catalogs, entity actions and event listeners, as well as writing code to validate the data.

Test your knowledge #

• After you complete the special lesson by implementing the library application on the chosen instance (the minimum presented):

  • You can try to add the rest of the validations if you want to finalize the implementation.

• Click here to test your knowledge.