Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Field Service-organisaties moeten werk plannen, vaak via een serviceagent, rechtstreeks door de klant. Het maken van boekingen is meestal gebaseerd op de resources die beschikbaar zijn voor het bedrijf en de vereisten van het werk.
Wanneer je ten minste Dynamics 365 Field Service v8.8.43.51 en Universal Resource Scheduling v3.12.46.21 gebruikt om werk te plannen, gebruik dan de msdyn_SearchResourceAvailability API om alle in aanmerking komende resources voor de taak op te halen, zodat je het werk efficiënt kunt inplannen. Op het moment van schrijven is v3 de nieuwste versie van msdyn_SearchResourceAvailability en ondersteunt het web-API-aanroepen.
Opmerking
Gebruik de nieuwste versie van de API, want oudere versies kunnen verouderde authenticatiemethoden gebruiken.
Invoerparameters
| Name | Type | Beschrijving | Verplicht | Default |
|---|---|---|---|---|
| Versie | Tekenreeks | Het versienummer van de API identificeert de versie van de API die moet worden aangeroepen. Het volgt de notatie primaire_versie.secundaire_versie.patch. De aanvraag hoeft niet het volledige versienummer te bevatten.
|
Yes | -N.v.t.- |
| IsWebApi | Booleaanse | Stel dit in op True om de planning assistant via de web-API te gebruiken. | Yes | -N.v.t.- |
| Requirement | Entiteit | Dit kenmerk specificeert de resourcevereiste waarvoor de resourcebeschikbaarheid wordt opgehaald. Dit is naar verwachting een entiteit van het type msdyn_resourcerequirement. De vereiste kan een reeds bestaande record uit de database zijn of een record die tijdens het werken is gemaakt met de nodige beperkingen. De entiteit moet alle details bevatten die relevant zijn voor uw zoekopdracht. De @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.msdyn_requirement zijn. Hieronder volgen enkele belangrijke kenmerken om in te vullen:
|
Yes | -N.v.t.- |
| Instellingen | Entiteit | Het instellingenkenmerk helpt om de opgehaalde resources verder te filteren. Specificeer instellingen als attributen in een entity bag. Het type entiteit maakt niet uit. U kunt elke logische naam voor een entiteit opgeven. | Yes | -N.v.t.- |
| ResourceSpecification | Entiteit | Definieer het resourceSpecification attribuut als attributen in een entity bag. De @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.expando zijn. |
No | Geen |
Instellingenentiteit
De instellingenentiteit is geen entiteit die bestaat in de Dataverse, maar een verzameling van alle volgende kenmerken die de API-filterresultaten van de planningsassistent helpen. Dus de @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.expando zijn.
| Name | Type | Beschrijving | Verplicht | Default |
|---|---|---|---|---|
| ConsiderSlotsWithLessThanRequiredCapacity | Booleaanse | Stel dit in op Waar als een tijdvak met minder dan de vereiste capaciteit (inspanning) moet worden overwogen bij het berekenen van potentieel beschikbare tijdvakken in de agenda van de resource. | No | Onwaar |
| ConsiderSlotsWithLessThanRequiredDuration | Booleaanse | Stel dit in op Waar als een tijdvak met minder dan de vereiste duur moet worden overwogen bij het berekenen van potentieel beschikbare tijdvakken in de agenda van de resource. | No | Onwaar |
| ConsiderSlotsWithOverlappingBooking | Booleaanse | Stel dit in op Waar als een tijdvak met overlappende boekingen moet worden overwogen bij het berekenen van potentieel beschikbare tijdvakken in de agenda van de resource. | No | Onwaar |
| ConsiderSlotsWithProposedBookings | Booleaanse | Stel dit in op Waar als een tijdvak met voorgestelde boekingen moet worden overwogen bij het berekenen van potentieel beschikbare tijdvakken in de agenda van de resource. | No | Onwaar |
| ConsiderAppointments | Booleaanse | Stel dit in op Waar als de API voor het zoeken naar de beschikbaarheid van resources bestaande Dataverse-afspraken moet respecteren als boekingen voor de resource, op voorwaarde dat de instellingen op organisatie- en resourceniveau zijn ingesteld. Afspraken met de status Druk of Voltooid worden als niet beschikbaar beschouwd voor het plannen van operaties. | No | Onwaar |
| ConsiderTravelTime | Booleaanse | Stel dit in op Waar als er rekening moet worden gehouden met de reistijd bij het berekenen van mogelijke tijdvakken in de agenda van de resource. | No | Klopt |
| ExcludeResourceCharacteristicsCharacteristics | Booleaanse | Zet dit op True om resource-eigenschappen voor de tijdslots in respons uit te sluiten. | No | Onwaar |
| MovePastStartDateToCurrentDate | Booleaanse | Stel dit in op Waar om een begindatum in het verleden naar de huidige datum te verplaatsen. | No | Onwaar |
| UseRealTimeResourceLocation | Booleaanse | Stel dit in op Waar als de realtime locatie van resources moet worden gebruikt bij het berekenen van mogelijke tijdvakken in de agenda van de resource. | No | Onwaar |
| SortOrder | EntityCollection | Geef de sorteervolgorde op met behulp van een entiteitsverzameling. Elke entiteit in de verzameling vertegenwoordigt één sorteercriterium en kan alleen sorteren Resources op basis van het antwoord, maar niet TimeSlotsop . De @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.expando zijn. Hieronder volgen de kenmerken die u moet invullen:
|
No | Geen |
| MaxResourceTravelRadius | Entiteit | Dit kenmerk geeft het maximum aan dat kan worden gedefinieerd in een entiteit. De @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.expando zijn. Hieronder volgen de kenmerken die u moet invullen:
|
No | 0 km. Als dat het geval is, worden er geen resources geretourneerd voor de vereisten op locatie. |
| MaxNumberOfResourcesToEvaluate | Integer | Dit kenmerk definieert een limiet voor het aantal resources dat in aanmerking komt voor de aanvraag. | No | Als dit attribuut niet is opgenomen in de API-aanroep, gebruikt het systeem de Resource Availability Retrieval Limit uit de schedulable entity definition zoals gedefinieerd in de Bewerk-instellingen voor ingeschakelde entiteiten. Als het wordt opgenomen in de aanroep, wordt de gedefinieerde limiet voor het ophalen van resourcebeschikbaarheid overschreven. |
| ConsiderOutlookSchedules | Booleaanse | Stel dit in op True als schema's van Outlook in aanmerking moeten worden genomen. Alleen beschikbaar in versies 3.1.0 en later. | No | Onwaar |
Entiteit voor resourcespecificatie
| Name | Type | Beschrijving | Verplicht | Default |
|---|---|---|---|---|
| ResourceTypes | EntityCollection | Dit kenmerk geeft het resourcetype aan dat is vereist voor de vereiste. Gebruik een entiteitscollectie om dit attribuut te specificeren. Elke entiteit in de verzameling vertegenwoordigt één boekbaar resourcetype. De @odata.type voor deze entiteit moet Microsoft.Dynamics.CRM.msdyn_resourceType zijn. Deze eigenschap is vereist:
|
No | Alle resourcetypen behalve ploegen |
| PreferredResources | EntityCollection | Dit kenmerk geeft de resources aan die de voorkeur hebben voor de vereiste. Voeg middelen toe aan deze entiteitencollectie om ervoor te zorgen dat ze bovenaan de lijst van beschikbare bronnen staan. Zelfs bronnen die niet tot de entiteitencollectie behoren staan op de lijst, maar alleen na de voorkeursbronnen. | No | Geen |
| RestrictedResources | EntityCollection | Dit kenmerk geeft de resources aan die niet in overweging moeten worden genomen voor de vereiste. Alle tijdslots van deze bron worden uit de lijst met resultaten van deze API gefilterd. | No | Geen |
| MustChooseFromResources | EntityCollection | Dit kenmerk geeft de enige resources aan die op de lijst met beschikbare resource kunnen staan. Alle andere resultaten worden uit de uitvoerlijst gefilterd. | ||
| Beperkingen | Entiteit | Dit kenmerk specificeert de aanvullende beperkingen die moeten worden toegepast op het ophalen van beschikbare resources. | No | Geen |
| RetrieveResourcesQueryId | Guid | De id voor de query Resources ophalen. | No | De standaard-id van Resourcequery ophalen. |
| BookedResourceId | Guid | Dit kenmerk geeft de resource aan die momenteel is geboekt voor de vereiste. | No | Geen |
Opmerking
Gebruik een entiteitscollectie van boekbare resource-entiteiten om de attributen Preferred, Restricted en MustChooseFrom resources te specificeren. Elke entiteit in de collectie vertegenwoordigt één Preferred, Restricted, of MustChooseFrom-resource . Deze eigenschap is voor hen vereist:
-
Waarde (Guid): De boekbare resource ID van de Preferred, Restricted, of MustChooseFrom-resource . De
@odata.typevoor deze entiteit moetMicrosoft.Dynamics.CRM.msdyn_bookableresourcezijn.
Beperkingen
Specificeer extra beperkingen via attributen in deze entiteit. Het type entiteit maakt niet uit. U kunt elke logische naam voor een entiteit opgeven.
Bekijk de Query Resources ophalen in de planbordinstellingen om te bepalen welke beperkingen van toepassing kunnen zijn. Standaard omvat dit het volgende:
| Name | Type | Beschrijving |
|---|---|---|
| Kenmerken | EntityCollection | Een verzameling kenmerken die een gekwalificeerde bron moet hebben. Elke vermelding bevat een characteristic met de karakteristieke ID. Optioneel kun je een ratingvalue met de beoordelingswaarde-ID toevoegen om middelen te filteren op een specifiek vaardigheidsniveau. |
| Rollen | EntityCollection | Een verzameling rol-id's die een gekwalificeerde resource moet hebben. |
| Rayons | EntityCollection | Een verzameling rayon-id's. Een gekwalificeerde resource moet aan een van de rayons worden toegewezen. |
| UnspecifiedTerritory | Booleaanse | In combinatie met de rayonbeperking geeft dit aan dat een gekwalificeerd persoon moet worden toegewezen aan een van de rayons of aan helemaal geen rayon. |
| OrganizationalUnits | EntityCollection | Een verzameling organisatie-eenheids-id's. Een gekwalificeerde resource moet lid zijn van een van de opgegeven organisatie-eenheden. |
| Teams | EntityCollection | Een verzameling team-id's. Een gekwalificeerde resource moet tot een van de teams behoren (dit houdt in dat het resourcetype een systeemgebruiker is). |
| BusinessUnits | EntityCollection | Een verzameling bedrijfsunit-ID's. Een gekwalificeerde resource moet tot een van de business units behoren (dit houdt in dat de resource een systeemgebruiker is). |
Uitvoerparameters
Op het hoogste niveau heeft de uitvoer de volgende vier parameters. De resultaten worden weergegeven in entiteitsverzamelingen en entiteiten. Responsen bevatten mogelijk niet alle kenmerken die hier als null-waarde worden beschreven of niet-N.v.t.-waarden worden weggelaten uit de respons. Controleer altijd op de aanwezigheid van een kenmerk voordat u probeert toegang te krijgen.
| Name | Type | Beschrijving |
|---|---|---|
| TimeSlots | EntityCollection | Een verzameling tijdvakresultaten. Zie de sectie Tijdslot entiteit voor meer informatie. |
| Resources | EntityCollection | Een verzameling resourceresultaten. Resources worden weergegeven als een verzameling entiteiten met de volgende kenmerken:
|
| Gerelateerd | Entiteit | Gerelateerde resources vertegenwoordigen resources en tijdvakken van resources die niet direct gekwalificeerd zijn voor de gevraagde vereiste, maar wel gerelateerd zijn. Als een bemanningslid bijvoorbeeld in aanmerking komt voor een vereiste, zouden de andere leden van die bemanning gerelateerde resultaten zijn.
|
| Exceptions | Entiteit | Dit kenmerk bevat informatie over eventuele uitzonderingen en informatie over of en waar het zoeken naar resources is afgebroken.
|
Entiteit tijdvakken
| Name | Type | Beschrijving |
|---|---|---|
| Id | Guid | Unieke id voor het tijdvak |
| Type | Integer | Het soort tijdslot. Dit kan een van de volgende waarden zijn:
|
| StartTime | DateTime | De begintijd van het tijdvak. Als er reizen is voor de vereiste, is deze tijd het begin van de reis. Zo niet, dan is dit de starttijd van de vereiste. |
| ArrivalTime | DateTime | De aankomsttijd van het tijdvak. Als er reizen is voor de vereiste, is deze tijd de starttijd van de vereiste, nadat de reis is voltooid. Zo niet, dan is dit gelijk aan de begintijd van het tijdvak. |
| EndTime | DateTime | De eindtijd van het tijdvak. |
| Effort | Integer | De inspanning of capaciteit van de resource om de vereisten uit te voeren. |
| ResourceRequirement | EntityReference | De resourcevereiste waarvoor tijdvakken worden opgehaald. |
| Potentieel | Booleaanse | Een booleaanse waarde die aangeeft of het tijdvak het potentieel heeft om aan de gevraagde vereiste te voldoen. |
| IsDuplicate | Booleaanse | Een booleaanse waarde die aangeeft of het tijdvak een duplicaat is. |
| AllowOverlapping | Booleaanse | Een booleaanse waarde die aangeeft of overlapping is toegestaan. |
| Resource | Entiteit | De resource waarvan het tijdvak deel uitmaakt. Zie tijdvakresource voor meer informatie. |
| Location | Entiteit | De locatie heeft drie kenmerken:
|
| Op reis | Entiteit | Deze entiteit bevat details van reistijd- en afstandsinformatie voor een tijdvak. De volgende kenmerken zijn beschikbaar:
|
| Volgende | Entiteit | Deze entiteit bevat details over de reistijd en afstand tot de volgende tijdvakboeking.
|
| Beschikbaarheid | Entiteit | De gedetailleerde beschikbaarheidsinformatie voor een tijdvak. Deze entiteit wordt gebruikt met tijdsgroepen.
|
| TimeGroup | Entiteit | De details over een tijdgroep.
|
Tip
Wanneer je boekingen aanmaakt met de API, gebruik dan het Potentieel-veld dat in de tabel wordt beschreven. Het niet gebruiken van dat veld kan leiden tot overlappende of ongeschikte boekingen.
Tijdvakresource
| Name | Type | Beschrijving |
|---|---|---|
| Resource | EntityReference | Een entiteitsverwijzing naar de boekbare resource. |
| ResourceGroup | EntityReference | Een entiteitsverwijzing naar de boekbare resourcegroep. |
| BusinessUnit | EntityReference | Een entiteitsverwijzing naar de business unit. |
| OrganizationalUnit | EntityReference | Een entiteitsverwijzing naar de organisatie-eenheid. |
| Bronsoort | Integer | Het hulpbrontype. Zie het kenmerk ResourceType van de entiteit BookableResource voor mogelijke waarden. |
| PoolId | Guid | De id van de pool waarvan de resource lid is gedurende het tijdvak. |
| CrewId | Guid | De id van het team waarvan de resource lid is gedurende het tijdvak. |
| Kenmerken | EntityCollection | De kenmerken van de boekbare resource. Elke entiteit in de verzameliung bevat entiteiten met kenmerken en beoordelingsinformatie.
|
| HasStartLocation | Booleaanse | Een booleaanse waarde die aangeeft of de resource een beginlocatie heeft. |
| HasEndLocation | Booleaanse | Een booleaanse waarde die aangeeft of de resource een eindlocatie heeft. |
| Tekenreeks | Het e-mailadres van de resource. | |
| Telefoon | Tekenreeks | Het telefoonnummer van de resource. |
| ImagePath | Tekenreeks | Het pad naar de afbeelding van de resource. |
| CalendarId | Guid | De agenda-id van de resource. |
Voorbeelden
In dit voorbeeld gebruik je versie 3 van de schedule assistant API, die web-API-aanroepen ondersteunt, voor een vereiste van 60 minuten. Door het settings attribuut te gebruiken, filter je de resultaten. Je beschouwt twee soorten grondstoffen voor het eindresultaat: 1 en 2 (met andere woorden, generiek en contact).
{
"Version": "4",
"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"
},
"ratingvalue": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}
],
"Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Territories": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
}
],
"Roles@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Roles": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "76998e42-744c-f011-877d-6045bdfb899e"
}
]
}
}
}
In het volgende voorbeeld ziet u het juiste gebruik van entiteitsverzamelingen. In dit geval specificeert MustChooseFromResourceshet .
{
"Version": "4",
"IsWebApi": true,
"Requirement": {
"msdyn_fromdate": "2021-07-14T00:00:00Z",
"msdyn_todate": "2021-07-15T23:59:00Z",
"msdyn_remainingduration": 60,
"msdyn_duration": 60,
"msdyn_latitude": 47.64807,
"msdyn_longitude": -122.41249,
"msdyn_worklocation": 690970000,
"msdyn_TimeGroup@odata.bind": "/msdyn_timegroups(c3dc79ea-d12f-ee11-9cc9-000d3a745a58)",
"@odata.type": "Microsoft.Dynamics.CRM.msdyn_resourcerequirement"
},
"Settings": {
"ConsiderSlotsWithProposedBookings": false,
"MovePastStartDateToCurrentDate": true,
"MaxNumberOfResourcesToEvaluate":500,
"ConsiderTravelTime": true,
"MaxResourceTravelRadius": {
"Value": 20,
"Unit" : 192350000,
"@odata.type": "Microsoft.Dynamics.CRM.expando"
},
"@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"
},
"ratingvalue": {
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}
],
"Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Territories": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
}
]
}
}
}