First Launch

Our application is done, of course, to a first approximation. Let’s compile and launch it!

1. Invoke the Run — Start application server action from the menu. Studio will deploy a local Tomcat instance in the project subdirectory, deploy the compiled application there and launch it

2. Open the application by clicking a link in the bottom part of the Studio

3. CUBA application welcomes us with the login screen. It’s a part of the security module, integrated into the platform. Default login and password are already set on the screen, so just click Submit.

4. After successful login you can see the main window of your application, which can be customised from the Studio, similarly to any other screen.

5. Open Application - Orders from the menu. The standard browser screen appears. It contains a generic data filter on top, a table of records with buttons on top, performing standard CRUD actions. There are more standard actions available in the platform, for example, export to excel. Click Create.

6. This is the autogenerated editor screen for the Order entity. Let’s fill up the form. Click […] to select a client.

7. There are no clients in the system yet, so the client browser is empty. Click Create to add a new client to the system and fill up client editor with the following values and click OK:

• Name: Alex
• Phone Number: 999-99-99
• Email: alex@home.com

8. Double click the client record we have just created or simply click Select on the bottom part of the client browser

9. We have specified a client for our order and it is shown in the client field accordingly to the Instance name, we specified for the Client entity (Name Phone number)

10. Create set the Mechanic field in the same way

• User: admin
• Hourly Rate: 10

11. Complete entering data for the order using the following values and click OK

• Description: Broken chain
• Status: New

Our CRUD application is ready, so we have successfully completed items 1-3 of the functional specification!

5.1 Generic Filter

Now let’s examine how data filter works. The CUBA generic filter enables you to filter data by all the fields of the screen main entity, all the entities it refers to as well as their fields. It also gives you the ability to create custom filtering rules based on JPQL queries and to save them for repeated use.

Create one more order with the following parameters:

Client

• Name: Freeman
• Phone Number: 111-11-11
• Email: freeman@world.com

Mechanic

• User: admin
• Hourly Rate: 8

Order

• Description: Wheels problem
• Hours Spent: 2
• Status: In progress

Parts (add one part)

• Title: Wheel 29’’
• Description: Standard wheel
• Price: 50

5.1.1 Client’s Orders Filter

Let’s create a simple filter to find all the orders of a particular client.

1. Go to the Order Browser screen (Application — Orders) and click the Add search condition link

2. Select the Client property

3. Click Select

4. Your filter automatically shows you options that can be applied for the Client field. Select Alex and click Search.

5. Only one record left after filtering.

6. Click on the [=] button to see what comparison options CUBA filters offer for users

[=] - exact equality

[in] - the field is contained in a specified set of values

[not in] - the field is NOT contained in a specified set of values

[<>] - the field is not equal to the specified value

[is set] - the field is null/not null

In a similar way, you can filter by all types of attributes (string, numeric, boolean, etc).

5.1.2 Part Specified in Order Filter

Sometimes it is not possible to filter records without join operation. Let’s take the following example: we want to filter all the orders that contain some particular part in it.

1. Click the Add search condition link

2. Select the Create new… option

3. Set condition Name: Part Specified in Order

4. Our main entity in the screen is Order, which has Set parts field, containing all the used parts. Let’s join parts to the orders: type join {E}. and the system will show you suggestions. Select the parts suggestion or just type it manually and assign alias p to the joining table. You should get the following Join clause: join {E}.parts p

5. Input p.id = ? in the Where field. The question mark here means the parameter that we will send to the condition from the generic filter UI.

6. Select Param type: Entity

7. Set Entity/Enum: SparePart

8. Click OK

9. Specify the Wheel 29’’ value in your custom filter and click Search to see the result list

5.1.3 Reusing Filters

Obviously, there are a number of filters, that end-users reuse frequently. For that purpose you can save filters you create. Let’s save the “part specified in order” filter we have just created.

1. Click the cogwheel button on the right-hand side of the filter component

2. Click Save

3. Input Filter name: Part specified in order

4. Now you can access your filter by clicking the down arrow button, placed next to the Search one. Apply the saved filter.

5. Applying a saved filter you can edit, remove it or make selected filter as default one by clicking the cogwheel button. Default filters appear in the screen automatically after opening.

5.1.4 Editing Saved Filters and Grouping Conditions

1. Open the saved filter

2. Click the cogwheel button — Edit

3. Selecting conditions users are able to edit them

4. Also there is an ability to additional conditions and group them using OR and AND logical operators. Let’s add one more condition. For example, we want to control our stock of spare parts, so, we would like to know how many parts of some particular type we need for the new or unstatused orders. The logical expression we are going to build is the following: Part Specified in Order = ? AND (Status = NEW OR Status is not set).

5. Click the Add OR button and check that the OR group item is selected in the conditions list

6. Click Add

7. Select the Status attribute

8. Set Default value: New

9. Select the OR group item in the conditions list and add one more condition for the Status attribute

10. Change Operation to [is set] one and specify No in the Default value field

11. Click OK

12. Now we can see our complex filter

13. Editing filters allows you to share them between users, set them as default screen filter, hide some conditions or groups of conditions. More information on generic filter component can be found here.

5.2 Security Setup

The platform has built-in functionality to manage users and access rights. This functionality is available from the Administration menu. The CUBA platform security model is role-based and controls CRUD permissions for entities, attributes, menu items and screen components and supports custom access restrictions. All security settings can be configured at runtime. There is also an additional facility to control row level access.

We need a role for mechanics in our application. A Mechanic will be able to modify an order and specify the number of hours they spent, and add or remove spare parts. The Mechanic role will have limited administrative functions. Only admin will be allowed to create orders, clients and spare parts.

