For any organization using Dynamics 365 Field Service, the ability to efficiently allocate resources can make all the difference in meeting customer demands and maintaining a competitive edge. Dynamics 365 Field Service allows us to leverage the Resource Search Availability API that revolutionizes resource allocation by providing real-time insights into resource availability. This API empowers businesses to streamline scheduling processes, optimize resource utilization, and ultimately deliver exceptional service experiences to customers.
With the integration of Dynamics 365 Field Service v8.8.43.51 and Universal Resource Scheduling v3.12.46.21, organizations gain access to the msdyn_SearchResourceAvailability API.
In this blog post, we’ll dive into how this API works with different programming languages like JavaScript and C#. We’ll cover what input details you need to provide and what results you can expect. By the end, you’ll have a clearer understanding of how to use this API to manage resources effectively and streamline your operations.
API Name: msdyn_SearchResourceAvailability
Input Parameters: Below are the critical input parameters necessary for using this API:
- Version: Specifies the API version.
- IsWebApi: Set to true if using the API within Web API; otherwise, set to false.
- Requirement: This parameter includes several key attributes:
- msdyn_fromdate: The start date range for checking resource availability.
- msdyn_todate: The end date range for checking resource availability.
- msdyn_remainingduration: Remaining time required in minutes.
- msdyn_duration: Total time required in minutes for the job.
- Settings: Represents the organizational settings for availability, including attributes like ConsiderSlotsWithProposedBookings and ConsiderSlotsWithLessThanRequiredCapacity.
- ResourceSpecification: Filters resources based on attributes such as Resource Type and Organizational Unit.
Scenario in Dynamics 365 CRM
Imagine a situation where a user needs to schedule a booking for a specific resource. It’s essential to confirm that the resource is available within the requested timeframe, ensuring efficient scheduling. If the resource is available, the booking proceeds; if not, the system restricts the user from scheduling, maintaining effective resource utilization.
A custom development approach can validate resource availability during the creation or update of a booking using the msdyn_SearchResourceAvailability API. If the resource is available, the system will allow the booking; otherwise, it will display a notification indicating that the resource is unavailable during the requested timeslot.
Preparing Resources: Setting Up Working Hours for Resources
To use the Resource Availability API effectively, it’s crucial first to configure working hours for each resource. Follow these steps:
Step 1: Go to the Resource record in CRM, open the Work Hours tab, and click New. Here, you can set the resource’s working hours, time zone, and break times.
Step 2: Ensure that the defined timeslots are visible in the Calendar view.
With the working hours configured, the next step is to establish restrictions for booking creation if a dispatcher tries to book a resource outside available hour. This setup involves developing a plugin that will trigger when a booking is created. It checks the resource’s availability, and if the resource is unavailable, it prevents the booking from being created.
Plugin Code for Resource Availability Validation
Below is a structured overview of the plugin code registered on the pre-validation operation for the Bookable Resource Booking entity in CRM:
1. Initialization and Global Parameters
The plugin initializes services and context objects essential for execution:
ITracingService logs information and traces plugin execution steps.
IPluginExecutionContext retrieves data on the execution context.
IOrganizationService allows interaction with CRM data.
ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService)); IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext)); IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory)); IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);
2. Extracting Start and End Times
The plugin fetches the starttime and endtime attributes from the target entity to define the timeframe for resource availability.
DateTime StartTime = TargetEn.GetAttributeValue<DateTime>("starttime");
DateTime EndTime = TargetEn.GetAttributeValue<DateTime>("endtime");
3. Setting Up Resource Requirements
An Entity object representing the resource requirement (msdyn_resourcerequirement) is created, with attributes for date range and duration.
var requirement = new Entity("msdyn_resourcerequirement");
requirement.Attributes.Add("msdyn_fromdate", fromDate);
requirement.Attributes.Add("msdyn_todate", toDate);
requirement.Attributes.Add("msdyn_duration", 60);
4. Configuring Resource Types
Using the helper method BuildOptionSetValueEntityCollection, the plugin specifies resource types to be considered in the availability check, added to the resource specification entity.
var resourceTypes = BuildOptionSetValueEntityCollection("resourcetypes", "value", new List<int> { 2, 3 });
resourceSpecification.Attributes.Add("ResourceTypes", resourceTypes);
5. Defining Search Settings
A settings entity is created to specify additional search parameters, such as including slots with proposed bookings.
var settings = new Entity("organization");
settings.Attributes.Add("ConsiderSlotsWithProposedBookings", false);
6. Executing the Search Request
The plugin prepares and executes an OrganizationRequest for msdyn_SearchResourceAvailability with configured settings, resource specifications, and versioning details.
var request = new OrganizationRequest() { RequestName = "msdyn_SearchResourceAvailability" };
request["Version"] = "1";
request["Requirement"] = requirement;
request["IsWebApi"] = false;
request["Settings"] = settings;
request["ResourceSpecification"] = resourceSpecification;
var response = service.Execute(request);
7. Parsing Available Time Slots
The plugin retrieves time slot data from the response and processes each entry to convert start and end times to local time. It checks for conflicts, such as overlapping times or slots marked as unavailable.
private static string showTimeSlotsUsingEntities(EntityCollection timeSlots, ITracingService tracingService) {
// Code to process time slots and construct the output string
If(conflict)
{ throw new InvalidPluginExecutionException("Conflict found: Timeslot overlaps with target's StartTime and EndTime, and Potential is set to 'False'.");
}
}
The Resource Availability API Response Structure
This example output shows various attributes of each timeslot:
- Booking Time: Shows the overall requested booking time:
- Booking Start: 11/14/2024 5:00:00 PM
- Booking End: 11/14/2024 5:30:00 PM
- TimeSlot Details: Each timeslot within this resource’s schedule is detailed, including:
- Start and End Times: For example, 11/14/2024 2:00:00 PM to 11/14/2024 3:00:00 PM.
- Type: Indicates the status of the timeslot. Types include:
- Scheduled: Indicates the timeslot is already booked.
- Available: The timeslot is open for new bookings.
- Off: The timeslot is not available due to resource unavailability.
- Potential: A boolean indicating if the timeslot is potentially available (True) or confirmed as unavailable (False).
- Resource: The resource assigned to this timeslot. In this case, all timeslots belong to “Michel Markel“.
Example Analysis
The details of each timeslot are as follows:
Booking Time : 11/14/2024 5:00:00 PM to 11/14/2024 5:30:00 PM
TimeSlots Data:
– TimeSlot: Start: 11/14/2024 2:00:00 PM, End: 11/14/2024 3:00:00 PM, Type: Scheduled, Potential: False, Resource: Michel Markel
– TimeSlot: Start: 11/14/2024 2:22:00 PM, End: 11/14/2024 2:22:00 PM, Type: Off, Potential: False, Resource: Michel Markel
– TimeSlot: Start: 11/14/2024 3:00:00 PM, End: 11/14/2024 3:30:00 PM, Type: Available, Potential: True, Resource: Michel Markel
– TimeSlot: Start: 11/14/2024 3:30:00 PM, End: 11/14/2024 4:00:00 PM, Type: Scheduled, Potential: False, Resource: Michel Markel
– TimeSlot: Start: 11/14/2024 4:00:00 PM, End: 11/14/2024 6:00:00 PM, Type: Available, Potential: True, Resource: Michel Markel
Example Booking Conflict Detection for Resource “Michel Markel”
If the booking time overlaps with a period when the resource is unavailable due to breaks, time-off, or other bookings, the plugin throws an exception with a message indicating the conflict: “Conflict found: Timeslot overlaps with Booking’s StartTime and EndTime, and Resource is unavailable for this time.”
Example Scenario To illustrate, we attempt to book Resource “Michel Markel” for 3:00 PM to 4:00 PM. If a second booking is attempted from 3:30 PM to 4:00 PM, a conflict message will display, preventing the booking. Below are sample screenshots showing the booking process and conflict message:
Booking 1:
Booking 2:
Conclusion
By leveraging the Resource Search Availability API in Dynamics 365 Field Service, organizations can automate resource availability validation, avoiding scheduling conflicts and optimizing resource allocation for enhanced operational efficiency.
