PCF – Use “ConversationControl”

A few weeks ago, I have published a new PCF Control, “ConversationControl” (Github, PCFGallery, my Page). Since the release, I received one or two questions on how to use the control. It looks like it is not as straight forward as I thought. In this post, I will describe the use case of the control as well as how to configure and use it.

Use case

Let me begin by explaining the use case of this control.

Let’s assume we do handle all correspondence with our customers via CDS. To do this we created a custom entity (an activity actually) that holds all the messages sent to and received from the customer. For the demo, I created a second entity, “Custom Incident”, which is activated for activities.

The Customer can see all the messages by logging in to a custom website/portal. This can be designed completely free and shown in a nice way.

For the user who is working in a Model-Driven App (MDA) it is a different story. Usually, we show all the related custom messages as a subGrid on the related main entity (custom incident).

This is not very user friendly or readable and needs a better layout. That is where the “ConversationControl” comes in the picture.

One of our community members (Nicolai Schjørmann) reached out to me with an additional use case. They would like to visualize the conversation between two different departments inside of the same organization.

There might be additional difficulties to implement this. For example, the sender and receiver are changing depending on who the viewer is.

We might release a cooperative blog post about this use case.

Prerequisites

To use the control, we do need two entities

Custom Message

This entity will, as described earlier, represent every message sent to or received from the customer and will be related to the “custom incident” entity. In the demo, described in this post, it will be a custom activity entity.

Custom Incident

The sole purpose of this entity is to have one place (or the parent) to all the messages in a conversation. This could be any other entity that is configured for activities. I have chosen a custom entity only for demo purposes.

Base configuration

We will start with the base configuration of the control. This is the minimum required configuration to get the control working.

Required fields on “Custom Message”

The first thing we will configure is the custom activity entity, message. I do assume you have created this entity already and will only describe what is needed for the “ConversationControl”. The control requires two fields on the entity.

Text Field

The field that holds the data that should be shown as the message text. In our demo we will use the “description” field of the activity entity

Sender Field

The field that holds the information who the sender of the message was. This must be an OptionSet. The field name, in my example, is “bebe_sender”.

View on “Custom Message”

The next step is to configure/create the view we will later use in the subGrid.

Important: Every field you would like to use in the control has to be added to the view.

Since we are doing the base configuration the view only needs to contain the two fields. Those are the two above mentioned once (Text field and sender field).

Since the order of the messages in the PCF will be the same as in the view, I also have added the “createdOn” field and sorted the view by this field ascending (“Older to newer”). This will show the messages in the order they would appear in a chat app (newest message at the bottom).

Form on “Custom Incident”

For the demo purpose I configured two subGrids on the main form of the “Custom Incident” entity.

Both of the subGrids show all related custom messages with the view we created earlier; in my case it’s called “Base”.

Configure the PCF Control

To configure the PCF control, we must switch to the classic UI. Unfortunately, this is not yet implemented in the UCI.

To add the control, we open the configuration “pop up” of the second subGrid and switch to the “Controls” tab. There you have to use the “Add Control…” button.

In the new popup you have to choose the “Conversation Control”, select it and press “Add”.

Now we have configured the PCF as our control of the subGrid. Let’s start with the real configuration.

If you press the little pencil beside the “Text column” configuration a pop up will open. Here you type your desired field name (schema name) in the first input field. In my case, it is “description”

The same you do for the sender field. For me it is “bebe_sender”. It’s important to at least check the checkbox for the web client at the top.

If you scroll a bit down you will find one more field that is required but empty, Customer Identifier. This seems to be the tricky part now. You remember the sender OptionSet you created? This field should contain the value of this field that identifies whether the sender was the customer. You can find out what the value is by opening your optionSet. If you click the three dots beside your customer item, you do have one choice called “View more”. It will show you the value.

For the configuration field you should use this value without the commas. So, for my example it would be “136980000”.

If you have several values that identify the customer, you can fill the configuration with a comma separated list of ids.

If you save and publish everything the subGrid should look like this.

Additional Configuration

