Search Resource Availability with Universal Resource Scheduling API
Applies to: Dynamics 365 Organization 9.0+ with Field Service Solution 8.8.x version or Universal Resource Scheduling 3.8.x version
In this blog post let’s talk about how to call the msdyn_SearchResourceAvailability API to return available resources.
At a high level, you pass the details of a single requirement (not a requirement group) to the API and retrieve a list of available resources and timeslots.
This is helpful for self-scheduling scenarios where a resource may want to query his or her availability, or for portal scheduling scenarios where a customer may want to view availability of desired resources from a web site or app.
To use this API, quick glance input and output parameter below and understand details below.
Input
- Version
- Requirement
- Settings
- Travel Radius
- Sort Order
- ResourceSpecification
- Resource Types
- Preferred Resources
- Restricted Resources
- Constraints
Output
- Time Slots.
- Time Slot Resource
- Time Slot Resource Characteristics
- Time Slot Location
- Time Slot Travel
- Time Slot Next
- Time Slot Availability
- Time Slot Availability Intervals
- Time Slot Time Group
- Resources
- Related Results
- Exceptions
Input
| Name | Type | Description | Required | Default value |
| Version | String | The version number of the API. See Version section more details | Yes | |
| Requirement | Entity |
The requirement to get availability for. See Requirement section for more details. |
Yes | |
| Settings | Entity | Settings for the request. See Settings section for more details. | Yes | |
| ResourceSpecification | Entity | Resource specification for the request | No | None |
Version
The version number identifies the version of the API that should be invoked. The version number is a semantic version number of the format major.minor.patch. The request does not have to contain the complete version number. See below table.
| Version number specified in request | Example | Description |
| Major version |
“1” “2” |
Invokes the highest minor and patch version available for the specified major version. If we had versions 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.1.2, 2.0.0 2.1.0 and 2.1.1, the invoked version in the first example would be 1.1.2, because it is the highest version number available under major version “1”. In the second example, the invoked version would be 2.1.1. |
| Major.Minor version |
“1.0” “2.0” |
Invokes the highest patch version available for the specified major and minor version. Using the same available versions as above, the invoked API version in the first example would be 1.0.1, because it is the highest available version number with the major/minor version “1.0”. In the second example, it would be 2.0.0. |
| Major.Minor.Patch version | “2.1.1” | Invokes the exact version number as specified. |
As of this writing, the highest and only version number available for this API is 1.0.0.
If no matching implementation for a version number specified in the request is available, the API will return an error.
Requirement
The requirement specifies the resource requirement to retrieve resource availability information for. This is expected to be a msdyn_resourcerequirement type entity.
This would typically be a requirement that is stored in the database, but it does not have to be. You can specify the details of the requirement in the entity without having a database record id. The intent is to call the API either using an existing requirement or construct one on the fly with the necessary constraints.
The entity should contain all the specifics that are relevant for your scenario. Below are some of the important attributes to populate.
| Attribute | Type | Description |
| msdyn_fromdate | Date and Time | The from date |
| msdyn_todate | Date and Time | The to date |
| msdyn_remainingduration | Whole Number | The remaining duration in minutes |
| msdyn_duration | Whole Number | The total duration in minutes |
Settings
Beyond the solution version and requirement details, you can pass along Settings for more filtered results such as retrieving available resources within a specific distance radius.
Settings are specified as attributes in an entity bag. The type of does not matter, you can specify any entity logical name.
| Name | Type | Description | Required | Default value |
|
ConsiderSlotsWithLess ThanRequiredCapacity
|
Boolean | Specifies if a time slot with less than the required capacity (effort) should be considered when computing potential time slots. | No | False |
|
ConsiderSlotsWithLess ThanRequiredDuration
|
Boolean | Specifies if a time slot with less than the required remaining duration should be considered when computing potential time slots. | No | False |
| ConsiderTravelTime | Boolean | Specifies if travel time should be considered when computing potential time slots. | No | True |
|
ConsiderSlotsWith OverlappingBooking
|
Boolean | Specifies if time slots with overlapping bookings should be considered when computing potential time slots. | No | False |
|
ConsiderSlotsWith ProposedBookings
|
Boolean | Specifies if time slots with proposed bookings should be considered when computing potential time slots. | No | False |
|
MovePastStartDate ToCurrentDate
|
Boolean | Defines how to handle a start date that is in the past | No | False |
|
UseRealTimeResource Location
|
Boolean | Specifies if the real time location of resources should be used when computing potential time slots. | No | False |
|
MaxResource TravelRadius
|
Entity | Specifies the maximum travel radius for a resource to qualify for the requirement. See Travel Radius section for more details. | No | 0 km |
|
SortOrder
|
Entity Collection |
Specifies the sort order for the result. See Sort Order section for more details. | No | None |
|
MaxNumberOfResources ToEvaluate
|
Whole Number | Defines a limit on the number of resources that are considered for the request. | No | Resource Availability Retrieval Limit from schedulable entity definition |
Travel Radius
The maximum travel distance can be defined in an Entity. The type of entity does not matter, you can specify any entity logical name.
| Name | Type | Description |
| Value | Floating Point Number | The radius. |
| Unit | Whole Number | The distance unit. See msdyn_distanceunit option set for possible values. |
Sort Order
The sort order can be specified using an entity collection. Each entity in the collection will represent one sort criteria. The type of entity does not matter, you can specify any entity logical name.
| Name | Type | Description |
| Name | String | The sort criteria. |
| SortOrder | Whole Number | The sort direction (0 for ascending, 1 for descending). |
ResourceSpecification
Resource specifications are defined as attributes in an entity bag. The type of entity does not matter, you can specify any entity logical name.
| Name | Type | Description | Mandatory | Default value |
| ResourceTypes | EntityCollection | The resources types | No | All except crews. |
|
PreferredResources
|
EntityCollection | The preferred resources. See Preferred Resources section for more details. | No | None |
|
RestrictedResources
|
EntityCollection | The restricted resources. See Restricted Resources section for more details. | No | None |
|
RetrieveResourcesQueryId
|
Guid | The Id for the Retrieve Resources query. | No | The default Retrieve Resource Query Id. |
| BookedResourceId | Guid | The resource currently booked on the requirement | No | None |
| Constraints | Entity | Additional constraints. | No | None |
Resource Types
Resource types can be specified using an entity collection. Each entity in the collection will represent one bookable resource type. The type of entity does not matter, you can specify any entity logical name.
| Name | Type | Description |
| value | Whole Number | The option set value that represents |
Preferred Resources
Preferred resources can be specified using an entity collection of bookable resource entities. Each entity in the collection will represent one preferred resource.
| Name | Type | Description |
| value | Guid | The bookable resource Id of the preferred resource. See the resourcetype attribute on the BookableResource entity for possible values. |
Restricted Resources
Restricted resources can be specified using an entity collection of bookable resource entities. Each entity in the collection will represent one restricted resource.
| Name | Type | Description |
| value | Guid | The bookable resource Id of the restricted resource. |
Constraints
Additional constraints can be specified through attributes in this entity. The type of entity does not matter, you can specify any entity logical name.
Please review the ‘Retrieve Resources Query’ on the schedule board settings to identify which constraints might apply. By default, it includes the following
| Name | Type | Description |
| Characteristics | EntityCollection | A collection of characteristic Ids that a qualified resource must have. |
| Roles | EntityCollection | A collection of role Ids that a qualified resource must have. |
| Territories | EntityCollection | A collection of territory Ids. A qualified resource must be assigned to one of the territories. |
| UnspecifiedTerritory | Boolean | In combination with the Territories constraint, specifies that a qualified must be assigned to one of the territories or no territory at all. |
| OrganizationalUnits | EntityCollection | A collection of organizational unit Ids. A qualified resource must be a member of one of the specified organizational units. |
| Teams | EntityCollection | A collection of team Ids. A qualified resource must belong to one of the teams (implies that the resource type is a system user). |
| BusinessUnits | EntityCollection | A of collection of business unit Ids. A qualified resource must belong to one of the business units (Implies that the resource is a system user). |
In each of the above constraints (with exception of the Boolean ‘UnspecifiedTerritories’ attribute), the assigned value must be an EntityCollection where each entity in the collection defines one Id.
Use the logical name of the entity that the constraint refers to and the primary key name as attribute name.
For example, when defining a constraint on organizational units, the entity collection should be a collection of entities with the logical name msdyn_organizationalunit. Each entity in the collection should have an attribute with name msdyn_organizationalunitid. The value of that attribute should be a Guid that identifies the record.
Output
At the highest level, the response has the following four properties. The results are represented in entity collections and entities. Responses may not include all the attributes described here as null value or not applicable attribute values are omitted from the response. Always check for the presence of an attribute before trying to access it.
| Name | Type | Description |
| TimeSlots | EntityCollection | A collection of time slot results. See Time Slots section for more details. |
| Resources | EntityCollection | A collection of resource results. See Resources section for more details. |
| Related | Entity | Related results. See Related Results section for more details. |
| Exceptions | Entity | Information about any exception that occurred. See Exceptions section for more details. |
Time Slots
Time slots are represented as a collection of entities with the following attributes.
| Name | Type | Description |
| Id | Guid | A unique identifier for the time slot |
| Type | Integer |
The type of time slot · Available (0) · Scheduled (1) · Off (2) · Break (3) |
| StartTime | Date and Time | The start time. |
| EndTime | Date and Time | The end time. |
| ArrivalTime | Date and Time | The arrival time. |
| Effort | Effort | The effort/capacity. |
| ResourceRequirement | EntityReference | The resource requirement. |
| Potential | Boolean | A Boolean value indicating if the time slot has potential to fulfill the requested requirement. |
| IsDuplicate | Boolean | A Boolean value indicating if the time slot is a duplicate. |
| AllowOverlapping | Boolean | A Boolean value indicating if overlapping is allowed. |
| Resource | Entity | The time slot resource. See Time Slot Resource section for more details. |
| Location | Entity | The location. See Time Slot Location section for more details. |
| Travel | Entity | The travel time information. See Time Slot Travel section for more details. |
| Next | Entity | Information about the next time slot. See Time Slot Next section for more details. |
| Availability | Entity | Information about the availability. See Time Slot Availability section for more details. |
| TimeGroup | Entity | Time group information. See Time Slot Time Group section for more details. |
Time Slot Resource
The entity contains detailed information about the resource of a given time slot.
| Name | Type | Description |
| Resource | EntityReference | An entity reference to the bookable resource. |
| ResourceGroup | EntityReference | An entity reference to the bookable resource group. |
| BusinessUnit | EntityReference | An entity reference to the business unit. |
| OrganizationalUnit | EntityReference | An entity reference to the organizational unit. |
| ResourceType | Integer | The resource type. See the resourcetype attribute on the BookableResource entity for possible values. |
| PoolId | Guid | The Id of the pool that the resource is a member of for the duration of the time slot. |
| CrewId | Guid | The Id of the crew that the resource is a member of for the duration of the time slot. |
| Characteristics | EntityCollection | The bookable resource characteristics. See Time Slot Resource Characteristics section for more details. |
| HasStartLocation | Boolean | A Boolean value indicating if the resource has a start location. |
| HasEndLocation | Boolean | A Boolean value indicating if the resource has an end location. |
| String | The resource’s email address. | |
| Phone | String | The resource’s phone number. |
| ImagePath | String | The path to the resource’s image. |
| CalendarId | Guid | The resource’s calendar Id. |
Time Slot Resource Characteristics
Each entity in the collection contains entities with characteristics and rating information.
| Name | Type | Description |
| Characteristic | EntityReference | An entity reference to the characteristic. |
| RatingId | Guid | The rating Id for the characteristic. |
| RatingName | String | The rating name. |
| RatingValue | Integer | The rating value. |
Time Slot Location
The entity contains details about the location of a time slot.
| Name | Type | Description |
| Location | Entity |
The location. The entity has two attributes · Latitude · Longitude |
| Workocation | Integer |
The work location · Onsite (0) · Facility (1) · Location agnostic (2) |
| LocationSourceSlot | Integer |
The source of the location information · Common (1) · Custom GPS entity (2) · Mobile audit (3) |
Time Slot Travel
The entity contains details of travel time and distance information for a time slot.
| Name | Type | Description |
| Distance | Double | The travel distance |
| TravelTime | Double | The travel time in minutes. |
| DistanceFromStartLocation | Double | The distance from the resource’s start location. |
| DistanceFromEndLocation | Double | The distance from the resource’s end location. |
| DistanceMethodSourceSlot | Integer |
The source / calculation type of the distance values · Map Service (1) · ‘As the crow flies’ (2) |
Time Slot Next
The entity contains details about the travel time and distance to the next time slot booking.
| Name | Type | Description |
| NextScheduleLocation | Entity |
The location of the next booking. The entity has two attributes · Latitude · Longitude |
| NextScheduleTravelTime | Integer | The travel time to the next booking in minutes. |
Time Slot Availability
The entity contains detailed availability information for a time slot. This is used in connection with time groups.
| Name | Type | Description |
| AvailableIntervals | EntityCollection | A collection of available intervals. See Time Slot Availability Intervals section for more details. |
| TotalAvailableDuration | Double | The total available duration in minutes. |
| TotalAvailableTime | Double | The total available time a resource has in a day (in minutes). |
Time Slot Availability Intervals
Each entity in this collection contains details about a time group interval.
| Name | Type | Description |
| StartTime | Date and Time | The start time. |
| EndTime | Date and Time | The end time. |
| ArrivalTime | Date and Time | The arrival time. |
| TimeGroupId | Guid | The time group Id. |
| TimeGroupDetailStartTime | Date and Time | The time group detail start time. |
| TimeGroupDetailEndTime | Date and Time | The time group detail end time. |
Time Slot Time Group
The entity contains details about a time group.
| Name | Type | Description |
| TimeGroupId | Guid | The time group Id. |
| TimeGroupDetail | EntityReference | An entity reference to the time group detail. |
| TimeGroupDetailStartTime | Date and Time | The time group detail start time. |
| TimeGroupDetailEndTime | Date and Time | The time group detail end time. |
Resources
Resources are represented as a collection of entities with the following attributes.
| Name | Type | Description |
| BookableResource | Entity | The bookable resource entity. |
| TotalAvailableTime | Double | The total available time. |
Related Results
Related resources represent resources and time slots of resources that are not directly qualified for the requested requirement but are related. For example, if a crew member qualifies for a requirement, then the other members of that crew would be related results.
| Name | Type | Description |
| TimeSlots | EntityCollection | Time slots of related resources. The definition of time slots is the same as described in the Time Slots section above. |
| Resources | EntityCollection | The related resources. The definition of resources is the same as described in the Resources section above. |
Exceptions
The entity contains an exception message if one occurred and information about if and where the resource search was truncated.
| Name | Type | Description |
| Message | String | Exception message |
| ResourcesTruncatedAt | Integer | If the number of resources exceeded the retrieval limit; the number where the resources where truncated. |
Stay tuned for more blog posts about scenarios and sample code of using this API
Feifei Qiu
Program Manager
Dynamics 365, Field Service team
