標準のアーカイブ シナリオにカスタム テーブルを追加する

この記事では、既存の Microsoft アーカイブ シナリオに関連するカスタム テーブルを追加する方法について説明します。 たとえば、一般会計アーカイブ シナリオにカスタム決済テーブルを追加したり、受注アーカイブ シナリオにカスタム出荷追跡テーブルを追加したりできます。

概要

このシナリオは、Microsoft マネージド テーブルに関連し、まとめてアーカイブする必要があるカスタム テーブルがある場合に適用されます。 カスタム テーブルには、標準テーブルとの外部キー リレーションシップがあります。

たとえば、次のようなシナリオが考えられます。

  • GeneralJournalAccountEntry に関連するカスタム元帳決済テーブル
  • SalesTable に関連するカスタム出荷追跡テーブル
  • InventJournalTableに関するカスタム品質検査表

このシナリオに関連するコンポーネントは次のとおりです。

  • カスタム ライブ テーブル (新規)
  • カスタム履歴テーブル (新規)
  • カスタム財務および運用データ エンティティ (新規)
  • ジョブ コントラクト作成者拡張機能 (コードが必要)
  • Dataverse の構成

コードが必要 - シナリオのジョブ コントラクト作成者クラスを拡張して、テーブルをアーカイブ スコープに追加します。

前提条件

  • Dynamics 365 財務および運用開発ツールを使用した Visual Studio へのアクセス。
  • アーカイブ フレームワークがデプロイされた開発環境。
  • 親子テーブルのリレーションシップの理解。
  • ジョブ コントラクト ビルダー API の理解。
  • Dynamics 365 の財務および運用におけるシステム管理者ロール。

カスタム ライブ テーブルを作成する

アーカイブ スコープに含めるカスタム トランザクション テーブルを作成します。

テーブル構造のデザイン

テーブルを作成する前に、次の情報を確認します。

  1. 親テーブル: このテーブルはどの Microsoft テーブルに関連していますか? (たとえば、 GeneralJournalAccountEntry、 SalesTable、 InventJournalTable)
  2. リレーションシップの種類: 一対一か一対多か。
  3. 外部キー: 親テーブルにリンクするフィールドはどれですか?
  4. ビジネス データ: 他にどのようなフィールドが必要ですか?

Visual Studio でテーブルを作成する

  1. プロジェクトを右クリックし、[追加>新しいアイテム>Table] を選択します。
  2. 名前付け規則を使用してテーブルに名前を付けます。
    • 例： CustomLedgerTransSettlement
    • 例： CustomShipmentTracking
    • 例： CustomQualityInspection

必須フィールドを追加する

親テーブルへの外部キー:

  • フィールド名の規則: [ParentTable]RecId ( TransRecId、 SalesRecIdなど)
  • 型: Int64
  • 親テーブルとの関係 RecId

必要に応じて分離フィールド (親テーブルと一致):

  • DataAreaId (EDT: DataAreaId) - 法人分離の場合
  • Partition (EDT: PartitionKey) - マルチテナント シナリオの場合

ビジネス固有のフィールド:

  • カスタム トランザクション フィールドを追加する
  • Dynamics 365 の財務および運用フィールドの名前付け規則に従う
  • 適切な拡張データ型 (EDT) を使用する

親テーブルにリレーションシップを追加する

  1. テーブル デザイナーで [リレーション] を展開します。
  2. 右クリックして [ 新規] を選択し、[ リレーション] を選択します。
  3. リレーションを設定します。
    • 名前: わかりやすい名前 (例: GeneralJournalAccountEntry)。
    • 関連テーブル: 親テーブル名。
    • カーディナリティ: ZeroMore (通常)。
  4. リレーションシップ制約を追加します。
    • フィールド: 外部キー フィールド (たとえば、 TransRecId)。
    • 関連フィールド: 親テーブルの RecId 。

テーブル構造の例:

CustomLedgerTransSettlement
├── RecId (Int64, Primary Key)
├── TransRecId (Int64, Foreign Key to GeneralJournalAccountEntry)
├── DataAreaId (DataAreaId)
├── Partition (PartitionKey)
├── SettlementDate (TransDate)
├── SettlementAmount (AmountMST)
└── SettlementStatus (Enum)

テーブル プロパティを構成する

  1. Visual Studio で、ライブ テーブルを選択します。
  2. [プロパティ] ウィンドウで、ChangeTrackingEnabled を見つけます。
  3. 値を [はい] に設定します。

アーカイブ条件インデックスの追加 (必須)

このインデックスは、アーカイブ ジョブのパフォーマンスと検証に不可欠です。

