Compartilhar via

Estender o Universal Resource Scheduling com o Universal FetchXML

  • Artigo

UFX é uma linguagem de consulta avançada que permite consultar dados usando FetchXML dinâmico, moldar e preparar os dados resultantes para consumo pela solução Universal Resource Scheduling (URS). Essa linguagem de consulta permite criar consultas personalizadas para personalizar e estender o painel de agendamento e os filtros do assistente de agendamento para que atendam às necessidades de negócios exclusivas da organização.

O UFX consiste em dois componentes: Bag UFX e Consulta UFX.

Bag UFX simples

Uma Bag UFX contém dados tipados estáticos. Na memória, ela é representada como um dicionário com chaves e valores. Ela pode ser serializada para JSON e XML. Ter os dados tipados permite que uma Consulta UFX consulte dados neles e que a interface do usuário do cliente vincule-se a eles.

Por motivos práticos e de desempenho, a bag na memória é implementada sobre o objeto Entity do SDK dos aplicativos do Dynamics 365.

Amostra de bag contendo dois valores.

Na memória:

chave valor tipo
name John string
idade 36 int

Em JSON:

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

Em XML:

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

Tipos de UFX permitidos

Uma Bag UFX pode conter valores de muitos tipos. Eles são categorizados em três classes de tipo:

Categoria Valor
Tipos simples bool (Boolean), int (Int32), long (Int64), double (Double), decimal (Decimal), datetime (DateTime), guid (Guid), string (String)
Tipos simples específicos do Dynamics 365: money (Money), option (OptionSet), lookup (EntityReference)
Outras bags bag (Entity)
Lista de bags list (EntityCollection)

Veja um exemplo de bag JSON contendo mais 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" }
    ]
}

A mesma bag em 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>

Introdução às Consultas UFX

As Consultas UFX são escritas como Bags UFX baseadas em XML. As propriedades na bag podem conter diretivas UFX para consultar dados dinamicamente. Uma Consulta UFX é executada em objetos na memória, não no XML. Somente as diretivas são escritas em XML. Sua saída pode ser serializada para JSON ou XML.

A Consulta UFX a seguir define a propriedade accounts na bag com a diretiva UFX source. Isso faz com que o FetchXML embutido seja executado pelo Dynamics 365 e a propriedade accounts se torne uma lista de bags, ou uma EntityCollection, com cada bag sendo uma instância de um registro da conta do 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>

Uma Consulta UFX é processada sequencialmente e pode conter muitas consultas FetchXML.

Veja a seguir um trecho do resultado da Consulta UFX anterior serializada para XML. Observe que alguns valores têm metadados descrevendo-os com mais detalhes.

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

A diretiva UFX select usa uma expressão XPath que seleciona valores da bag atual.

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

A bag resultante em XML:

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

Certamente o aspecto mais poderoso de uma Consulta UFX é sua capacidade de gerar FetchXML dinamicamente com base nos dados de entrada.

No exemplo abaixo, pesquisamos contas por um valor fornecido pelo usuário e disponível como uma Bag UFX por meio da variável XPath $input. Observe as diretivas UFX if e value no 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>

Se a propriedade NameFilter na bag de entrada contivesse %city%, a condição FetchXML produzida executada pelo Dynamics 365 teria esta aparência.

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

Chaves, valores e metadados

Uma Bag UFX contém chaves e valores, com alguns valores tendo metadados adicionais descrevendo-os com mais detalhes.

Um exemplo pode ser um valor do tipo lookup (EntityReference). Quando consultada no Dynamics 365 por meio de FetchXML, ela retornará o nome lógico da entidade, bem como o nome de exibição formatado do registro. O Saco UFX preserva essas informações adicionais como metadados anexados ao valor principal.

Serializado para JSON, um lookup com metadados se pareceria com isso:

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

Em XML:

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

XPath sobre dados do Dynamics 365

Ter os dados em uma Bag UFX tipada permite que uma Consulta UFX os veja em um formato estruturado e use XPath para percorrer os dados e selecionar valores neles.