Now that the basic configuration is working, we can add some more information to the control.

Fields

All the following fields are on the custom message entity. As mentioned earlier you need to add all the fields you will use to the view.

The following fields could be configured

Date column

The field that should be shown as the date in the message. I usually use “createdOn”.

Read column

The field that indicates whether the customer read the messages. It could be any type. If it contains a value it will be considered at read.

Published column

The field that indicates whether the messages was send. It could be any type. If it contains a value it will be considered at sent.

Has attachments column

A two-option field that indicates whether the message contains attachments.

General Configuration

The following configurations are done on the control level. You do not have to add those to the view.

Show Scrollbar

Defines whether to show the scrollbar. If you choose to not show the scrollbar the control will expand to use as much space as needed to show all the messages.

Max height

The maximum height the conversation should have before the scrollbar appears. Will only have effect if the scrollbar is shown.

Open Strategy

Indicates how the message should be opened if the user clicks it in the conversation. You could choose out of four options.

• Modal Center: The record will be opened in a centered modal.
• Modal right: The record will be opened in a modal that is sticks to the right side of the browser.
• New Window: The record will be opened in a new window.
• Current Tab: The record will be opened in the current tab.

Modal width

If you choose one of the first two options as the open strategy this option will define the width (in percentages) the modal should have.

If you configure all of them your subGrid should look like this.

Customization

Like you properly noticed are there some more configurations left. With those you can customize the colors of various parts of the control. All of them accept CSS color definitions (either hex or rgb).

You can customize the following things

• Background color of received messages
• Background color of outgoing messages
• Background color of outgoing messages which are not yet published
• Text color of received messages
• Text color of outgoing messages
• Text color of outgoing messages (unpublished)
• Metadata color of received messages
• Metadata color of outgoing messages
• Metadata color of outgoing messages (unpublished)
• The checkmark color if the messages was read

If you configure all or some of them you control could look like this

Advanced configuration

In the last release (v. 1.9.4) of the control I have added the possibility for a rather advanced configuration.

With the control configuration “Use Subgrid Data” it is now possible to configure the control in a way to not use the data that will be provided by the subgrid. Instead the control will load the needed data via the WebApi.

Use case

This may sound like a weird thing to do. Let me explain the use case we had.

The customer would like to be able to see the conversation even on the message form. This would mean to have a subgrid on the message form that shows all the messages that are related to the “parent” Case/Conversation entity. All the messages are activities and “only” related to the Case/Conversation entity via the “regardingobject” field. Since there is no relation between messages and messages, most certainly no N:N relation, it is not possible to show a subgrid that contains the correct data.

Since “quick view forms” are read-only they do not support PCF controls at the moment. That is why those are unfortunately no option either.

This solution is only a workaround until Microsoft releases the new "form component". Those will make it possible to have fully functional forms inside of forms and support PCF. The "form components" will hopefully be released in Release 2020 Wave 2

Function

That’s where the new functionality comes in the game. The new functionality ignores the data present in the subgrid and loads the needed data itself. It will construct a fetchXml to load all the different fields that were configured earlier. At the moment it is only working with activity entities.

Configuration

The configuration is not more than switching the “Use Subgrid Data” from “Yes” to “No” and providing the schema name of the activity entity that should be loaded in the control configuration “Entity Name”.

Add message button

There is actually one thing that might be a bit complicated. The Control shows the standard “add” button.

To get this working properly we have to add a relation between our message entity and our message entity. In the relation mapping we add a mapping from “regardingobject” to “regardingobject”. The last step is to show a subgrid with the related messages on the message form.

After that, the “add” button will add another message that will have the regarding object prefilled correctly.

Delimitation

The control has some delimitations.

• It only supports one entity at the moment
• The order is defined by the view
• All used fields must be in the view

Conclusion

The control is a fantastic way of displaying a conversation in a user-friendly way. It could be difficult to understand the configuration at the beginning. But it can be highly customized if you have figured it out.

I hope this blog post helped. Please let me know what you think and if you any questions. I am always happy to help.