Utöka Universal Resource Scheduling med universell FetchXML

Artikel
03/21/2023

UFX är ett avancerat frågespråk som gör att du kan hämta frågedata med hjälp av dynamisk FetchXML-form och förbereda resultatet för förbrukning av lösningen Universal Resource Scheduling (URS). Den här frågespråket låter dig skapa anpassade frågor för att anpassa och utöka schematavlan och schemaläggningsassistentfilter för att tillgodose unika affärsbehov i organisationen.

UFX består av två komponenter UFX uppsättning och UFX frågan.

Enkel UFX uppsättning

En UFX uppsättning innehåller statiska skrivna data. I minnet visas den som en ordlista med nycklar och värden. Den kan serialiseras till JSON och XML. Om du skriver data tillåter detta att en UFX fråga frågar data från den och klientens användargränssnitt för att koppla till den.

Av praktiska och prestandaskäl kan den minnesinterna uppsättningen implementeras ovanför Dynamics 365 SDK-appar Entity-objekt.

Exempeluppsättningen innehåller två värden.

Minnesintern:

Nyckel	värde	typ
namn	John	sträng
ålder	36	heltal

I JSON:

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

I XML:

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

UFX-typer som stöds

En UFX uppsättning kan innehålla värden av olika typer. De kategoriseras i 3 typklasser:

Kategori	Värde
Enkla typer	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Dynamics 365-specifika enkla typer: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Övriga uppsättningar	`bag (Entity)`
Lista över uppsättningar	`list (EntityCollection)`

Här följer en JSON exempeluppsättning som innehåller flera 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" }
    ]
}

Samma uppsättning i XML:

<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 till UFX frågor

UFX frågor skrivs som XML-baserade UFX uppsättningar. Egenskaper i uppsättningen kan innehålla UFX direktiv för att fråga data dynamiskt. En UFX fråga kör på minnesinterna objekt, inte XML. Endast direktiv skrivs i XML-format. Dess utdata kan serialiseras till JSON eller XML.

Följande UFX-fråga definierar egenskapen accounts i uppsättningen med source UFX-direktivet. Detta resulterar i att inline FetchXML körs av Dynamics 365 och egenskapen accounts blir en lista över uppsättningar, eller en EntityCollection, med varje uppsättning som en instans av en kontopost från 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 fråga bearbetas efter varandra och kan innehålla många FetchXML-frågor.

Här är ett kodavsnitt av resultatet av föregående UFX fråga serialiserad till XML. Observera att vissa värden har metadata som ytterligare beskriver dem.

<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>

select UFX direktiv tar ett XPath-uttrycket som väljer värden från aktuell uppsättning.

<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>

Resulterande uppsättning i XML:

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

Den mest kraftfulla aspekten av en UFX fråga är möjligheten att dynamisk generera FetchXML baserat på indata.

I exemplet nedan söker vi efter konton med ett värde som tillhandahålls av användaren och är tillgänglig som en UFX uppsättning via XPath $input variabeln. Observera UFX-direktiven om och värde på elementet condition.

<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>

Om egenskapen NameFilter i indatauppsättningen innehåller %city% skulle det producerade FetchXML-villkoret som körs av Dynamics 365 se ut så här.

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

Nycklar, värden och metadata

En UFX uppsättning innehåller nycklar och vissa värden med ytterligare metadata som beskriver dem.

Ett exempel kan vara ett värde av typen lookup (EntityReference). När en förfrågan från Dynamics 365 görs via FetchXML returneras det logiska namnet på entiteten och det formaterade visningsnamnet för posten. UFX uppsättningen bevarar denna ytterligare information som metadata kopplad till det primära värdet.

Serialiseras till JSON, en lookup med metadata ser ut så här:

{
    "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 över Dynamics 365-data

Om du har data skriven i ett UFX uppsättning kan en UFX fråga se den i ett strukturerat format och använda XPath till att bläddra över data och välja värden från den.

Ett XPath-uttryck som anges i ett UFX-direktiv ser data i uppsättningen mycket liknande strukturen i uppsättningen i XML-serialiserade formulär. Men data lagras även i minnesinterna .NET-objekt (i instanser av Entity och EntityCollection-typer) och inte i XML-dokument.

Bilaga A: UFX typreferens

Obs! Alla UFX-typer stöder metadata ufx-type och ufx-formatvalue. Ytterligare metadata beskrivs bredvid varje typ i tabellen nedan.

UFX-namn	Attributtypkod	.NET namn	UFX-metadata
bool	Boolesk	Boolesk
heltal	Heltal	Int32
lång	BigInt	Int64
dubbel	Dubbel	Dubbel
decimaltal	Decimaltal	Decimaltal
datum och tid	DatumTid	DatumTid
guid	Uniqueidentifier	Guid
sträng	Anteckning	Sträng
belopp	Belopp	Belopp
alternativ	Plocklista	OptionSetValue
slå upp	Slå upp	EntityReference	`ufx-logicalname`
uppsättning	Saknas	Entitet	`ufx-id` `ufx-logicalname`
list	Saknas	EntityCollection
Saknas	Saknas	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Bilaga B: UFX fråga direktiv

UFX direktiv kan användas på uppsättningsegenskaper och på XML-element i en FetchXML-fråga.

UFX uppsättning direktiv

Attribut	Value	Beskrivning
`ufx:if`	XPath	Testar XPath-uttrycket och hanterar bara egenskapen bara om testet returnerar sant
`ufx:source`	`fetch`	Kör inline `<fetch>` XML-element och tilldelar resultatet till egenskapen
`ufx:select`	XPath	Kör XPath-uttrycket och tilldelar resultatet till egenskapen När du hämtar en `bag` eller `list` kan en valfri underordnad `bag` i XML-formulär anges för att omvandla resultatet av XPath-uttrycket

UFX FetchXML direktiv

Element	Attribut	Value	Beskrivning
Alla element	`ufx:if`	XPath	Testar XPath-uttrycket och avger endast XML-elementet om dessa tester lyckas
`ufx:apply`	`select`	XPath	Går genom över noduppsättningen som returneras av XPath-uttrycket och visar underordnade XML-element för varje nod
`ufx:value`	`select`	XPath	Kör XPath-uttrycket och visar resultatet i det aktuella XML-elementet
`ufx:value`	`attribute`	attributnamn	Tilldelar resultatet för XPath-uttryck till det angivna attributnamnet på det aktuella XML-elementet

Bilaga C: UFX XPath-funktioner

UFX lägger till ett antal nya funktioner förutom de som finns inbyggda i XPath.

datetime()

datetime(): Returnerar aktuell tid i UTC

list()

list(bag | list, ...[uppsättning | lista]): Tar ett antal bag- eller list-värden som indata och lägger samman dem till en enda list

lookup-to-list()

lookup-to-list(lookup, ...[slå upp]): Tar ett antal lookup-värden, konverterar dem till en bag med ufx-id och ufx-logicalname metadatauppsättning och lägger samman dem till en enda list

option-to-list()

option-to-list(option, ...[alternativ]): Tar ett antal option-värden och konverterar dem till en bag med en enda option-egenskap och lägger samman dem till en enda list

order()

order(list, string, bool): Beställer en lista med en egenskap i varje uppsättning. Egenskapen anges i argument 2, fallande anges i argument 3.
order(list, list): Beställer en lista med flera sorteringsorder som anges som en lista i argument 2. Varje bag i andra listan kan ha en name och descending egenskap

iif()

iif(any, any, any): Om argument 1 är sant, returneras argument 2, annars returneras argument 3

Bilaga D: UFX XPath-variabler

Namn	Beskrivning
$input	En `bag` finns för UFX frågan med inmatningsvärden
$null	En konstant null. Välja `$null` på en egenskap tar bort egenskapen från uppsättningen
$current	Referens till aktuell uppsättning bearbetas av UFX-frågan

Se även

Förstå och anpassa resursmatchning i Universal Resource Scheduling

Universal Resource Scheduling utökningsbarhet – Viktig information