Uma expressão XPath especificada em uma diretiva UFX vê os dados na bag de maneira semelhante à estrutura do saco no formulário serializado por XML. Entretanto, os dados são armazenados em objetos .NET na memória (em instâncias de Entity e EntityCollection), e não em documentos XML.

Apêndice A: Referência ao tipo UFX

Observação: todos os tipos UFX aceitam os metadados ufx-type e ufx-formatvalue. Os metadados adicionais são descritos ao lado de cada tipo na tabela abaixo.

Nome UFX Código do tipo de atributo Nome .NET Metadados UFX
bool Booliano Booliano
int Inteiro Int32
long BigInt Int64
double Duplo Duplo
decimal Decimal Decimal
datetime DateTime DateTime
guid Uniqueidentifier Guid
string Memorando Cadeia de caracteres
money Dinheiro Dinheiro
option Atributos de lista de seleção OptionSetValue
pesquisa Pesquisa EntityReference ufx-logicalname
bag N/D Entidade ufx-id
ufx-logicalname
lista N/D EntityCollection
N/D N/D AliasedValue ufx-aliasentity
ufx-aliasattribute

Apêndice B: Diretivas de Consulta UFX

As diretrizes UFX podem ser usadas nas propriedades de bag e em elementos XML de uma consulta FetchXML.

Diretivas da Bag UFX

Atributo Value Descrição
ufx:if XPath Testa a expressão XPath e processa a propriedade apenas se o teste retornar true
ufx:source fetch Executa o elementos XML <fetch> embutido e atribui o resultado à propriedade
ufx:select XPath Executa a expressão XPath e atribui o resultado à propriedade
Ao consultar uma bag ou list, uma bag filho opcional no formulário XML pode ser especificada para transformar o resultado da expressão XPath

Diretivas do FetchXML UFX

Elemento Atributo Value Descrição
Todos os elementos ufx:if XPath Testa a expressão XPath e emite o elemento XML somente se o teste for bem-sucedido
ufx:apply select XPath Executa loop sobre o conjunto de nós retornado pela expressão XPath e gera os elementos XML filho uma vez para cada nó
ufx:value select XPath Executa a expressão XPath e gera o resultado no elemento XML atual
ufx:value attribute nome do atributo Atribui o resultado da expressão XPath ao nome do atributo especificado no elemento XML atual

Apêndice C: Funções XPath UFX

O UFX adiciona várias funções novas além das disponíveis nativamente no XPath.

datetime()

  • datetime(): retorna a hora atual em UTC

list()

  • list(bag | list, ...[bag | list]): obtém vários valores de bag ou list como entrada e mescla-os em uma única list

lookup-to-list()

  • lookup-to-list(lookup, ...[lookup]): obtém vários valores de lookup, converte cada um deles em uma bag com o conjunto de metadados ufx-id e ufx-logicalname, mesclando-os em uma única list

option-to-list()

  • option-to-list(option, ...[option]): obtém vários valores de option, converte cada um deles em uma bag com uma única propriedade option e mescla-os em uma única list

order()

  • order(list, string, bool): ordena uma lista por uma propriedade em cada bag. A propriedade é especificada no argumento 2, descendente é especificado no argumento 3.
  • order(list, list): ordena uma lista por várias ordens de classificação especificadas como uma lista em argumento 2. Cada bag na segunda lista pode ter uma propriedade name e descending

iif()

  • iif(any, any, any): se o argumento 1 for true, retornará argumento 2; caso contrário retornará argumento 3

Apêndice D: Variáveis XPath UFX

Nome Descrição
$input Uma bag disponível para uma Consulta UFX com valores de entrada
$null Uma constante nula. A seleção de $null em uma propriedade remove a propriedade da bag
$current Referência à bag atual que está sendo processada pela Consulta UFX

Consulte também

Noções básicas e personalização da correspondência de recursos no Universal Resource Scheduling

Notas sobre a versão da extensibilidade do Universal Resource Scheduling