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.
The requirement to get availability for.
See Requirement section for more details.
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.
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.
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.
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.
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.
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.
The maximum travel distance can be defined in an Entity. The type of entity does not matter, you can specify any entity logical name.
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.
Resource specifications are defined as attributes in an entity bag. The type of entity does not matter, you can specify any entity logical name.
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.
Preferred resources can be specified using an entity collection of bookable resource entities. Each entity in the collection will represent one preferred resource.
Restricted resources can be specified using an entity collection of bookable resource entities. Each entity in the collection will represent one restricted resource.
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
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.
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.
Time slots are represented as a collection of entities with the following attributes.
The type of time slot
The entity contains detailed information about the resource of a given time slot.
Each entity in the collection contains entities with characteristics and rating information.
The entity contains details about the location of a time slot.
The location. The entity has two attributes
The work location
Location agnostic (2)
The source of the location information
Custom GPS entity (2)
Mobile audit (3)
The entity contains details of travel time and distance information for a time slot.
The source / calculation type of the distance values
Map Service (1)
As the crow flies (2)
The entity contains details about the travel time and distance to the next time slot booking.
The location of the next booking. The entity has two attributes
The entity contains detailed availability information for a time slot. This is used in connection with time groups.
Each entity in this collection contains details about a time group interval.
The entity contains details about a time group.
Resources are represented as a collection of entities with the following attributes.
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.
The entity contains an exception message if one occurred and information about if and where the resource search was truncated.
Stay tuned for more blog posts about scenarios and sample code of using this API
Dynamics 365, Field Service team
The post Retrieve Resource Availability with Universal Resource Scheduling API appeared first on Microsoft Dynamics 365.