Extindeți Universal Resource Scheduling cu Universal FetchXML

Articol
06/06/2024

UFX este un limbaj de interogare avansat care vă permite să interogați date folosind forma dinamică FetchXML și pregătiți datele rezultate pentru consumul de către soluția Universal Resource Scheduling (URS). Acest limbaj de interogare vă permite să creați interogări particularizate pentru a personaliza și extinde filtrele pentru tabloul de planificare și asistentul de planificare pentru a satisface nevoile de business unice ale organizației.

UFX este format din două componente sac UFX și interogare UFX.

Sac simplu UFX

Un sac UFX conține date statice introduse. În memorie, acesta este reprezentat ca un dicționar cu chei și valori. Acesta poate fi serializat la JSON și XML. Având datele tastate permite o Interogare UFX pentru interogarea datelor din acesta, și clientul UI pentru asociere.

Din motive practice și de performanță, sacul din memorie este implementat peste obiectul SDK Entity al aplicației Dynamics 365.

Sac eșantion ce conține două valori.

În memorie:

cheie	valoare	tip
nume	Ioan	șir
vârstă	36	int

În JSON:

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

În XML:

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

Tipuri de UFX acceptate

Un sac UFX poate conține valori de multe tipuri. Acestea sunt clasificate în trei clase de tip:

Categorie	Valoare
Tipuri simple	`bool (Boolean)`,`int (Int32)`,`long (Int64)`,`double (Double)`,`decimal (Decimal)`,`datetime (DateTime)`,`guid (Guid)`,`string (String)` Tipuri simple specifice Dynamics 365: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Alți saci	`bag (Entity)`
Listă de saci	`list (EntityCollection)`

Iată o mostră de sac JSON ce conține mai multe tipuri:

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

Același sac în 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>

Introducere în Interogări UFX

Interogările UFX sunt scrise ca Saci UFXi bazați pe XML. Proprietățile din sac pot conține Directivele UFX pentru a interoga datele dinamic. O interogare UFX este executată pe obiectele din memorie, nu XML. Numai directivele sunt scrise în XML. Ieșirea sa poate fi serializată ca JSON sau XML.

Următoarea interogare UFX definește accounts proprietatea în sacul cu source directiva UFX. Acest lucru duce la FetchXML în linie să fie executat de Dynamics 365 iar proprietatea accounts va deveni o listă de saci, sau un EntityCollection, cu fiecare sac fiind o instanță a unei înregistrări de cont din 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>

O interogare UFX este procesată secvențial și poate să conțină multe interogări FetchXML.

Iată un fragment din rezultatul interogării UFX anterioare serializate XML. Observați că unele valori au metadate suplimentare care le descriu.

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

Directiva UFX select preia o expresie XPath care selectează valorile din sacul curent.

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

Sacul rezultat în XML:

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

Desigur, aspectul cel mai puternic al unei interogări UFX este capacitatea sa de a genera dinamic FetchXML pe baza datelor de intrare.

În eșantionul de mai jos, am căutare pentru conturile cu o valoare furnizată de utilizator și disponibile ca un sac UFX prin variabila XPath $input. Observați UFX dacă și valoarea directivelor asupra elementului 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>

Dacă proprietatea NameFilter din sacul de intrare ar cuprinde condiția %city% pentru FetchXML produs executată de Dynamics 365 ar arăta astfel.

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

Chei, valori și metadate

Un sac UFX conține chei și valori, cu unele valori având metadate suplimentare descriindu-le în continuare.

Un exemplu ar putea fi o valoare de tip lookup (EntityReference). Când este interogat din Dynamics 365 prin FetchXML, acesta va returna numele logic al entității, precum și numele de afișat formatat al înregistrării. Sacul UFX păstrează aceste informații suplimentare ca metadate atașate la valoarea primară.

Serializată la JSON, o lookup cu metadate arata astfel:

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

În XML:

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

XPath peste data Dynamics 365

Având datele într-un sac UFX dactilografiate, permite o interogare UFX pentru a se vedea într-un format structurat și folosirea XPath pentru a trece peste date și selectați valorile obținute.

