If you are a customer that relies heavily on the “book” button to search for availability for your resources, this may open up implementation possibilities you did not think were possible.
Prior to reading this post, you may have assumed that when you click the “book” button on either a requirement, or any schedulable entity, the filters the schedule assistant used was only controllable via settings, attributes, and records. You likely assumed that in order to manipulate the search, you either needed to manually change the values in the filter panel once the schedule board loads, or you needed to actually add data to the requirement entity, it’s child entities (e.g., Requirement Characteristics, organizational units), or the header entity (e.g., lead, opportunity, work order, project).
This blog post is an advanced post explaining how you can set all of your search criteria dynamically via URL.
Before explaining the “how” and the “why”, let’s first explore the way the book button defaults its search filters today. If you are already very familiar with the defaulting logic, skip to the Benefits to URL approach section below.
Current Defaulting Logic
Currently, when a user is on any schedulable entity’s form or view, there is a book button that is enabled in the ribbon.
By default, when you click “book”, a pop out schedule board appears allowing the user to create a booking(s) for that respective record.
By default, when a user clicks the book button which launches the pop out scheduling experience, first there is a check to see if there is a child resource requirement record related to the entity from which the book button was initiated.
If there is only one child resource requirement record, then the board runs against that resource requirement record.
If there are multiple resource requirement records, then the board runs against the resource requirement which is flagged as “primary”.
Of course, if a user clicks book on a resource requirement record itself, then the schedule board simply launches against that requirement.
If there are no resource requirement records, then the board launches directly against the record from which the book button was launched, but uses the values in the search that are set in the 1:N entity mapping between the schedulable entity (e.g.. lead, opportunity) and the resource requirement. This deserves a blog post in itself, but here is one example.
For example, if you are scheduling a lead, and you would like to pass in a territory filter from the lead entity instead of needing to create a resource requirement, you could create an attribute on the lead entity which is a lookup to the territory entity, and populate that value on the lead record, and map that field to the requirement territory field. Then, when clicking “book”, the territory filter will be populated directly from the lead entity presuming there is no resource requirement, and presuming the territory value on the lead record is populated.
Here are some visuals:
Territory added to the lead entity
Mapping populated on booking setup metadata record from the territory attribute on the Lead entity to the territory attribute on the Resource Requirement entity.
Attribute mapping between fields auto populated in traditional manner after setting this up on Booking Setup Metadata record
User clicks book on Lead record that does not have a Resource Requirement, yet the territory is populated in search:
Defaults on scheduling parameters record:
There are also some settings that are inherited from the global scheduling parameters record:
Now that we have summarized the defaulting logic, let’s review why you would be inclined to change your schedule assistant search via URL.
Benefits to URL approach
Avoid pre-creating resource requirements for every record
We know that in certain implementations, pre-generating a resource requirement for every single record that may or may not be scheduled can be a burden that is not quite sensible. For example. When creating a case, if 20 percent of the time a case ends up being scheduled, but the other 80 percent of the time it doesn’t, there may unnecessary workflows and plugins that you would need to run, as well as an unnecessary data explosion caused on the database to pre-create a resource requirement every time. Even if it is not a big deal to create a resource requirement record for each schedulable record (e.g., lead, case, opportunity), for each resource requirement there are potentially additional child entities that need to be created such as roles/categories, characteristics, org units, and resource preferences. Additionally, there may be plugins or workflows needed to populate attributes which may default from other entities. For example, latitude and longitude may default from the “customer” attribute on the case.
For Work Orders, where nearly 100 percent of Work Orders will be scheduled, it makes sense to pre-create a resource requirement, in fact, this is what the field service solution does today, but for other entities, this may or may not make sense. This is a way to give customers the ability to have the full power of the scheduling experience without being forced to pre-create a requirement and the related information.
Pass in non-schema based scheduling parameters
Many of the scheduling parameters used when finding availability are schema based, so system customizers can change values of attributes and records to change the search criteria. However, there are some search properties not stored in the schema on each requirement. For example, business units, teams, radius, real time mode, etc. You may want the scheduling results to appear for your users perfectly setup with the right settings without your users needing to change a thing. When a user clicks “book” and initiates the pop out schedule board, it is important to add the flexibility for system customizers to setup the board according to the scenario, on the fly.
Conditional Values at Runtime
In many cases, the scheduling filters can be dynamic in nature. Perhaps you would like to populate the team, or the business unit based on the user initiating the search. Perhaps you would like to set the search “to” date to 5 days from “today” if the lead is in stage A, and 7 days if lead is in stage B, and 1 day if the case was opened more than 7 days ago. And as mentioned earlier, you may want to populate attributes which may default from other entities. For example, latitude and longitude may default from the “customer” attribute on the case.
Control the pop out schedule board search criteria by interacting with the URL
For the reasons outlined above, we allow system customizers to completely control the pop out schedule board search criteria by interacting with the URL. Here is how:
You will need to create your own custom “book” button on the ribbon.
In short, you can set the parameters of your schedule assistant search in the pop out schedule board by changing the URL.
Here are the basic rules:
The URL must look like the below URL through the ID portion of the URL. This references the schedule board web resource, and an ID/guid which we will discuss in a moment. These are required.
To construct the beginning of the URL, (e.g. https://crmorg.crm.dynamics.com/19234281938), use the XRM client side context - https://msdn.microsoft.com/en-us/library/gg334511.aspx#BKMK_getclientURL
Moving forward, we will only focus on customizing the URL beginning with “/WebResources” portion of the URL.
If you are clicking “book” on a requirement record, then the ID to use in the URL is the resource requirement’s guid:
If you are initiating the book button from the schedulable entity, such as a lead, work order, project, then the guid you pass in is the guid of the lead record (see yellow highlight just above). In this scenario, where you are passing in the header guid instead of the requirement guid, you also must specify the entity type (lead, opportunity, work order, etc)
You MUST pass in what type of entity you are searching against if you are not passing in the resource requirement guid.
Now that we understand the basic rules of what is absolutely required, we can get into the fun part.
In order to change any part of the schedule assistant query, we will add a parameter to the URL. If you do not specifically add a parameter to the URL, then the default values will be used from the requirement, or parent schedulable record.
To make any changes to the query, simply add an ampersand (&), an equals sign (=), and a value.
Here is how you would change the search duration via URL:
To add a territory, or multiple territories to the search:
You can see that in the above URL I added both the duration and the territory by simply adding another “&=”.
After the ID portion of the URL as referenced earlier, once you are adding the actual search criteria by adding the “&” symbol, the order doesn’t matter.
Here are the fiters you can see in the filter control when searching for availability.
Below is the snapshot of all of the search criteria and how you can modify the values via URL:
As you can see after reviewing how simple it is to change the search criteria via URL, you can see that there are few limitations, and tons of possibilities.
I do want to point out a few limitations to be aware of:
If you change the search criteria through the URL, keep in mind that these changes to the search criteria are not stored anywhere, with few exceptions. Meaning, if you add a territory via URL, and create a booking, the territory is not added to the resource requirement record. The URL manipulates the search itself, but does not update the requirement when you book as that is not the intention of this feature. This may not matter in your implementation, but for others, it may. For example, if you are using the resource scheduling optimization solution (RSO), which can move bookings around after they are created, RSO will not understand that there is a specific territory or specific characterisitics that the requirement should be booked within, unless you add the territory and characteristics to the requirement itself.
There are a few exceptions. After searching for availability and then creating a booking, there is a feature that auto creates a requirement if there is no backing requirement to the booking that was just created. This only applies when searching for availability against the schedulable record itself when there is no requirement.
In this scenario, there are some defaults that get saved onto the requirement when the requirement is auto generated:
- “From” and “To” – These values are saved on the requirement from the “search start” and “search end” fields in the filter control.
- “Duration” – Value is saved on the requirement from the “duration” field in the filter control.
- “Work Location” – Value is saved on the requirement from the “work location” field in the filter control.
- Latitude and Longitude – Values are saved from the URL if they are passed in since there is no way to change the latitude and longitude within the filter control itself.
Other items of note once we are discussing defaults, even though they do not relate to the URL feature:
- The Resource Requirement allocation method is set to “none”
- The status of the booking created is set to the default specified on the relative booking setup metadata record. Note if this is blank on the entity you are trying to schedule, it uses the Booking Setup Metadata record called “none” as this is the fallback.
The second point to make here once again is that this feature was built for the pop out schedule board initiated from a record. This is not applicable when you begin your search from within the schedule board.
The goal of this feature is to make usage easier. It takes some setup, but it can help implementations in a major way.
We hope you enjoy this feature!
Sr. Program Manager, Microsoft Dynamics 365 Engineering