Blogs

Inter Portlet Communication (IPC) is a way of exchange the data between portlets. In Liferay there are different ways we can achieve this. One of them is the client-side IPC that is supported by LIMS MUC. In other words, you may e.g. open a conversation or read user presence from your own portlet. There is only one limitation. Since the communication is client-side LIMS needs to be on the page together with your portlet.

This tutorial is also available on the official LIMS website.

Enable IPC in Admin Area Panel

By default the IPC is turned off. To turn it on go to the Admin Area panel (you need to be an omni admin) and enable it.

Sample IPC for LIMS Messenger

Before we start the tutorial take a look at the Sample IPC for LIMS Messenger project available on Github: https://github.com/marcelmika/sample-lims-ipc. Especially the main.js file that contains the main client-side IPC logic. The WAR file is available here. If you deploy the sample portlet and drag it to the page you should see something similar to this:

Wait Until the Portlet is Ready

As we mentioned before, the communication with LIMS can be established only if the portlet is rendered on the page and ready to go. LIMS will fire the lims:ready event when it's ready to listen to the IPC calls. Thus you should always wrap your IPC communication to the following code:

Liferay.on('lims:ready', function () {
    // Call IPC
});

As you can see all the request are going to be called on the Liferay global object. Thanks to this approach all portlets on the page can listen to events. Also take a look at the lims: prefix which is used to avoid collisions with other portlets using IPC as well.

Create Conversation

If you want to create a conversation, call the lims:createConversation event.

// Create IPC request
Liferay.fire('lims:createConversation', {

    // Input data is an array of users ids with whom you want to 
    // create the conversation. If you pass one id a Single User Chat (SUC) 
    // conversation will be created. If you you pass more than one id 
    // a Multi User Chat (MUC) conversation will be created.
    data: [10434, 10567],

    // Called on request success
    success: function (response) {

        // You're code on success. The response object contains id 
        // of the conversation in the case you want to store it somewhere

    },

    // Called on request failure
    failure: function (code, reason) {

        // You may want to show an error message or do something else.
        // Code contains error code and reason contains human readable 
        // reason of the failure

    }
});

The IPC calls have three major properties:

• data - input data, in this case a list of user ids
• success - method that will be called on success with a response object
• failure - method that will be called on failure with code and reason message

Note that if you pass just your own id (e.g. 10434) LIMS will detect it and doesn't let you create a SUC with yourself. However, if you pass two ids where one is your own (e.g. 10434, 10567) a SUC with user 10567 will be created. Similarly, if you pass three ids (e.g. 10434, 10567 and 10789) a MUC with user 10567 and 10789 will be created. Note that you don't need to pass your user id if you want to create MUC conversation. LIMS always adds creators of the conversation to the participant list.

Success

If the conversation is successfully created a response object is passed as a parameter of the success function.

response = {
    conversationId: "jane.austen_woody.allen"
}

Failure

If anything fails, the failure method is called. This method will provide you with the error code and the human readable reason of failure. Possible failures are:

code: 4000 - you provided wrong input
code: 4002 - you wanted to create SUC conversation with yourself
code: 5000 - server returned error, take a look on the reason message

Read Presence

If you want to read user presence, call the lims:createConversation event.

// Create IPC request
Liferay.fire('lims:readPresence', {

    // Input data is an array of users ids of whom you want to read the presence.
    data: [10434, 10567],

    // Called on request success
    success: function (response) {

        // You're code on success. The response object contains an array of 
        // objects with user id and presence.

    },

    // Called on request failure
    failure: function (code, reason) {

        // You may want to show an error message or do something else.
        // Code contains error code and reason contains human readable reason
        // of the failure

    }
});

Note that you can read up to 100 user presences at once. If you want to read more you will need to call the event multiple times.

Success

If the conversation is successfully created a response object is passed as a parameter of the success function.

response = [{
    userId: 10434,
    // Possible values are:
    // ACTIVE - user is online (green)
    // AWAY - user is busy (yellow)
    // DND - user is unavailable (red)
    // OFFLINE - user is offline or turned off the chat (grey)
    // UNRECOGNIZED - such user doesn't exist or hasn't logged into the portal yet
    presence: "ACTIVE"
}, {
   userId: 10567,
   presence: "DND"
}]

Failure

If anything fails, the failure method is called. This method will provide you with the error code and the human readable reason of failure. Possible failures are:

code: 4000 - you provided wrong input
code: 4001 - you wanted to read more than 100 presences
code: 5000 - server returned error, take a look on the reason message