Microsoft Dynamics 365 v9.0: lookupObjects – closer look

After I posted my previous post about new namespaces and methods I got several questions about lookupObjects method from Xrm.Utility namespace. I decided to make additional research to check what was not documented but can be used.

Here is url that contains description of method with standard parameters:

And here is the list and usage of additional parameters that are not documented but can be set using JavaScript:

1. 1. Lookup form properties:
      • disableViewPicker – boolean, when set to “true” disables dropdown with views (default value is “false”)
      • disableQuickFind – string, when set to “1” disables “Quick Find Search”
      • lookupBrowse – boolean, when set to “true” hides whole section related to search (“Look For”, “Look In” and “Views” dropdown)
      • showNew – boolean, when set to “true” adds “New” button to lookup dialog (default value is “false”)
      • searchText – string, when populated, passes that value to “Search” field of lookup dialog
   2. Additional prefiltering – the same possibilities like we have with addPreSearch/addCustomFilter. If you want to use this feature you will have to pass both following parameters – customFilters and customFilterTypes:
      • customFilters – array of url-encoded string filters, example –

        ["%3Cfilter%20type%3D%22and%22%3E%3Ccondition%20attribute%3D%22name%22%20operator%3D%22eq%22%20value%3D%22test%22%20%2F%3E%3C%2Ffilter%3E"]

      • customFilterTypes – array of strings. When you have one entity or you want to apply the same filter for all available entities just pass [“”], when you have several entities and you want to apply different filters for entities you will have to pass array with names of entities along with array of filters
      • example of code for single entity or the same filter for all entities:

        var lookupOptions = {
        	defaultEntityType: "account",
        	entityTypes: ["account"],
                allowMultiSelect: false,
                customFilters: ["%3Cfilter%20type%3D%22and%22%3E%3Ccondition%20attribute%3D%22name%22%20operator%3D%22eq%22%20value%3D%22test%22%20%2F%3E%3C%2Ffilter%3E"],
        	customFilterTypes: [""]
        };
        
        Xrm.Utility.lookupObjects(lookupOptions)
        	.then(function(result){
        	})
        	.fail(function(error){
        	});

      • example of code for multiple entities and different filters:

        var lookupOptions = {
        	defaultEntityType: "account",
        	entityTypes: ["account", "contact"],
                allowMultiSelect: false,
                customFilters: ["%3Cfilter%20type%3D%22and%22%3E%3Ccondition%20attribute%3D%22name%22%20operator%3D%22eq%22%20value%3D%22test%22%20%2F%3E%3C%2Ffilter%3E",
        			"%3Cfilter%20type%3D%22and%22%3E%3Ccondition%20attribute%3D%22firstname%22%20operator%3D%22eq%22%20value%3D%22Andrii%22%20%2F%3E%3C%2Ffilter%3E"],
        	customFilterTypes: ["account", "contact"]
        };
        
        Xrm.Utility.lookupObjects(lookupOptions)
        	.then(function(result){
        	})
        	.fail(function(error){
        	});

   3. “Related Records Filtering” – filtering of lookup dialog through code settings the same way as it described here through customization:
      • allowFilterOff – boolean, when set to “false” disallows user to turn of filtration applied
      • filterRelationshipDependantAttribute – string, name of attribute in related entity in format “relatedentityname.attributename”, example – “contact.parentcustomerid”
      • filterRelationshipId – Guid, id of relationship
      • filterRelationshipName – string, name of relationship used for join
      • filterRelationshipType – string, use “1” when want to turn on “Related Records Filtering”
   4. customViews – array that you can use to add any custom views you want to show in View Picker – the same functionality that you can get using addCustomView method of lookup control. Here is example of usage:

          var fetchXml = "<fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='false'>" +
              "  <entity name='contact'>" +
              "    <attribute name='fullname' />" +
              "    <attribute name='createdon' />" +
              "    <attribute name='contactid' />" +
              "  </entity>" +
              "</fetch>";
      
          var layoutXml = "<grid name='resultset' object='1' jump='productid' select='1' icon='1' preview='1'>" +
              "<row name='result' id='contactid'>" +
              "<cell name='fullname' width='150' />" +
              "<cell name='createdon' width='150' />" +
              "</row>" +
              "</grid>";
      
      var customView = {
      	id: "{00000000-0000-0000-0000-000000000001}",//Some fake id
      	recordType: 2,//Entity Type Code of entity... yes, again
      	name: "Custom View Name",
      	fetchXml: fetchXml,
      	layoutXml: layoutXml,
      	Type: 0//Hardcoded, leave it as it is
      };
      
      var lookupOptions = {
      	defaultEntityType: "contact",
      	entityTypes: ["contact"],
              allowMultiSelect: false,
      	customViews: [ customView ]
      };
      
      Xrm.Utility.lookupObjects(lookupOptions)
      	.then(function(result){
      	})
      	.fail(function(error){
      	});