Skip to content
Dynamics 365 Blog

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.

RequirementSample

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.
Email 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

We're always looking for feedback and would like to hear from you. Please head to the Dynamics 365 Community to start a discussion, ask questions, and tell us what you think!

Join the conversation

Loading comments...