Customize entity views
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Entity views are special saved queries that retrieve data by using a specific filter. They also contain information about how the data in the view should be displayed in the application. Entity views are SavedQuery records that you can create programmatically. You can also define them as XML, and import them into Microsoft Dynamics 365 with an unmanaged solution.
An Entity view is different from a UserQuery. A user query, called a Saved view in the application, is owned by an individual user, can be assigned and shared with other users, and can be viewed by other users depending on the query's access privileges. This is appropriate for frequently used queries that span entity types and queries that perform aggregation. More information: UserQuery (saved view) entity
You can also use the customization tool in Dynamics 365 to customize views. More information: TechNet: Create and edit views
In This Topic
Types of views
View tasks
Create views
Update views
Delete views
Retrieve views
Deactivate views
Edit filter criteria or configure sorting
Edit columns
Add custom icons with tooltip for a column
Set as default
Types of views
The following table lists the five types of views that are supported for customization. The type code of a view is stored in the SavedQuery.QueryType attribute. Note that there are other valid values for the QueryType attribute not listed here because this entity is also used to store Microsoft Office Outlook filters and templates. For more information, see Offline and Outlook filters and templates.
When views are defined for a specific entity, the SavedQuery.ReturnedTypeCode attribute returns the entity logical name.
View Type |
Type Code |
Description |
|---|---|---|
Public |
0 |
|
Advanced Find |
1 |
|
Associated |
2 |
|
Quick Find |
4 |
|
Lookup |
64 |
|
View tasks
Because views are SavedQuery records, you can create, update, retrieve, delete and deactivate them. In addition you can edit filter criteria or configure sorting, edit columns or set a view as a default view.
Create views
To create a public view, specify the following properties:
SavedQuery.Name: A unique identifier for the saved query.
SavedQuery.ReturnedTypeCode: Matches the logical name of the entity.
SavedQuery.FetchXml: See Use FetchXML to construct a query.
SavedQuery.LayoutXml: See <layoutxml> (SavedQuery) for the valid elements.
SavedQuery.QueryType: Must always be zero (0).
The following sample creates a new public view for the opportunity entity:
System.String layoutXml =
@"<grid name='resultset' object='3' jump='name' select='1'
preview='1' icon='1'>
<row name='result' id='opportunityid'>
<cell name='name' width='150' />
<cell name='customerid' width='150' />
<cell name='estimatedclosedate' width='150' />
<cell name='estimatedvalue' width='150' />
<cell name='closeprobability' width='150' />
<cell name='opportunityratingcode' width='150' />
<cell name='opportunitycustomeridcontactcontactid.emailaddress1'
width='150' disableSorting='1' />
</row>
</grid>";
System.String fetchXml =
@"<fetch version='1.0' output-format='xml-platform'
mapping='logical' distinct='false'>
<entity name='opportunity'>
<order attribute='estimatedvalue' descending='false' />
<filter type='and'>
<condition attribute='statecode' operator='eq'
value='0' />
</filter>
<attribute name='name' />
<attribute name='estimatedvalue' />
<attribute name='estimatedclosedate' />
<attribute name='customerid' />
<attribute name='opportunityratingcode' />
<attribute name='closeprobability' />
<link-entity alias='opportunitycustomeridcontactcontactid'
name='contact' from='contactid' to='customerid'
link-type='outer' visible='false'>
<attribute name='emailaddress1' />
</link-entity>
<attribute name='opportunityid' />
</entity>
</fetch>";
SavedQuery sq = new SavedQuery
{
Name = "A New Custom Public View",
Description = "A Saved Query created in code",
ReturnedTypeCode = "opportunity",
FetchXml = fetchXml,
LayoutXml = layoutXml,
QueryType = 0
};
_customViewId = _serviceProxy.Create(sq);
Console.WriteLine("A new view with the name {0} was created.", sq.Name);
Update views
If the SavedQuery.IsCustomizable managed property allows the view to be updated, you can use the IOrganizationService.Update method or the UpdateRequest message to update the view.
Delete views
You should only delete saved queries that you have created. A solution component or part of the application may depend on a specific saved query. If there are queries you do not want to appear in the application, you should deactivate them.
Retrieve views
Use a RetrieveMultipleRequest or IOrganizationService.RetrieveMultiple to retrieve saved query records.
The following sample retrieves all the public views for the opportunity entity:
QueryExpression mySavedQuery = new QueryExpression
{
ColumnSet = new ColumnSet("savedqueryid", "name", "querytype", "isdefault", "returnedtypecode", "isquickfindquery"),
EntityName = SavedQuery.EntityLogicalName,
Criteria = new FilterExpression
{
Conditions =
{
new ConditionExpression
{
AttributeName = "querytype",
Operator = ConditionOperator.Equal,
Values = {0}
},
new ConditionExpression
{
AttributeName = "returnedtypecode",
Operator = ConditionOperator.Equal,
Values = {Opportunity.EntityTypeCode}
}
}
}
};
RetrieveMultipleRequest retrieveSavedQueriesRequest = new RetrieveMultipleRequest { Query = mySavedQuery };
RetrieveMultipleResponse retrieveSavedQueriesResponse = (RetrieveMultipleResponse)_serviceProxy.Execute(retrieveSavedQueriesRequest);
DataCollection<Entity> savedQueries = retrieveSavedQueriesResponse.EntityCollection.Entities;
//Display the Retrieved views
foreach (Entity ent in savedQueries)
{
SavedQuery rsq = (SavedQuery)ent;
Console.WriteLine("{0} : {1} : {2} : {3} : {4} : {5},", rsq.SavedQueryId, rsq.Name, rsq.QueryType, rsq.IsDefault, rsq.ReturnedTypeCode, rsq.IsQuickFindQuery);
}
Deactivate views
If you do not want a public view to appear in the application, you can deactivate it. You cannot deactivate a public view that is set as the default view. The following sample deactivates the Closed Opportunities in Current Fiscal Year view for the Opportunity entity:
System.String SavedQueryName = "Closed Opportunities in Current Fiscal Year";
QueryExpression ClosedOpportunitiesViewQuery = new QueryExpression
{
ColumnSet = new ColumnSet("savedqueryid", "statecode", "statuscode"),
EntityName = SavedQuery.EntityLogicalName,
Criteria = new FilterExpression
{
Conditions =
{
new ConditionExpression
{
AttributeName = "querytype",
Operator = ConditionOperator.Equal,
Values = {0}
},
new ConditionExpression
{
AttributeName = "returnedtypecode",
Operator = ConditionOperator.Equal,
Values = {Opportunity.EntityTypeCode}
},
new ConditionExpression
{
AttributeName = "name",
Operator = ConditionOperator.Equal,
Values = {SavedQueryName}
}
}
}
};
RetrieveMultipleRequest retrieveOpportuntiesViewRequest = new RetrieveMultipleRequest { Query = ClosedOpportunitiesViewQuery };
RetrieveMultipleResponse retrieveOpportuntiesViewResponse = (RetrieveMultipleResponse)_serviceProxy.Execute(retrieveOpportuntiesViewRequest);
SavedQuery OpportunityView = (SavedQuery)retrieveOpportuntiesViewResponse.EntityCollection.Entities[0];
_viewOriginalState = (SavedQueryState)OpportunityView.StateCode;
_viewOriginalStatus = OpportunityView.StatusCode;
SetStateRequest ssreq = new SetStateRequest
{
EntityMoniker = new EntityReference(SavedQuery.EntityLogicalName, (Guid)OpportunityView.SavedQueryId),
State = new OptionSetValue((int)SavedQueryState.Inactive),
Status = new OptionSetValue(2)
};
_serviceProxy.Execute(ssreq);
Edit filter criteria or configure sorting
To edit the filter or edit how the data is sorted, you must set the SavedQuery.FetchXml attribute. For more information, see Build queries with FetchXML.
Tip
If you are not familiar with FetchXML the following messages can be used to convert between QueryExpression and FetchXML:QueryExpressionToFetchXmlRequest and FetchXmlToQueryExpressionRequest.
Edit columns
The columns that you want to display in views can be taken from the entity or related entities. For more information about how to specify the columns to display, see <layoutxml> (SavedQuery).
Add custom icons with tooltip for a column
You can add custom icon with tooltip text to display in a column depending on the column value; you can also specify localized tooltip text. This can be done by adding the custom icons as image web resources in your Dynamics 365 instance and then using a JavaScript web resource to add JavaScript code for a column to display the icons depending on the column value.
Note
This feature was introduced in the December 2016 update for Dynamics 365 (online and on-premises). Adding custom icons with tooltip is supported only for the read-only grids; this feature isn't supported for the editable grids. For more information about editable grids, see Use editable grids.
Two new attributes, imageproviderwebresource and imageproviderfunctionname, are added to the layoutxml of savedquery (see <cell> (SavedQuery) that lets you specify the name of a web resource and a JavaScript function name to display custom icons and tooltip text for a column. The JavaScript code gets executed when the page loads.
You can also use the new Web Resource and Function Name fields in the Column Properties page while modifying the property of an attribute (column) in a view definition in the Dynamics 365 web client to specify the web resource name and JavaScript function name.
The following sample code demonstrates how you can programmatically specify a web resource and a JavaScript function name for adding custom icons and tooltip for the opportunityratingcode column in layoutxml:
System.String layoutXml =
@"<grid name='resultset' object='3' jump='name' select='1'
preview='1' icon='1'>
<row name='result' id='opportunityid'>
<cell name='name' width='150' />
<cell name='customerid' width='150' />
<cell name='estimatedclosedate' width='150' />
<cell name='estimatedvalue' width='150' />
<cell name='closeprobability' width='150' />
<cell name='opportunityratingcode' width='150' imageproviderwebresource='new_SampleWebResource'
imageproviderfunctionname='displayIconTooltip' />
<cell name='opportunitycustomeridcontactcontactid.emailaddress1'
width='150' disableSorting='1' />
</row>
</grid>";
The JavaScript function for displaying custom icons and tooltip text expects the following two arguments: the entire row object specified in layoutxml and the calling user’s Locale ID (LCID). The LCID parameter enables you to specify tooltip text for the icon in multiple languages. For more information about the languages supported by CRM, see Enable languages and Install or upgrade Language Packs for Microsoft Dynamics 365. For a list of locale ID (LCID) values that you can use in your code, see Locale IDs Assigned by Microsoft.
Assuming you will most likely be adding custom icons for an option set type of attribute as it has a limited set of predefined options, make sure you use the integer value of the options instead of label to avoid breaking the code due to changes in the localized label string. Also, in your JavaScript function, specify just the name of an image web resource that you want to use as an icon for a value in the attribute. The image should be of 16x16 pixels size; larger images will be automatically scaled down to 16x16 pixels size.
The following sample code displays different icons and tooltip text based on one of the values (1: Hot, 2: Warm, 3: Cold) in the opportunityratingcode (Rating) attribute. The sample code also shows how to display localized tooltip text. For this sample to work, you must create three image web resources each with 16x16 images (.jpeg "Hot rating icon")
, .jpeg "Warm rating icon")
, and .jpeg "Cold rating icon")
) in your Dynamics 365 instance with the following names respectively: new_Hot, new_Warm, and new_Cold.
function displayIconTooltip(rowData, userLCID) {
var str = JSON.parse(rowData);
var coldata = str.opportunityratingcode_Value;
var imgName = "";
var tooltip = "";
switch (coldata) {
case 1:
imgName = "new_Hot";
switch (userLCID) {
case 1036:
tooltip = "French: Opportunity is Hot";
break;
default:
tooltip = "Opportunity is Hot";
break;
}
break;
case 2:
imgName = "new_Warm";
switch (userLCID) {
case 1036:
tooltip = "French: Opportunity is Warm";
break;
default:
tooltip = "Opportunity is Warm";
break;
}
break;
case 3:
imgName = "new_Cold";
switch (userLCID) {
case 1036:
tooltip = "French: Opportunity is Cold";
break;
default:
tooltip = "Opportunity is Cold";
break;
}
break;
default:
imgName = "";
tooltip = "";
break;
}
var resultarray = [imgName, tooltip];
return resultarray;
}
This results in displaying the values in the Rating column with appropriate icons depending on the value, and icon tooltip text when you hover over the icons.
.jpeg "Custom icons displayed for a column in a view")
Set as default
Only one active public view can be set as the default view. To make a view the default view, set the IsDefault property to true.
See Also
Sample: Work with views
SavedQuery (view) entity messages and methods
Saved query XML reference
Build queries with FetchXML
Use the Organization service with Dynamics 365 metadata
Customize entity forms
Customize global option sets
Customize Microsoft Dynamics 365 applications
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright