Udvide Universal Resource Scheduling med Universal FetchXML

Artikel
06/06/2024

UFX er et avanceret forespørgselssprog, som gør det muligt at forespørge om data ved hjælp af dynamisk FetchXML og tilpasse og forberede dataene til forbrug af løsningen Universal Resource Scheduling (URS). Med dette forespørgselssprog kan du oprette brugerdefinerede forespørgsler for at tilpasse og udvide planlægningsområde- og planlægningsassistentfiltre, så de stemmer overens med organisationens særlige forretningsbehov.

UFX består af to komponenter, UFX-beholder (UFX Bag) og UFX-forespørgsel (UFX Query).

Simpel UFX-beholder

En UFX-beholder indeholder statiske indtastede data. I hukommelsen repræsenteres den som et katalog med nøgler og værdier. Den kan serialiseres til JSON og XML. Fordi dataene kan indtastes, kan UFX-forespørgsel forespørge om data fra den, og brugergrænsefladen (UI ) i klienten kan oprette binding til den.

Af praktiske årsager og af hensyn til ydeevnen implementeres beholderen i hukommelsen oven på SDK Entity-objektet i Dynamics 365-apps.

Eksempel på beholder, der indeholder to værdier.

I hukommelsen:

key	værdi	type
name (navn)	John	string (streng)
age (alder)	36	int (heltal)

I JSON:

{
    "name": "John",
    "age": 36
}

I XML:

<bag>
    <name ufx-type="string">John</name>
    <age ufx-type="int">36</age>
</bag>

UFX-understøttede typer

En UFX-beholder kan indeholde mange forskellige typer værdier. De kategoriseres i tre typeklasser:

Kategori	Værdi
Simple typer	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Specifikke simple typer for Dynamics 365: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Andre beholdere	`bag (Entity)`
Liste over beholdere	`list (EntityCollection)`

Her er et eksempel på en JSON-beholder, der indeholder flere typer:

{
    "citizen": true,          // implicit bool
    
    "age": 36,                // explicit int
    "age@ufx-type": "int",

    "name": {                 // nested bag
        "first": "John",
        "last": "Doe"
    },

    "children": [             // list of bags
        { "name": "Sam" },
        { "name": "Judy" }
    ]
}

Den samme beholder i XML-format:

<bag>
    <citizen ufx-type="bool">true</citizen>

    <age ufx-type="int">36</age>

    <name ufx-type="bag">
        <first ufx-type="string">John</first>
        <last ufx-type="string">Doe</last>
    </name>

    <children ufx-type="list">
        <bag>
            <name ufx-type="string">Sam</name>
        </bag>
        <bag>
            <name ufx-type="string">Judy</name>
        </bag>
    </children>
</bag>

Introduktion til UFX Queries

UFX-forespørgsler skrives som XML-baserede UFX-beholdere. Beholderen kan have egenskaber som UFX direktiver, som gør det muligt at hente data dynamisk. En UFX-forespørgsel køres på objekter i hukommelsen, ikke XML. Kun direktiverne skrives i XML-format. Outputtet kan serialiseres til JSON eller XML.

Følgende UFX-forespørgsel definerer accounts-egenskaben i beholderen med source UFX-direktivet. Dette medfører, at den indbyggede FetchXML udføres af Dynamics 365 og accounts-egenskaben bliver en liste over beholdere eller en EntityCollection, hvor de enkelte beholdere er en forekomst af en firmapost fra Dynamics 365.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>
</bag>

En UFX-forespørgsel behandles sekventielt og kan indeholde mange FetchXML-forespørgsler.

Her er et kodestykke fra resultatet af den forrige UFX-forespørgsel serialiseret til XML. Bemærk, at nogle værdier har metadata, der beskriver dem yderligere.

<bag>
  <accounts ufx-type="list">
    <bag ufx-id="166e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">166e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ABSS4G45</accountnumber>
      <name ufx-type="string">Fourth Coffee (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.fourthcoffee.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Yvonne McKay (sample)" ufx-logicalname="contact">7c6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    <bag ufx-type="bag" ufx-id="186e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">186e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ACTBBDC3</accountnumber>
      <name ufx-type="string">Litware, Inc. (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.litwareinc.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    ...
  </accounts>
</bag>

UFX-direktivet select tager et XPath-udtryk, der vælger værdier fra den aktuelle beholder.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>

    <first_account_name ufx:select="accounts/bag[1]/name" />

    <!-- null values remove properties from the bag -->
    <accounts ufx:select="$null" />
</bag>

Den beholder, der oprettes, i XML-format:

<bag>
    <first_account_name ufx-type="string">Fourth Coffee (sample)</first_acount_name>
</bag>

Den mest effektive egenskab ved en UFX-forespørgsel er uden tvivl evnen til dynamisk at generere FetchXML baseret på inputdata.

I eksemplet nedenfor søger vi efter firmaer ud fra en værdi, der er angivet af brugeren, og som er tilgængelig som en UFX-beholder via XPath $input-variablen. Bemærk UFX if og value direktiverne i condition-elementet.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account">
                <filter>
                    <condition attribute="name" operator="like" ufx:if="$input/NameFilter">
                        <ufx:value select="$input/NameFilter" attribute="value" />
                    </condition>
                </filter>
            </entity>
        </fetch>
    </accounts>
</bag>

Hvis NameFilter-egenskaben i inputbeholderen indeholdt %city%, ville den producerede FetchXML-betingelse, der blev udført af Dynamics 365, se således ud.

<condition attribute="name" operator="like" value="%city%" />

Nøgler, værdier og metadata

En UFX-beholder indeholder nøgler og værdier, hvor nogle værdier har yderligere metadata, der beskriver dem yderligere.

Et eksempel kan være en værdi af typen lookup (EntityReference). Når der forespørges fra Dynamics 365 via FetchXML, returneres det logiske navn på objektet samt det formaterede viste navn på posten. UFX-beholderen gemmer disse yderligere oplysninger som metadata, der er knyttet til den primære værdi.

Når et lookup med metadata serialiseres til JSON, ser det sådan ud:

{
    "primarycontactid": "7e6e39dd-34a1-e611-8111-00155d652f01",
    "primarycontactid@ufx-type": "lookup",
    "primarycontactid@ufx-logicalname": "contact",
    "primarycontactid@ufx-formatvalue": "Susanna Stubberod (sample)"
}

I XML:

<primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>

XPath over Dynamics 365-data

Når dataene i en UFX-beholder indtastes, kan en UFX-forespørgsel se dem i et struktureret format og bruge XPath til at gennemgå dataene og vælge værdier fra dem.

For et XPath-udtryk, der er angivet i et UFX-direktiv, ser dataene i beholderen ud på samme måde som strukturen af beholderen i XML-serialiseret form. Men data gemmes i hukommelsen i .NET objekter (i forekomster af Entity og EntityCollection typer) og ikke i XML-dokumenter.

Tillæg A: reference af UFX-typen

Bemærk: Alle UFX-typer understøtter ufx-type og ufx-formatvalue metadata. Yderligere metadata er beskrevet ud for hver type i tabellen nedenfor.

UFX-navn	Kode for attributtype	.NET-navn	UFX-metadata
bool	Boolesk værdi	Boolesk værdi
heltal	Heltal	Int32
long	BigInt	Int64
dobbelt	Dobbelt	Dobbelt
decimal	Decimal	Decimal
dato/klokkeslæt	DateTime	DateTime
guid	Uniqueidentifier	Guid
streng	Notat	Streng
penge	Penge	Penge
indstilling	Valglisteattributter	OptionSetValue
opslag	Opslag	EntityReference	`ufx-logicalname`
bag	I/T	Objekt	`ufx-id` `ufx-logicalname`
liste	I/T	EntityCollection
I/T	I/T	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Tillæg B: UFX-forespørgselsdirektiv

UFX-direktiver kan bruges til beholderegenskaber og i XML-elementer i en FetchXML-forespørgsel.

UFX-beholderdirektiver

Attribut	Værdi	Beskrivelse
`ufx:if`	XPath	Tester XPath-udtrykket og behandler kun egenskaben, hvis testen returnerer true
`ufx:source`	`fetch`	Kører det indbyggede `<fetch>` XML-element og tildeler resultatet til egenskaben
`ufx:select`	XPath	Kører XPath-udtrykket og tildeler resultatet til egenskaben Når der forespørges om en `bag` eller `list`, kan en valgfri underordnet `bag` i XML-format angives til transformering af resultatet af XPath-udtrykket

UFX FetchXML-direktiver

Element	Attribut	Value	Beskrivelse
Alle elementer	`ufx:if`	XPath	Tester XPath-udtrykket og udsender kun XML-elementet, hvis testene lykkes
`ufx:apply`	`select`	XPath	Gentages over det nodesæt, der returneres af XPath-udtrykket, og leverer output i form af underordnede XML-elementer én gang for hver node
`ufx:value`	`select`	XPath	Udfører XPath-udtryk og viser resultatet i det aktuelle XML-element
`ufx:value`	`attribute`	attribute name	Tildeler resultatet af XPath-udtrykket til det angivne attributnavn i det aktuelle XML-element

Tillæg C: UFX XPath-funktioner

UFX tilføjer en række nye funktioner ud over dem, der er indbygget i XPath.

datetime()

datetime(): returnerer det aktuelle tidspunkt i UTC

list()

list(bag | list, ...[bag | list]): Benytter en række bag- eller list-værdier som input og komprimerer dem til en enkelt list

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): Benytter en række lookup-værdier, konverterer dem til en bag med metadatasættene ufx-id og ufx-logicalname og komprimerer dem til en enkelt list

option-to-list()

option-to-list(option, ...[option]): Benytter en række option-værdier, konverterer hver af dem til en bag med en enkelt option-egenskab og komprimerer dem til en enkelt list

order()

order(list, string, bool): Arrangerer en liste efter en egenskab i hver beholder. Egenskaben er angivet i argument 2, faldende er angivet i argument 3.
order(list, list): Sorterer en liste i flere sorteringsrækkefølger, der er angivet som en liste i argument 2. Hver bag i den anden liste kan have en name og descending egenskab

iif()

iif(any, any, any): Hvis argument 1 er true, returneres argument 2, ellers returneres argument 3

Tillæg D: UFX XPath-variabler

Navn	Beskrivelse
$input	En `bag`, der er tilgængelig for UFX-forespørgslen med inputværdier
$null	En null-konstant. Hvis du vælger `$null` i en egenskab, fjernes egenskaben fra beholderen
$current	Reference til den aktuelle beholder, der behandles af UFX-forespørgslen

Se også

Forstå og tilpasse brugerdefineret ressourcematchning i Universal Resource Scheduling

Produktbemærkninger til Mulighed for udvidelse af Universal Resource Scheduling

Del via