Lookup PCF – let’s dive deeper

Ok, this time the Lookup PCF was released! For real :-). My first blog about Lookup PCF was a little early, but I could have a look on how it looks like. The announcement in the official blogs made last week, was mainly about a huge milestone (the GA of PCF for Canvas) but there were also the Lookup.Simple and MultiSelectOptionSet types made available for Model-Driven Apps PCFs. So I had a second look on how a Lookup PCF is working.

What a Lookup property means for the architecture of a PCF

In the announcement blog, Hemant Gaur mentions that the Lookup and MultiSelectOptionSet types were added based on the community feedback. Thank you so much for hearing us. We probably won’t get from the beginning the full power of the Lookup PCFs, but we get unblocked to use it for a lot of use cases, and that’s huge. The use cases where a Lookup PCF will unblock us:

1. As input property

I think a lot of the requests for this feature, were made simply for being able to use the value in combination with other types inside a PCF. Just for consuming the value. One example could be the ability to show information from a linked table (similar to the Form Component Control which is now provided out of the box).

For a lot of cases, it’s enough to use the out of the box Lookup Control to edit the value, and use the attribute/column additionally inside a custom PCF (maybe even as a second property). Without this feature, we could have used webAPI requests to read this data, but we wouldn’t have been notified when the value changes on the form. On top, we get some metadata for the lookup.

Not only the developers have a better experience, but also the maker is able to customize the component by choosing from a list, instead of having to know the name of the lookup column.

2. As property-set inside a dataset

From now on we can declare property-sets inside a dataset. This way we can extend the view provided, add linked tables or add a custom filter also based on lookups. Or make a PCF for a hierarchy table. In the case of the dataset we don’t get much metadata information, but the maker is able to choose from a given set of lookups, corresponding to the available relations.

3. As a bound property

What if we need to change the data? I see there two ways:

1. Using the Utility feature lookupObjects we can open the standard dialog for lookups and grab the output.(Utility needs to be declared in the manifest). This option is already there and it works, as shown in the official example.
2. By implementing our own lookup dialog, or let the user choose the value through other UX. This one seems to be already prepared, with a functionality similar to a dataset property. I could change the view and get the records corresponding using only the lookup property. But for now, since it’s not documented, I’ll consider this option unsupported and stay away from using it. I guess that there might be changes when the Lookup PCF will move to Canvas Apps too, since there it can be used with other Connectors, where we don’t have an lookup Dialog like in Model-Driven Apps. Still, I like to see the whole picture of what is coming, and I’m really looking forward to this.

What the lookup doesn’t seem to cover

No static values / Only for existing lookups (relations)

For the other data type, when working with input properties, we have the possibility to choose a static value or a dynamic one.

But not for a lookup; here we can only choose a dynamic value.

I was hoping that through the lookup we can also link some configurations to the PCF. Through a lookup property. The maker could choose a static record (row). Maybe even from a relation that’s not defined on the table. I know, the id doesn’t necessarily get transported in another environment, but I think it would be nice to be able to choose an EnvironmentVariable as a property for the PCF (or a WebResources, something that probably won’t change while transporting the data). This  would allow a more flexible configuration, and the maker still doesn’t have to navigate away. And thinking further, if the Lookup is able to retrieve the data, the extended configuration is already available. Since the Lookup is still “work in progress”, maybe I shouldn’t lose hope yet. Or maybe there are other, better plans, that I don’t know about. I love nice surprises 🙂

Open the lookup dialog – lookupObjects

Let’s have a look, how to open the lookup dialog. In order to be able to use the PCF utils.lookupObjects, don’t forget to enable the Utility feature in your manifest.

The only options available for lookupOptions are documented here:

“allowMultiSelect” will be true, since only the Lookup.Simple is supported for now. Where to find the other ones?

There are two special methods: getTargetEntityType() and getViewId(). These are not documented yet, but they are used in the official sample”Lookup component”. Also if we use the latest pac cli (1.7.2) they are included in the provided typings, so they are supported and probably documented soon.

So the call could look like this:

 context.utils.lookupObjects({
			defaultEntityType: lookup1.getTargetEntityType(),
			defaultViewId: lookup1.getViewId(),
			allowMultiSelect: false,
			entityTypes: [lookup1.getTargetEntityType()],
			viewIds: [lookup1.getViewId()]
		})
        .then((values) => {
			if (values?.length>0){
				this.val = values;
				notifyOutputChanged();
			}
			// otherwise the "Cancel" button was clicked
		})
		.catch(console.error);

After notifyOutputChanges, the updateView will be called again with the new value (if the runtime accepted it).