O expresie XPath specificată într-o directivă UFX vede datele din geantă asemănătoare cu structura sac în forma serializată XML. Cu toate acestea, datele sunt stocate în memoria internă .NET (în cazurile de Entity și EntityCollection tipurile), și nu în documentele XML.

Anexa A: Tip de referință UFX

Notă: toate tipurile UFX susțin ufx-type și ufx-formatvalue metadate. Metadate suplimentare sunt descrise lângă fiecare tip în tabelul de mai jos.

Nume UFX	Cod tip de atribut	Nume .NET	Metadate UFX
boolean	Booleean	Booleean
int	Întreg	Int32
Lung	BigInt	Int64
dublu	Dublu	Dublu
zecimal	Zecimal	Zecimal
datetime	DateTime	DateTime
guid	Identificator unic	Guid
șir	Memo	Coadă
bani	Bani	Bani
opțiune	Listă verticală	OptionSetValue
căutare	Căutare	EntityReference	`ufx-logicalname`
sac	Nu se aplică	Entitate	`ufx-id` `ufx-logicalname`
list	Nu se aplică	EntityCollection
Nu se aplică	Nu se aplică	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Anexa B: directive de interogare UFX

Directivele UFX pot fi folosite pe proprietățile și pe elemente XML ale unei interogări FetchXML.

Directivele sac UFX

Atribut	Value	Descriere
`ufx:if`	Xpath	Teste expresia XPath și procesează proprietatea numai dacă testul returnează adevărat
`ufx:source`	`fetch`	Execută inline elementul XML `<fetch>` și atribuie rezultatul proprietății
`ufx:select`	Xpath	Execută expresia XPath și atribuie rezultatul proprietății Când interogarea pentru o `bag` sau `list` un copil opțional `bag` în formularul XML se poate specifica transformarea rezultatului expresiei XPath

Directivele UFX FetchXML

Element	Atribut	Value	Descriere
Toate elemente	`ufx:if`	Xpath	Testează expresia XPath și emite doar elementul XML, în cazul în care testele reușesc
`ufx:apply`	`select`	Xpath	Bucle peste nodeset returnate cu expresia XPath și ieșirile elementelor XML copil o dată pentru fiecare nod
`ufx:value`	`select`	Xpath	Execută expresia XPath și prezintă rezultatul în elementul XML curent
`ufx:value`	`attribute`	nume atribut	Atribuie rezultatul expresiei XPath pentru numele atribut specificat pe elementul curent XML

Anexa C: Funcții UFX XPath

UFX adaugă o serie de noi funcții în plus față de cele disponibile nativ în XPath.

datetime()

datetime(): Returnează timpul curent în UTC

listă()

listă(sac | listă, ...[sac | listă]): ia un număr de valori bag sau list ca intrare și le aplatizează într-o singură list

Listă căutare pentru()

listă de căutare(căutare, ...[căutare]): ia un număr de valori lookup, le transformă pe fiecare într-un bag cu set de metadate ufx-id și ufx-logicalname și le aplatizează într-o singură list

option-to-list()

opțiune listă de căutare(opțiune, ...[opțiune]): ia un număr de valori option, le transformă pe fiecare într-un bag cu o singură proprietate option și le aplatizează într-o singură list

order()

Ordine (lista, coarde, bool): ordonează o listă conform proprietății din fiecare sac. Proprietatea este specificată în argumentul 2, reducerea este specificat în argumentul 3.
Ordine (listă, listă): Comandați o listă prin multiple ordine de organizare specificate ca listă în argumentul 2. Fiecare bag în a doua listă pot avea o name și descending de proprietate

iif()

IIF (oricare, orice, oricare): în cazul în care argumentul 1 este adevărat, întoarce argumentul 2, altfel întoarce argumentul 3

Anexa D: Variabilă UFX XPath

Nume	Descriere
$intrare	Un `bag` disponibil pentru interogarea UFX cu valori de intrare
$null	O constantă nulă. Selectarea `$null` pe o proprietate elimină proprietatea din pungă
$current	Referință la sacul curent ca fiind prelucrate de interogarea UFX

Consultați și

Înțelegerea și particularizarea potrivirii resurselor în Universal Resource Scheduling

Universal Resource Scheduling note de lansare privind extensibilitatea

Partajați prin