Applies to: Dynamics 365 Organization 9.0+ with Field Service Solution 8.7.x version or Universal Resource Scheduling 3.7.x version

In this blog post lets talk about how to call the msdyn_GetResourceAvailability 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.

RequirementSampleRequirementSample

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 resources email address.
Phone
String
The resources phone number.
ImagePath
String
The path to the resources image.
CalendarId
Guid
The resources 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 resources start location.
DistanceFromEndLocation
Double
The distance from the resources 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

The post Retrieve Resource Availability with Universal Resource Scheduling API appeared first on Microsoft Dynamics 365.