Skip to main content
Dynamics 365

How to use the Search Resource Availability API – Universal Resource Scheduling

Applies to: Dynamics 365 Organization 9.0+ with Universal Resource Scheduling 3.8.x version

In the latest Field Service v8.8.x/Universal Resource Scheduling v3.8.x update, we released the Search Resource Availability API for scheduling single requirements. A list of available resources and their time slots can be retrieved by passing the details of a single resource requirement to this API as input. In this blog post, we will walk you through a scenario with an example of how to use this API.

Let’s consider this scenario: You are looking for list of available resources and their time slots for a requirement in which you have specific constraints—from and to dates of the requirement, duration of the requirement, effort needed for the requirement, resource types, resource characteristics, rating, roles, territories, organizational units, and resource preferences (preferred and restricted resources).

To be precise, in our example we are looking for available robotics technicians (resources: account, contact, user) for three hours of work over the next three days, who are familiar with assembly maintenance in the Washington territory and belong to the organizational units Seattle OU or Redmond OU.

Here is the list of input parameters used for our resource requirement and the exact values used in our example:

Input Description Type Mandatory Value used in this example
Version Version number of the API to be called String Yes 1.0.0
FromDate From Date on the requirement Date and Time No Today
ToDate To Date on the requirement Date and Time No Next 3 days
Duration Duration in minutes Whole Number No 3 hours = 180 mins
Effort Effort/capacity needed for the requirement Effort No 1
ResourceTypes The type of resource needed for the requirement (example: account, contact, crew) Whole Number No 2,3,5 (account, contact, user)
RestrictedResources Resources to be excluded from the available resource suggestions GUID No ‘8F419662-1BE7-E611-8102-E0071B69FFE1′,’07F73BD9-17F3-E611-8112-E0071B66BF01’
(Brady Hannon/Edgar Ramirez)
PreferredResources Resources to be included in the available resource suggestions GUID No 1FF73BD9-17F3-E611-8112-E0071B66BF01′, ‘0BF73BD9-17F3-E611-8112-E0071B66BF01’
(Jorge Gault, Joseph Gonsalves)
Characteristics Bookable resource characteristics needed for the requirement GUID No ‘FAC12CAB-1BE7-E611-8102-E0071B69FFE1’ (Assembly Maintenance)
Ratings Minimum rating needed for a resource characteristic on the requirement Integer No 1 (Familiar)
Roles Resource categories/roles needed for the requirement GUID No ‘EB357955-1AE7-E611-80F4-E0071B661F01’ (Robotics Technician)
Territories Resource territories needed for the requirement GUID No ‘395C7D14-1CE7-E611-8102-E0071B69FFE1’ (Washington)
OrganizationUnits Resource organization units required for the requirement GUID No ‘6AAEE41E-CA82-E911-A979-000D3AC041FB’, ’68AEE41E-CA82-E911-A979-000D3AC041FB’
(Seattle/Redmond)

 

Note:

  • To run this API, we are going to need the GUIDs for the bookable resources, characteristics, roles, territories, and organizational units, which you can retrieve using the Web API.
  • If the API is called from a client (browser or an app like canvas app) that is based on JavaScript/TypeScript, you would need to have the extended SOAP SDK, which is provided in the sample files for download.
  • The extended SOAP SDK is not a Microsoft official release but is provided in the sample for guidance.
  • We suggest you test this in your development or test environments first to validate your scenarios and results before you run it in your production environments.

To execute this search against your organization, you can download the sample files here. Once you download the sample folder, follow these steps:

  1. Modify the hard-coded input parameters provided in the sample.js file to reflect the GUIDs of records (for example, resources, characteristics, territories) in your org.
    • SA API Sample 1
  2. Add the files in the sample folder as web resources in your organization.
    • SA API Sample 2
    • SA API Sample 3
  3. Navigate to the newly added sample.htm page. It would look like <<YourOrgURL>>//WebResources/new_sample.htm.
    • SA API Sample 4
  4. Open the browser’s developer tools by using the F12 function key. Set breakpoints as needed and inspect the request/responses in the developer tool’s console.
    • SA API Sample 5
    • SA API Sample 7

 

We can see the list of time slots returned for the resources who match the search criteria with time slot types Off, Available, Scheduled returned. Jorge Gault and Joseph Gonsalves are the two potential resources who can fulfill our Resource Requirement/Work Order between the times of 09:00 to 17:00 hours GMT on June 26th and 27th.

Once these time slots are returned by the API, you could choose to display the available time slots on your custom web portal, app or a canvas app. If the user chooses an available time slot, you could use your custom logic to create a booking.

A few other scenarios that could leverage the API are as follows:

  • Build a custom web app or a Dynamics 365 portal to provide appointment scheduling for their end users to show the available time slots for the service/product they offer from a Dynamics 365 CE organization data.
  • Build a PowerApps canvas app to support scheduling scenarios for their line-of-business apps.

 

Vinay Nalam,

Program Manager, Dynamics 365 Engineering

 

Additional Resources:

Docs: The primary documentation for Dynamics 365 for Field Service

Scheduling Docs: Documentation for Universal Resource Scheduling

Learn: Tutorials for Universal Resource Scheduling

Field Service YouTube channel: Includes concept videos for Field Service

Ideas portal: Contribute product feedback and ideas for Universal Resource Scheduling

Forum: Go here to ask questions, find answers, and see upcoming events

Blogs: Ongoing release notes and posts from the product team