Rozšíření Universal Resource Scheduling pomocí Univerzálního FetchXML

Článek
06/06/2024

UFX je pokročilý dotazovací jazyk, který umožňuje dotazovat data pomocí dynamického FetchXML, tvarovat a připravovat výsledná data pro spotřebu pomocí řešení Universal Resource Scheduling (URS). Tento dotazovací jazyk umožňuje vytvářet vlastní dotazy pro přizpůsobení a rozšíření filtrů plánovací vývěsky a pomocníka plánování, aby splňovaly jedinečné obchodní potřeby organizace.

UFX se skládá ze dvou částí - UFX kontejneru a UFX dotazu.

Jednoduchý UFX kontejner

UFX kontejner obsahuje statická data. V paměti je představován jako slovník s klíči a hodnotami. Může být serializován do formátu JSON a XML. Mít k dispozici zadaná data umožňuje UFX dotazu žádat z něj data a uživatelskému rozhraní klienta se na něj vázat.

Z praktických a výkonnostních důvodů je kontejner v paměti implementován nad objektem Entity SDK aplikací Dynamics 365.

Vzorový kontejner obsahující dvě hodnoty.

V paměti:

klíč	hodnotu	typ
název	Jiří	řetězec
stáří	36	int

V JSON:

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

V XML:

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

Podporované typy UFX

UFX kontejner může obsahovat mnoho typů hodnot. Jsou zařazené do třech typových tříd.

Kategorie	Hodnota
Jednoduché typy	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Specifické jednoduché typy Dynamics 365: `money (Money)`, `option (OptionSet)`,`lookup (EntityReference)`
Jiné kontejnery	`bag (Entity)`
Seznam kontejnerů	`list (EntityCollection)`

Zde je ukázkový kontejner JSON obsahující více typů:

{
    "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" }
    ]
}

Stejný kontejner v 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>

Úvod do dotazů UFX

UFX dotazy jsou zapsány jako UFX kontejnery založené na XML. Vlastnosti v kontejneru mohou obsahovat směrnice UFX pro dynamické dotazování dat. UFX dotaz se spouští na objektech v paměti, nikoli XML. Pouze směrnice jsou napsány v XML. Jeho výstup lze serializovat do JSON nebo XML.

Následující dotaz UFX definuje vlastnost accounts v kontejneru s UFX směrnicí source. To má za následek vložený FetchXML prováděný aplikací Dynamics 365 a vlastnost accounts, která se stane seznamem kontejnerů, nebo EntityCollection, kde je každý kontejner instancí záznamu obchodního vztahu z 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>

Dotaz UFX se zpracovává postupně a může obsahovat mnoho dotazů FetchXML.

Zde je fragment kódu výsledku z předchozího dotazu UFX serializovaného do XML. Všimněte si, že některé hodnoty mají metadata, které je dále popisují.

<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 směrnice select bere výraz XPath, který vybere hodnoty z aktuálního kontejneru.

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

Výsledný kontejner v XML:

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

Nejvýkonnějším aspektem UFX dotazu je zcela jistě jeho schopnost dynamicky generovat FetchXML na základě vstupních dat.

V následující ukázce jsme hledali obchodní vztahy podle hodnoty zadané uživatelem a dostupné jako UFX kontejner pomocí proměnné XPath $input. Všimněte si směrnic if a value na prvku 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>

Pokud by vlastnost NameFilter ve vstupním kontejneru obsahovala %city%, vytvořená podmínka FetchXML provedená aplikací Dynamics 365 by vypadala takto.

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

Klíče, hodnoty a metadata

Kontejner UFX obsahuje klíče a hodnoty a některé hodnoty mají další metadata, která je dále popisují.

Příkladem může být hodnota typu lookup (EntityReference). Při dotazu z Dynamics 365 prostřednictvím FetchXML se vrátí logický název entity a formátovaný zobrazovaný název záznamu. Kontejner UFX uchovává tyto dodatečné informace jako metadata připojená k primární hodnotě.

lookup s metadaty, serializovaný do JSON, vypadá takto:

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

V XML:

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

XPath přes data Dynamics 365

Zapsaná data v UFX kontejneru umožňují, aby je viděl dotaz UFX ve strukturovaném formátu a použil XPath pro přechod přes data a volbu hodnot z dat.

Výraz XPath specifikovaný ve směrnici UFX vidí data v kontejneru podobně jako ve struktuře kontejneru ve formě serializovaného XML. Data jsou však uložena v paměti v objektech .NET objekty (v instancích typu Entity a EntityCollection ) a nikoli v dokumentech XML.

