ユニバーサル FetchXML で Universal Resource Scheduling を拡張する

[アーティクル]
06/06/2024

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

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

単純な UFX バッグ

UFX バッグには静的種類のデータが含まれます。メモリ内では、キーと値を持つ辞書として表されます。これは JSON と XML にシリアル変換することができます。 UFX クエリがそこからデータをクエリし、クライアント UI がそれをバインドすることを許可する種類のデータを持ちます。

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

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

メモリ内:

キー	値	種類
名前	John	文字列
年齢	36	int

JSON 内:

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

XML 内:

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

UFX でサポートされる種類

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

カテゴリ	値
簡単な種類	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Dynamics 365 固有の簡単な種類: `money (Money)`、`option (OptionSet)`、`lookup (EntityReference)`
他バッグ	`bag (Entity)`
バッグの一覧	`list (EntityCollection)`

さらに多くの種類を含むサンプル 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 クエリはバッグ内の accounts プロパティを source UFX ディレクティブで定義します。この結果、インライン FetchXML が Dynamics 365 により実行されて accounts プロパティがバッグの一覧になるか、各バッグを持つ EntityCollection が 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>

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 バッグとして利用可能な値により、取引先企業を検索します。 condition 要素上の UFX if および value ディレクティブに注意してください。

<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 バッグにはキーおよび値が含まれ、一部の値には説明のためのメタデータがあります。

1 つの例は 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 バッグの種類のデータを持ち、UFX クエリはそれを構造化書式で表示して、XPath を使用してデータ上を走査し値を選択することができます。

UFX ディレクティブで指定された XPath 式は、XML でシリアル変換された書式のバッグの構造に類似したバッグ内のデータを読みます。ただし、データは、XML ドキュメントではなく、メモリ内 .NET オブジェクトで保管されます (Entity および EntityCollection の種類のインスタンスで)。

付録 A: UFX の種類の参照

メモ: すべての UFX の種類は ufx-type および ufx-formatvalue メタデータをサポートします。追加のメタデータは以下の表の各種類の隣で説明されています。

UFX 名	属性の種類のコード	.NET 名	UFX メタデータ
bool	Boolean	Boolean
int	Integer	Int32
long	BigInt	Int64
double	Double	Double
小数	小数	小数
datetime	日時	日時
guid	Uniqueidentifier	Guid
文字列	メモ	String
金額	金額	金額
option	候補リスト	OptionSetValue
lookup	検索	エンティティ参照	`ufx-logicalname`
bag	なし	Entity	`ufx-id` `ufx-logicalname`
リスト	なし	エンティティコレクション
なし	なし	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

付録 B: UFX クエリディレクティブ

UFX ディレクティブはバッグプロパティ上、および FetchXML クエリ内の XML 要素滋養のバッグで使用することができます。

UFX バッグディレクティブ

属性	Value	説明
`ufx:if`	XPath	XPath 式をテストして、テストが true を返す場合にのみプロパティを処理します
`ufx:source`	`fetch`	インライン `<fetch>` XML 要素を実行して結果をプロパティに割り当てます
`ufx:select`	XPath	XPath 式を実行して結果をプロパティに割り当てます `bag` または `list` をクエリすると、XML 形式のオプションの子 `bag` を指定して XPath 式の結果を変換することができます。

UFX FetchXML ディレクティブ

Element	属性	Value	説明
すべての要素	`ufx:if`	XPath	XPath 式をテストしてテストが成功する場合にのみ XML 要素を送信します
`ufx:apply`	`select`	XPath	XPath 式が返すノードセット全体をループして各ノードの子 XML 要素を 1 回出力します
`ufx:value`	`select`	XPath	XPath 式を実行して現在の XML 要素の結果を出力します
`ufx:value`	`attribute`	属性名	XPath 式の結果を、現在の XML 要素上の指定属性名に割り当てます

付録 C: UFX XPath の機能

UFX は XPath でもともと使用可能な関数に加えて多くの新しい関数を追加しました。

datetime()

datetime(): 現在の時間を UTC で返します

list()

list(bag | list, ...[bag | list]): bag または list 値の数を、入力して単一 list にするように取得します。

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): lookup 値の数を取得して、それぞれを ufx-id および ufx-logicalname メタデータセットを持つ bag に変換し、単一の list にします

option-to-list()

option-to-list(option, ...[option]): option 値の数を取得して、それぞれを単一の option プロパティを持つ bag に変換し、単一の list にします

order()

order(list, string, bool): リストを各バッグ内のプロパティで整理します。プロパティは引数 2 で指定され、降順は引数 3 で指定されます。
order(list, list): 引数 2 内のリストとして指定された複数の並び変え順でリストを整理します。 2 番目のリスト内の各 bag は name およびdescending プロパティを持つ場合があります

iif()

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

付録 D: UFX XPath の変数

名前	説明
$input	入力値を持つ UFX クエリで利用可能な `bag`
$null	空の定数。プロパティ上の `$null` を選択するとバッグからそのプロパティが削除されます
$current	UFX クエリが処理する現在のバッグを参照します

次の方法で共有

ユニバーサル FetchXML で Universal Resource Scheduling を拡張する

単純な UFX バッグ

UFX でサポートされる種類

UFX クエリの概要

キー、値、およびメタデータ

Dynamics 365 データ上の XPath

付録 A: UFX の種類の参照

付録 B: UFX クエリディレクティブ

付録 C: UFX XPath の機能

datetime()

list()

lookup-to-list()

option-to-list()

order()

iif()

付録 D: UFX XPath の変数

関連項目

フィードバック

その他のリソース

次の方法で共有

ユニバーサル FetchXML で Universal Resource Scheduling を拡張する

単純な UFX バッグ

UFX でサポートされる種類

UFX クエリの概要

キー、値、およびメタデータ

Dynamics 365 データ上の XPath

付録 A: UFX の種類の参照

付録 B: UFX クエリ ディレクティブ

付録 C: UFX XPath の機能

datetime()

list()

lookup-to-list()

option-to-list()

order()

iif()

付録 D: UFX XPath の変数

関連項目

フィードバック

その他のリソース

付録 B: UFX クエリディレクティブ