Filter Records

By using the Filters settings, you can dynamically alter the records that are retrieved without having to edit your FetchXML data. In this case, the CRM Lookup widget will be used to demonstrate its functionality. When you first navigate to the Filters tab of any widget that uses the Filters option, it should look like this:

For Beginners; a Simple Usage Case for the Static and ParentCustomerID/ContactID Options

The Static Option

1.  From the CRM Lookup Properties prompt, click on the Data tab. It should look like this:
   
    


2. The FetchXML text box appears to be empty! Let’s define a simple fetch to demonstrate the static option functionality. First, click on the Load Default Fetch option and then click on the Build button to navigate to the FetchXML Builder. It should look like this:
   
   


3. For the purposes of this demonstration, the FetchXML has been set to look for Contacts and Full Names from the CRM Entity of Contacts. Notice that a filter has been manually applied, targetting the Education attribute. The value field has been set to @Education@.


4. Click on the Save Fetch button to save the FetchXML. You will be returned to the Data tab, which should look like this:
   
   


5. Notice that our filter is set to the value of @Education@. Next, click on the Filters tab. Please ensure that the type and value of the filter are set. It should look like this:
   
   


6. The filter has been set to the variable of @Education@, which was seen in the FetchXML in the previous step. The value has been set to College, in effect only looking up Contacts that have completed a college education. In addition, if you would like to look up both College and University educations, you could simply return to the FetchXML to define another OR filter, in which the variable could be @Education2@ with the Value of University.

The ParentCustomerID/ContactID Option

1. From the CRM Lookup Properties prompt, click on the Data tab. It should look like this:
   
   


2. Notice that the FetchXML option is empty! Let’s define a simple FetchXML. Click on the Load Default Fetch option and then click the Build button to be brought to this page:




3. For the purposes of this demonstration, the BuildXML has been defined to look up the Contact and Full Name data fields from the Contacts CRM Entity. Note that a filter has been manually applied to our FetchXML. This filter will look for any account that has a parent contact id of the value ‘@me@’.


4. Click the Save Fetch button to return to the Data tab. It should look like this:
   
   


5. Notice that the Value Field and Display Field happens to be the contactID and fullName respectively. Note that our @me@ variable is visible in our XML. Click on the Filters tab, it should look like this:
   
   


6. After entering in the Variable of @me@ and setting the Type to ParentCustomerID, the filter is ready to perform. If you were to be logged in, the filter will attempt to retrieve your ParentCustomerID, which will technically be the Value. The Variable in the FetchXML data will be set to whatever the ParentCustomerID is, in effect only looking for Contacts in which the ParentContactID is the same as the one we logged in as which effectively fetches yourself as a contact if such a record exists.

For Advanced Users; the QueryString and Session Options

The QueryString Option

1. From the CRM Lookup Properties prompt, click on the Data tab. It should look like this:
   
   


2. The FetchXML appears to be empty! Let’s define a simple fetch to demonstrate the querystring functionality. Click on the Load Default Fetch button and then click the Build button to navigate to the FetchXML Builder. It should look like this:
   
   


3. For the purposes of this demonstration, the FetchXML has been set to look for Contacts and it will retrieve the Contact and Full Name data fields from the Contacts CRM Entity. Notice that a filter has been manually applied. It will filter for whatever the @firstName@ variable has been set to.


4. Click on Save Fetch to return to the Data tab. It should look like this:
   
   


5. Notice that the variable of @firstName@ is right there in the FetchXML. Next, click on the Filters tab. It should look like this:
   
   


6. For this demonstration, the variable was set to match the one that was defined in the FetchXML and the Value is set to firstName. This means that the filter will look through your URL for a parameter matching that value. The variable will then be set to the value of that parameter. For example, if our URL was ‘http://www.lookup.com?firstName=James’, our filter would disregard all contacts that do not have the first name of James.

The Session Option

1. From the CRM Lookup Properties prompt, click on the Data tab. It should look like this:
   
   
2. The FetchXML appears to be empty! Let’s define a simple fetch to demonstrate the session functionality. Click on the Load Default Fetch button and then click the Build button to navigate to the FetchXML Builder. It should look like this:
   
   
3. The FetchXML has been defined to look up the Contact and Full Name attributes from the CRM Entity of Contacts. In addition, a filter has been manually applied, looking for the parentcontactidname data field with a Value of @userID@.
4. Click on Save Fetch to save your XML. You will be returned to the Data tab. It should look like this:
   
   
5. Note that our filter is visible in the FetchXML text box. It is looking for the value of @userID@. Click on the Filters tab. It should look like this:
   
   
6. In the case of sessions, the Value text box is reserved for the name of the session variable. In this case, it is set to look for the session variable of userID. The value of this session variable is what will be applied to our @userID@ variable, in effect looking up contacts that share the same parentcontactidname as the one that was stored in your session variable.

Properties

 

Name	Description
Value Field	TheValue Fieldtext box will determine what actual value is passed when an option is selected.It is different from theDisplay Fieldin that theDisplay Fieldwill be the actual, selectable options.
Display Field	TheDisplay Fieldtext box will determine what selectable options are present in a widget. However, it is different from theValue Fieldtext box in that theValue Fieldpasses the actual value to be submitted which may not necessarily be the visible option.
FetchXML	TheFetchXMLtext area determines what sort of data a widget will be populated with. Clicking theLoad Default Fetchoption will populate theFetchXMLarea with a default fetch based on theCRM Entitychosen. By clicking theBuildbutton, we will be sent to another page in order to determine what the widget will look up. For more information on how to use theFetchXMLfunction, please see theFetchXML BuilderHow-To.
Filter Variable	TheVariabletext box is used to designate where your filter will be applied in yourFetchXMLdata. To name your variable, type whatever name you please in between the two @@.
Filter Type	TheTypedrop down list contains a variety of options for how your filter will fetch theVariable. Options include: TheStaticoption will apply whatever is in theValuetext box to yourVariable. For theStaticoption, a blankValuetext box is allowed. TheSessionoption will look for the session variable of whateverValueis provided. If a session variable that matches theValueis found, the value of that session variable will be applied to theVariable. This option is intended for developers only. TheValuetext box must be filled. TheQuerystringoption will attempt to search for the querystring parameter that is provided within theValuetextbox. If there is an existing parameter found, theVariablewill be set to the parameter’s value. For theQuerystringoption, aValueis mandatory. TheParentCustomerIDandContactIDoptions, theVariablewill be filled by the current logged in users’ ID. AValueshould not be provided for these options.
Filter Value	TheValuetext box varies in usage based on theTypeoption selected. In the case of theStaticoption, theValuewill be set to theVariable. TheValuetext box can be empty. For theSessionoption, theValueshould be set to the session variable. If the session variable is found, theVariablewill be set to the value of the session variable. TheValuetext box must be filled. For theQuerystringoption, theValueshould be set to the desired parameter in the URL string. The value of that parameter will fill theVariable. TheValuetext box must be filled. For theParentCustomerIDandContactIDoptions theValuetext box must be empty because it will be filled by the current logged in user.