<AxTableIndex>
    <Name>ArchiveCriteriaIdx</Name>
    <Fields>
        <AxTableIndexField>
            <DataField>DataAreaId</DataField><!-- Match parent segregation if needed-->
        </AxTableIndexField>
        <AxTableIndexField>
            <DataField>TransRecId</DataField><!-- Foreign key for JOIN -->
        </AxTableIndexField>
    </Fields>
    <IncludedColumns>
        <AxTableIndexIncludedColumn>
            <DataField>RecId</DataField><!-- If not clustered key -->
        </AxTableIndexIncludedColumn>
        <AxTableIndexIncludedColumn>
            <DataField>SysRowVersion</DataField>
        </AxTableIndexIncludedColumn>
        <AxTableIndexIncludedColumn>
            <DataField>SysDataStateCode</DataField>
        </AxTableIndexIncludedColumn>
    </IncludedColumns>
</AxTableIndex>

長期保有の調整インデックスを追加する (必須)

<AxTableIndex>
    <Name>ArchiveSysVersionIdx</Name>
    <Fields>
        <AxTableIndexField>
            <DataField>SysDataStateCode</DataField>
        </AxTableIndexField>
        <AxTableIndexField>
            <DataField>SysRowVersion</DataField>
        </AxTableIndexField>
    </Fields>
</AxTableIndex>

Important

どちらのインデックスも必須です。 条件インデックスがない場合、アーカイブ ジョブは検証に失敗します。 調整インデックスがないと、LTR 操作のパフォーマンスが低下します。

履歴テーブルの作成

アーカイブされたデータ ストレージの対応する履歴テーブルを作成するには、次の手順に従います。

  1. プロジェクトを右クリックし、[追加>新しいアイテム>Table] を選択します。
  2. 名前を入力します: [YourTable]History。
    • 例： CustomLedgerTransSettlementHistory
    • 例： CustomShipmentTrackingHistory

ライブ テーブルのすべてのフィールドをミラー化する

ライブテーブル内の全てのフィールドをコピーします。ただし、次のフィールドは除く。

  • SysRowVersion (システムマネージド)
  • SysDataState (システムマネージド)

その他のフィールドはすべて同じである必要があります。

  • 同じフィールド名
  • 同じデータ型
  • 同じ EDT
  • 同じ長さ (文字列の場合)

履歴テーブルのプロパティを構成する

履歴テーブルでは、ライブ テーブルの一意のインデックスは必要ありません。

抽出条件フィールドのインデックスを追加する

アーカイブ条件とクエリで使用されるフィールドにインデックスを追加します。

<AxTableIndex>
    <Name>TransRecIdIdx</Name>
    <Fields>
        <AxTableIndexField>
            <DataField>TransRecId</DataField>
        </AxTableIndexField>
    </Fields>
</AxTableIndex>

<AxTableIndex>
    <Name>SettlementDateIdx</Name>
    <Fields>
        <AxTableIndexField>
            <DataField>SettlementDate</DataField>
        </AxTableIndexField>
    </Fields>
</AxTableIndex>

これらのインデックスを使用すると、アーカイブされたデータの効率的なクエリが可能になり、取り消しジョブのスケジュール設定が適切に機能するために必要です。

財務および運用データ エンティティを作成する

長期保有のために Dataverse 仮想エンティティを有効にする財務および運用データ エンティティを作成するには、次の手順に従います。

  1. プロジェクトを右クリックし、[ 追加>新しい項目>Data エンティティ] を選択します。
  2. 名前を入力します。 [YourTable]BiEntity
    • 例： CustomLedgerTransSettlementBiEntity
    • 例： CustomShipmentTrackingBiEntity

プライマリ データ ソースを構成する

  1. エンティティ デザイナーで、 データ ソースを設定します。
    • プライマリ データ ソースをライブ テーブルに設定します。
    • すべてのフィールドが含まれていることを確認します。
  2. フィールドの表示設定:
    • すべてのフィールドを パブリック 表示に設定します。
    • 外部からアクセスできないフィールドは、アーカイブ用にパブリックとして保持します。

重要なエンティティ プロパティを構成する

アーカイブ エンティティと LTR エンティティに次のプロパティを設定します。

財産 価値 必要な理由
IsPublic はい エンティティを Dataverse で使用できるようにする
PublicEntityName あなたのエンティティ名 OData/Virtual エンティティの外部名
PublicCollectionName エンティティ名 + 's' OData コレクション エンドポイント
Is Read Only Yes アーカイブ エンティティは読み取り専用である必要があります
Auto Create Yes Dataverse で仮想エンティティを自動的に作成する
Auto Refresh Yes メタデータの同期を維持する
Allow Retention Yes LTR 機能を有効にする
Allow Row Version Change Tracking Yes 変更の追跡に必要
ChangeTrackingEnabled はい データの変更を追跡する

