CUBA Platform Component - User Inbox

This CUBA component gives users a mailbox for user to user and system to user messages. Using this add-on allows you to notify users about certain events that happened within the application. Also it is possible to let users send messages / notification to other users. Using context-based messages, the user can link to particular business objects when sending messages.

Installation

user-inbox is available in the CUBA marketplace
Select a version of the add-on which is compatible with the platform version used in your project:

Platform Version	Add-on Version
7.2.x	0.8.x
7.1.x	0.7.x
7.0.x	0.6.x
6.10.x	0.5.x
6.9.x	0.4.x
6.8.x	0.1.x - 0.3.x

The latest version is:

Add custom application component to your project:

Artifact group: de.diedavids.cuba.userinbox
Artifact name: user-inbox-global
Version: add-on version

dependencies {
  appComponent("de.diedavids.cuba.userinbox:user-inbox-global:*addon-version*")
}

CHANGELOG

Information on changes that happen through the different versions of the application component can be found in the CHANGELOG. The Changelog also contains information about breaking changes and tips on how to resolve them.

Supported DBMS

The following databases are supported by this application component:

HSQLDB
PostgreSQL
MySQL

All other DBMS systems are also possible to work with by the fact that CUBA studio generates the corresponding init / update scripts within the application.

Example Usage

To see this application component in action, check out this example: cuba-example-using-user-inbox.

Using the Inbox as a User

As a logged in user you'll see a menu entry called "Messages" which will show the incoming messages that are either from another user of the system or from the system itself, which has send a message to the system in order to notify the user about something changed in the system.

Sending Messages

To send messages to a particular user, there are two options available:

manually sending message to a user
system messages that are send programmatically

Send Manual Messages

In order to send a message to a particular user, there is a button "Send message" in the users inbox.

This screen allows to manually send a message. A message contains a subject and a body, just like a regular Email.

Context-based Messages

Therefore there is another option to send a Message. In this case it is a message that is send through the context of a particular entity.

This is comparable of sending a email with a link that points to a particular customer / order etc. in your application together with the information from the sender.

Share Entity Instances (CUBA 6 Screens)

The way to send context-based messages is to use the @Shareable annotation for CUBA 6 based screens (AbstractLookup / AbstractEditor). The annotation is used in any Entity browse / editor screen.

Example:

@Shareable(listComponent = "customersTable")
public class CustomerBrowse extends AnnotatableAbstractLookup {
}

For the @Shareable annotation you need to define the list component on which it should add the share button. Normally this is the id of the table you defined in your browse screen.

This annotation will create a button in the buttonsPanel of the table and add the share button after the default CUBA buttons.

The @Shareable annotations can be customized through the following attributes:

String listComponent - the id of the list component / table where the button will be added - REQUIRED
String buttonId - the id of the newly created button that will be created ("attachmentBtn" by default)
String buttonsPanel - the id of the buttons panel where the new button will be added ("buttonsPanel" by default)

more information on this topic can be found here: balvi/declarative-controllers

Share entity instances (CUBA 7 Screens)

The way to send context-based messages is to use the WithEntitySharingSupport interface. The interface can be used in any Entity browse screen. It requires to specify the table component as well as the buttonsPanel of the table.

Example:

import de.diedavids.cuba.userinbox.web.WithEntitySharingSupport

public class CustomerBrowse extends StandardLookup<Customer> implements WithEntitySharingSupport {

    @Inject
    protected GroupTable<Customer> customersTable;


    @Inject
    protected ButtonsPanel buttonsPanel;

    @Override
    public Table getListComponent() {
        return customersTable;
    }

    @Override
    public ButtonsPanel getButtonsPanel() {
        return buttonsPanel;
    }
}

This interface will create a button in the buttonsPanel of the table and add the share button after the default CUBA buttons.

Send System Messages (programmatically)

The other way to send a message to a user is that the developer defines points in the application, where it is useful to notify some user about a particular thing happened. This can be various actions, like:

a new Customer has been created
an order was placed with a total amount > 10k
an import of data through an API was successful
...

There are lot of things that might happen in the lifecycle of an application that are worth to notify.

To send a message to user programmatically, there is a MessageService which will allow exactly this. The interface of this service looks like this:

public interface MessageService {

    void sendSystemMessage(User receiver, String subject, String messageText);
    
    void sendSystemMessage(User receiver, String subject, String messageText, Entity entityReference);

}

sendSystemMessage will add a message in the given receivers inbox with a subject, a text and an optional entity reference.

Using pre-defined Main Window Screens

This application component comes with multiple options for the main screens, that can be used in the final application.

UserInboxSideMenuMainScreen (userInboxSideMenuMainScreen) (CUBA 7 based Side Menu)
SideMainwindowWithMessages (sideMainWindowWithMessages) (CUBA 6 based Side Menu)
AppMainWindowWithMessages (appMainWindowWithMessages) (CUBA 6 based Main Menu)

One of these classes can be used as the main screen via web-app.properties:

cuba.web.mainScreenId=appMainWindowWithMessages

Custom Main Screen

In case you are using a custom main screen, you will need to add a Timer to the descriptor:

        <timer id="updateCountersTimer" delay="3000"  autostart="true" repeating="true" />

Then, the following logic has to be implemented to leverage the menu entry and the automatic reload of the new messages:

import de.diedavids.cuba.userinbox.web.screens.UserInboxMessageMenuBadge;

public class CustomApplicationMainScreen extends MainScreen {

    @Inject
    protected SideMenu sideMenu;
    @Inject
    protected Timer updateCountersTimer;

    @Inject
    protected UserInboxMessageMenuBadge userInboxMessageMenuBadge;

    @Subscribe
    protected void onInit(InitEvent event) {
        userInboxMessageMenuBadge.initMessagesMenuItem(
                sideMenu,
                updateCountersTimer,
                this
        );
    }

    @Subscribe
    protected void onAfterShow(AfterShowEvent event) {
        userInboxMessageMenuBadge.updateMessageCounter(sideMenu);
    }

    @Subscribe("updateCountersTimer")
    protected void onUpdateCountersTimerTimerAction(Timer.TimerActionEvent event) {
        userInboxMessageMenuBadge.updateMessageCounter(sideMenu);
    }
}

Unread Messages Counter in pre-defined Main Window Screens

In order to display the messages that are marked as unread, the main windows will be refreshed in a particular interval. The logic is the same as the Count script which is available within the Application Folders feature of CUBA itself.

Therefore the refresh period can be adjusted by the existing application property: cuba.web.appFoldersRefreshPeriodSec in the web-app.properties file.

saijun97 / cuba-component-user-inbox