REST Collection Objects

Finesse JavaScript library provides REST collection objects, which is a collection of Finesse REST API objects. For instance, a User is a Finesse JavaScript REST object, and Users is a Finesse JavaScript REST collection object, which can hold multiple User objects.

Significance of REST Collection Object

To understand the significance of a REST collection object, consider the example of all the Dialogs associated with a User in a grid.

A Dialog is a JavaScript representation of a call. It can be a regular phone call, a conference, or a silent monitor session. A User object can be composed of many other objects, one of which is the Dialogs object. Note that it is Dialogs and not Dialog. This is because a user can be involved in multiple calls.

Copyvar _user = new finesse.restservices.User({
    id: '1001001', // user id
    onLoad: function(user) {

        // User has successfully loaded, now get User Dialogs
        user.getDialogs({
            onLoad: function(dialogs) {
                // successfully loaded the dialogs collection object, now format and display in the grid var dialogCollection = dialogs.getCollection();
                for (dialogId in dialogCollection) {
                    if (dialogCollection[dialogId] instanceOf finesse.restservices.Dialog) {
                        // each item in the Dialogs Collection will be an instance of Dialog object.
                        // can format and display each record here.
                    }
                }
            }
            // for the sake of simplicity of this example, not adding other handlers.
        });
    }
});

In the above example, after the User has successfully loaded, you call the getDialogs() API of the User object to get the Dialogs collection object and perform certain operations on it before you display it in a grid. Note that we did not explicitly initialize the Dialogs collection object. The getDialogs() API of the User object did it for us internally.

You do not have to explicitly create the collection objects. All the JavaScript REST objects which are composed of such collection object provides certain APIs which are internally taken care of initializing the objects. You must provide the handlers to control once the collection is loaded, modified, or deleted. The following are some examples of APIs which internally initialize and return respective REST collection objects.

Copy_team.getUsers // Team REST API Object is composed of a Users Collection Object.(Users who are the part of that team)
_user.getMediaList // User REST API Object is composed of MediaList Collection Object.
_user.getQueues // User REST API Object is composed of Queues Collection Object.
_team.getTeamMessages // Team REST API Object is composed of a TeamMessages Collection Object.

Consider the Dialogs in a grid example to include a feature where the grid updates in real-time if any new dialog shows up or any existing dialog gets removed. REST collection objects also provide multiple handlers. The following example shows two new handlers provided by the collection object onCollectionAdd and onCollectionDelete that are triggered when an item is added or removed respectively.

Example—Multiple Handlers

Copyuser.getDialogs({
    onLoad: function(dialogs) {},
    onCollectionAdd: function(dialog) {
        // called when a new Dialog is added to the collection
        // add this new dialog to the Grid
    },
    onCollectionDelete: function(dialog) {
        // called when a new Dialog is removed from the collection
        // remove this dialog from the Grid
    }
});

Commonly used REST collection object handlers are:

• onLoad—Triggers when the collection object is successfully loaded.

• onCollectionAdd—Triggers when a new item is added to the collection.

• onCollectionDelete—Triggers when a item is deleted from the collection.

• onError—Triggers when some error occurs during any of the above operations.