rowversion のサポートを有効にする

詳細については、「 エンティティ変更の追跡」を参照してください。

エンティティのビルドとテスト

# Build your model
# Test in Dynamics 365 finance and operations:
# - Navigate to Data Management
# - Export/Import using your entity
# - Verify all fields are accessible

仮想エンティティを Dataverse に発行する

次のいずれかの方法を使用して、エンティティを Dataverse で長期保持できるようにします。

  1. 自動発行 (推奨) - Auto Create を Yesに設定した場合:

    • 仮想エンティティは、最初のエンティティの同期後に自動的に発行されます。
    • 自動発行には 24 ~ 48 時間かかる場合があります。
    • 特に何か操作をする必要はありません。

  2. 手動発行 - 即時発行が必要な場合、または自動発行が機能しなかった場合:

  • Power Platform管理センター にアクセスします。
  • 環境を選択します。
  • 設定>製品>機能に移動します。
  • Dynamics 365 Finance and Operations 仮想エンティティを検索します。
  • エンティティを検索します。
  • [ 有効にする] を 選択して発行します。

仮想エンティティ メタデータを更新する (必要な場合)

変更後にエンティティ メタデータを更新する必要がある場合は、次のいずれかのオプションを使用します。

  1. 高度な検索による手動更新:
    • Dataverse 環境で [Advanced Find]\(高度な検索 \) に移動します。
    • [利用可能な財務] エンティティと [操作] エンティティを選択します。
    • 名前 をフィルターして、エンティティ名 (例: customledgertranssettlementbientity) を含めます。
    • 結果からレコードを開きます。
    • [ 最新の情報に更新 ] チェック ボックスをオンにします。
    • レコードを保存します。
  2. Power Apps Maker ポータルを使用します。
    • Power Apps Maker ポータルに移動します。
    • [テーブル] に移動し、エンティティを見つけます。
    • エンティティを開き、更新をトリガーします。

詳細については、「 仮想エンティティの更新のトラブルシューティング」を参照してください。

変更の追跡と LTR を構成する

サード パーティ (ISV、パートナー、顧客) は、長期的な保持のためにエンティティを構成するために 2 つの方法を使用します。

  • 手動構成 - ほとんどのシナリオに推奨 - ほとんどの実装では、このよりシンプルなアプローチを使用します。 Power Apps Maker で各エンティティに対して変更の追跡と LTR を手動で有効にします。
  1. Power Apps Maker ポータルに移動します。
  2. 環境 >テーブル を選択します。
  3. 仮想エンティティ ( mserp_customledgertranssettlementbientity など) を見つけます。
  4. エンティティの変更の追跡と長期的な保持を有効にします。

詳細については、以下を参照してください:

ソリューションの自動デプロイ (詳細)

複数の環境にわたる自動デプロイのためにエンティティ構成をパッケージ化する Dataverse ソリューションを構築します。 Dataverse ソリューションの構築とデプロイに関する完全な手順については、「 長期保有のための Dataverse の構成」を参照してください。

カスタム テーブルを含むようにジョブ コントラクトを拡張する

アーカイブ ジョブ コントラクトを変更して、カスタム テーブルをアーカイブ スコープに含めます。

既存の雇用契約作成者を探す

拡張するシナリオのコントラクト作成者クラスを見つけます。

  • 一般会計: LedgerArchiveAutomationJobRequestCreator
  • 販売注文: SalesOrderArchiveAutomationJobRequestCreator
  • 在庫仕訳帳: InventJournalArchiveAutomationJobRequestCreator

顧客所有モデルで拡張機能を作成してください

この拡張機能は顧客所有モデルで作成してください。 ビジネスインテリジェンスモデルで作らないでください。

  1. モデルプロジェクトで新しいクラスを作成します。
  2. 名前: [ExistingCreator]_[YourModel]_Extension。
  3. 拡張属性を追加します。
using Microsoft.Dynamics.Archive.Contracts;

[ExtensionOf(classStr(LedgerArchiveAutomationJobRequestCreator))]
public final class LedgerArchiveAutomationJobRequestCreator_CustomExtension
{
    // Extension logic here
}

createPostJobRequest メソッドを拡張する

コマンドチェーンを使用して、ジョブ コントラクトを構築するメソッドを拡張します。

