Search resource availability API
Field service organizations need to schedule work, often through a service agent directly by the customer. Bookings are typically created based on the resources available to the company and the requirements of the work.
When using at least Dynamics 365 Field Service v8.8.43.51 and Universal Resource Scheduling v3.12.46.21 to schedule work, the msdyn_SearchResourceAvailability
API can be used to retrieve all the eligible resources for the job, to allow for efficient scheduling of the work. At the time of writing, v3 is the latest version of msdyn_SearchResourceAvailability and supports web API calls.
Note
Using the latest version of the API is highly recommended as older versions may use deprecated authentication methods.
Input parameters
Name | Type | Description | Required | Default |
---|---|---|---|---|
Version | String | The version number of the API identifies the version of the API that should be invoked. It follows the format of major.minor.patch. The request doesn't have to contain the complete version number.
|
Yes | -N/A- |
IsWebApi | Boolean | Set to True in order to use the schedule assistant via the web API. | Yes | -N/A- |
Requirement | Entity | This attribute specifies the resource requirement for which resource availability is being retrieved. It's expected to be a msdyn_resourcerequirement type entity. The requirement can be a preexisting record from the database, or one created on the fly with the necessary constraints. The entity should contain all the specifics that are relevant for your search. The @odata.type for this entity should be Microsoft.Dynamics.CRM.msdyn_requirement . The following some important attributes to populate:
|
Yes | -N/A- |
Settings | Entity | The settings attribute helps to filter the retrieved resources further. Settings are specified as attributes in an entity bag. The type of entity doesn't matter. You can specify any entity logical name. | Yes | -N/A- |
ResourceSpecification | Entity | The resourceSpecification attribute is defined as attributes in an entity bag. The @odata.type for this entity should be Microsoft.Dynamics.CRM.expando . |
No | None |
Settings entity
The settings entity isn't an entity that exists in the Dataverse; however, it's a collection of all the following attributes that helps the schedule assistant API filter results. Thus, the @odata.type
for this entity should be Microsoft.Dynamics.CRM.expando
.
Name | Type | Description | Required | Default |
---|---|---|---|---|
ConsiderSlotsWithLessThanRequiredCapacity | Boolean | Set this to True if a time slot with less than the required capacity (effort) should be considered when computing potential available time slots on the resource's calendar. | No | False |
ConsiderSlotsWithLessThanRequiredDuration | Boolean | Set this to True if a time slot with less than the required duration should be considered when computing potential available time slots on the resource's calendar. | No | False |
ConsiderSlotsWithOverlappingBooking | Boolean | Set this to True if a time slot with overlapping bookings should be considered when computing potential available time slots on the resource's calendar. | No | False |
ConsiderSlotsWithProposedBookings | Boolean | Set this to True if a time slot with proposed bookings should be considered when computing potential available time slots on the resource's calendar. | No | False |
ConsiderAppointments | Boolean | Set this to True for search resource availability API to respect existing Dataverse appointments as bookings on the resource, provided the organization and resource level settings have been set. Appointments with statuses Busy or Completed will be considered as unavailable for scheduling operations. | No | False |
ConsiderTravelTime | Boolean | Set this to True if travel time should be considered when computing potential time slots on the resource's calendar. | No | True |
MovePastStartDateToCurrentDate | Boolean | Set this to True to move a start date in the past to the current date. | No | False |
UseRealTimeResourceLocation | Boolean | Set this to True if the real-time location of resources should be used when computing potential time slots on the resource's calendar. | No | False |
SortOrder | Entity | The sort order can be specified using an entity collection. Each entity in the collection represents one sort criteria. The @odata.type for this entity should be Microsoft.Dynamics.CRM.expando . The following are the attributes you need to populate:
|
No | None |
MaxResourceTravelRadius | Entity | This attribute specifies the maximum that can be defined in an entity. The @odata.type for this entity should be Microsoft.Dynamics.CRM.expando . The following are the attributes you need to populate:
|
No | 0 km. If that's the case, no resources are returned for onsite requirements. |
MaxNumberOfResourcesToEvaluate | Integer | This attribute defines a limit on the number of resources that are considered for the request. | No | Resource Availability Retrieval Limit from schedulable entity definition |
ConsiderOutlookSchedules | Boolean | Set this to True if schedules from Outlook should be considered. Only available in versions 3.1.0 and later | No | False |
Resource specification entity
Name | Type | Description | Required | Default |
---|---|---|---|---|
ResourceTypes | EntityCollection | This attribute specifies the resource type required for the requirement. It can be specified using an entity collection. Each entity in the collection represents one bookable resource type. The @odata.type for this entity should be Microsoft.Dynamics.CRM.msdyn_resourceType . This is the attribute required:
|
No | All resource types except crews |
PreferredResources | EntityCollection | This attribute specifies the resources preferred for the requirement. Adding resources to this entity collection ensures that they are at the top of the list of available resources. Even resources that aren't a part of the entity collection will be on the list, but only after the preferred resources. | No | None |
RestrictedResources | EntityCollection | This attribute specifies the resources that shouldn't be considered for the requirement. All time slots of this resource will be filtered out of the list of results from this API. | No | None |
MustChooseFromResources | EntityCollection | This attribute specifies the only resources that can be on the list of available resources. It filters out all the other results from the output list. | ||
Constraints | Entity | This attribute specifies the additional constraints that should be applied to the retrieval of available resources. | No | None |
RetrieveResourcesQueryId | Guid | The ID for the Retrieve Resources query. | No | The default Retrieve Resource Query ID. |
BookedResourceId | Guid | This attribute specifies the resource currently booked for the requirement. | No | None |
Note
The Preferred/ Restricted / MustChooseFrom resources attributes can be specified using an entity collection of bookable resource entities. Each entity in the collection represents one Preferred / Restricted / MustChooseFrom resource. This is the attribute required for them:
- Value (Guid): The bookable resource ID of the Preferred / Restricted / MustChooseFrom resource. The
@odata.type
for this entity should beMicrosoft.Dynamics.CRM.msdyn_bookableresource
.
Constraints
Additional constraints can be specified through attributes in this entity. The type of entity doesn't matter. You can specify any entity logical name.
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). |
Output parameters
At the highest level, the output has the following four parameters. The results are represented in entity collections and entities. Responses might not include all the attributes described here as null value or not NA 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. For more information, see (time slot entity)[#time-slots-entity] section. |
Resources | EntityCollection | A collection of resource results. Resources are represented as a collection of entities with the following attributes:
|
Related | Entity | Related resources represent resources and time slots of resources that aren't 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.
|
Exceptions | Entity | This attribute contains information about any exception that occurred and information about if and where the resource search was truncated.
|
Time slots entity
Name | Type | Description |
---|---|---|
ID | Guid | Unique identifier for the time slot |
Type | Integer | The type of time slot can be one of the following:
|
StartTime | DateTime | The start time of the time slot. If there's travel for the requirement, then this is the start time of travel. If not, this is the start time of the requirement. |
ArrivalTime | DateTime | The arrival time of the time slot. If there's travel for the requirement, then this is the start time of requirement, after travel has been completed. If not, it's the same as the start time of the time slot. |
EndTime | DateTime | The end time of the time slot. |
Effort | Integer | The effort or capacity of the resource to carry out the requirements. |
ResourceRequirement | EntityReference | The resource requirement for which time slots are being retrieved. |
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 resource to which the time slot belongs. For more information, see time slot resource. |
Location | Entity | The location has three attributes:
|
Travel | Entity | This entity contains details of travel time and distance information for a time slot. The following are the attributes:
|
Next | Entity | This entity contains details about the travel time and distance to the next time slot booking.
|
Availability | Entity | The detailed availability information for a time slot. This is used with time groups.
|
TimeGroup | Entity | The details about a time group.
|
Tip
When you create bookings with the API, use the Potential field described in the table. Not using that field might lead to overlapping or unsuitable bookings.
Time slot resource
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 during the time slot. |
CrewId | Guid | The ID of the crew that the resource is a member of during the time slot. |
Characteristics | EntityCollection | The bookable resource characteristics. Each entity in the collection contains entities with characteristics and rating information.
|
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. |
Examples
In this example, v3 of schedule assistant API, which allows for web API calls, is being used for a requirement of duration 60 minutes. Using the settings attribute, the results are being filtered down. Two resource types are being considered for the final results: 1 and 2 (in other words, generic and contact).
{
"Version": "3",
"IsWebApi": true,
"Requirement": {
"msdyn_fromdate": "2021-07-14T00:00:00Z",
"msdyn_todate": "2021-07-15T23:59:00Z",
"msdyn_remainingduration": 60,
"msdyn_duration": 60,
"msdyn_TimeGroup@odata.bind": "/msdyn_timegroups(c3dc79ea-d12f-ee11-9cc9-000d3a745a58)",
"@odata.type": "Microsoft.Dynamics.CRM.msdyn_resourcerequirement"
},
"Settings": {
"ConsiderSlotsWithProposedBookings": false,
"MovePastStartDateToCurrentDate": true,
"@odata.type": "Microsoft.Dynamics.CRM.expando"
},
"ResourceSpecification": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"ResourceTypes@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"ResourceTypes": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "1"
},
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "2"
}
],
"Constraints": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"Characteristics@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Characteristics": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"characteristic": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "67387f9f-12e2-ec11-bb43-000d3aed25f7"
}
}
],
"Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Territories": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
}
]
The following example demonstrates proper usage of entity collections. In this case, it specifies MustChooseFromResources.
{
"Version": "3",
"IsWebApi": true,
"Requirement": {
"msdyn_fromdate": "2021-07-14T00:00:00Z",
"msdyn_todate": "2021-07-15T23:59:00Z",
"msdyn_remainingduration": 60,
"msdyn_duration": 60,
"msdyn_TimeGroup@odata.bind": "/msdyn_timegroups(c3dc79ea-d12f-ee11-9cc9-000d3a745a58)",
"@odata.type": "Microsoft.Dynamics.CRM.msdyn_resourcerequirement"
},
"Settings": {
"ConsiderSlotsWithProposedBookings": false,
"MovePastStartDateToCurrentDate": true,
"@odata.type": "Microsoft.Dynamics.CRM.expando"
},
"ResourceSpecification": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"ResourceTypes@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"ResourceTypes": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "1"
},
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "2"
}
],
"MustChooseFromResources@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"MustChooseFromResources": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "2145a982-f718-ed11-b83e-0022482d79c8",
}
],
"Constraints": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"Characteristics@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Characteristics": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"characteristic": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "67387f9f-12e2-ec11-bb43-000d3aed25f7"
}
}
],
"Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Territories": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
}
]
}
}
}
}
}
}