1. Open Administration — Roles from the menu

2. Click Create

3. Set Name: Mechanic

5.2.1 Screen Permissions

We want to restrict access to the Administration screens for all Mechanic users, so let’s forbid the Administration menu item. Also, mechanics don’t need access to the mechanics and clients browsers, let’s forbid the corresponding screens too.

1. Select the Administration row in the Screens table

2. Select deny

3. Similarly deny access for Clients and Mechanics

5.2.2 CRUD Permissions

As it has already been mentioned we want a mechanic only allow read access to clients, mechanics and parts. Also a mechanic should not be able to create or delete an order in the system. Only update it’s status, hours spent and manipulate with parts in the order.

1. Open the Entities tab

2. Select the Client entity and forbid create, update and delete operations

3. Repeat the second step for the Mechanic and SparePart entities

4. Forbid only create and delete operations for the Order entity

5.2.3 Attribute Permissions

On attribute level we don’t want to allow a mechanic to set values for the client, mechanic and description attributes; also we would like to hide the amount field from them.

1. Open the Attributes tab

2. Select the Order row

3. Tick read-only for client, mechanic and description; tick hide for the amount attribute

4. Click OK to save the role

5.2.4 Role-based Security in Action

Let’s apply the mechanic role to a new user and take a look at the application from the mechanic’s point of view.

1. Open Administration — Users

2. Click Create

3. Set Login: jack

4. Set password and password confirmation: qwe

5. Set Name: Jack

6. Add the Mechanic role to user Roles

7. Click OK to save the user

8. Let’s exit the application by clicking the top-right door button of the screen

9. Login with the new user Login: jack, Password: qwe

10. The Administration menu item is hidden as well as Mechanics and Clients browsers;

The Spare Parts browser is available in read-only mode;

The Orders browser allows us only editing of existing records;

The Order editor allows only changing the Hours spent and Status fields, as well as adding parts to an order; the amount field is hidden from our user.

5.2.5 Row-level Security

The CUBA Platform Security subsystem allows you to control and restrict access to the level of records using the access groups mechanism. For example, we want to restrict access to our mechanics to see only orders that were assigned to them.

1. Log out from the system and login under administrator (Login: admin; Password: admin)

2. Open Administration — Access Groups from the menu. The groups have the hierarchical structure, where each element defines a set of constraints, allowing controlling access to individual entity instances (at row level).

3. Click Create — New

4. Set Name: Mechanics

5. Click OK

6. Open the Constraints tab for the newly created group

7. Click Create in the Constraints tab

8. Set Entity Name: Order

9. We can define what operation type we want to assign restriction to. Keep Operation Type: Read

10. For some operation types it is not possible to perform check at the database level, e.g. delete and update operations. For this reason there are three Check Types implemented in the platform: Check in database (using JPQL), Check in memory (using Groovy script; the only option for Create, Update, Delete, All operation types) and Check in database and in memory (using both JPQL and Groovy). In our example, we will use the Check in database check type

11. For the Check in database check type you can specify a JPQL query in the same way as we did for custom conditions in the generic filter. Click the Constraint Wizard link

12. Expand the Mechanic field and select the child User attribute

13. Click Select

14. Click OK in the Define query window. The platform has generated the where clause as {E}.mechanic.user.id = 'NULL'. We will need to tune it a bit.

15. Click the question mark located in the top-right corner of the Where Clause filed to see what predefined constants can be used here

16. We need the ID of the current user to compare with the mechanic’s user id. So, change 'NULL' to :session$userId. Finally, you should have the following code:

{E}.mechanic.user.id = :session$userId

17. Click Test Constraint

18. If test shows that constraint is valid, then click OK

19. Select the Company group on the Access Groups screen

20. Select Jack in the Users tab

21. Click Move To Group

22. Select the Mechanics group and click Select

23. Let’s now assign one of our mechanics to the new user. Go to Application - Mechanics in the main menu

24. Select the mechanic with hourly rate of 10

25. Click Edit

26. Specify the Jack user for this record and click OK

27. Now our mechanic is associated with the jack user. Re-login into the application using Jack’s credentials: Login: jack; Password: qwe

28. Open the Orders browser (Application — Orders). Now we can only see the orders assigned to Jack

5.3 Audit

There is a requirement in our functional specification to track critical data changes. CUBA Platform has a built-in mechanism to track entity changes, which you can configure to track operations with critical system data.

Keeping track of our application, it happens when one day someone has accidentally erased the order description. It is not appropriate to call the client on the phone, apologise and ask them to repeat the what needs to be done. Let’s see how this can be avoided.

1. Re-login into the application as administrator (Login: admin; Password: admin)

2. Open Administration — Entity Log from the menu

3. Go to the Setup tab

4. Click Create

5. Set Name: Order Auto: true Attributes: all

6. Click Save

Now the system will track all CRUD changes of all the fields of the Order entity. Go to the order browser and change status or description of any record, then get back to the Entity Log screen and you will see who made what change. On the screenshot below we changed the description of one of the orders and see what we have in the entity log:

5.4 First Launch Conclusion

While spending short time exploring the CUBA Platform and its features we have already finished the following requirements from the functional specification:

1. Store customers with their name, mobile phone and email

2. Record information about orders: price for repair and time spent by mechanic

3. Keep track of spare parts in stock

4. Automatically calculate price based on spare parts used and time elapsed

5. Control security permissions for screens, CRUD operations and records' attributes

6. Perform Audit of critical data changes

7. Provide API for a mobile client to place an order

Note that we didn’t even type any line of source code, everything has been provided by the platform or scaffolded by the Studio. Let’s move forward towards business logic.

next →