Version: 10

Customize the item list in the Agent Inbox panel

Level: intermediate

Besides chats and calls, agents might work with other records that are specific to how your company works with customers, for example, records of a custom object. You can customize the item list of the Agent Inbox panel to let agents handle records of any object together with chats and calls. For example, show records of a custom object in the In progress list, open the record page when an agent clicks the tile, and highlight records that need attention. To do this, extend the "Agent side bar" (AgentSideBar code) schema of the "Client module" type. The Agent Inbox panel is built on the Omnichannel inbox component and its child components, for example, the Item list component that shows the tiles. Learn more: Omnichannel inbox component.

Add a data source to the item list

The item list shows records of the data sources whose collections are merged into the list attribute. The New items list uses the NewItemsList attribute, and the In progress list uses the InProgressItemsList attribute.

To add a data source to the item list:

Open the Contact Center app in the Application Designer.
Open the Agent side bar page.
Click → Source code to open the source code of the Freedom UI page.

Set up the data source.

Go to the modelConfigDiff schema section.

Add a data source of the crt.EntityDataSource type.

modelConfigDiff schema section
modelConfigDiff: /**SCHEMA_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["dataSources"],
        "values": {
            /* Name of the data source. */
            "UsrCustomObjectDS": {
                "type": "crt.EntityDataSource",
                "scope": "page",
                "config": {
                    /* Code of the object whose records to show. */
                    "entitySchemaName": "UsrCustomObject",
                    "loadParameters": {
                        "options": {
                            "pagingConfig": {
                                /* Number of records to load per
                                page. */
                                "rowCount": 10,
                                "rowsOffset": -1
                            },
                            /* Order to load the records. */
                            "sortingConfig": {
                                "columns": [
                                    {
                                        "columnName": "ModifiedOn",
                                        "direction": "desc"
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        }
    }
]/**SCHEMA_MODEL_CONFIG_DIFF*/,

Set up the collection attribute.

Go to the viewModelConfigDiff schema section.
Add the collection attribute that binds the data source columns to the view model.

Add the collection attribute to the from property of the list attribute. The merge operation replaces arrays entirely. When you add a collection to the from property of the list attribute, list the out-of-the-box collections as well. Otherwise, the list does not show chats and calls.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            /* Name of the collection attribute. */
            "UsrCustomObjectItems": {
                "isCollection": true,
                "modelConfig": {
                    "path": "UsrCustomObjectDS"
                },
                "viewModelConfig": {
                    "attributes": {
                        "Id": {
                            "modelConfig": {
                                "path": "UsrCustomObjectDS.Id"
                            }
                        },
                        /* The "crt.MergeCollectionsConverter" converter
                        sorts the merged items by this attribute. If you
                        do not specify the attribute, Creatio shows the
                        records of the object at the end of the "In
                        progress" list and at the beginning of the "New
                        items" list. Use the same data type as the
                        out-of-the-box collections. Otherwise, the sort
                        order is unpredictable. */
                        "ModifiedOn": {
                            "modelConfig": {
                                "path": "UsrCustomObjectDS.ModifiedOn"
                            }
                        },
                        /* Attribute for each column that the tile
                        shows. */
                        "Title": {
                            "modelConfig": {
                                "path": "UsrCustomObjectDS.UsrName"
                            }
                        }
                    }
                }
            },
            /* "NewItemsList" for the "New items" list. */
            "InProgressItemsList": {
                /* The converter of the "AgentSideBar" schema sorts the
                merged items by the "ModifiedOn" attribute: in
                descending order for the "In progress" list and in
                ascending order for the "New items" list. To change the
                sort order of the merged items, specify the "converter"
                property, for example,
                "crt.MergeCollectionsConverter:'ModifiedOn':'asc'." */
                "from": [
                    /* Out-of-the-box collections. For the "New items"
                    list, "ChatsNewItems." */
                    "ChatsInProgressItems",
                    "CallsInProgressItems",
                    /* Collection attribute of the data source. */
                    "UsrCustomObjectItems"
                ]
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Add a tile template.

Go to the viewConfigDiff schema section.

Add the tile template to the list. Use a layout element, for example, a Flex container layout element, whose child elements show the item data.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "insert",
        /* Name of the data source. */
        "name": "UsrCustomObjectDS",
        "values": {
            "type": "crt.FlexContainer",
            "direction": "row",
            "items": [
                {
                    "type": "crt.Label",
                    "name": "UsrCustomObjectTileTitleLabel",
                    /* Bind to the collection attribute, not to the
                    data source. */
                    "caption": "$UsrCustomObjectItems.Title",
                    "labelEllipsis": true
                },
                {
                    "type": "crt.Label",
                    "name": "UsrCustomObjectTileTimestampLabel",
                    "caption": "$UsrCustomObjectItems.ModifiedOn | crt.AdaptiveDateTimeFormat"
                }
            ]
        },
        /* List name. "NewItemsList" for the "New items"
        list. */
        "parentName": "InProgressItemsList",
        "propertyName": "items"
        /* Without the "index" property, Creatio adds the template
        after the out-of-the-box templates. */
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Save the changes.

As a result, the In progress list of the Agent Inbox panel shows the records of the object together with chats and calls. Creatio sorts the chats and the records of the object by the modification date: in descending order for the In progress list and in ascending order for the New items list. The collection of calls does not include the modification date, so Creatio shows calls at the end of the In progress list.

Set up the tile of queue items

For Creatio version 10X, the Queued tasks tab shows the queue items of the queues available to the agent, regardless of the assignee. For Creatio version 10.1, the tab shows the unassigned queue items of the queues available to the agent and the queue items assigned to the agent in any queue. In all versions, the tab shows only items that are not in a final status and whose postponement date has passed. Unlike the lists of the Real-time tab, the list of queue items does not use a separate data source for each object. Instead, Creatio reads the columns of each object from the QueueItemsColumns attribute. Out of the box, the tile shows the primary display column of the object as the title. To show other columns, map them to the tile elements. A queue is available to the agent if it is in progress, its object is in the Queue objects lookup and is not marked as a closed queue, and the agent is an active operator of the queue or is assigned to one of its queue items.

To set up the tile of queue items:

Add the object to the Queue objects lookup and make sure the object is not marked as a closed queue. Otherwise, Creatio does not show the queue items of this object, except for the items assigned to the agent in version 10.1. Instructions: Manage queue objects (user documentation).
Create a queue for the object. Instructions: Create a dynamic queue, Create a static queue (user documentation).
Open the Contact Center app in the Application Designer.
Open the Agent side bar page.
Click → Source code to open the source code of the Freedom UI page.

Add the column mapping of the object.

Go to the handlers schema section.

Add a custom implementation of the crt.HandleViewModelInitRequest base request handler.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    ...,
    {
        request: "crt.HandleViewModelInitRequest",
        /* The custom implementation of the base request handler. */
        handler: async (request, next) => {
            /* Wait for the rest of the initialization handlers to
            finish. */
            await next?.handle(request);
            const columnsMapping = await request.$context["QueueItemsColumns"];
            if (columnsMapping) {
                /* Column mapping of the object. */
                columnsMapping.push({
                    "entitySchemaName": "UsrCustomObject",
                    /* Each item maps a column of the object to a tile
                    element. */
                    "columns": [
                        {
                            /* Tile element: "TitleLabel,"
                            "DescriptionLabel," "TimeLabel,"
                            "ContactName," or "ContactPhoto." */
                            "attributeName": "TitleLabel",
                            "name": "UsrName",
                            /* Column path from the queue item to the
                            object record. */
                            "path": "[UsrCustomObject:Id:EntityRecordId].UsrName"
                        },
                        {
                            "attributeName": "TimeLabel",
                            "name": "CreatedOn",
                            "path": "[UsrCustomObject:Id:EntityRecordId].CreatedOn"
                        }
                    ]
                });
            }
        }
    }
]/**SCHEMA_HANDLERS*/,

Save the changes.

As a result, the tiles of the queue items on the Queued tasks tab of the Agent Inbox panel show the mapped columns of the object.

Set up the tile click behavior

When an agent clicks a tile on the Real-time tab, Creatio executes the crt.BaseAgentItemClickedRequest request. The out-of-the-box handler of the request opens the chats of the In progress list and does nothing for the chats of the New items list. For calls and other items, it selects the item and, in split mode, hides the item list. Creatio shows a selected call in the item view but does not show other items there. Handle the click on the tiles of your data source in a custom handler. Creatio opens the record page in place of the page that is open in the main area and does not ask the agent to save the changes on that page. Make sure agents save their changes before they click a tile.

To set up the tile click behavior:

Add a data source to the item list. Instructions: Add a data source to the item list.

Add the dependencies.

Add the @creatio-devkit/common library as a dependency.

Add the sdk argument.

Schema dependencies
define("AgentSideBar",
    /**SCHEMA_DEPS*/["@creatio-devkit/common"]/**SCHEMA_DEPS*/,
    function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
})

Add a request handler.

Go to the handlers schema section.

Add a custom implementation of the crt.BaseAgentItemClickedRequest base request handler.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    ...,
    {
        request: "crt.BaseAgentItemClickedRequest",
        /* The custom implementation of the base request handler. */
        handler: async (request, next) => {
            /* Check the name of the data source of the clicked item. */
            if (request.collectionName !== "UsrCustomObjectDS") {
                /* Call the next handler if it exists and return its
                result. This keeps the out-of-the-box behavior of chats
                and calls. */
                return next?.handle(request);
            }
            /* Retrieve the instance of the handler chain service from
            "@creatio-devkit/common." Do not call the next handler for
            items of the data source. If the next handler is not
            called, Creatio does not change the selected item and, in
            split mode, does not hide the item list. */
            const handlerChain = sdk.HandlerChainService.instance;
            /* Send the base request to open the record page. Creatio
            opens the page in the main area, in place of the page that
            is currently open there. Creatio does not check that page
            for unsaved changes. */
            await handlerChain.process({
                type: "crt.UpdateRecordRequest",
                $context: request.$context,
                entityName: "UsrCustomObject",
                recordId: request.id
            });
        }
    }
]/**SCHEMA_HANDLERS*/,

Save the changes.

As a result, if an agent clicks a tile of the data source in the Agent Inbox panel, Creatio opens the record page in the main area. Chats and calls open as before.

Filter the items in the list

Add a data source to the item list. Instructions: Add a data source to the item list.

Add a filter attribute.

Go to the viewModelConfigDiff schema section.

Add the filter attribute. Set the filter in the value property using the Creatio filter format.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            "UsrCustomObjectItemsFilter": {
                /* Records whose owner is the current user. */
                "value": {
                    "isEnabled": true,
                    "trimDateTimeParameterToDate": false,
                    "filterType": 6,
                    "logicalOperation": 0,
                    "items": {
                        "OwnerFilter": {
                            "filterType": 1,
                            "comparisonType": 3,
                            "isEnabled": true,
                            "leftExpression": {
                                "expressionType": 0,
                                /* Column of the object that references
                                the "Contacts" section. */
                                "columnPath": "UsrOwner"
                            },
                            "rightExpression": {
                                "expressionType": 1,
                                "functionType": 1,
                                /* Contact of the current user. To
                                compare the column with the current
                                user, use "1" and the "SysAdminUnit"
                                reference schema. */
                                "macrosType": 2
                            },
                            "dataValueType": 10,
                            "referenceSchemaName": "Contact"
                        }
                    },
                    "rootSchemaName": "UsrCustomObject"
                }
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Bind the filter to the collection.

Go to the viewModelConfigDiff schema section.

Add the filter attribute to the filterAttributes property of the collection attribute.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            "UsrCustomObjectItems": {
                "modelConfig": {
                    "filterAttributes": [
                        {
                            "name": "UsrCustomObjectItemsFilter",
                            /* Reload the collection when the filter
                            changes. */
                            "loadOnChange": true
                        }
                    ]
                },
                ...
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

To build the filter dynamically, compute the value of the filter attribute using a custom converter. Use the "usr." prefix in the converter name. Learn more: "converters" schema section.

Save the changes.

As a result, the item list shows only the records of the object that match the filter.

Show a custom state on the tile

Add a data source to the item list. Instructions: Add a data source to the item list.

Add the attribute of the state.

Go to the viewModelConfigDiff schema section.

Add the attribute that binds the column of the state to the viewModelConfig.attributes property of the collection attribute.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            "UsrCustomObjectItems": {
                ...,
                "viewModelConfig": {
                    "attributes": {
                        ...,
                        /* Attribute for the "UsrIsUrgent" column of the
                        "Boolean" type. */
                        "UsrIsUrgent": {
                            "modelConfig": {
                                "path": "UsrCustomObjectDS.UsrIsUrgent"
                            }
                        }
                    }
                }
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Add an element of the state.

Add a localizable string that stores the caption of the element. For example, set the code of the string to "UsrCustomObjectTileUrgentLabel_caption." Instructions: Add a localizable string.
Go to the viewConfigDiff schema section.

Add the element that shows the state, for example, a Label component, to the tile template. Bind the visible property of the element to the attribute of the state.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "insert",
        "name": "UsrCustomObjectTileUrgentLabel",
        "values": {
            "type": "crt.Label",
            "caption": "#ResourceString(UsrCustomObjectTileUrgentLabel_caption)#",
            /* Bind to the collection attribute, not to the data
            source. */
            "visible": "$UsrCustomObjectItems.UsrIsUrgent | crt.ToBoolean"
        },
        /* Name of the tile template. */
        "parentName": "UsrCustomObjectDS",
        "propertyName": "items"
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

To show time-based states, use the Timer component. Learn more: Set up Timer components (user documentation).

Save the changes.

As a result, the tile shows the element of the state for the records that match the condition, for example, for urgent records.

Add a data source to the item list​

Set up the tile of queue items​

Set up the tile click behavior​

Filter the items in the list​

Show a custom state on the tile​

See also​

Add a data source to the item list

Set up the tile of queue items

Set up the tile click behavior

Filter the items in the list

Show a custom state on the tile

See also