Well, that works, but there is still a lot missing. Let’s compare with the Xrm.Utility.lookupObjects Sdk:

The options I miss the most are the searchText and the filters, but missing disableMru could make some trouble too. Let’s see where the road is taking us to.

Starting from here we are leaving the supported path. The next thoughts and research are UNSUPPORTED for now. They might eventually become supported in the future in one way or another.

Grab the lookup configuration

Let’s suppose that the options for lookupOptions are not enough, and we decide to make an own dialog or want to provide other user experience. The maker has the possibility to set quite a few options when customizing. In case we want to respect them, how should we read these settings inside the PCF. Basically we would need these settings ( on the left are the settings for a primary property of type lookup, on the right are the settings for a secondary property ):

• 

• 

I’ve made a GitHub Repository where I’ve logged the needed content. I have two properties of type Lookup. If you want to play around, have a look. In the next screenshots we’ll see two values for each setting (primary property and the secondary one)

In case I see changes or something gets supported, I’ll update this blog. Let’s take each at a time…

1. Display Search Box in Lookup Dialogs

A tough one for the beginning.

I’ve configured like this, for both the first and the second lookup property:

So it’s lookup1.disableQuickFind, but the seconds Lookup property seems to show the wrong value. I suppose that the first one is right, since the name is inverted. Just to see that I’m grabing the right property, see what happens if both properties are not checked:

if(lookup1.disableQuickFind === false){
    //show a search box
} else {
   //no search box
}

2 & 3. View Selector & Views

We have three possibilities to choose:

2.1 Selected Views

each red box represents the views for one of my lookup properties.

2.2 All Views

So the availableViewNames are undefined. I’ve found a method to retrieve all views using the lookup property, also unsupported for now, like the rest of the options in this chapter.

lookup1.getAllViews(lookup1.getTargetEntityType()).then(console.log)

2.3. View Selector Off

Please note that the availableViewIds is a string, containing the ids comma separated. It’s not an array. I suppose this will be changed, in case this will get supported.

Putting it all together:

 const viewIds = 
lookup1.enableViewPicker === true //more views possible
    ? lookup1.availableViewIds == null // "All Views"
        ? lookup1.getAllViews(lookup1.getTargetEntityType()).then((allViews) => allViews.map((view) => view.viewId)) 
        : Promise.resolve(lookup1.availableViewIds.split(",")) //the selected views were defined
    : undefined; //else the user shouldn't be able to change the view	

4. DefaultViewId

For that I’ve found a .getDefaultViewId() and even a .getTitle(). It’s looking almost official, but it’s not,

lookup1.getDefaultViewId()
lookup1.getTitle() // the title of the defaultView

5 & 6. Filtering based on another lookup

7. Most recent used items

If the maker doesn’t want the most recent used items, he/she can turn it off.

If the feature is not disabled, the .getLookupConfiguration().isMruDisabled is of course false, and we can access these records by calling

if(myLookupProperty.getLookupConfiguration().isMruDisabled === false){
    const mruRecords = myLookupProperty.getRecentItems();
}

Nice feature (in case it will get supported).

Let’s recap (but keep in mind that they are all unsupported):

All of them unsupported for now…

Open the lookup record

A typical requirement for a lookup is to navigate to the record (row). One way to implement it would be to use the context.navigation methods, more exactly the openForm.

But we remember that in Model-Driven Forms we have the possibility to overwrite the navigation using the sdk method addOnLookupTagClick. So I would prefer the method who would take care of everything, exactly like the dataset openDatasetItem. Indeed, the lookup has an openDatasetItem, which worked in my test (but again, unsupported for now)

lookup1.openDatasetItem(lookup1.raw[0])

There must be more

I’ve asked myself, what happens if a developer used Form-Scripting and attaches “addPreSearch” for a lookup control? How will I be able to get that filter and use it further? In case that’s planned, I couldn’t figure it out yet.

Conclusion

Even if I couldn’t stay put and dug into unsupported stuff for now, I understand that I need to have some patience until the Lookup PCF will have full power. The Microsoft PCF Team did a big effort to help the community and unblock us to a lot of use cases. Even if already much more is working than documented, I’m sure that the api will change until everything is settled. One big step in this direction is probably to build the bridge to Canvas Apps, where the Lookup will be able to work not only for Dataverse, but also for all the other Connectors.

For me it was important to see where the trip is taking me to. Seeing that eventually the lookup will be able to provide the data for the lookup dialog, is a big step in making me understand how to design a PCF for the future and what I should keep in mind.. and I love it!