public ArchiveJobPostRequest createPostJobRequest(var _criteria)
{
    // Call base implementation to get existing contract
    ArchiveJobPostRequest postRequest = next createPostJobRequest(_criteria);
    
    // Add your custom table
    postRequest = this.addCustomTableForLongTermRetention(postRequest, _criteria);
    
    return postRequest;
}

カスタム テーブルを追加するメソッドを実装する

private ArchiveJobPostRequest addCustomTableForLongTermRetention(
    ArchiveJobPostRequest _postRequest,
    var _criteria)
{
    ArchiveServiceArchiveJobPostRequestBuilder builder = 
        ArchiveServiceArchiveJobPostRequestBuilder::constructFromArchiveJobPostRequest(_postRequest);

    builder.addSourceTableForLongTermRetention(
        ArchiveServiceSourceTableConfiguration::newForChildSourceTable(
            tableStr(CustomLedgerTransSettlement),
            tableStr(CustomLedgerTransSettlementHistory),
            tableStr(CustomLedgerTransSettlementBiEntity),
            tableStr(GeneralJournalAccountEntry)))
        .addJoinCondition(
            tableStr(CustomLedgerTransSettlement),
            fieldStr(CustomLedgerTransSettlement, TransRecId),
            fieldStr(GeneralJournalAccountEntry, RecId))
        .addDataAreaIdWhereCondition(tableStr(CustomLedgerTransSettlement), _criteria.DataAreaId)
        .addPartitionWhereCondition(tableStr(CustomLedgerTransSettlement));

    return builder.finalizeArchiveJobPostRequest();
}

実装ポイント

  • 親テーブルの仕様:
    • シナリオ内の親テーブル名と正確に一致しなければなりません。
    • 親テーブル名の誤字は検証失敗の原因となります。
  • JOIN 条件:
    • 実際の外部キー関係と一致している必要があります。
    • テーブル名、子フィールド、親フィールドを使ってください。
  • 「WHERE」条件：
    • 親と同じ分離フィールドを含める必要があります。例えば DataAreaId。
    • addDataAreaIdWhereCondition()と、該当する場合はaddPartitionWhereCondition()を使いましょう。
  • 事業体名:
    • ライブテーブルに対応する財務・運営エンティティを使いましょう。

カスタム テーブルを使用してアーカイブをテストする

カスタム テーブルがアーカイブ ジョブに適切に含まれていることを確認します。

テスト データを作成する

  1. 履歴エントリなどの親テーブル レコードを作成します。
  2. 外部キー参照を使用して関連するカスタム テーブル レコードを作成します。
  3. DataAreaIdなど、分離フィールドが一致していることを確認します。
  4. テスト フィールドに意味のあるデータを追加します。

テスト アーカイブ ジョブを作成する

  1. Dynamics 365 の財務および運用アーカイブ ワークスペースに移動します。
  2. 拡張したアーカイブの種類を選択します。
  3. テスト データを含む条件を使用してアーカイブ ジョブを作成します。
  4. ジョブの詳細を確認して、テーブル数にカスタム テーブルが含まれていることを確認します。

ジョブ コントラクトを確認する

ジョブの作成に関するアーカイブ サービス ログを確認します。

  • カスタム テーブルがジョブ コントラクトに表示されていることを確認します。
  • JOIN 条件が正しいことを確認します。
  • WHERE 条件が基準に一致するか検証します。

データ移動のテスト

アーカイブ ジョブを実行するには、次の手順に従います。

  1. アーカイブ ジョブを実行します。
  2. ジョブの進行状況を監視します。
  3. ジョブが正常に完了したことを確認します。

履歴テーブルのデータを確認します。

-- Check custom table data moved to history
SELECT * FROM CustomLedgerTransSettlementHistory
WHERE TransRecId = [TestParentRecId]

-- Verify parent-child relationship maintained
SELECT c.*, p.* 
FROM CustomLedgerTransSettlementHistory c
INNER JOIN GeneralJournalAccountEntryHistory p ON c.TransRecId = p.RecId

マネージド データ レイク内のデータを確認します。

  • Dataverse マネージド データ レイクに移動します。
  • カスタム テーブルの CSV ファイルを検索します。
  • レコードが存在することを確認します。
  • フィールド値が正しいことを確認します。

復元操作のテスト

  1. アーカイブされたデータの取り消しジョブを作成します。
  2. 復元ジョブを実行します。
  3. カスタム テーブル データがライブ テーブルに戻ってくるかどうかを確認します。
  4. 親子関係がそのままであることを検証します。
SELECT * FROM CustomLedgerTransSettlement WHERE TransRecId = [TestParentRecId]
  • 最終更新: