Delen via

Universal Resource Scheduling uitbreiden met Universeel FetchXML

  • Artikel

UFX is een geavanceerde querytaal waarmee u query's op gegevens kunt uitvoeren op basis van dynamische FetchXML en de resulterende gegevens voor verbruik kunt vormen en voorbereiden voor gebruik door de oplossing URS (Universal Resource Scheduling). Met deze querytaal kunt u aangepaste query's maken om de planbord- en planningsassistentfilters uit te breiden om te voldoen aan de unieke zakelijke behoeften van de organisatie.

UFX bestaat uit twee componenten: UFX-verzameling en UFX-query.

Eenvoudige UFX-verzameling

Een UFX-verzameling bevat statische getypte gegevens. In het geheugen wordt dit weergegeven als een woordenboek met sleutels en waarden. Het kan naar JSON en XML worden geserialiseerd. Omdat de gegevens getypt zijn, kan er een UFX-query op de gegevens worden uitgevoerd en kan er client-UI aan worden gebonden.

Uit praktische overwegingen en omwille van de prestaties wordt de verzameling in het geheugen geïmplementeerd naast het SDK-object Entity van de Dynamics 365-apps.

Voorbeeldverzameling met twee waarden.

In geheugen:

key waarde type
naam Johan tekenreeks
age 36 geheel getal (int)

In JSON:

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

In XML:

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

Door UFX ondersteunde typen

Een UFX-verzameling kan waarden van vele typen bevatten. Deze zijn gecategoriseerd in drie typeklassen:

Categorie Weergegeven als
Eenvoudige typen bool (Boolean), int (Int32), long (Int64), double (Double), decimal (Decimal), datetime (DateTime), guid (Guid), string (String)
Specifieke eenvoudige typen voor Dynamics 365: money (Money), option (OptionSet), lookup (EntityReference)
Andere verzamelingen bag (Entity)
Lijst met verzamelingen list (EntityCollection)

Hier volgt een voorbeeld van een JSON-verzameling met meer typen:

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

Dezelfde verzameling in 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>

Inleiding tot UFX-query's

UFX-query's worden geschreven als op XML gebaseerde UFX-verzamelingen. Eigenschappen in de verzameling kunnen UFX-richtlijnen bevatten om dynamisch query's op gegevens uit te voeren. Een UFX-query wordt uitgevoerd op objecten in het geheugen, niet op XML. Alleen de richtlijnen worden geschreven in XML. De uitvoer kan naar JSON of XML worden geserialiseerd.

Met de volgende UFX-query wordt de eigenschap accounts in de verzameling gedefinieerd met de UFX-richtlijn source. Dit leidt ertoe dat de inline FetchXML wordt uitgevoerd door Dynamics 365 en de eigenschap accounts een lijst met verzamelingen wordt of een EntityCollection, waarbij elke verzameling een exemplaar van een accountrecord uit Dynamics 365 is.

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

Een UFX-query wordt op volgorde verwerkt en kan veel FetchXML-query's bevatten.

Hier is een fragment van het resultaat van de vorige naar XML geserialiseerde UFX-query. Naast sommige waarden worden nog metagegevens weergegeven.

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

De UFX-richtlijn select gebruikt een XPath-expressie waarmee waarden uit de huidige verzameling worden geselecteerd.

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

De resulterende verzameling in XML:

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

Het krachtigste aspect van een UFX-query is het vermogen om dynamisch FetchXML te genereren op basis van invoergegevens.

In het onderstaande voorbeeld zoeken we naar accounts op basis van een waarde die door de gebruiker is opgegeven en als UFX-verzameling beschikbaar is via de XPath-variabele $input. Let op de UFX-richtlijnen if en value in het element 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>

Als de eigenschap NameFilter in de invoerverzameling %city% bevatte, zou de geproduceerde FetchXML-voorwaarde die door Dynamics 365 wordt uitgevoerd er als volgt uitzien.

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

Sleutels, waarden en metagegevens

Een UFX-verzameling bevat sleutels en waarden, waarbij sommige waarden extra metagegevens bevatten waarin deze gegevens verder worden beschreven.

Een voorbeeld kan een waarde van het type lookup (EntityReference) zijn. Wanneer vanuit Dynamics 365 via FetchXML een query wordt uitgevoerd, wordt de logische naam van de entiteit en de opgemaakte weergavenaam van de record geretourneerd. In de UFX-verzameling worden deze aanvullende gegevens bewaard als metagegevens die aan de primaire waarde zijn gekoppeld.

Geserialiseerd naar JSON ziet een lookup met metagegevens er als volgt uit:

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

In XML:

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

XPath via Dynamics 365-gegevens

Omdat de gegevens in een UFX-verzameling getypt zijn, kunnen deze met een UFX-query in een gestructureerde indeling worden weergegeven en worden doorlopen om hier waarden in te selecteren.

Bij een XPath-expressie opgegeven in een UFX-richtlijn lijken de gegevens in de verzameling op de structuur van de verzameling in XML-geserialiseerde vorm. De gegevens worden echter opgeslagen in .NET-objecten in het geheugen (in exemplaren van van de typen Entity en EntityCollection) en niet in XML-documenten.

Bijlage A: UFX-typen

Opmerking: alle UFX-typen ondersteunen de metagegevens ufx-type en ufx-formatvalue. Extra metagegevens worden naast elk type in de onderstaande tabel beschreven.

UFX-naam Code kenmerktype .NET-naam UFX-metagegevens
bool Boole-waarde Boole-waarde
geheel getal (int) Geheel getal Int32
long BigInt Int64
dubbel Double Double
decimaal Decimaal Decimaal
datum/tijd (datetime) DateTime DateTime
guid Uniqueidentifier GUID
tekenreeks Memo Tekenreeks
valuta (money) Geld Geld
optie Selectielijst OptionSetValue
opzoeken Opzoekveld EntityReference ufx-logicalname
bag N.v.t. Entiteit ufx-id
ufx-logicalname
lijst N.v.t. EntityCollection
N.v.t. N.v.t. AliasedValue ufx-aliasentity
ufx-aliasattribute

Bijlage B: Richtlijnen voor UFX-query's

UFX-richtlijnen kunnen worden gebruikt voor verzamelingseigenschappen en in XML-elementen van een FetchXML-query.

UFX-verzamelingsrichtlijnen

kenmerk Value Beschrijving
ufx:if XPath Hiermee wordt de XPath-expressie getest en wordt de eigenschap alleen verwerkt als de test de waarde true retourneert
ufx:source fetch Hiermee wordt het inline XML-element <fetch> uitgevoerd en wordt het resultaat toegewezen aan de eigenschap
ufx:select XPath Hiermee wordt de XPath-expressie uitgevoerd en wordt het resultaat toegewezen aan de eigenschap
Wanneer u een query wilt uitvoeren op een bag of list, kan een optionele onderliggende bag in XML-vorm worden opgegeven om het resultaat van de XPath-expressie te transformeren

UFX FetchXML-richtlijnen

Element kenmerk Value Beschrijving
Alle elementen ufx:if XPath Hiermee wordt de XPath-expressie getest en wordt het XML-element alleen uitgegeven als de test slaagt
ufx:apply select XPath Hiermee wordt een lusbewerking uitgevoerd voor de knooppuntenset die wordt geretourneerd door de XPath-expressie en worden voor elk knooppunt één keer de onderliggende XML-elementen geretourneerd
ufx:value select XPath Hiermee wordt de XPath-expressie uitgevoerd en wordt het resultaat uitgevoerd in het huidige XML-element
ufx:value attribute kenmerknaam Hiermee wordt het XPath-expressieresultaat toegewezen aan de opgegeven kenmerknaam voor het huidige XML-element

Bijlage C: UFX XPath-functies

UFX voegt een aantal nieuwe functies toe naast de native XPath-functies.

datetime()

  • datetime(): retourneert de huidige tijd in UTC

list()

  • list(bag | list, ...[bag | list]): hiermee wordt een aantal waarden voor bag of list als invoer gebruikt en worden deze opgenomen in één list

lookup-to-list()

  • lookup-to-list(lookup, ...[lookup]): hiermee wordt een aantal waarden voor lookup gebruikt, wordt elk geconverteerd naar een bag met de ingestelde metagegevens ufx-id en ufx-logicalname en worden ze platgemaakt in één list

option-to-list()

  • option-to-list(option, ...[option]): hiermee wordt een aantal waarden voor option gebruikt, wordt elk geconverteerd naar een bag met één eigenschap option en worden ze platgemaakt in één list

order()

  • order(list, string, bool): hiermee wordt een lijst gesorteerd op een eigenschap in elke verzameling. De eigenschap wordt opgegeven in argument 2, aflopend wordt opgegeven in argument 3.
  • order(list, list): sorteer een lijst op meerdere sorteervolgordes opgegeven als een lijst in argument 2. Elke bag in de tweede lijst kan een eigenschap descending en name hebben

iif()

  • iif(any, any, any): als argument 1 true is, wordt argument 2 geretourneerd en anders argument 3

Bijlage D: UFX XPath-variabelen

Naam Beschrijving
$input Een beschikbare bag voor de UFX-query met invoerwaarden
$null Een null-constante. Wanneer $null voor een eigenschap wordt geselecteerd, wordt de eigenschap uit de verzameling verwijderd
$current Verwijzing naar de huidige verzameling die door de UFX-query wordt verwerkt

Zie ook

Vergelijken van resources in Universal Resource Scheduling begrijpen en aanpassen

Releaseopmerkingen voor Universal Resource Scheduling-uitbreidbaarheid