Ampliar Universal Resource Scheduling con Universal FetchXML

Artículo
06/06/2024

UFX es un lenguaje de consulta avanzado que le permite consultar datos utilizando FetchXML dinámico, así como dar forma y preparar los datos resultantes para su uso por la solución Universal Resource Scheduling (URS). Este idioma de consulta le permite crear consultas personalizadas para personalizar y ampliar el tablero de programación y programar filtros del asistente para cumplir con las necesidades de negocio exclusivas de la organización.

UFX consta de dos componentes: contenedor UFX y consulta UFX.

Contenedor UFX simple

Un contenedor UFX contiene datos escritos estáticos. En la memoria, se representa como un diccionario con claves y valores. Se puede serializar con JSON y XML. Disponer de datos escritos permite a una consulta UFX realizar una consulta de datos desde ella y posibilita la vinculación de la interfaz de usuario del cliente con ella.

Por razones prácticas y de rendimiento, el contenedor en memoria se implementa en la parte superior del objeto Entity de aplicaciones de Dynamics 365 SDK.

El contenedor de ejemplo contiene dos valores.

En memoria:

tecla	valor	tipo
nombre	John	cadena
edad	36	int

En JSON:

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

En XML:

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

Tipos admitidos de UFX

Un contenedor UFX puede disponer de valores de muchos tipos. Se categorizan en tres clases de tipos:

Categoría	valor
Tipos sencillos	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Tipos sencillos específicos de Dynamics 365: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Otros contenedores	`bag (Entity)`
Lista de contenedores	`list (EntityCollection)`

Aquí le mostramos un contenedor JSON de ejemplo que contiene más tipos:

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

El mismo contenedor en 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>

Introducción a consultas UFX

Las consultas UFX se escriben como contenedores UFX basados en XML. Las propiedades del contenedor pueden contener directivas UFX para consultar datos dinámicamente. Una consulta UFX se ejecuta en objetos en memoria, no XML. Solo las directivas se escriben en XML. El resultado se puede serializar en JSON o XML.

La siguiente consulta UFX define la propiedad accounts en el contenedor con la directiva UFX source. Esto provoca que Dynamics 365 ejecute este resultado en FetchXML en línea y que la propiedad accounts sea una lista de contenedores, o EntityCollection, en la que cada contenedor es una instancia de un registro de cuenta de 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>

Se procesa una consulta UFX de forma secuencial y puede contener varias consultas FetchXML.

Aquí se muestra un fragmento del resultado de la consulta UFX anterior serializada en XML. Tenga en cuenta que algunos valores disponen de metadatos además de describirlos.

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

La directiva UFX select toma la expresión de XPath que selecciona valores del contenedor actual.

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

El contenedor resultante en XML:

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

Realmente, el aspecto más potente de una consulta UFX es la capacidad de generar dinámicamente FetchXML basado en datos de entrada.

En el ejemplo siguiente, buscamos cuentas por un valor proporcionado por el usuario y se encuentra disponible como contenedor UFX a través de la variable $input de XPath. Tenga en cuenta las directivas if y value de UFX sobre el elemento 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>

Si la propiedad NameFilter del contenedor de entrada contenía %city%, la condición de FetchXML producida ejecutada por Dynamics 365 tendría un aspecto similar a este.

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

Claves, valores y metadatos

Un contenedor UFX contiene claves y valores, con algunos valores que disponen de metadatos adicionales que los describen aún más.

Un ejemplo podría ser un valor de tipo lookup (EntityReference). Cuando se realice la consulta de Dynamics 365 a través de FetchXML, se devolverá el nombre lógico de la entidad, así como el nombre con formato del registro. El contenedor UFX conserva esta información adicional como metadatos adjuntos al valor principal.

Con la serialización JSON, lookup con metadatos tendrá el siguiente aspecto:

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

En XML:

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

XPath sobre datos de Dynamics 365

Disponer de los datos escritos en un contenedor UFX permite a la consulta UFX verlos con un formato estructurado y usar XPath para recorrer los datos y seleccionar los valores a partir de ellos.