Dodatek A: Odkaz na typ UFX

Poznámka: Všechny typy UFX podporují ufx-type a ufx-formatvalue metadata. Další metadata jsou popsána u jednotlivých typů v tabulce níže.

Název UFX	Kód typu atributu	Název .NET	Metadata UFX
bool	logický	logický
int	Celé číslo	Int32
long	BigInt	Int64
double	Dvojitá přesnost	Dvojitá přesnost
decimal (desetinné číslo)	Desetinné číslo (decimal)	Desetinné číslo (decimal)
datetime	Datum a čas	Datum a čas
guid	Uniqueidentifier	Guid
řetězec	Memo	Řetězec
money (peněžní hodnota)	Peněžní hodnota (money)	Peněžní hodnota (money)
option	Rozevírací seznam	OptionSetValue
lookup	Vyhledávání	EntityReference	`ufx-logicalname`
bag	Nelze použít	Entita	`ufx-id` `ufx-logicalname`
seznam	Nelze použít	EntityCollection
Nelze použít	Nelze použít	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Dodatek B: Směrnice dotazu UFX

UFX směrnice lze použít na vlastnostech kontejneru a na prvcích XML dotazu FetchXML.

Směrnice kontejneru UFX

Attribute (Atribut)	Value	Popis
`ufx:if`	XPath	Otestuje výraz XPath a pouze zpracovává vlastnost, pokud test vrátí hodnotu true
`ufx:source`	`fetch`	Spustí vložený `<fetch>` XML prvek a přiřadí výsledek k vlastnosti
`ufx:select`	XPath	Spustí výraz XPath a přiřadí výsledek k vlastnosti Při dotazu na `bag` nebo `list` lze určit podřízený `bag` v XML formě pro převod výsedku výrazu XPath

Směrnice UFX FetchXML

Element (Prvek)	Attribute (Atribut)	Value	Popis
Všechny prvky	`ufx:if`	XPath	Otestuje výraz XPath a vydá prvek XML jen tehdy, pokud je test úspěšný
`ufx:apply`	`select`	XPath	Loops přes sadu uzlů vrácenou výrazem XPath a výstupem jsou podřízené prvky XML, jeden pro každý uzel
`ufx:value`	`select`	XPath	Provede výraz XPath a vydá výsledek v aktuálním prvku XML
`ufx:value`	`attribute`	název atributu	Přiřadí výsledek výrazu XPath k určenému názvu atributu na aktuálním prvku XML

Dodatek C: Funkce UFX XPath

UFX přidává několik nových funkcí, kromě těch, které jsou k dispozici nativně ve výrazu XPath.

datetime()

DATETIME(): vrací aktuální čas v UTC

list()

list(bag | list, ...[kontejner | seznam]): Vezme počet hodnot bag (kontejner) nebo list (seznam) jako vstup a spojí je do jednoho list

lookup-to-list()

Vyhledávání list(lookup, ...[vyhledávání]): Vezme počet hodnot lookup (vyhledávání), převede každou z nich na bag (kontejner) se sadou metadat ufx-id a ufx-logicalname a sloučí je do jednoho list (seznam)

option-to-list()

option-to-list(option, ...[volba]): Vezme počet hodnot option (volba), převede každou z nich do bag (kontejner) s jedinou vlastností option a sloučí je do jednoho list (seznam)

order()

order(list, string, bool): Seřadí seznam podle vlastnosti v každém kontejneru. Vlastnost je určena v argumentu 2, sestupně je určena v argumentu 3.
order(list, list): Seřadí seznam podle několika pořadí řazení, určených jako seznam v argumentu 2. Každý bag ve druhém seznam může mít vlastnosti name a descending

iif()

iif(any, any, any): Pokud má argument 1 hodnotu true, vrátí argument 2, jinak vrátí argument 3

Dodatek D: Proměnné UFX XPath

Jméno	Popis
$input	`bag` dostupná pro dotaz UFX se vstupními hodnotami
$null	Konstanta null. Výběr `$null` na vlastnosti odebere vlastnost z kontejneru
$current	Odkaz na aktuální kontejner zpracovávaný dotazem UFX

Viz také

Pochopení a přizpůsobení párování zdrojů v Universal Resource Scheduling

Poznámky k rozšiřitelnosti Universal Resource Scheduling

Sdílet prostřednictvím