Universal Resource Scheduling を拡張する Universal FetchXML

Universal FetchXML (UFX) は、動的 FetchXML を使用してデータをクエリし、結果のデータを整形し、 Universal Resource Scheduling (URS) ソリューションで使用できるように準備できる高度なクエリ言語です。 このクエリ言語を使用すると、カスタム クエリを作成して、スケジュール ボードとスケジュール アシスタント フィルターをカスタマイズおよび拡張し、組織固有のビジネス ニーズを満たすことができます。

UFX は、UFX バッグと UFX クエリの 2 つのコンポーネントで構成されています。

シンプルなUFXバッグ

UFX バッグには、静的型データが含まれています。 メモリ内では、キーと値を持つ辞書をモデル化します。 JSON と XML にシリアル化できます。 データを型指定すると、 UFX クエリ でデータをクエリし、クライアント UI をデータにバインドできます。

実用的およびパフォーマンス上の理由から、インメモリ バッグは Dynamics 365 アプリ SDK Entity オブジェクトの上に実装されます。

2 つの値を含むサンプル バッグ。

メモリ内:

JSON の場合:

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

XML の場合:

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

UFX がサポートするタイプ

UFX バッグには、多くの種類の値を含めることができます。 これらは、次の 3 つのタイプ クラスに分類されます。

以下は、その他のタイプを含むサンプル JSON バッグです。

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

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>

UFX クエリ

UFX クエリは、XML ベースの UFX バッグとして記述されます。 バッグ内のプロパティには、データを動的にクエリするための UFX ディレクティブ を含めることができます。 UFX クエリは、XML ではなくメモリ内オブジェクトに対して実行されます。 ディレクティブのみが XML で記述されます。 その出力は、JSONまたはXMLにシリアル化できます。

次の UFX クエリは、source UFX ディレクティブを使用してバッグ内の accounts プロパティを定義します。 その結果、Dynamics 365 はインライン FetchXML を実行し、 accounts プロパティにバッグのリストを設定します。 各バッグが Dynamics 365 の個々の取引先企業レコードを表す EntityCollection 。

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

UFX クエリは順番に処理され、多くの FetchXML クエリを含めることができます。

以下は、XML にシリアル化された前の UFX クエリの結果のスニペットです。 一部の値には、それらをさらに説明するメタデータがあることを確認します。

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

select UFX ディレクティブは、現在のバッグから値を選択する XPath 式を取ります。

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

XML で生成されたバッグ:

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

確かに、UFX クエリの最も強力な側面は、入力データに基づいて FetchXML を動的に生成する機能です。

次のサンプルでは、ユーザーによって提供され、XPath $input 変数を介して UFX バッグとして使用できる値でアカウントを検索します。 要素の UFX if ディレクティブと 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>

入力バッグの NameFilter プロパティが %city% 含まれている場合、Dynamics 365 によって実行される生成された FetchXML 条件は次のようになります。

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

キー、値、メタデータ

UFX バッグにはキーと値が含まれており、一部の値にはそれらを記述するためのメタデータが増えています。

たとえば、 lookup (EntityReference) 型の値などです。 FetchXML を介して Dynamics 365 からクエリを実行すると、エンティティの論理名とレコードの書式設定された表示名が返されます。 UFX バッグは、これらの追加情報をプライマリ値に添付されたメタデータとして保持します。

JSON にシリアル化されたメタデータを持つ lookup は次のようになります。

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

XML の場合:

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

Dynamics 365 データに対する XPath

UFX Bag 内のデータを入力することで、UFX クエリで構造化された形式でデータを表示し、XPath を使用してデータを走査し、そこから値を選択できるようになります。

UFX ディレクティブで指定された XPath 式は、XML シリアル化された形式のバッグの構造と同様に、バッグ内のデータを参照します。 ただし、データはメモリ内の .NET オブジェクト ( Entity 型と EntityCollection 型のインスタンス) に格納され、XML ドキュメントには格納されません。

UFX タイプリファレンス

すべての UFX タイプは、 ufx-type メタデータと ufx-formatvalue メタデータをサポートします。 追加のメタデータは、各タイプの横に記載されています。

UFX クエリ ディレクティブ

UFX ディレクティブは、bag プロパティと FetchXML クエリの XML 要素で使用できます。

UFX バッグのディレクティブ

UFX FetchXML ディレクティブ

UFX XPath 関数

UFX は、XPath でネイティブに利用可能な機能に加えて、多くの新機能を追加します。

日時()

• datetime(): 現在の時刻を UTC で返します。

リスト()

• list(バッグ | list, ...[bag | list]): 複数の bag または list の値を入力として受け取り、それらを 1 つに平坦化します list

ルックアップからリストへ

• lookup-to-list（ルックアップ）[lookup]): いくつかのlookup値を受け取り、それぞれを bag と ufx-id メタデータが設定された ufx-logicalnameに変換し、それらを 1 つにフラット化します。list

オプションからリストへの変換()

• option-to-list(オプション, ...[option]): いくつかのoption値を取り、それぞれを 1 つの bag プロパティを持つ 1 つのoptionに変換し、それらを 1 つのlist

注文()

• order(list, string, bool): 各バッグ内のプロパティでリストを並べ替えます。 プロパティは引数 2 で指定され、降順は引数 3 で指定されます。
• order(list, list): 引数 2 でリストとして指定された複数のソート順でリストを並べ替えます。 2 番目のリストの各 bag には、 name プロパティと descending プロパティを含めることができます

iif()

• iif(any, any, any): 引数 1 が true の場合は引数 2 を返し、それ以外の場合は引数 3 を返します

UFX XPath 変数

その他のリソース

Universal Resource Scheduling でのリソース照合の理解とカスタマイズ