Partilhar via

Expandir o Universal Resource Scheduling com o Universal FetchXML

  • Artigo

UFX é uma linguagem de consulta avançada que lhe permite consultar dados utilizando FetchXML dinâmico, moldar e preparar os dados resultantes para consumo pela solução Universal Resource Scheduling (URS). Este linguagem de consulta permite-lhe criar consultas personalizadas para personalizar e expandir o quadro da agenda e agendar filtros do assistente de agendamento para satisfazer as necessidades de negócio exclusivas da organização.

UFX consiste em dois componentes, Pacote UFX e Consulta UFX.

Pacote UFX simples

Um Pacote UFX contém dados digitados estáticos. Na memória, é representado como um dicionário com chaves e valores. Pode ser serializado para JSON e XML. Ter os dados digitados permite que uma Consulta UFX consulte dados a partir deles, bem como cliente IU para o ligar.

Por razões práticas e de desempenho o pacote na memória é implementado sobre o objeto Entity das aplicações SDK do Dynamics 365.

Pacote de exemplo que contém dois valores.

Na memória:

key valor tipo
nome João Cadeia de carateres
idade 36 número inteiro

Em JSON:

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

Em XML:

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

Tipos suportados UFX

Um Pacote UFX pode conter valores de muitos tipos. Estes são categorizadas em 3 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)
Outros pacotes bag (Entity)
Lista de Pacotes list (EntityCollection)

Eis um pacote JSON de exemplo que contem 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" }
    ]
}

O mesmo pacote 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 a Consultas UFX

Consultas UFX são escritas como Pacotes UFX baseados em XML. Propriedades no pacote podem conter Diretivas UFX para consultar dados dinamicamente. Uma Consulta UFX é executada em objetos na memória, não XML. Só as diretivas são escritas em XML. Os seus dados de saída podem ser serializados em JSON ou XML.

A Consulta UFX seguinte define a propriedade accounts no pacote com a diretiva UFX source. Isto faz com que o FetchXML inline seja executado pelo Dynamics 365 e que a propriedade accounts se torne numa lista de pacotes, ou numa EntityCollection, sendo que cada pacote é uma instância de um registo de 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.

Segue-se um fragmento dos resultados da consulta UFX anterior serializados para XML. Observe que alguns valores têm metadados adicionais que os descrevem.

<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 utiliza uma expressão XPath que seleciona valores do pacote 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>

O pacote resultante em XML:

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

Certamente, o aspeto mais poderoso de uma consulta UFX é a capacidade para gerar dinamicamente FetchXML com base nos dados de entrada.

No exemplo abaixo, vamos procurar contas por um valor fornecido pelo utilizador e disponíveis como um Pacote UFX através da variável $input XPath. Repare nas diretivas UFX se e valor 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 no pacote de entrada contiver %city%, a condição FetchXML produzida executada pelo Dynamics 365 teria este aspeto.

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

Chaves, valores e metadados

Um Pacote UFX contém chaves e valores, com alguns valores contendo metadados adicionais que os descrevem.

Um exemplo poderá ser um valor de tipo lookup (EntityReference). Quando consultado a partir do Dynamics 365 através de FetchXML, apresentará o nome lógico da entidade, bem como o nome a apresentar formatado do registo. O Pacote UFX preserva estas informações adicionais como metadados anexados ao valor primário.

Serializado para JSON, um lookup com metadados tem o seguinte aspeto:

{
    "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 através de dados do Dynamics 365

Ter os dados num Pacote UFX digitado, permite que uma Consulta UFX o veja num formato estruturado e utilizar XPath para percorrer os dados e selecionar os valores do mesmo.

Uma expressão XPath especificada numa diretiva UFX vê os dados no pacote de forma semelhante à estrutura do pacote no formulário serializado XML. No entanto, os dados são armazenados em objetos .NET na memória (em instâncias de tipos Entity e EntityCollection) e não em documentos XML.

Apêndice A: referência de tipo UFX

Nota: todos os tipos de UFX suportam os metadados ufx-type e ufx-formatvalue. Metadados adicionais são descritos junto de cada tipo na tabela abaixo.

Nome do UFX Código do Tipo de Atributo Nome .NET Metadados UFX
booleano Booleano Booleano
número inteiro Número Inteiro Int32
longo BigInt Int64
duplo Duplo Duplo
decimal Decimal Decimal
datetime DateTime DateTime
guid Uniqueidentifier Guid
Cadeia de carateres Memorando Cadeia
dinheiro Dinheiro Dinheiro
opção Lista de Opções OptionSetValue
pesquisa Pesquisa EntityReference ufx-logicalname
pacote N/D Entidade ufx-id
ufx-logicalname
list N/D EntityCollection
N/D N/D AliasedValue ufx-aliasentity
ufx-aliasattribute

Apêndice B: diretivas de Consulta UFX

Diretivas UFX podem ser utilizadas em propriedades de pacote e em elementos XML de uma consulta FetchXML.

Diretivas de Pacote UFX

Atributo Value Descrição
ufx:if XPath Testa a expressão XPath e apenas processa a propriedade se o teste devolve verdadeiro
ufx:source fetch Executa o elemento XML <fetch> inline e atribui o resultado à propriedade
ufx:select XPath Executa a expressão XPath e atribui o resultado à propriedade
Quando consulta por um bag ou list um bag subordinado opcional em forma XML pode ser especificado para transformar o resultado da expressão XPath

Diretivas UFX FetchXML

Elemento Atributo Value Descrição
Todos os elementos ufx:if XPath Testa a expressão XPath e emite apenas o elemento XML se os testes tiverem êxito
ufx:apply select XPath Repete por cima do conjunto de nós devolvido pela expressão XPath e gera os elementos XML subordinados uma só 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 UFX XPath

UFX adiciona um número de novas funções para além das disponíveis nativamente no XPath.

datetime()

  • datetime(): devolve a hora atual em UTC

list()

  • list(bag | list, ...[bag | list]): recebe um número de valores bag ou list como entrada e agrega-os numa única list

lookup-to-list()

  • lookup-to-list(lookup, ...[lookup]): recebe um número de valores lookup, converte cada um deles num bag com o conjunto de metadados ufx-id e ufx-logicalname, e agrega-os numa única list

option-to-list()

  • option-to-list(option, ...[option]): recebe um número de valores option, converte cada um deles num bag com uma única propriedade option, e agrega-os numa única list

order()

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

IIf()

  • iif(any, any, any): se argumento 1 for verdadeiro, devolve argumento 2, caso contrário, devolve argumento 3

Apêndice D: variáveis UFX XPath

Nome Descrição
$input Um bag disponível para a Consulta UFX com valores de entrada
$null Uma constante nula. Selecionar $null numa propriedade remove a propriedade do pacote
$current Referência ao pacote atual a ser processado pela Consulta UFX

Consulte também

Noções básicas e personalizar a correspondência de recursos no Universal Resource Scheduling

Notas de versão da extensibilidade do Universal Resource Scheduling