Una expresión XPath especificada en una directiva UFX comprueba los datos del contenedor que son parecidos a la estructura del contenedor en el formulario con serialización XML. Sin embargo, los datos se almacenan en objetos .NET en memoria (en instancias de tipos Entity y EntityCollection) y no en documentos XML.

Apéndice A: Referencia de tipo UFX

Nota: Todos los tipos UFX admiten los metadatos ufx-type y ufx-formatvalue. Los metadatos adicionales se describen junto a cada tipo en la siguiente tabla.

Nombre de UFX	Código de tipo de atributo	Nombre de .NET	Metadatos UFX
bool	Valor booleano	Valor booleano
int	Entero	Int32
long	BigInt	Int64
doble	Double	Double
decimal	Decimal	Decimal
datetime	DateTime	DateTime
guid	Uniqueidentifier	Guid
cadena	Memorando	String
money	Dinero	Dinero
opción	Picklist	OptionSetValue
búsqueda	Búsqueda	EntityReference	`ufx-logicalname`
bag	N/D	Entity	`ufx-id` `ufx-logicalname`
lista	N/D	EntityCollection
N/D	N/D	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Apéndice B: Directivas de consulta UFX

Las directivas UFX se pueden usar en las propiedades del contenedor y en elementos XML de una consulta de FetchXML.

Directivas de contenedor UFX

Atributo	Value	Descripción
`ufx:if`	XPath	Realiza una prueba de la expresión XPath y solo procesa la propiedad si la prueba devuelve true.
`ufx:source`	`fetch`	Ejecuta el elemento XML `<fetch>` en línea y asigna el resultado a la propiedad.
`ufx:select`	XPath	Ejecuta la expresión XPath y asigna el resultado a la propiedad. Cuando se realiza una consulta para `bag` o `list`, puede especificarse un elemento secundario opcional `bag` con formato XML para transformar el resultado de la expresión XPath.

Directivas FetchXML UFX

Elemento	Atributo	Value	Descripción
Todos los elementos	`ufx:if`	XPath	Realiza una prueba de la expresión XPath y solo emite el elemento XML si las pruebas son correctas
`ufx:apply`	`select`	XPath	Recorre en bucle el conjunto de nodos devuelto por la expresión XPath y genera los elementos XML secundarios una vez para cada nodo.
`ufx:value`	`select`	XPath	Ejecuta la expresión XPath y genera el resultado en el elemento XML actual.
`ufx:value`	`attribute`	nombre de atributo	Asigna el resultado de la expresión XPath al nombre de atributo especificado en el elemento XML actual.

Apéndice C: Funciones XPath UFX

UFX agrega un número de funciones nuevas además de las ya disponibles de forma nativa en XPath.

datetime()

datetime(): devuelve la hora actual en UTC.

list()

list(bag | list, ...[bag | list]): toma un número de valores bag o list como entrada y los aplana en una única list.

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): toma un número de valores lookup, los convierte en un bag con el conjunto de metadatos ufx-id y ufx-logicalname y los aplana en una única list.

option-to-list()

option-to-list(option, ...[option]): toma un número de valores option, los convierte en un bag con una única propiedad option y los aplana en una única list.

order()

order(list, string, bool): ordena una lista por propiedad en cada contenedor. La propiedad se especifica en el argumento 2. La propiedad descending se especifica en el argumento 3.
order(list, list): ordena una lista por varios criterios de ordenación especificados como una lista en el argumento 2. Cada bag de la segunda lista puede tener una propiedad name and descending.

iif()

iif(any, any, any): si el argumento 1 es true, devuelve el argumento 2. De lo contrario, devuelve el argumento 3.

Apéndice D: Variables de XPath UFX

Nombre	Descripción
$input	Un `bag` disponible para la consulta UFX con valores de entrada.
$null	Una constante nula. Si selecciona `$null` en una propiedad, se quita la propiedad del contenedor.
$current	Referencia al contenedor actual que procesa la consulta UFX.

Consultar también

Comprensión y personalización de la coincidencia del recurso en Universal Resource Scheduling

Notas de la versión de extensibilidad de Universal Resource Scheduling

Compartir a través de