C コネクタAPI

この付録では、コネクタAPI、コネクタとエンジン間の規定事項、およびデータ表現構造を示します。

この付録のトピックは、次のとおりです。

• コネクタAPIの概要

• コネクタ・インタフェース

• エンジン・コールバック・インタフェースAPI

• コネクタ・ランタイム・インタフェースAPI

• データ表現構造

• コネクタの作成に関するベスト・プラクティス

• Exchange 2007コネクタAPI

• カレンダの同期化に対する汎用コンポーネントのサポート

C.1 コネクタAPIの概要

次のコネクタAPIがあります。

• コネクタ・インタフェース

• エンジン・コールバック・インタフェースAPI

• コネクタ・ランタイム・インタフェースAPI

用語

APIに関連する用語は次のとおりです。

• 関連データ

• コネクタ名

• 作成/作成競合

• フィールド・クラス

• PIMドメイン・ターゲット

• PIMレコード説明

• PIMレコードID

• PIMレコード・バージョンID

• 同期化セッション

• 同期状態

C.1.1 関連データ

関連データとは、コネクタのかわりにハブに格納されるコネクタ定義のデータです。任意のタイプのデータを使用できますが、コネクタではデータがAssociatedData構造に準拠していることを確認する必要があります。

関連データは、一意の識別子および複数グループのコレクションで構成されます。各グループには、グループ識別子、および関連データを格納する任意の数のKeyValuePair構造が含まれます。コネクタでは、各グループ内に任意の数のグループおよびKeyValuePair構造を定義できます。たとえば、Microsoft Exchange 2007用Oracle BDSSコネクタでは、識別子がMailboxPropertiesのユーザー・レベルの関連データを定義し、その関連データにグループ識別子がMailboxPropertiesの1つのグループを含めることができます。このグループには2つのKeyValuePair構造が含まれ、キーはlegacyExchangeDNとmsExchHomeServerNameで、値はActive Directoryから取得されたデータが移入されます。同様に、Exchange 2007コネクタでは、識別子がPIMレコードIDのレコード・レベルの関連データを定義し、その関連データにグループ識別子がSourceKey、ChangeKeyおよびPredecessorChangeListの3つのグループを含めることができます。SourceKeyグループには単一のKeyValuePairが保持され、キーはSKで、値はExchangeレコードのソース・キー値です。ChangeKeyグループには単一のKeyValuePairが保持され、キーはCKで、値はExchangeレコードの変更キー値です。PredecessorChangeListグループには任意の数のKeyValuePair構造が保持されます(Exchangeレコードの先行変更リストの各変更キーがKeyValuePairとして表されます)。

関連データの特徴は次のとおりです。

• ハブに対して不透明です(つまり、ハブから識別されません)。

• これはオプションです。

• データ・ストアにテキストとして格納されます。

• サイズは任意です。

• レコード・レベルのRTL(ランタイム・ライブラリ)アクセスAPIに加えて、コネクタではレコード・レベルの関連データをCreateRecordまたはUpdateRecordコールの結果構造で提供できます。ハブでは、新しい関連データでデータ・ストアを更新します。

• レコード・レベルのRTLアクセスAPIに加えて、コネクタではレコード・レベルの関連データをExtractResponseの各UpsertRecordで提供できます。ハブでは、その関連データでデータ・ストアを更新します。

C.1.2 コネクタ名

PIMサーバー・インスタンスの特定のセットにサービスを提供するコネクタ・インスタンス用の一連の構成の名前。

注意: コネクタ名は指定の同期化セッション中は変更されません。したがって、ステートフル・コネクタの場合は、指定のユーザーおよび同期化セッションの値をキャッシュし、その値をハブ・コールバックまたはRTL(ランタイム・ライブラリ)APIのコール時に使用することもできます。

C.1.3 作成/作成競合

作成/作成競合は、キー・フィールドのフィールド値が一致する同期化されていない複数のレコードが、同じ同期化セッション中に異なる複数のシステムから抽出された場合に発生します。

C.1.4 フィールド・クラス

フィールド・クラスとは、データ型に優先してPIMフィールドに追加セマンティクを適用する、PIMフィールドの分類です。フィールド・クラスの例には、Phone、Address、Email、Category、To、CCおよびBCCがあります。フィールド・クラスでは、次の処理を実行します。

• コネクタ間のフィールドの自動マッピングを容易にします。

• コネクタ実装を有効にし、特定のクラスに基づいてロジックを実装します。たとえば、コネクタでは、システム内で値(参加者など)を解決するためにフィールド・クラス(To、CC、BCCなど)に関するフィールド情報が必要になる場合があります。

C.1.5 PIMドメイン・ターゲット

PIMドメイン・ターゲットとは、指定のユーザーおよびドメインについて、ドメインのPIMデータが存在する場所に関する構成メタデータです(オプション)。PIMドメイン・ターゲットは、PIMサーバーが各ユーザーのPIMデータを複数の異なる場所に格納するコネクタで使用できます。たとえば、Exchangeが各ユーザーのタスク・データと連絡先データを異なるフォルダに格納する場合、Exchangeのタスク・データは「Task」フォルダ(または「Task」フォルダのサブフォルダ)に格納され、Exchangeの連絡先データは「Contact」フォルダ(または「Contact」フォルダのサブフォルダ)に格納されます。構成メタデータはコネクタ固有であるため、コネクタ実装ではその構成メタデータを解析します。次に例を示します。

• フォルダの相対パスの構成(例: \root\calendar\mycalendar)は、ドメインのサブフォルダに対する同期化を示します。

• 抽象値の構成(例: Root)は、ドメインのデフォルトの主フォルダに対する同期化を示します。

コネクタによっては、PIMフォルダを指定せずに、他の方法(Siebel PDQフィルタなど)を指定する場合があります。たとえば、連絡先ドメインの場合、コネクタでは同期化リストのPDQをドメイン・ターゲットとして識別します。PDQでは、フォルダ・パスと異なりターゲット上の物理的な場所を識別しませんが、フォルダ・パスと同様に同期化対象となるレコードのセットを識別します。

注意: このオプションのメタデータはユーザーおよびドメインごとに指定されるため、管理者はBDSSで同期化されるユーザーおよびドメインごとにPIMドメイン・ターゲットを指定する必要があります。コネクタ構成を簡略化するために、開発者はデフォルトのPIMドメイン・ターゲットを作成し、構成が使用できない場合にコネクタでデフォルト値を使用するようにできます。たとえば、構成が使用できない場合、コネクタではドメインに対してデフォルト・フォルダを使用できます。また、開発者は、Rootなどの構成値を要求し、コネクタではドメインに対してデフォルト・フォルダを使用するように指定することもできます。デフォルトのPIMドメイン・ターゲットがない場合、各ユーザーおよびドメインのメタデータが必要になると、コネクタはその構成を要求できます。

C.1.6 PIMレコード説明

PIMレコード説明とは、KeyValuePair構造の配列です。各KeyValuePair構造には、ハブ・フィールド名がキーとして、ハブ・フィールド値が値として保持されます。コネクタでは、RTL(ランタイム・ライブラリ)API GetConfigurationMetadataを使用して、各ハブ・ドメインのPIMレコード説明に含めるように構成されたハブ・フィールドのリストを取得する必要があります。

PIMレコード説明で使用するハブ・フィールドの構成は、FtsKeyFieldsプロファイルに格納されています。プロファイルのセクション名には、ハブ・ドメイン名が含まれています。プロファイルのパラメータの名前はKeyFieldX形式で、Xは表内の他の行から該当する行を識別するだけでなく、コネクタによるPIMレコード説明の作成時にフィールドの表示順を指定する数値です。コネクタでは、PIMレコード説明を作成し(構成が存在する場合)、KeyValuePair配列に表示するフィールドの順序がKeyFieldXで指定した順序と同じであることを確認する必要があります。たとえば、FtsKeyFieldsプロファイルの「Task」ハブ・ドメインには、表C-1に示す構成があります。

表C-1 「Task」ハブ・ドメインの構成

プロファイル	セクション(ハブ・ドメイン名)	パラメータ	値
FtsKeyFields	Task	KeyField1	Subject
FtsKeyFields	Task	KeyField2	StartDate

コネクタでレコードが抽出されると、2つの要素を含むKeyValuePair配列が作成されます。最初の要素(index0)にはKeyValuePairが含まれ、キーはSubjectで、値はレコードのハブ・フィールド値です。2番目の要素(index1)にはKeyValuePairが含まれ、キーはStartDateで、値はレコードのハブ・フィールド値です。

ハブ・レコードに構成済のキー・フィールドの値がない場合、コネクタではそのフィールドに空の文字列を挿入する必要があります。

注意: コネクタでは、レコード説明にハブ・フィールド名とハブ・フィールド値を提供する必要があります。コネクタではこの情報を提供するために、PIMからレコードを抽出してハブ書式に変換し、PimRecordDescriptionを作成する必要があります。同様に、コネクタでは、作成または更新操作が正常終了したときに、ハブ・フィールドの名前と値を提供する必要があります。これは非常に重要で、ハブでは、複数のPIMサーバーからの抽出レスポンスを評価するときに、これらのキー・フィールドが含まれたPIMレコード説明を使用してPIMレコードのキー・フィールド照合を実行します。PIMレコード説明は、ハブ・レコードがシステム内を移動するときにハブ・レコードに対して実行された特定の操作に関する情報を記録する場合にも使用されます。

Oracle Fusion Middleware 11gリリース1のBDSSの場合、レコード説明のメンバーとして指定するフィールドは複数値タイプにできません。

C.1.7 PIMレコードID

PIMレコードIDとは、コネクタがPIMサーバー上のレコードを一意に識別するために使用する識別子です。PIMレコードIDは、ユーザーおよびドメインごとにPIMサーバー内で一意である必要があります。コネクタでは、PIMレコードIDとして使用するプロパティがレコードの識別およびレコードへのアクセスに使用できることを確認する必要があります。

コネクタでは、次の場合にPIMレコードIDをBDSSに提供します。

• PIMサーバーからレコードを抽出するとき

• プッシュされた作成操作が完了したとき

BDSSでは、更新操作または削除操作がPIMサーバーにプッシュされると、PIMレコードIDをコネクタに提供します。

C.1.8 PIMレコード・バージョンID

PIMレコード・バージョンIDとは、PIMレコードのバージョンを取得するコネクタ定義の値です。これは、変更されたPIMレコードを追跡できる任意の値です。たとえば、PIMレコードに「最終変更日時」フィールドがある場合、その「最終変更日時」フィールドは、レコードが更新されるたびに更新されるため、コネクタではこのフィールドをPIMレコード・バージョンIDとして使用できます。同様に、レコードが変更されると増分される整数値がPIMレコードにある場合、コネクタではその整数値を使用することもできます。

C.1.9 同期化セッション

同期化セッションとは、ハブでBDSSコネクタを介して、1つ以上のハブ・ドメインのハブ・ユーザーのデータを1つ以上のPIMストア間で同期化するセッションです。セッションは、ハブでコネクタAPI InitializeUserSyncSessionをコールすると開始され、同期化セッションIDと呼ばれる一意の識別子によって識別されます。このセッションは、ハブでEndUserSyncSession APIをコールすると終了します。これら2つのコールの間に、ハブでは次のコネクタAPIをコールできます。

• ExtractDomains API: すべてのハブ・ドメインに対してコネクタがインバウンドのみの同期化用に構成されたハブ構成の場合、このAPIはコネクタでコールされません。コールされるのは、少なくとも1つのハブ・ドメインに対してコネクタが双方向またはアウトバウンドのみの同期化用に構成されたハブ構成の場合です。

• CreateRecord、UpdateRecordまたはDeleteRecord APIは、セッション中に任意の回数コールできます。

C.1.10 同期状態

エンジンは、コネクタが提供する同期状態と呼ばれるデータを使用して、PIMサーバーから正常にエクスポートされたユーザーのドメイン・レコードを追跡します。同期状態は、コネクタ・ドメイン・レベルで監視されます。

コネクタでは、同期状態とその書式を定義します。たとえば、コネクタでは、日時スタンプを使用して前の同期化セッション中に実行した抽出問合せの時刻を示したり、PIM APIによって定義された規則を使用して、コネクタがPIMサーバーとデータを交換する方法を記述することができます。たとえば、Exchange 2007用Oracle BDSSコネクタでは、増分変更同期化(ICS)バイナリBLOBが使用されます。コネクタによる同期状態の管理方法の詳細は、第C.4.3項「CommitCachedSyncStateメソッドAPI」、第C.4.8項「GetSyncState API」および第C.4.10項「SaveSyncState API」を参照してください。

注意: このデータはエンジンに対して不透明ですが、エンジンは、いつ同期状態をハブ・データ・ストアに保存するかを指示します。

1人のユーザーの各コネクタ・ドメインに対して1つの同期状態があります。同期状態はハブ・データ・ストアに存在し、これによってシステムでは、1つのドメインからすべてのレコードを抽出したり、前の同期状態から発生した作成、読取り、更新および削除操作のみを抽出できます。

注意: エンジンは、ユーザーの各同期化セッションの後にコネクタ・ドメインの同期状態を更新しますが、これは、送信されたレコードの処理時に他のすべてのコネクタでエラーが発生していない場合のみです。コネクタでエラーが発生した場合は、(エラーの修正後に)後続の同期化セッションで一部のレコードを再度抽出する必要があるため、同期状態は更新されません。

C.1.11 更新/更新競合

更新/更新競合は、以前に同期化されたレコードが複数のシステムで更新され、同じ同期化セッションで抽出された場合に発生します。

C.2 コネクタ・インタフェース

コネクタのPIMサーバー同期化サービスは、Webサービスとして公開されています。コネクタ開発者は、このドキュメントで定義されているWebサービス・インタフェースを実装します。エンジン、テスト・アプリケーションおよびその他のWebサービス・クライアントはコネクタ・インタフェースのコンシューマで、このインタフェースには次のAPIが含まれます。

• InitializeUserSyncSession API

• ExtractDomains API

• EndDomainSynchronization API

• EndUserSyncSession API

• CreateRecord API

• UpdateRecord API

• DeleteRecord API

• GetPimServerEndPoint API

注意: ExtractDomains APIは非同期です。その他のAPIはすべて同期です。

C.2.1 InitializeUserSyncSession API

ハブでは、各ユーザーの同期化セッションが開始されるたびに、InitializeUserSyncSession APIをコールします。コネクタはユーザーベースの初期化を実行して、ユーザーがそのコネクタを使用して、指定のsyncSessionIdで識別される同期化セッション中に後続のリクエストを処理できるようにする必要があります。表C-2に、InitializeUserSyncSession APIのパラメータを示します。

表C-2 InitializeUserSyncSession APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	[in]	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	[in]	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	[in]	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタがBDSSからメタデータを取得する必要がある場合にコールするURLが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomainArray	DomainInfo []	[in]	DomainInfo構造の配列が格納されます。配列には、構成されたすべてのハブ・ドメインのメタデータが含まれます。このパラメータは、NULL以外の配列である必要があります。各DomainInfo構造は、次の基準を満たしている必要があります。 pimDomainTarget: このメンバーは、NULL以外である必要があり、空にすることはできません。 pimFilterCondition: このメンバーは、NULL以外である必要がありますが、空にはできます。 hubDomain: このメンバーは、NULL以外である必要があり、空にすることはできません。 pimDomainSyncState: このメンバーは、NULL以外である必要がありますが、空にはできます。 コネクタでは配列を検証し、指定したDomainInfo配列がこの基準を満たしていない場合はエラーを返します。
connectorUrl	String	[out]	オプション・パラメータ。入力時は、パラメータはNULLです。出力時に、コールを受信したコネクタの完全URLが格納されるか、またはNULLのままです。 指定した同期化セッションIDで識別される同期化セッション中に指定のハブ・ユーザーに対して後続のコールを行うときに、同じコネクタ・インスタンス(URLで識別される)をコールするようにコネクタがBDSSに要求する場合、このコールを受信したコネクタはそのURLを提供できます。

戻り値

void

例外

コネクタでユーザーを初期化できない場合は、例外をスローして問題を特定するメッセージを提供する必要があります。これによって、BDSSでそのメッセージを記録できます。

C.2.1.1 エンジン規定

InitializeUserSyncSession APIをコールするには、エンジンで次の処理を実行する必要があります。

• すべてのハブ・ドメインのドメイン・メタデータを提供します。

• ExtractDomains、CreateRecord、UpdateRecordまたはDeleteRecordをコールする前に、InitializeSyncSession APIをコールします。

  
  

  注意: エンジンは、InitializeSyncSession APIをコールする前に、GetPimServerEndPointをコールできます。

  
  

• コネクタで例外がスローされると、ハブではコネクタがユーザーを初期化できなかったと判断されます。したがって、ハブでは、指定のハブ・ユーザーおよび同期化セッションについて、コネクタへの後続のコールが実行されません。

• 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

• コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameを使用する必要があります。

C.2.1.2 コネクタ規定

コネクタでは、エンジンのInitializeUserSyncSession APIコールのレスポンスとして、次の処理を実行する必要があります。

• APIに渡された各パラメータを検証し、表C-2に示す基準を満たしていることを確認します。

• 必要なユーザーベースの初期化を実行して、コネクタが後続のハブ・リクエストを処理できるようにします。リクエストには、ハブ・ドメインを抽出したり、レコードを作成、更新または削除するためのものがあります。

• コネクタで後続のすべてのコールを同じコネクタ・インスタンスにルーティングする必要がある場合は、コールを受信したコネクタ・インスタンスのURLを提供します。

• コネクタでは、後続のハブ・コールを処理するためにこのAPIに渡されたパラメータをキャッシュする必要がある場合、syncSessionIdとpimUserIdの組合せを使用できます。ほとんどのコネクタでは、同期化セッション中に後で使用できるように、提供されたドメイン情報データをキャッシュする必要があります。ステートレス・コネクタで状態を保持する必要がある場合は、これがコネクタ実装詳細とみなされます。

• コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

C.2.2 ExtractDomains API

エンジンは、非同期のWebサービスAPIであるExtractDomainsをコールして、コネクタに指定のハブ・ドメインを抽出するようにリクエストします。抽出とは、変更されたすべてのPIMレコードをPIMストアから取得してダウンロードするプロセスです。コネクタでは、前回の同期状態以降に変更されたすべてのPIMレコードを抽出する必要があります(前回の同期状態は、ハブでInitializeUserSyncSessionがコールされて同期化セッションが開始されると、ユーザーおよびドメインごとに提供されます)。各PIMレコードは、第8章「ハブ・フィールドへのコネクタ・フィールドのマッピング」の定義に従ってハブ書式に変換されます。ハブ書式のレコードは、ExtractDomainResultsCallback APIを介してハブに提供されます。

表C-3 ExtractDomains APIのパラメータ

パラメータ	データ型	タイプ	説明
extractRequest	ExtractRequest	[in]	抽出が必要なユーザーおよびドメインに関連する情報が格納されます。このパラメータは、NULL以外である必要があります。 ExtractRequestメンバーは、次の基準を満たしている必要があります。 hubUserId: このメンバーは、NULL以外である必要があり、空にすることはできません。 pimUserId: このメンバーは、NULL以外である必要があり、空にすることはできません。 hubDomainArray: このメンバーは、NULL以外である必要があります。配列内の各要素は、1つのハブ・ドメインIDが含まれたNULL以外の文字列である必要があり、空にすることはできません。
hubContext	HubContext	[in]	コネクタで抽出リクエストを処理するために必要なコンテキスト情報が格納されます。NULL以外である必要があります。 HubContextメンバーは、次の基準を満たしている必要があります。 engineEndPointURL: このメンバーは、NULL以外である必要があり、空にすることはできません。 syncSessionId: このメンバーは、NULL以外である必要があり、空にすることはできません。 connectorRuntimeLibraryURL: このメンバーは、NULL以外である必要があり、空にすることはできません。 connectorName: このメンバーは、NULL以外である必要があり、空にすることはできません。

コネクタでは、このメソッドを非ブロック化の非同期メソッドとして実装する必要があります。実装では、コール側Webサービスのスレッドでの抽出の実行とは異なり、各コネクタ所有のスレッドで各ドメインのデータ抽出が実行される必要があります。

C.2.2.1 エンジン規定

エンジンは、ExtractDomains APIをコールするときに次の処理を実行します。

• このAPIをコールする前に、指定の同期化セッションでInitializeUserSyncSessionへのコールが正常に実行されたことを確認します。

• すべてのコネクタから取得したExtractResponseを分析して競合を解決し、他のPIMコネクタを介して作成、読取り、更新および削除操作を他のPIMサーバーにプッシュします。

• システムからエクスポートされて別のシステムにインポートされたPIMレコードのマッピングを保守します。

• コネクタから提供されたExtractResponseが非同期で処理されたことを確認します。

• 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。同じ同期化セッション中は、コネクタへの後続の各コールで同じURLが提供されます。

• コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameを使用する必要があります。

注意: ExtractRequestに含まれるハブ・ドメインの配列は、同じ同期化セッション中にInitializeUserSyncSessionへのハブ・コールで指定したハブ・ドメインのサブセットである必要があります。

C.2.2.2 コネクタ規定

コネクタでは、ExtractDomains APIに対して次のようにレスポンスします。

1. 指定のPIMユーザーIDおよびPIMドメイン・ターゲットのドメインに属するPIMストアから、前回の同期状態以降のすべてのレコードを抽出します。コネクタ実装では、個々のスレッドで指定のドメイン配列内の各ドメインを抽出し、指定のHubContext構造に含まれるコールバックURLを使用してエンジンへの非同期コールバックを実行する必要があります。ExtractResponseに次のタイプの更新済PIMレコードを含めることはできません。

   1. PIMドメイン・ターゲットが同じで、ドメインに含まれていないレコードは無視されます。たとえば、Exchangeの電子メール・アイテム(IPM.Noteドメイン)が「Task」フォルダ(IPM.Task)に存在することは可能です。この場合、Exchange 2007コネクタは、Taskを抽出するときにIPM.Noteアイテムを無視する必要があります。

   2. PIMフィルタ条件によってフィルタで除去されたすべてのレコード。

2. リクエストで指定したハブ・ドメインごとに、ExtractResponseをハブに提供します。前回の同期状態以降に変更されたPIMレコードごとに、変更済PIMレコードのハブ表現が含まれたUpsertRecordが1つ存在する必要があります。また、前回の同期状態以降にPIMサーバーから削除されたレコードごとに、PIMレコードIDが1つ存在する必要があります。

3. 各コネクタには、「Extract Response Batch Size」というBDSSプロファイル・パラメータ構成があります。このパラメータの値には、各ExtractResponseが保持できるレコードの最大数が格納されます。コネクタは、一連のExtractResponse(各ExtractResponseにはこの最大数のレコードが含まれる)を提供するように記述する必要があります。エンジンは、これらのバッチの受信を使用して、コネクタの異常終了などのコネクタ障害の判断に使用する内部タイムアウトをリセットします。たとえば、コネクタで5,000件のカレンダ・レコードを抽出する必要があり、コネクタの構成済バッチ・サイズが100の場合、コネクタはエンジンへのコールバックを少なくとも50回実行します。

   
   

   注意: Oracle Fusion Middleware 11gリリース1では、BDSSは1つのハブ・ドメインに対して複数のExtractResponseの受信をサポートしていません。したがって、「Extract Response Batch Size」のコネクタ構成は、任意のユーザーの任意のドメインを単一のExtractResponseに抽出できる十分なサイズである必要があります。

   
   

4. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

5. 抽出されたレコードごとにPIMレコード説明を作成します。

6. レコードの抽出に失敗すると、コネクタは抽出を終了し、ExtractDomainResultsCallback APIを介してハブに通知します。コネクタでは、エラーを示す結果コードを設定してエラー発生を示し、ハブで障害に関する情報を記録できるようにエラー説明文を提供する必要があります。

7. PIMフィルタ条件定義に示すように、コネクタでは、抽出された各レコードに対する構成済フィルタを評価し、レコードの同期化が必要かどうかを判断する必要があります。

   
   

   注意: Oracle Fusion Middleware 11gリリース1のBDSSでは、コネクタのソフトウェア・コードに、PIMフィルタ条件との比較に使用するPIM日付フィールドを含める必要があります。比較で使用するPIM日付フィールドの値が含まれていないPIMレコードは、ExtractResponseに含める必要があります。

   
   

   コネクタでフィルタを適用する方法の詳細は、第C.2.2.3.3項「不正なレコードのダウンロードの防止」を参照してください。

8. コネクタは、抽出されたすべてのインバウンド・レコードを、ネイティブPIM API書式から、PIMドメインに対して定義したPIM XMLスキーマ(XSDファイル)に準拠したXMLメッセージに変換する必要があります。PIM XMLメッセージが作成された後、コネクタはXSL変換を使用して、そのPIM XMLメッセージを、提供されたハブXMLスキーマ(XSD)に準拠したハブXMLメッセージに変換する必要があります。コネクタでは、どのPIMフィールドがどのハブPIMにマップされているか、またはデータがどのように変換されるか不明であるため、PIM API書式からハブXML書式への直接変換はできません。第8.1項「データ変換の概要」を参照してください。

9. エコーの抑制を実行し、ExtractDomainResultsCallback APIを介してレコード・セットをハブに提供する前に、PIMサーバーから抽出したレコードのコレクションからすべてのエコーを削除します。すべてのエコーが削除された場合、コネクタは、エコーのないレコード・セットをエンジンに提供するときに、ExtractResponseMetadataのechoesSuppressedフラグ・メンバーをTRUEに設定する必要があります。

10. コネクタによっては、BDSSコール間で状態を保持することが必要になる場合があります。コネクタは、状態を保持するかどうかに関係なく、同期状態の保存に関連したBDSSとの規定事項を満たす必要があります。このため、ステートフルおよびステートレスのコネクタの同期状態を簡単に保存するために、次のAPIが提供されています。

    1. ステートレスのコネクタは、PIMサーバーから変更済レコードの最終バッチを収集すると同時に、そのバッチをBDSSに提供する前に、CacheTempSyncStateを介して同期状態をキャッシュする必要があります。ハブでは、ドメインの同期化が完了すると、EndDomainSynchronizationをコールし、同期状態を保存する必要があるかどうかを指示します。その場合、コネクタはCommitCachedSyncStateをコールして、キャッシュされた同期状態をコミットする必要があります。

    2. コネクタがBDSSコール間で状態情報を保持している場合は、BDSSがEndDomainSynchronizationをコールして同期状態を保存する必要があることを指示すると、そのコネクタはSaveSyncState APIのみを使用して同期状態を直接保存します。

11. 削除の検出。

    ハブでは、コネクタでの削除操作について次の2つのユースケースがサポートされています。

    1. ユースケース1: コネクタはネイティブで削除操作を検出できません。この場合、コネクタは、指定のユーザーおよびドメインのすべてのPIMレコードIDを含めた配列を作成することによって、PIMサーバーから削除されたレコードを判別できます。(この配列には、変更済および未変更のレコードのレコードIDを含める必要があります。)コネクタは、このレコードIDの配列をコネクタ・ランタイム・インタフェース・メソッドGetDeletesByIdsに提供し、削除されたレコードを識別するレコードIDの配列を取得できます。次に、コネクタは、これらのレコードIDをExtractResponseのExtractResponseDataメンバーのdeleteRecordIdArrayに追加できます。コネクタですべてのレコードIDを問い合せることができない場合、そのコネクタは削除操作を同期化できません。

    2. ユースケース2: 次の同期化セッションの前にBDSSで作成されたレコードをエンド・ユーザーが削除すると、コネクタではネイティブでそのレコードの削除を検出できません。

       PIMから正常にエクスポートされたレコードは同期状態によって追跡されるため、PIMストアからエクスポートされる直前に作成されたレコードがストアから削除されると、コネクタによってはその削除を検出できない場合があります(つまり、そのレコードはストアにインポートされたがエクスポートされなかったため、同期状態ではその削除を検出できません)。

       このユースケースは、エンド・ユーザーがPIMでレコードを作成して削除した場合、つまり、両方の操作が同期化セッションの有効範囲外で発生した場合も同様です。たとえば、BDSSの同期化が5分ごとに発生する場合、その5分が経過する前に、ユーザーがOutlookを使用してExchangeにレコードを作成して削除したとします。そのユーザーが同期化されると、同期状態では、作成されて削除されたレコードとして取得されません。つまり、同期状態は必ずしもPIMストアで実行された操作の履歴レコードではありません。BDSSのコンテキストとの違いは、レコード作成を実行するのがBDSSであることのみです。

       コネクタでこの機能を利用するには、エコーを識別できる必要があります。この場合、コネクタでは、エコーの抑制を実行するため、そのエコーを識別するPIMレコードIDが含まれる配列を作成し、GetDeletesByPendingCreateEchoesをコールして削除済レコードのレコードIDを取得します。次に、コネクタは、これらのレコードIDをExtractResponseのExtractResponseDataメンバーのdeleteRecordIdArrayに追加できます。

12. このAPIは非同期です。コネクタ実装では、リクエストの前処理を可能なかぎり少なくして、制御をハブに返す必要があります。つまり、このAPIでは、抽出リクエスト(またはリクエストに関するメタデータ)をコネクタ所有のスレッドにポストした後に、制御をハブに返す必要があります。この方法によって、時間がかかるPIMデータ抽出操作はコネクタ所有のスレッドで実行されます。コネクタでは、Webサービス・コールを正常に受信すると、例外のスローが可能になります。ただし、例外は、前処理に失敗した場合のみスローする必要があります。APIが戻った後、抽出を実行するスレッドは、ExtractDomainResultsCallback APIを介して、成功か失敗かを示す各ハブ・ドメインのExtractResponseをハブに提供する必要があります。

13. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。RTL URLとコネクタ名は両方とも、HubContext構造で提供されます。

戻り値

void

例外

コネクタで抽出リクエストをコネクタ所有のスレッドにポストできない場合、そのコネクタは例外をスローして問題を特定するメッセージを提供する必要があります。この処理によって、BDSSではそのメッセージを記録できます。

C.2.2.3 ExtractDomainsのベスト・プラクティス

この項では、ExtractDomainsに関するベスト・プラクティスについて説明します。トピックは次のとおりです。

• 効率的な抽出

• PIMフィールド定義のキャッシュ

• 不正なレコードのダウンロードの防止

C.2.2.3.1 効率的な抽出

変更が存在しない場合にPIM抽出操作を実行すると多くのリソースと時間が使用されるため、コネクタでは、指定のドメインに抽出が必要な変更が存在するかどうかを事前に判別する必要があります。たとえば、エンジンがコネクタをコールしてドメインを抽出する場合、コネクタでは、変更がないことを確認するためにのみ、ユーザーをコネクタ・アプリケーションに関連付けて多数のMAPIリソースを割り当てます。より効率的に処理するには、コネクタで、前回の同期状態以降の変更を問い合せるWebDAVリクエストをExchangeサーバーに発行する機能のみを備えたアプリケーションをユーザーに関連付けます。

C.2.2.3.2 PIMフィールド定義のキャッシュ

コネクタでは、PIMフィールド定義およびその他のドメイン関連の構成情報をコネクタ・ランタイム・インタフェース・メソッドGetPimDomainMetadataを介して取得し、それらを抽出サイクルで使用できるようにキャッシュする必要があります。

C.2.2.3.3 不正なレコードのダウンロードの防止

カレンダ・ドメインおよびタスク・ドメインを抽出するときは、pimFilterConditionを適用して、フィルタの基準を満たさないレコードがサーバーからダウンロードされるのを防ぎます。たとえば、コネクタでは、最初に変更済レコードをすべてサーバーからダウンロードし、次にすべてのレコードをフィルタと照合して評価し、抽出結果セットに含めるかどうかを判断する強制的な方法を実行することも可能です。さらに効率的な方法は、フィルタを適用して、そのようなレコードがPIMサーバーからダウンロードされるのを防ぐことです。たとえば、MAPI制限構成をExchange 2007コネクタで使用して、古いレコードがダウンロードされるのを防ぎます。

C.2.3 EndDomainSynchronization API

ハブでは、このEndDomainSynchronizationインタフェースをコールして、指定ユーザーのドメインの同期化を終了します。このインタフェースをコールすると、ユーザーのハブ・ドメインの同期化セッションを正常に(または強制的に)終了できます。

表C-4 EndDomainSynchronization APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	[in]	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタが指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubDomain	String	[in]	ハブ・ドメインを識別します。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	[in]	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	[in]	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
saveSyncState	Boolean	[in]	コネクタで同期状態を保存する必要があるかどうかを示すブール値。
extractResponseCount	Integer	[out]	特定の同期化セッションで、指定のドメインおよびユーザーについてコネクタがハブに正常に送信したバッチの数が格納されます。Oracle Fusion Middleware 11gリリース1のBDSSでは、このパラメータは0または1のいずれかです。

C.2.3.1 エンジン規定

エンジンは、EndDomainSynchronization APIをコールするときに次の処理を実行します。

1. 指定のドメインの処理の最後にこのメソッドをコールします。

2. コネクタで同期状態を保存する必要があるかどうかを示します。次の場合は、フラグをFalseに設定します。

   • 現在の同期化セッション中にドメインが抽出されなかった場合。

   • ドメインが抽出され、コネクタでレコードを含まないExtractResponseが提供され、echoesSuppressedフラグがfalseの場合。この場合、抽出されたレコードはありません(エコーまたはエコー以外)。

     
     

     注意: コネクタは、ExtractResponseのechoesSuppressedフラグを設定して、ExtractResponseでエコーが削除されたかどうかを示します。Oracle Fusion Middleware 11gリリース1のBDSSでは、1つのハブ・ドメインに対する複数のExtractResponseの受信はハブでサポートされていません。

     
     

3. extractResponseCountを使用して、エラー発生時にハブで受信したExtractResponseをクリーン・アップします。

4. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

5. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameを使用する必要があります。

C.2.3.2 コネクタ規定

エンジンでEndDomainSynchronization APIがコールされると、コネクタでは次のようにレスポンスします。

1. ユーザーに関連するドメイン・レベルのリソースをクリーン・アップします(該当する場合)。

2. saveSyncStateがtrueの場合、ExtractDomains APIの「コネクタ規定」の項で説明したように、コネクタは、コネクタ・ランタイム・インタフェースAPIを介してドメインの同期状態をハブ・データ・ストアに保存します。

3. ハブでこのAPIをコールして同期化セッションを強制的に終了する場合でも、ハブに送信するExtractResponseがないことを確認します。

4. extractResponseCountに、指定の同期化セッションでハブに正常に送信されたExtractResponseの正しい数が常に移入されていることを確認します。

5. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

6. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

注意: コネクタが認識していないユーザー・セッションでハブがコネクタをコールした場合、そのコネクタはこのコールで空操作(操作なし)を実行する必要があります。これは、他のコネクタの障害によってハブが同期化セッションを終了する場合などに発生する場合があります。これによって、ハブで同期化セッションを急に終了する必要が生じた場合のハブ・ロジックが簡略化されます。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

C.2.4 EndUserSyncSession API

エンジンは、指定したユーザーの全ドメインの同期化の終了時にEndUserSyncSessionインタフェースをコールして、指定したsyncSessionIdで識別される同期化セッションを終了します。コネクタ実装では、この時点を利用して、指定のユーザーに関連付けられたユーザー固有のリソースを解放できます。表C-5に、EndUserSyncSessionインタフェースのパラメータを示します。

表C-5 EndUserSyncSession APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	[in]	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタが指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubUserId	String	[in]	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	[in]	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。

C.2.4.1 エンジン規定

エンジンは、EndUserSyncSession APIをコールするときに次の処理を実行します。

1. 同じユーザーに対しては、別の同期化セッションが開始されるまでコネクタをコールしません。

2. このAPIをコールして、指定のsyncSessionIdで識別される同期化セッションを終了します。

3. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

4. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameパラメータを使用する必要があります。

C.2.4.2 コネクタ規定

エンジンでEndUserSyncSession APIがコールされると、コネクタでは次のようにレスポンスします。

1. ユーザーに関連するすべてのリソースをクリーン・アップします。

2. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

3. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

注意: コネクタが認識していないユーザー・セッションでハブがコネクタをコールした場合、そのコネクタはこのコールで空操作(操作なし)を実行する必要があります。これは、他のコネクタの障害によってハブが同期化セッションを終了する場合などに発生する場合があります。これによって、ハブで同期化セッションを終了する必要が生じた場合のハブ・ロジックが簡略化されます。

C.2.5 CreateRecord API

ハブでは、PIMでレコードを作成する必要がある場合、常にCreateRecordインタフェースをコールします。表C-6は、CreateRecordインタフェースのパラメータを示します。

注意: ドメインが抽出されていない場合でも、ハブではこのAPIをコールできます。

表C-6 CreateRecord APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	[in]	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタがランタイム・ライブラリをコールするときに指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubDomain	String	[in]	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	[in]	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	[in]	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubRecord	アップサート・レコード	[in/out]	入力時に、ハブ・レコードがハブXML書式で格納されます。RecordMetadataメンバーは、NULLである必要があります。出力時に、RecordMetadataが割り当てられ、コネクタによって次の内容が移入されます。 PIMレコードID: 必須パラメータです。NULL以外である必要があり、空にすることはできません。 PIMレコード関連データ: オプション・パラメータで、NULLにできます。NULL以外の場合、関連データ・メンバーの少なくとも1つはNULL以外である必要があり、空にすることはできません。 PIMレコード・バージョンID: 必須パラメータです。NULL以外である必要があり、空にすることはできません。 (オプション)コネクタがレコードの作成に失敗した場合は、recordErrorをtrueに設定し、recordErrorDescriptionを指定します。 PIMレコード説明: このパラメータ(オプション、構成から導出されるパラメータ)は、ハブ・ドメインに対して使用可能なKeyField構成がない場合にNULLにできます。ハブ・ドメインに対してKeyField構成が存在する場合、配列はNULL以外である必要があります。記述配列内の各KeyValuePairは、NULL以外の(空にすることができない)キーに加えて、NULL以外の(空にすることができない)値も持つ必要があります。

C.2.5.1 エンジン規定

エンジンは、CreateRecord APIをコールするときに次の処理を実行します。

1. エンジンでは、このコネクタAPIコールから戻された後に、UpsertRecordの提供されたRecordMetadataメンバーに含まれる次のデータでデータ・ストアを更新する必要があります。

   • PIMレコードID

   • PIMレコード・バージョンID

   • PIMレコード関連データ(提供された場合)

   • PIMレコード説明(提供された場合)

2. レコードが正常に作成された場合、エンジンでは、メタデータが格納されるようにハブ・データ・ストアを更新するのに加えて、ストア内の指定の行のechoPendingフラグをTRUEに設定する必要があります。

3. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

4. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameを使用する必要があります。

C.2.5.2 コネクタ規定

エンジンでCreateRecord APIがコールされると、コネクタでは次のようにレスポンスします。

1. PIMストアにレコードを作成し、表C-6に示すメタデータを提供します。

2. ハブ書式のXMLメッセージを、PIMサーバーでのレコードの作成に適した書式に変換します。

3. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

4. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

C.2.6 UpdateRecord API

エンジンは、PIMサーバーでレコードを更新する必要がある場合、常にUpdateRecordインタフェースをコールします。表C-7に、UpdateRecordメソッドのパラメータを示します。

注意: ドメインが抽出されていない場合でも、ハブではこのAPIをコールできます。

表C-7 UpdateRecord APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタがランタイム・ライブラリをコールするときに指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubRecord	UpsertRecord	In	ハブ・レコード、および更新されるレコードに関してハブ・データ・ストアから取得されるメタデータが格納されます。 RecordMetadataメンバーはNULL以外で、ハブでコネクタ固有のメタデータが移入される必要があります。
updatedMetadata	RecordMetaData	Out	出力時に、次の内容を含む更新済レコード・メタデータがPIMレコードから取得されて格納されます。 PIMレコードID: これは必須パラメータです。このパラメータは、NULL以外である必要があり、空にすることはできません。 PIMレコード関連データ: このパラメータはオプションで、NULLにできます。NULL以外の場合、関連データ・メンバーの少なくとも1つはNULL以外である必要があり、空にすることはできません。 PIMレコード説明: このパラメータ(オプションで構成から導出されるパラメータ)は、ハブ・ドメインに対して使用可能なKeyField構成がない場合にNULLにできます。ハブ・ドメインに対してKeyField構成が存在する場合、配列はNULL以外である必要があります。記述配列内の各KeyValuePairは、NULL以外の(空にすることができない)キーおよびNULL以外の(空にすることができない)値を持つ必要があります。 (オプション)コネクタがレコードの作成に失敗した場合は、recordErrorをtrueに設定し、recordErrorDescriptionを指定します。 PIMレコード・バージョンID(必須)。このパラメータは、NULL以外である必要があり、空にすることはできません。

C.2.6.1 エンジン規定

エンジンは、UpdateRecord APIをコールするときに次の処理を実行します。

1. エンジンは、抽出レスポンスの評価時に検出された競合を解決するときに次の処理を実行します。

   1. 更新/更新競合の場合、ハブでは、非優先コネクタでこのAPIをコールしたときに抽出されたレコードで提供されるAssociatedDataではなく、BDSSストアからのAssociatedDataを非優先コネクタに提供する必要があります。

   2. 作成/作成競合の場合、ハブでは、非優先コネクタでこのAPIをコールしたときにその非優先コネクタから抽出されたレコードで提供されるAssociatedDataを使用する必要があります。

2. レコードが正常に更新された場合、エンジンでは、メタデータが格納されるようにデータ・ストアを更新するのに加えて、ストア内の指定の行のechoPendingフラグをFALSEに設定する必要があります。

3. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

4. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたコネクタ名を使用する必要があります。

C.2.6.2 コネクタ規定

エンジンでUpdateRecord APIがコールされると、コネクタでは次のようにレスポンスします。

1. PIMサーバーで指定のPIMレコードIDによって識別されるレコードを更新し、RecordMetaData構造を移入します。

2. BDSSによる抽出の後、コネクタによる更新の処理の前にPIMサーバーでレコードが削除された場合、コネクタでは、レコードが削除されたために更新が無視されたことを示すログ・メッセージを提供する必要があります。(後続の抽出サイクルでは、削除操作を検出してエンジンに伝播する必要があります。)

3. アウトバウンド更新のプッシュ直前にPIMレコードが変更された場合に発生する競合をPIM APIで検出した場合、コネクタではその競合を「BDSS優先」方式で解決します(つまり、BDSSがコネクタに提供したレコードによって、エンド・ユーザーの変更が上書きされます)。

4. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

5. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

C.2.7 DeleteRecord API

エンジンは、PIMサーバーからレコードを削除する必要がある場合、常にDeleteRecord APIをコールします。表C-8に、DeleteRecordメソッドのパラメータを示します。

注意: ドメインが抽出されていない場合でも、ハブではこのAPIをコールできます。

表C-8 DeleteRecord APIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String		コネクタがコネクタ・ランタイム・ライブラリをコールするときに指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubDomain	String	[in]	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimRecordId	String	In	削除するレコードのPIMレコードIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimRecordDescription	PIMレコード説明	In	PIMレコード説明が格納されます。

C.2.7.1 エンジン規定

エンジンは、DeleteRecord APIをコールするときに次の処理を実行します。

1. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

2. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameパラメータを使用する必要があります。

C.2.7.2 コネクタ規定

エンジンでDeleteRecord APIがコールされると、コネクタでは次のようにレスポンスします。

1. 指定のPIMレコードIDで識別されるレコードをPIMで削除します。

2. コネクタでは、PIMレコード関連データが必要な場合、コネクタ・ランタイム・インタフェース・メソッドGetRecordAssociatedDataを介してこのデータを取得できます。ほとんどのPIMサーバーでは、PIMレコードIDのみ必要です。

3. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

4. 削除がPIMに送信される前にPIMレコードが削除された場合は、エラー以外のコードを返します。コネクタでは、レコードがすでに削除されていたために削除に失敗したことを示すメッセージを記録できます。

5. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

C.2.8 GetPimServerEndPoint API

ハブでは、GetPimServerEndPointインタフェースをコールして指定の同期化対応ユーザーのPIMサーバー・エンドポイントを取得し、返されたendPointTokenを使用して、同期化セッション中にユーザーを同期化するときにコネクタのクラスタ内のどのコネクタ・インスタンスをコールするかを決定します。表C-9に、GetPimServerEndPointインタフェースのパラメータを示します。

表C-9 GetPimServerEndPointインタフェースAPIのパラメータ

パラメータ	データ型	タイプ	説明
connectorName	String	[in]	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
rtlUrl	String	[in]	コネクタがコネクタ・ランタイム・ライブラリをコールするときに指定の同期化セッションで使用する、コネクタ・ランタイム・インタフェースへのURLが格納されます。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
endPointToken	String	Out	出力時に、コネクタ定義のエンドポイント・トークンが格納されます。このパラメータは、NULLにできます。また、空にもできます。
canSyncUser	Boolean	Out	出力時に、受信コネクタが指定のユーザーを同期化できるかどうかを示します。

C.2.8.1 エンジン規定

ハブでは、ユーザーのPIMサーバー・エンドポイントを取得する必要がある場合のみ、GetPimServerEndPoint APIをコールします。ハブでは、このAPIをコールするときに次の処理を実行します。

1. 構成メタデータ、および返されたendPointTokenとcanSyncUserを使用して、指定のユーザーを抽出するためにコールするコネクタを決定します。ハブでは、最初にendPointTokenをチェックします。endPointToken値がNULL以外文字列であり、空にすることはできない場合、ハブではそのendPointToken値を使用して、ユーザーの同期化に使用するコネクタURLを取得します。NULLまたは空の場合、ハブではブール値をチェックして、そのブール値を返した受信コネクタがユーザーの同期化に使用できるかどうかを判断します。

2. 指定のユーザーおよび同期化セッションでコネクタが使用するコネクタ・ランタイム・ライブラリURLを提供します。コネクタでは、このメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合、提供されたURLを使用する必要があります。

3. コネクタ名を提供します。コネクタでこのメソッドの実装の一環としてコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたconnectorNameを使用する必要があります。

C.2.8.2 コネクタ規定

GetPimServerEndPoint APIコールを受信するコネクタでは、次の処理を実行します。

1. 指定のユーザーに対してPIMサーバー・エンドポイントを解決します。コネクタで指定のユーザーを解決できない場合は、エラーを返す必要があります。

   
   

   注意: 受信コネクタ・インスタンスは、ユーザーの同期化を実行するインスタンスと異なる(クラスタは同じでも)場合があります。

   
   

   PIMサーバー・エンドポイント値(endPointToken)は、コネクタ実装詳細です。管理者がURLをエンドポイントに正しくマップできるように、開発者はPIMサーバー・エンドポイント値を文書化する必要があります。たとえば、Exchangeの場合、コネクタでは指定のユーザー・メールボックスをホストするExchangeサーバーのNetBios名を返します。このため、管理者はExchangeサーバーのこれらのNetBios名をクラスタURLにマップする必要があります。

2. 提供された同期化セッションID、ハブ・ドメインおよびハブ・ユーザーIDをロギング文で使用します。

3. コネクタでコネクタ・ランタイム・ライブラリをコールする必要がある場合は、提供されたRTL(ランタイム・ライブラリ)URLとコネクタ名を使用します。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

C.3 エンジン・コールバック・インタフェースAPI

エンジン・コールバック・インタフェースは単一のメソッドExtractDomainResultsCallbackで構成されたWebサービスベースのインタフェースで、ハブにExtractResponseを提供するときにコネクタでコールされます。

C.3.1 ExtractDomainResultsCallback API

ExtractDomainResultsCallback APIは非同期で、エンジンが指定のExtractResponseで提供される情報をキューに入れた直後にコール側コネクタに戻ります。表C-10に、ExtractDomainResultsCallbackメソッドのパラメータを示します。

表C-10 ExtractDomainResultsCallback APIのパラメータ

パラメータ	データ型	タイプ	説明
extractResponseData	ExtractResponse	In	コネクタによって提供される一連のレコードが格納されます。

C.3.2 エンジン規定

エンジンは、ExtractDomainResultsCallback APIをコールすると、ExtractResponseをキューに入れてすぐに戻ります。

C.3.3 コネクタ規定

コネクタでは、エンジンのExtractDomainResultsCallback APIコールのレスポンスとして、次の処理を実行します。

• コネクタでは、PIMからレコードを抽出して指定のExtractResponseを作成するとき、このAPIをコールする前にすべてのエコーをレスポンスから削除する必要があり、エコーが削除されている場合はechoesSuppressedフラグをtrueに設定する必要があります。

• コネクタでは、ExtractResponseの順序番号を指定する必要があります。1番目の抽出レスポンスは1に、2番目は2のように番号を付けます。Oracle Fusion Middleware 11gリリース1のBDSSでは、順序番号は常に1です。

戻り値

void

C.4 コネクタ・ランタイム・インタフェースAPI

コネクタ・ランタイム・インタフェースは、コネクタがハブ・データ・ストア内の特定のメタデータ(AssociatedDataなど)にアクセスできる、WebサービスベースのAPIです。このインタフェースは、同期状態の保存など、すべてのコネクタに共通のサービスを提供します。

コネクタ作成者はこのインタフェースを実装しません。コネクタ実装はこのインタフェースのコンシューマです。

通常、すべてのAPIは整数を返して成功(0)または失敗(0以外)を示します。すべてのAPIでは、リカバリ不能なエラー(BDSSストアに対する読取りや書込みが不可、不正なパラメータなど)が発生すると、RemoteExceptionをスローできます。開発者は、例外およびAPIコール全体の成功を判断するための戻り値を考慮してコネクタを記述する必要があります。

C.4.1 GetPimRecordVersions API

コネクタでは、GetPimRecordVersionsメソッドを使用して、BDSSデータ・ストアに格納されている1つ以上のPIMレコードのPIMレコード・バージョンIDを取得できます。この情報を取得すると、コネクタでは、BDSSが正常に同期化したPIMレコード(1つまたは複数)の最新バージョンを判別できます。

表C-11 GetPimRecordVersions APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimRecordIdArray	String []	In	コネクタでバージョンIDを取得するPIMレコードIDの配列が格納されます。
pimRecordVersionIdArray	String []	Out	出力時に、pimRecordIdArrayで指定した各レコードのPIMレコード・バージョンIDが格納されます。pimRecordIdArrayとpimRecordVersionIdArrayの間には位置関係があり、pimRecordVersionIdArrayのi番目の要素には、pimRecordIdArrayのi番目の要素に対応するバージョンIDが格納されます。次のいずれかの条件に該当する場合、pimRecordVersionIdArrayのi番目の要素はNULL以外の空の文字列です。 pimRecordIdArrayのi番目の要素がBDSSストアに見つからない場合。 pimRecordIdArrayのi番目の要素はBDSSストアに存在するが、バージョンがNULLの場合(前の同期化セッションで障害が検出された場合に発生することがあります)。 同期化セッションが障害なしで完了すると、(空にすることができない)バージョンIDがpimRecordVersionIdArrayのi番目の要素に提供されます。 GetPimRecordVersionsメソッドが、対応するバージョンIDとしてPIMレコードのバージョンIDと同じバージョンIDを返す場合、コネクタではPIMレコードのエコーを抑制する必要があります。したがって、GetPimRecordVersionsメソッドが対応するバージョンIDとして空の文字列を返す場合、コネクタではPIMレコードのエコーを抑制しないでください。 pimRecordIdArrayのi番目の要素に対応するpimRecordVersionIdArrayのi番目の要素がNULLとして返されることはありません。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERRORの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.2 CacheTempSyncState API

CacheTempSyncStateメソッドは、指定の同期状態をBDSSストアの一時的なデータ格納場所に保存します。状態を保持しないコネクタでは、指定のドメインのPIMデータを抽出した後、最新の一連のレコードをBDSSに提供する前に、このメソッドをコールします。

表C-12 CacheTempSyncState APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSession	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainTarget	String	In	PIMドメイン・ターゲットが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainSyncState	String	In	指定のユーザー、ドメイン、ドメイン・ターゲットおよびサーバー・タイプについてキャッシュされる同期状態が格納されます。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERRORの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.3 CommitCachedSyncStateメソッドAPI

CommitCachedSyncStateメソッドは、BDSSストア内の一時的な格納場所にすでに保存されている同期状態を、BDSSストア内の永続的な格納場所に保存します。これは、BDSSコール間で状態情報を保持できないコネクタで使用することを目的にしています。

コネクタでは、このメソッドをコールする前に、同じ同期化セッション内でCacheTempSyncStateを正常にコールしている必要があります。通常、ステートレス・コネクタでは、特定のドメインのデータ抽出が完了する直前にCacheTempSyncStateをコールします。次に、ハブでEndDomainSynchronizationをコールするときにこのメソッドをコールして、同期状態を保存する必要があることを示します。表C-13に、CommitCachedSyncStateメソッドのパラメータを示します。

表C-13 CommitCachedSyncState APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainTarget	String	In	PIMドメイン・ターゲットが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERRORの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.4 GetConfigurationMetaData API

コネクタでは、GetConfigurationMetaData APIをコールして、プロファイル構成メタデータを取得します。1つのプロファイルには1つ以上のセクションがあります。各セクションには1つ以上のパラメータがあり、各パラメータには1つの値が含まれます。プロファイルは、概念的にはWindowsの.ini構成ファイルと同じです。BDSSコネクタでは、独自のプロファイルを定義して、コネクタに固有のメタデータを格納できます。表C-14に、GetConfigurationMetaDataメソッドのパラメータを示します。

表C-14 GetConfigurationMetaData APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
configMetadataArray	ConfigurationProfile []	In/Out	入力時に、取得されるプロファイル・メタデータが移入されるConfigurationProfile構造が格納されます。出力時に、リクエストされたプロファイル・メタデータが含まれるように配列が更新されます。

GetConfigurationMetaData APIを使用すると、コネクタでは、1回のコールで複数のプロファイル間の任意の構成メタデータを取得できます。コネクタでconfigMetadataArrayパラメータを作成および移入し、そのコネクタで取得する内容を指定すると、APIではリクエストされた構成(構成が存在する場合)をconfigMetadataArrayに移入します。

基本的に、コネクタでは、ConfigurationProfile構造の配列を作成し、取得する構成のスコープを指定する方法で移入し、GetConfigurationMetaData APIによって構造の移入を完了します。スコープの指定は、プロファイル、セッションまたはパラメータ・ベースで実行できます。たとえば、コネクタでプロファイルのセクション全体が必要な場合は、ConfigurationProfile構造を作成し、目的のプロファイル名とセクション名のみを指定して、そのConfigurationProfileをconfigMetadataArrayに追加します。同様に、コネクタでプロファイルのセクションの1つのパラメータが必要な場合は、プロファイル名、セクション名およびパラメータ名を指定したConfigurationProfileを作成してconfigMetadataArrayに追加します。

表C-15に、コネクタでconfigMetadataArrayを作成して構成メタデータを取得する方法、およびGetConfigurationMetaData APIによってconfigMetadataArrayを更新する方法について、共通のユースケースを示します。

表C-15 ConfigMetadataArrayのユースケース

ユースケース	コネクタによるconfigMetadataArray [in]の作成	APIによるconfigMetadataArray[out]の更新
特定のプロファイルにある特定のセクションの特定のパラメータ値を取得します。 スコープはProfile.Section.Parameterです。	配列のサイズは1で、次のように移入される単一のConfigurationProfile構造が格納されます。 ConfigurationProfile: プロファイル名メンバーが移入されます。 configSectionArrayメンバーには、単一のConfigurationSection構造が移入されます。 ConfigurationSection: セクション名メンバーが移入されます。 paramNameValueArrayメンバーには、単一のKeyValuePair構造が移入されます。 KeyValuePair: キー・メンバーが移入されて、取得するパラメータの名前が格納されます。	paramNameValueArrayのvalueメンバーを更新して、パラメータ値が格納されます。つまり、configMetadataArray[0].configSectionArray[0].paramNameValueArray[0].valueになります。
プロファイル内のセクションのパラメータの名前と値を取得します。スコープはProfile.Sectionです。	配列のサイズは1で、次のように移入される単一のConfigurationProfile構造が格納されます。 ConfigurationProfile: プロファイル名メンバーが移入されます。 configSectionArrayメンバーには、単一のConfigurationSection構造が移入されます。 ConfigurationSection: 配列のサイズは1で、次のように移入される単一のConfigurationProfile構造が格納されます。 セクション名メンバーが移入されます。 paramNameValueArrayは空の配列です。	ConfigurationSectionのparamNameValueArrayメンバーを更新します。(つまり、configMetadataArray[0].configSectionArray[0].paramNameValueArrayが割り当てられ、セクション内のすべてのパラメータと値が移入されます。)
プロファイル内のすべてのセクションのパラメータの名前と値を取得します。スコープはProfileです。	配列のサイズは1で、次のように移入される単一のConfigurationProfile構造が格納されます。 ConfigurationProfile: プロファイル名メンバーが移入されます。 configSectionArrayメンバーは空の配列です。 ConfigurationSection: NULL	configSectionArrayが割り当てられ、プロファイル内の各セクションのConfigurationSectionが移入されます。 各ConfigurationSectionにはセクション名が移入され、paramNameValueArrayは移入されてセクション内の各構成オプションのパラメータと値が格納されます。
複数のプロファイル内のすべてのセクションのパラメータの名前と値を取得します。 スコープはMultiple Profilesです。	配列はProfileスコープの場合と同様に作成されますが、サイズは1より大きくなります(つまり、リクエストされるプロファイルごとに配列に1つのConfigurationProfile要素があります)。	Profileスコープの場合と同様に処理されますが、配列内の各ConfigurationProfileメンバーが更新されます。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERRORの場合は0以外

GetConfigurationMetaData APIがエラーを返すのは、ストアが使用不可、メモリー不足など処理が中断される状況が発生したためにBDSSストアからメタデータを取得できなかった場合のみです。特定の構成値、セクションまたはプロファイルを取得できなかった場合は、エラーを返しません。コネクタでは、特定の構成メタデータ値の取得に失敗した場合、実際に障害が発生しているかどうかを判断します。たとえば、コネクタで、コネクタ・プロファイルの1つのセクションから抽出レスポンス・バッチ・サイズを取得するとします。不要なイベントは発生せず、カスタマがこの値の構成に失敗すると、このAPIはSUCCESS/OKエラー・コードを返し、対応する値はそのままにします。(つまり、抽出レスポンス・バッチ・サイズに設定したコネクタ構成値に応じて、値はNULLまたは空にできます。)この時点で、コネクタは構成エラーの重大度を判断して適切に処理します。たとえば、コネクタ機能を停止するようなリカバリ不能なエラーとみなさない場合は、エラーまたは警告を記録してデフォルト値を使用できます。また、エラーまたは警告を記録して、リカバリ不能なエラーとみなすこともできます。

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.5 GetDeletesByPendingCreateEchoes API

現在の同期化セッションでハブでレコードが作成された後、次の同期化セッションの前に削除操作が発生した場合、コネクタでは、ハブで作成されたレコードの削除をネイティブで検出できない場合にGetDeletesByPendingCreateEchoes APIをコールします。表C-16に、GetDeletesByPendingCreateEchoes APIのパラメータを示します。

表C-16 GetDeletesByPendingCreateEchoes APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
echoIdArray	String []	In	エコーをそれぞれ識別するPIMレコードIDの配列が格納されます。このパラメータは、NULL以外である必要があります。配列の長さは1以上である必要があります。ハブでは、PIMレコードIDが空の文字列または-1のエントリは無視します。コネクタにエコーが存在しない場合でも、配列を提供する必要があります。PIMレコードIDとして空の文字列を格納する配列のサイズは1にすることをお薦めします。
upsertIdArray	String []	In	前回の同期状態以降にPIMで更新または作成されたレコードをそれぞれ識別するPIMレコードIDが格納されます。NULL以外である必要があります。配列の長さは1以上である必要があります。ハブでは、PIMレコードIDが空の文字列または-1のエントリは無視します。コネクタにアップサート・レコードが存在しない場合でも、PIMレコードIDとして空の文字列が格納された配列(配列のサイズは1を推奨)を提供する必要があります。
deleteRecordIdArray	String []	Out	出力時に、PIMから削除済と識別された各レコードのPIMレコードIDが格納されます。削除操作が検出されなかった場合、返される配列はNULLです。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.6 GetDeletesBylds API

コネクタでは、PIMサーバーからの削除をネイティブで検出できない場合、GetDeletesByldsメソッドをコールします。このメソッドは、前回に同期化された指定のユーザー、ハブ・ドメインおよびコネクタ名について、PIMレコードIDのリストをハブ・ストアに問い合せます。次に、ハブ・ストア・ベースの配列をコネクタ提供の配列と比較して、削除されたレコードを識別するPIMレコードIDの配列を作成します。ハブ・ストア・ベースの配列にあり、コネクタが提供する配列にないPIMレコードIDは、削除されたとみなされます。表C-17に、GetDeletesByIdsメソッドのパラメータを示します。

表C-17 GetDeletesBylds APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。NULL以外である必要があり、空にすることはできません。
recordIdArray	String[]	In	指定のユーザー、ドメインおよびサーバー・タイプのすべてのPIMレコードのPIMレコードIDが格納された配列。このパラメータは、NULL以外である必要があります。PIMにPIMレコードが存在しない場合、コネクタでは、PIMレコードIDとして空の文字列が格納されたサイズ1の配列を提供する必要があります。
deleteRecordIdArray	String[]	Out	出力時に、PIMから削除されたレコードを識別するPIMレコードIDの配列が格納されます。削除対象がない場合、返される配列はNULLです。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.7 GetRecordAssociatedData API

コネクタでは、GetRecordAssociatedData APIをコールして、レコードに関連付けられたPIMレコード関連データをハブ・データ・ストアから取得します。これは、コネクタでデータをPIMレコードに関連付けている場合に役立ちます。たとえば、コネクタでデータを各PIMレコードに関連付けると、エコー検出が容易になり、このAPIを使用してそのデータを取得できます。表C-18に、GetRecordAssociatedData APIのパラメータを示します。

表C-18 GetRecordAssociatedData APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。NULL以外である必要があり、空にすることはできません。
pimRecordIdArray	String []	Out	PIMレコード関連データを取得する各レコードのPIMレコードIDが格納された配列。このパラメータは、NULL以外でサイズが0より大きい必要があります。配列の各要素は、NULL以外である必要があり、空にすることはできません。
pimRecordAssocDataArray	String []	Out	出力時に、この配列には、pimRecordIdArrayで指定した各レコードのPIMレコード関連データが格納されます。 pimRecordIdArrayの要素とpimRecordAssocDataArrayの要素の間には位置関係があります。pimRecordIdArrayのi番目の要素のAssociatedDataは、pimRecordAssocDataArrayのi番目の要素に位置します。pimRecordIdArrayのi番目の要素でPIMレコード関連データがないレコードを識別した場合、この配列のi番目の要素には空のAssociatedData要素が格納されます(つまり、構造は割り当てられますが、構造のメンバーはNULLです)。
errorArray	String []		出力時に、成功またはエラー・コードで構成される配列です。この配列とpimRecordAssocDataArrayの間には位置関係があります。i番目のエラー・コードは、i番目のAssociatedDataの取得の成功または失敗に対応します。( 0 = OK、1 = ERROR、2 = データがDBに存在しない)

戻り値

Integer

• SUCCESS/OKの場合は0。すべてのAssociatedDataがデータ・ストアから読み取られた場合です。

• ERROR/NOTOKの場合は0以外。いずれかのAssociatedData要素の読取りに失敗した場合です。コール元ではerrorArrayを検証して読取りが失敗した要素を判別し、コネクタではエラーの重大度を判断します。errorArrayのエラー・コードには、より明示的なエラー・コードを含めることができます。

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.8 GetSyncState API

コネクタでは、GetSyncState APIをコールして、ドメインに関連付けられたコネクタ定義の同期状態を取得します。このメソッドは、データ・ストアの永続的な格納場所に格納された同期状態のみを返します。永続的および一時的な同期状態の詳細は、「CacheTempSyncState API」、「CommitCachedSyncState Method API」および「SaveSyncState API」を参照してください。表C-19に、GetSyncState APIのパラメータを示します。

表C-19 GetSyncState APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainTarget	String	In	PIMドメイン・ターゲットが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainSyncState	String	In	出力時に、指定のユーザー、ドメイン、ドメイン・ターゲットおよびサーバー・タイプの同期状態が格納されます。指定のユーザー、ドメイン、コネクタ名およびドメイン・ターゲットの同期状態が存在しない場合、戻り値はNULLです。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

例外

リカバリ不能なエラーが発生した場合、または同期状態が存在しない場合は、RemoteExceptionがスローされます。

C.4.9 GetUserAssociatedData API

コネクタでは、GetUserAssociatedData APIをコールして、ユーザー・レベルでコネクタ固有のPIMユーザー関連データを取得します。このAPIを使用すると、複数のスレッドで指定のユーザーの関連データにアクセスできます。表C-20に、GetUserAssociatedData APIのパラメータを示します。

表C-20 GetUserAssociatedData APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
assocDataIdArray	String	In	コネクタ定義のユーザー関連データの識別子の配列が格納されます。
pimUserAssocDataArray	関連データ[]	Out	出力時に、ユーザー固有の関連データが格納されます。この配列とassocDataIdArrayの間には位置関係があります。pimUserAssocDataArrayのi番目の要素には、assocDataIdArrayに示すi番目の要素のPIMユーザー関連データが格納されます。
errArray	Integer []	Out	出力時に、PIMユーザー関連データの取得の成功または失敗を示すエラー・コードの配列が格納されます。errArrayのi番目の要素には、pimUserAssocDataArrayに示すi番目の要素の取得の成功または失敗コード(0 = OK、1 = ERROR、2 = データがDBに存在しない)が保持されます。

戻り値

Integer

• SUCCESS/OKの場合は0(すべてのAssociatedData要素がデータ・ストアから読み取られた場合です。)

• ERROR/NOTOKの場合は0以外。いずれかのAssociatedData要素の読取りに失敗した場合です。コール元ではerrArrayを検証して読取りが失敗した要素を判別し、コネクタではエラーの重大度を判断します。errArrayのエラー・コードには、より明示的なエラー・コードを含めることができます。

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.10 SaveSyncState API

BDSSコール間で状態を保持するコネクタでは、このAPIをコールして、ドメインに関連付けられたコネクタ定義の同期状態をハブ・ストアに保存する必要があります。状態を保持しないコネクタでは、CacheTempSyncStateおよびCommitCachedSyncStateを使用して同期状態を保持する必要があります。表C-21に、SaveSyncState APIのパラメータを示します。

表C-21 SaveSyncState APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainTarget	String	In	PIMドメイン・ターゲットが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimDomainSyncState	String	In	指定のユーザー、ドメイン、ドメイン・ターゲットおよびサーバー・タイプの同期状態が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。

戻り値

Integer

• SUCCESS/OKの場合は0

• ERROR/NOTOKの場合は0以外

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.11 SetRecordAssociatedData

コネクタでは、setRecordAssociatedData APIをコールして、コネクタ定義のPIMレコード関連データを指定のレコードに関連付けます。表C-22に、SetRecordAssociatedData APIのパラメータを示します。

表C-22 SetRecordAssociatedData APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimRecordIdArray	String []	In	PIMレコード関連データがBDSSデータ・ストアに書き込まれるレコードのPIMレコードIDの配列。
pimRecordAssocDataArray	関連データ[]	In	BDSSデータ・ストアに書き込まれる各レコードのPIMレコード関連データが格納された配列。pimRecordIdArrayとpimRecordAssocDataArrayの間には位置関係があります。pimRecordIdArrayのi番目のPIMレコードIDの場合、そのPIMレコード関連データはpimRecordAssocDataArrayのi番目のAssociatedDataとして存在する必要があります。
errorArray	Integer []	Out	出力時は、エラー・コードの配列です。この配列とpimRecordAssocDataArrayの間には位置関係があります。i番目のエラー・コードは、i番目のAssociatedDataの設定の成功または失敗(0 = OK、1 = ERROR)に対応します。

戻り値

Integer

• SUCCESS/OKの場合は0すべてのAssociatedData要素がBDSSデータ・ストアに書き込まれた場合です。

• ERROR/NOTOKの場合は0以外。いずれかのAssociatedData要素の書込みに失敗した場合です。コール元ではerrorArrayを検証して書込みが失敗した要素を判別し、コネクタではエラーの重大度を判断します。

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.4.12 SetUserAssociatedData API

コネクタでは、SetUserAssociatedData APIをコールして、ユーザー・レベルのコネクタ固有のPIMユーザー関連データを保存します。このAPIを使用すると、複数のスレッドで指定のユーザーの関連データにアクセスできます。表C-23に、SetUserAssociatedData APIのパラメータを示します。

表C-23 SetUserAssociatedData APIのパラメータ

パラメータ	データ型	タイプ	説明
syncSessionId	String	In	同期化セッションIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	In	ハブ・ドメインが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	In	ハブ・ユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	In	PIMユーザーIDが格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
connectorName	String	In	コネクタ名が格納されます。このパラメータは、NULL以外である必要があり、空にすることはできません。
assocDataIdArray	String []	In	コネクタ定義のユーザー関連データの識別子の配列。
pimUserAssocDataArray	関連データ	In	ユーザー固有の関連データが格納されます。pimUserAssocDataArrayとassocDataIdArrayの間には位置関係があります。assocDataIdArrayのi番目の要素には、この配列のi番目の要素に対応するPIMユーザー関連データが格納されます。
errArray	Integer []	Out	出力時に、ユーザー関連データの設定(BDSSストアに永続的に保持)の成功または失敗を示すエラー・コードの配列が格納されます。この配列、assocDataIdArrayおよびpimUserAssocDataArrayの間には位置関係があります。この配列のi番目の要素には、pimUserAssocDataArrayのi番目の要素の設定に関するエラー・コード(0 = OK、1 = ERROR)が保持されます。

戻り値

Integer

• SUCCESS/OKの場合は0すべてのAssociatedData要素がBDSSデータ・ストアに書き込まれた場合です。

• ERROR/NOTOKの場合は0以外。いずれかのAssociatedData要素の書込みに失敗した場合です。コール元ではerrArrayを検証して書込みが失敗した要素を判別し、コネクタではエラーの重大度を判断します。

例外

リカバリ不能なエラーが発生した場合は、RemoteExceptionがスローされます。

C.5 データ表現構造

この項では、BDSSとコネクタの間で渡されるデータの構造について説明します。

C.5.1 共通構造

共通構造にはKeyValuePair構造が含まれます。

C.5.1.1 KeyValuePair

KeyValuePairは、メタデータをキーと値の構造に保持するために使用する基本構造です。コネクタに対して定義されている他の多くのデータ構造で使用されます。表C-24に、KeyValuePair構造のメンバーを示します。

表C-24 KeyValuePair構造のメンバー

メンバー	データ型	説明
key	String	キーと値のペアのkey値を保持します。
value	String	キーと値のペアのvalue値を保持します。

C.5.2 BDSSエンジンのコネクタ・インタフェース関連の構造

コネクタ・インタフェース関連の構造は次のとおりです。

• DomainInfo

• ExtractRequest

• ExtractResponseData

• ExtractResponseMetaData

• HubContext

• PimRecordDescription

• AssociatedData

• AssocDataElement

• RecordMetaData

• UpsertRecord

• Enum ExtractResultCode

C.5.2.1 DomainInfo

DomainInfo構造には、同期化セッションでコネクタがユーザーに対して初期化を実行するために必要なドメイン情報が格納されます。この構造は、ハブでコネクタのInitializeUserSyncSession APIをコールした場合のみ使用されます。表C-25に、DomainInfo構造のメンバーを示します。

表C-25 DomainInfoデータ構造のメンバー

メンバー	データ型	説明
pimDomainTarget	String	PIMドメイン・ターゲットが格納されます。NULL以外である必要があります。空にはできます。 このメンバーの詳細は、第C.1.5項「PIMドメイン・ターゲット」を参照してください。
pimFilterCondition	String	ドメイン抽出に適用されて、抽出に含まないレコードを除外するPIMフィルタ条件が格納されます。このメンバーは、NULL以外である必要があります。空にはできます。
hubDomain	String	ハブ・ドメインを識別します。このメンバーは、NULL以外である必要があり、空にすることはできません。
pimDomainSyncState	String	ドメインのPIM同期状態が格納されます。このメンバーは、NULL以外である必要があります。このメンバーは空にできます。

C.5.2.2 ExtractRequest

BDSSでExtractDomains APIを介してユーザーの抽出を開始すると、ExtractRequest構造がコネクタに渡されます。表C-26に、ExtractRequest構造のメンバーを示します。

表C-26 ExtractRequestデータ構造のメンバー

メンバー	データ型	説明
hubUserId	String	ハブ・ユーザーIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	PIMユーザーIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
hubDomainArray	String []	ハブ・ドメインの配列。この配列は、NULL以外でサイズが1以上である必要があります。配列内の要素は、NULL以外である必要があり、空にすることはできません。

C.5.2.3 ExtractResponse

ExtractResponse構造は、コネクタでエンジン・コールバック・インタフェースのExtractDomainResultsコールバック・メソッドを介してレコード・データおよびステータス情報をエンジンに伝播するために使用します。表C-27に、ExtractResponse構造のメンバーを示します。

表C-27 ExtractResponseデータ構造のメンバー

メンバー	データ型	説明
extractResponseMetaData	extractResponseMetaData	抽出レスポンスに関するメタデータが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
extractResponseData	extractResponseData	抽出されたPIMレコードが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。

C.5.2.4 ExtractResponseData

ExtractResponseData構造には、PIMサーバーから抽出されたレコードが格納されます。表C-28に、ExtractResponseData構造のメンバーを示します。

表C-28 ExtractResponseDataデータ構造のメンバー

メンバー	データ型	説明
hasUpserts	Boolean	構造にアップサート・レコードがあるかどうかを示します。この配列には、有効なUpsertRecord構造があります。
upsertRecordArray	UpsertRecord []	UpsertRecord構造の配列。配列内の各要素は、前回の同期化セッション以降にPIMで更新または作成された各PIMレコードを表します。 この配列は、NULL以外である必要があり、空にすることはできません。変更されたレコードがない場合、配列は長さが1で、NULL以外のメンバーが含まれるNULL以外のUpsertRecordが1つ必要です。ただし、メンバーは空の文字列にできます。 hasUpsertsがfalseの場合、この配列は無視されます。
hasDeletes	Boolean	deleteRecordIdArrayに有効な文字列メンバーが存在するかどうかを示します。
deleteRecordIdArray	String []	文字列の配列で、配列の各要素には、前回の同期化セッション以降に削除されたPIMレコードのPIMレコードIDが格納されます。 NULL以外である必要があり、空にすることはできません。削除されたレコードがない場合、配列は長さが1で、NULL以外のPIMレコードID(空も可能)が1つ必要です。 hasDeletesがfalseの場合、この配列は無視されます。

C.5.2.5 ExtractResponseMetaData

ExtractResponseMetaData構造には、ドメイン抽出の指定のExtractResponseMetaDataに関するメタデータ情報が格納されます。表C-29に、ExtractResponseMetaData構造のメンバーを示します。

表C-29 ExtractResponseMetaDataデータ構造のメンバー

メンバー	データ型	説明
syncSessionId	String	同期化セッションIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
hubDomain	String	ハブ・ドメインが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
hubUserId	String	ハブ・ユーザーIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
resultCode	String	ExtractResultCode列挙値の1つが格納されます。
extractErrorDescription	String	抽出に失敗した理由が格納されます。このメンバーは、NULL以外である必要がありますが、空にはできます。resultCodeがエラー・コードの場合のみ移入されます。
pimDomain	String	PIMドメインが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
pimUserId	String	PIMユーザーIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
connectorName	String	コネクタ名が格納されます。
echoesSuppressed	String	ExtractResponseでエコーが削除されたかどうかを示します。
sequenceNumber	String	ExtractResponseの順序番号を示します。たとえば、コネクタで1番目のExtractResponseをハブに送信するとき、sequenceNumberは1です。同様に、2番目のExtractResponseを送信するとき、sequenceNumberは2のようになります。 sequenceNumberは、ドメイン、ユーザーおよび同期化セッションごとに1から始まります。Oracle Fusion Middleware 11gリリース1のBDSSでは、コネクタの「Extract Response Batch Size」構成は、1つのハブ・ドメインに対して1つのExtractResponseのみをハブに送信できる大きさにする必要があります。

C.5.2.6 HubContext

HubContext構造(表C-30を参照)は、ランタイム・ライブラリまたはエンジン・コールバック・インタフェースのコール時に、コールするBDSSインスタンスの情報をコネクタに提供します。

表C-30 HubContextデータ構造のメンバー

メンバー	データ型	説明
engineEndPointURL	String	コネクタでコールするBDSS Webサービス・コンポーネントをホストするサーバーのURLが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
syncSessionId	String	セッションIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
connectorRuntimeLibraryURL	String	コネクタでコネクタ・ランタイム・ライブラリをコールしてメタデータの読取りまたは書込みを行うときに使用するURLが格納されます。
connectorName	String	コネクタ名が格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。

C.5.2.7 PimRecordDescription

PimRecordDescription構造(表C-31)には、PIMレコード説明が格納されます。KeyFieldメタデータがドメインに対して構成されている場合、コネクタでは指定のドメインのアップサート・レコードすべてについてこの説明を作成する必要があります。

表C-31 PimRecordDescriptionデータ構造のメンバー

メンバー	データ型	説明
descriptionArray	KeyValuePair []	PIMレコード説明を構成するハブ・フィールド名とハブ・フィールド値が格納されたKeyValuePair構造の配列。配列は、NULL以外である必要があります。 ドメインに対してKeyFieldが構成されている場合、配列のサイズは構成済のKeyFieldの数と等しくし、hasDescriptionをtrueに設定する必要があります。配列内の各KeyValuePairは、NULL以外である必要があります。各キーは、NULL以外である必要があり、空にすることはできません。各値は、NULL以外である必要がありますが、空にはできます。 ドメインに対してKeyFieldが構成されていない場合、配列のサイズは1で、hasDescriptionをfalseに設定する必要があります。配列にはNULL以外のKeyValuePairが格納され、キーおよび値は両方ともNULL以外である必要がありますが、空にはできます。
hasDescription	Boolean	descriptionArrayに有効な要素が存在するかどうかを示すブール値。このフラグがfalseに設定されている場合、指定のdescriptionArrayは無視されます。

C.5.2.8 AssociatedData

コネクタでは、AssociatedData構造(表C-32)を使用して、データをPIMレコードまたはPIMユーザーのいずれかに関連付けることができます。

表C-32 AssociatedDataデータ構造のメンバー

メンバー	データ型	説明
assocDataId	String	関連データを一意に識別するコネクタ定義の識別子が格納されます。このメンバーは、NULL以外である必要があります。hasAssocDataがfalseの場合は、空にできます。hasAssocDataがtrueである場合、空にすることはできません。
hasAssocData	Boolean	assocDataArrayに有効な(空にすることができない)AssocDataElementメンバーが存在するかどうかを示すブール値。
assocDataArray	AssocDataElement []	関連データのグループ(1つまたは複数)を定義するAssocDataElement構造の配列。このメンバーは、NULL以外である必要があります。 このメンバーのサイズは1以上である必要があります。 hasAssocDataがfalseの場合、配列のサイズは1で、空のAssocDataElementが1つ格納される必要があります。

C.5.2.9 AssocDataElement

AssocDataElementデータ構造には、関連データのグループが格納されます。表C-33に、AssocDataElement構造のメンバーを示します。

表C-33 AssocDataElementデータ構造のメンバー

メンバー	データ型	説明
groupName	String	groupAssocDataArrayに格納される関連データをグループ化するための文字列識別子。このメンバーは、NULL以外である必要があります。hasAssocDataがfalseの場合、このメンバーは空にできます。このメンバーは、指定のAssocData.assocDataArray内で一意である必要があります。
hasAssocData	Boolean	groupAssocDataArrayに有効な(空にすることができない)KeyValuePairメンバーが存在するかどうかを示すブール値。
groupAssocDataArray	KeyValuePair []	グループ内の1つの関連データを表す、任意の大きさのKeyValuePair構造の配列。このメンバーは、NULL以外である必要があります。サイズは1以上である必要があります。 hasAssocDataがfalseの場合、配列のサイズは1で、キーおよび値には空の文字列が格納されます。受信者はこの配列を無視できます。 hasAssocDataがtrueである場合、各要素はNULL以外のキーおよび値を持つ必要があり、キーおよび値を空にすることはできません。

注意: 関連データがバイナリの場合、コネクタではデータをBase64にエンコードして、データベースに非BLOBとして保存します。この場合、関連データのチャンクおよびチャンク解除はコネクタで実行されます。

C.5.2.10 RecordMetaData

RecordMetaData構造には、PIMサーバーから抽出されたりPIMサーバーにプッシュされるPIMレコードに関するメタデータが格納されます。表C-34に、RecordMetaData構造のメンバーを示します。

表C-34 RecordMetaDataデータ構造のメンバー

メンバー	データ型	説明
recordId	String	PIMレコードIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
versionId	String	PIMレコード・バージョンIDが格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。
recordError	Boolean	レコード処理に失敗したかどうかを示すブール値。この値がtrueに設定されている場合は、recordIdおよびrecordErrorDescriptionの両方が提供される必要があります。
recordErrorDescription	String	UpsertRecordの処理中に発生したエラーの理由を説明します。このメンバーは、NULL以外である必要がありますが、空の文字列にはできます。recordErrorがtrueに設定されている場合は、移入される必要があります。
assocData	AssociatedData	AssociatedDataが格納されます。
pimRecordDescription	PimRecordDescription	PIMレコード説明が格納されます。ドメインに対してKeyFieldデータが構成されていない場合は、NULLにできます。ドメインに対してKeyFieldデータが構成されている場合、このメンバーはNULLである必要があります。

C.5.2.11 UpsertRecord

UpsertRecord構造は、PIMサーバーから抽出されたりPIMサーバーにプッシュされるハブ・レコードの構造を定義します。削除されたハブ・レコードは、この構造に表示されません。表C-35に、UpsertRecord構造のメンバーを示します。

表C-35 UpsertRecordデータ構造のメンバー

メンバー	データ型	説明
pimRecordMetadata	RecordMetaData	レコードに関連するメタデータが格納されます。このメンバーは、NULL以外である必要があります。
hubRecordData	String	ハブ・レコードのXML表現が格納されます。このメンバーは、NULL以外である必要があり、空にすることはできません。

C.5.2.12 Enum ExtractResultCode

抽出リクエストの結果コードを定義する列挙型。例C-1に、Enum定義を示します。

例C-1 Enum定義

Enum ExtractResultCode
{
FULL_EXTRACT_COMPLETED_OK,
FULL_EXTRACT_COMPLETED_NOTOK,
PARTIAL_EXTRACT_COMPLETED_OK,
PARTIAL_EXTRACT_COMPLETED_NOTOK
};

C.5.3 構成関連構造

次の構成構造があります。

• ConfigurationSection

• ConfigurationProfile

C.5.3.1 ConfigurationSection

ConfigurationSection構造は、構成ファイルまたは.ini構成ファイルと概念的に同等なプロファイルのセクションを表します。つまり、プロファイルには一意の名前が付いたセクションのコレクションが含まれ、各セクションにはパラメータと値のコレクションが含まれます。表C-36に、ConfigurationSection構造のメンバーを示します。

表C-36 ConfigurationSection構成構造のメンバー

メンバー	データ型	説明
sectionName	String	プロファイルに含まれるセクション名を識別します。
paramNameValueArray	KeyValuePair []	プロファイルのセクションに含まれる構成パラメータと値が格納されます。

C.5.3.2 ConfigurationProfile

ConfigurationProfile構造はプロファイルを表します。表C-37に、ConfigurationProfile構造のメンバーを示します。

表C-37 ConfigurationProfile構成構造のメンバー

メンバー	データ型	説明
profileName	String	構成プロファイルの名前を識別します。
configSectionArray	ConfigurationSection []	プロファイルのセクションに関する情報を含むConfigurationSection構造の配列が格納されます。

C.6 コネクタの作成に関するベスト・プラクティス

開発者は、コネクタを少なくとも3つのパッケージ(ハブ・トランスポート・パッケージ、PIMトランスポート・パッケージ、変換パッケージ)に分割する必要があります。

• ハブ・トランスポート・パッケージ

  ハブ・トランスポート・パッケージには、ハブと直接通信するコンポーネントが含まれます。これらのコンポーネントでは、ハブとの通信に関連するすべての詳細を処理しますが、PIMストアやサーバーに対して直接データ交換操作を実行することはありません。かわりに、PIMトランスポート・パッケージと通信して、PIMストアとデータを交換します。このコンポーネントは汎用で、再利用して1つ以上のPIMトランスポート・パッケージと通信できます。

• PIMトランスポート・パッケージ

  PIMトランスポート・パッケージには、PIMサーバーおよびPIMストアと直接通信するコンポーネントが含まれます。これらのコンポーネントではハブと直接通信しませんが、かわりに、PIM関連のすべての詳細を処理します。これらは、ハブとPIMトランスポート・パッケージの間の通信を容易にするPIMトランスポートAPIです。

• 変換パッケージ

  変換パッケージには、レコード・データをハブ書式とPIM書式の間で変換するコンポーネントが含まれます。

詳細は、第2.2項「コネクタの概要」を参照してください。

C.7 Exchange 2007コネクタAPI

この項では、Exchange 2007コネクタの動作を説明するために、次の前提を使用します。

• cjonesおよびtsmytheというユーザーが存在するBPELシステム。

• [e-mail]および[e-mail]というユーザーが存在するExchangeシステム。

• cjonesユーザーを[e-mail]ユーザーにマップするハブ・ユーザー。

• BPELサーバーおよびExchange組織外に存在し、電子メール・アドレスが[e-mail]のユーザー。

C.8 カレンダの同期化に対する汎用コンポーネントのサポート

ハブでのカレンダ・サポートの目的と同様に、汎用コネクタ・コンポーネントの目的は、他のドメインの同期化と同じ方法でカレンダの同期化をサポートすることです。つまり、特定のドメインのレコード・データは汎用コンポーネントに関連付けられません。さらに、汎用コンポーネントでは、特定のドメイン固有のロジックを実装しません。

削除を検出できないPIMトランスポートのために、ハブ・トランスポートでは削除検出機能を提供します。PIMトランスポート・コンポーネントで削除をネイティブで検出できない場合は、削除するレコードIDのリストが決定した後にハブ・トランスポートで新しいPIMトランスポート・インタフェース・メソッドを起動すると、PIMトランスポートでは、削除したレコードを削除として抽出レスポンスに表示するか、またはファンニング済インスタンスであるカレンダ・レコードに対する例外として表示するかを決定できます。前者の場合、レコードIDは削除リストに残ります。後者の場合、レコードIDは削除リストから削除され、コネクタでは、EXDATEリストにある削除発生の開始日がマスターVEVENTに含まれるように該当するアップサート・レコードを更新する必要があります。ハブ・トランスポートではこの処理をカレンダ・ドメインに対して実行できると同時に、すべてのドメインに対しても実行できるため、PIMトランスポートでは抽出レスポンスを変更して最終的にハブに送信できます。PIMExtractResponse、FinalizeExtractResponse (PIMExtractResponse response)などのメソッドは適切なシグネチャです。

カレンダの同期化をテストするには、反映同期化を使用します。PIMトランスポート・インタフェースでは、コネクタ・タイプを返す新しいメソッドが必要です。ハブ・トランスポートでは、BDSSから構成プロファイルを読み取る前の時点でこのメソッドをコールし、コネクタ名に対応するプロファイル名ではなく、新しいPIMトランスポート・メソッドからの戻り値に対応する名前のプロファイルをロードします。

C.8.1 カレンダ・サポート・メソッド

この項では、ランタイム・ライブラリ(RTL)のメソッドについて説明します。

C.8.1.1 ハブ規定

ハブ規定では、次のメソッドおよび機能を使用します。

• GetAssocDataIdOfAssociatedData

• 参加者サポート

• AttendeeMetadata

C.8.1.1.1 GetAssocDataIdOfAssociatedData

このメソッドはランタイム・ライブラリに含まれるメソッドの1つで、コネクタではこのメソッドを使用して関連データ値から関連データIDを取得できます。このメソッドはgetUserAssociatedDataおよびgetRecordAssociatedDataに似ており、コネクタでは関連データ値のコレクションを提供して、対応するassocdata IDのコレクションとともに、リクエストした各assocDataIDのステータス・コード(成功、失敗、またはデータベースに存在しない)を取得します。

たとえば、関連データのキーと値のペアのコレクション{Key1,Value1}、{Key2,Value2}、{Key3,Value3}が含まれるMyGroupのグループ名がMyCalendarAssocDataZに保持され、そのassocDataIdが保持されるassocDataをコネクタでBDSSに格納した場合、後でコネクタで値MyCalendarAssocDataZを取得するときは、MyGroupおよび{Key1,Value1}、{Key2,Value2}、{Key3,Value3}の一部または全部を指定してこのAPIをコールできます。APIでは、指定したグループ名およびキーと値のペアが含まれる行について関連データ表を問い合せて、IDを取得します。APIでは、関連データ値が複数の行にわたってセグメント化されている場合があることを考慮する必要があります。

C.8.1.1.2 参加者サポート

ハブでは、カレンダ・レコードを作成または更新するコネクタ・メソッドをコールするときに、ユーザー・マップ・メタデータを使用して、作成/更新リクエストに付随するレコード・メタデータの一部としてターゲット・システムのPIMユーザーIDを提供することにより、参加者の解決をサポートしています。ハブで作成/更新操作中にこのメタデータを提供するには、ソース・コネクタで、カレンダ・レコードのソース・システムの参加者を抽出レスポンスに提供する必要があります。BDSSコネクタのRecordMetadataには、参加者メタデータを保持するデータ・メンバーが含まれます。

たとえば、ハブでBPELサーバーからcjonesのカレンダを抽出するとき、BPELタスク・コネクタでは、アップサート・レコードに関連付けられたレコード・メタデータにcjonesを指定します。次にハブでは、そのレコードが[e-mail]ユーザーのExchangeカレンダに作成される必要があると判断します。ハブでは、ユーザー・マップでcjonesを検索し、cjonesがExchangeの[e-mail]にマップされていることを検出します。ユーザーがマップされているため、ハブでは、アップサート・レコードに関連付けられたレコード・メタデータに[e-mail](cjonesではなく)を提供し、これをExchange 2007コネクタをコールしてレコードを作成するときに提供します。

これをサポートするには、BDSSコネクタのRecordMetadataを更新して、タイプAttendeeMetadataのデータ・メンバーが参加者メタデータを保持する必要があります。

C.8.1.1.3 AttendeeMetadata

AttendeeMetadaは、コネクタ・インタフェース用のBDSS WSDLのWSDL構成です。このクラスは、ハブ・カレンダ・レコードに関連付けられた参加者情報を管理します。

次のことが前提になります。

• 繰返しのカレンダ会議には、マスター・レコードとは異なる参加者を含む例外や他の例外を含めることができます。

• カレンダを作成または更新するターゲット・コネクタでは、ICAL内に含まれる参加者情報を使用できません(ICALの参加者情報はソース・コネクタで定義されているため)。

このクラスを使用すると、ターゲット・コネクタでは各会議の発生に関連付けられた参加者を判別できます。これはコレクションのマップ構成を意味し、マップは会議発生の開始日をキーとして取得し、指定のキーのコレクションにはその会議に関連付けられた参加者が含まれます。マップに含まれるエントリが1つの場合は、例外がないカレンダ・レコードであることを意味します。マップに複数のエントリが含まれる場合は、例外があるカレンダ・レコードであることを意味し、その例外にはマスター・レコードとは異なる参加者が含まれます。

C.8.1.2 コネクタ規定

次の各項では、BDSSを使用してカレンダ・レコードを同期化する際にコネクタ実装で準拠する必要がある規定上の義務事項を定義します。コネクタは、コネクタ・インタフェースのドキュメントに定義されている規定上の義務事項にも準拠する必要があります。

C.8.1.2.1 フェデレーテッドと非フェデレーテッドの相違

コネクタがデータを交換するカレンダ・システムがフェデレーテッドPIMの場合、コネクタではハブからフェデレーション・モデルを抽出する必要があります。たとえば、ある1つのカレンダ会議がSiebelモデルに類似しており、カレンダ・レコードをリレーショナル・データベースに格納すると、各レコードには一意の行IDが含まれ、カレンダ・レコードからユーザー表に外部キーを追加することによってカレンダ・レコードを表示できます。コネクタで指定のカレンダ・レコードを抽出すると、各参加者が同期化されるときに、参加者ごとにカレンダ・レコードの行IDと参加者の行IDを連結したPIMレコードIDを作成できます。後続の同期化セッションで、BDSSがコネクタに対して更新操作または削除操作を実行するように指示すると、ハブでは作成されたIDを提供し、コネクタではその2つの行IDを解析して適切な操作を実行できます。

フェデレーテッド・システムのコネクタでは、指定のBDSSリクエストを別の操作に変換する必要がある場合があります。たとえば、システムのカレンダ・モデルでは、参加者が変更できるのは、その参加者が開催する会議のみとします。BDSSはコネクタに対して更新操作を実行するように指示したが、コネクタでは同期化するユーザーの行IDが開催者ではなく参加者であると判断した場合、コネクタではBDSSコールに対して操作を実行せず、場合によってはメッセージを記録することもできます。つまり、開催者が同期化されると、変更(ある場合)が同期化されるため、コネクタが開催者を同期化の対象と判断した場合は操作なしが適切です。(ソースが非フェデレーテッドPIMの場合、開催者は会議のコピーを変更できません。)コネクタが開催者を同期化の対象と判断した場合は(ユーザーが組織に定義されていない場合、またはユーザーが同期化用のBDSSユーザー・マップに追加されていない場合のいずれか)、操作なしは適切ではありません。同様に、BDSSがコネクタに対してレコードを削除するように指示し、コネクタでは参加者がそのレコードをすでに削除したと判断した場合、コネクタはレコード全体を削除するのではなく、その参加者をカレンダ・レコードから削除します(つまり、カレンダ・レコード全体を削除するのではなく、参加者ユーザーを識別する外部キーをカレンダ・レコードから削除します)。コネクタが開催者から削除を取得した場合は、カレンダ・レコード自体を削除できます。ユーザーを同期化する順序は保証されていないため、開催者の削除が同期化された後にコネクタで参加者の削除を受信した場合、コネクタでは以降の削除に対して操作を実行しないことがあります。

これは、フェデレーションの抽出方法に関するコネクタ実装詳細ですが、実装では次の動作を保証する必要があります。

• コネクタでは、各参加者ユーザーを同期化するとき、会議から削除された各参加者の削除を送信する必要があります。たとえば、レコードAに開催者のユーザーAと参加者のユーザーBが含まれ、ユーザーCは削除されていた場合は、ユーザーAを同期化すると抽出レスポンスに削除が含まれ、ユーザーBを同期化すると抽出レスポンスに削除が含まれます。

• 参加者の削除とは異なり、カレンダ・レコードが削除されると、開催者および各参加者の抽出には削除が含まれます。

• レコードが会議(参加者あり)から予定(参加者なし)に変更された場合、コネクタでは、カレンダ・レコードに関連付けられた残りのユーザーのアップサート(PIMのカレンダ・モデルに応じて、開催者である場合とそうでない場合があります)、および残りのユーザーの削除を提供する必要があります。

• コネクタでは、最初の抽出時、または進行中の抽出でレコードが更新された場合、カレンダ・レコードに関連付けられた各ユーザーのアップサート・レコードを提供する必要があります。たとえば、レコードAに開催者のユーザーAと参加者のユーザーBが含まれている場合は、ユーザーAを最初に同期化するとき、およびユーザーBを最初に同期化するときに、レコードAがハブへの抽出レスポンスに提供される必要があります。さらに、レコードAがユーザーによって更新された場合は、ユーザーAを同期化するとき、およびユーザーBを同期化するときに、レコードAが提供される必要があります。レコードAへの更新が新規参加者ユーザーCの追加であった場合は、ユーザーA、ユーザーBおよびユーザーCの抽出レスポンスにレコードAが提供される必要があります。

• コネクタでは、特定のユーザーがBDSSを介して行った更新のエコーは伝播しませんが、レコードに関連付けられた他のユーザーの更新は伝播する必要があります。たとえば、フェデレーテッド・システム内のレコードAには参加者としてユーザーA、ユーザーBおよびユーザーCが含まれ、このレコードはセッション1で同期化されるとします。次に、セッション2では、コネクタはdeleteRecordコールを受信してユーザーCを削除します。コネクタでは、カレンダ・レコードを削除するのではなく、カレンダ・レコードからユーザーCを削除します。セッション3では、アップサートはユーザーAおよびユーザーBの抽出レスポンスに表示され、新しい参加者リスト(ユーザーCは参加者に含まれません)が示されます。ユーザーCを同期化するとき、この削除はエコーの削除とみなされるため、ハブに送信される抽出レスポンスにレコードの削除は含まれません。このような方法で、ユーザーCにマップされた参加者が他のシステムからレコードを削除すると、BDSSでは、他のシステムでユーザーAおよびユーザーBにマップされた参加者がレコードを更新して、ユーザーCが会議の参加者でなくなったことを示します。

C.8.1.2.2 参加者の解決

ハブでは参加者の解決がサポートされていますが、コネクタ実装では次のシナリオを考慮する必要があります。

• ユースケース1: ユーザーがBDSSで同期化対象として構成されていないケースです。たとえば、BPELサーバーで作成されたカレンダ・レコードにtsmytheという名前の参加者が含まれ、tsmytheは有効なBPELサーバー・アカウントとExchangeアカウントを持っていますが、tsmytheは自分のBPELデータをBDSSを介して同期化することを希望していないとします。レコードは、BPELタスク・コネクタによって抽出されます。cjonesを同期化するときは、参加者としてcjonesおよびtsmytheをレコード・メタデータに指定します。ハブでは、Exchange 2007コネクタをコールしてレコードを作成するとき、Exchange 2007コネクタに[e-mail]を提供できますが、レコード・メタデータのtsmytheに対するExchangeユーザーIDは提供できません。

• ユースケース2: ユーザーは組織内の人員として認識されていないケースです。たとえば、Comany XのExchangeユーザー[e-mail]が会議を開催して[e-mail]を招待した場合、この招待者が会議への参加を承諾するとExchangeフォルダにカレンダ・アイテムが作成されます。さらに、[e-mail]はExchangeシステムおよびBPELシステムに定義されていないとします。BDSSで、cjonesを[e-mail]にマップするハブ・ユーザーを同期化すると、Exchange 2007コネクタでは[e-mail]をExchange組織内のユーザーとして解決できません。[e-mail]がレコード・メタデータに指定されます。次に、ハブでレコードをBPELサーバーにプッシュすると、BPELタスク・コネクタでも[e-mail]をBPELユーザーに解決できません。

• ユースケース3: 受信コネクタがターゲット・システムでレコードを作成または更新するときに、レコード・メタデータに格納された参加者情報が不十分なケースです。この場合、コネクタでは提供された情報を使用してユーザーの解決を試みます。たとえば、Exchangeコネクタでは、カレンダ・レコードを作成するときに、参加者の名、姓およびユーザー電子メール・アドレスを指定する必要があります。コネクタでレコード・メタデータに格納された電子メール・アドレスをActive Directoryへの問合せに指定すると、電子メール・アドレスが一致するユーザーの名と姓が返されます。

コネクタでは、特定の参加者をコネクタのシステム内のユーザーに解決できない場合、次の抽出時に、未解決の参加者をハブに戻す必要があります。これによって、レコードの更新が別のコネクタにプッシュされても、参加者が会議から削除されません。

指定のカレンダ・レコードの抽出時に、カレンダ・レコードに関連付けられた未解決の参加者をコネクタで解決するには、次の方法があります。

• BDSSデータ・モデルを拡張して、参加者メタデータを保持する表を作成し、コネクタがメタデータを設定または取得できる新規のランタイム・ライブラリAPIを定義します。

• BDSSのレコード・レベルまたはユーザー・レベルの関連データ機能を使用します。レコード・レベルの関連データを使用すると、BDSSストア内で未解決の参加者が多数重複する可能性があります。このため、ユーザー・レベルの関連データを使用することをお薦めします。ユーザー・レベルの関連データを使用する場合もBDSSストア内で未解決の参加者が重複する可能性がありますが、レコード・レベルの関連データを使用する場合と比較すると重複は少なくなります。重複を回避するには、未解決の参加者のみを保持するための特別なBDSS PIMユーザーをコネクタで作成します。

• 解決不能な参加者を作成/更新時にPIMレコード自体に書き込むと、次回にレコードが抽出されるときに、コネクタで未解決の参加者を取得できます。コネクタがデータを交換するシステムで参加者の値が不明確でも許容される場合、コネクタでは解決不能な参加者を単純に参加者フィールドに書き込むことができます。ただし、システムでは参加者の値を明確にする必要があるため、コネクタでは、エンド・ユーザーはデフォルトで表示できないカスタム・フィールドに解決不能な参加者を書き込む必要があります。

注意: 指定のユーザーは同じコネクタ・タイプの異なるコネクタ・インスタンスで同期化できるため、未解決の参加者をメモリー内キャッシュに保持することは有効な方法ではありません。たとえば、Exchange 2007コネクタにInstance 1とInstance 2という2つのインスタンスがあり、異なるサーバーにデプロイされているとします。同期化セッション1で、[e-mail]がInstance 1を介して同期化されます。[e-mail]は解決できないため、コネクタではExchangeレコードの作成時にこの参加者を含めないことを決定します。会議が更新され、その後、BDSSで別の同期化セッションが実行されると、[e-mail]はInstance 2を介して同期化されます。このセッションでは、レコードが抽出されるときにInstance 2で[e-mail]を簡単にリストアする方法はありません(コネクタ・インスタンスが相互に通信しない場合)。

解決不能な参加者をシステム・レコードに保持できないコネクタでは、BDSSソリューション(レコードまたはユーザー関連データ)を使用するか、または独自のメソッドを実行する必要があります。

会議の参加者が参加者のグループまたは配信リストで識別される場合、コネクタでは配信リストを参加者としてICALに提供できません。かわりに、コネクタでは、グループの各メンバーをICALに提供する必要があります。あるシステムの参加者のグループが別のシステムでも定義されている場合があり、グループ名または配信リスト名がシステム間で一致している場合はグループのメンバーシップが同じである保証がないため、この配信リストを展開する必要があります。また、コネクタでは、すべての埋込みグループまたは配信リストのメンバーを展開し、ICALに重複が含まれないようにする必要があります。次に例を示します。

• 配信リストAのメンバーはUser1およびUser2です。

• 配信リストBのメンバーは、配信リストA、User1、User2およびUser3です。

• カレンダ・レコードにリストされる参加者は次のとおりです。

  • 配信リストA

  • 配信リストB

  • User3

グループのメンバーシップによってカレンダ・レコードに重複が含まれますが、ICALに含まれるのはUser 1、User 2およびUser 3のみです。

C.8.1.2.3 繰返しパターン

コネクタでは、すべてのICAL繰返しパターンをサポートするように試みる必要があります。

抽出時に、コネクタでは、繰返しパターンをネイティブ定義から同等のICAL定義に変換する必要があります。同様に、コネクタでは、カレンダ・レコードを作成または更新するときに、ICAL繰返しパターンを同等のネイティブ・パターンに変換する必要があります。

ただし、コネクタで指定のICAL繰返しパターンをネイティブでサポートできない場合があります。このような場合でも、コネクタでは、ハブからの作成/更新リクエストを実行しようとします。これを解決する主要な方法はファンニングです。この形式のファンニングとは、元のパターンをコピーして複数のカレンダ・レコードを作成するプロセスです(非フェデレーテッド・システムと混同しないでください)。

コネクタでは常に、1つのレコードを繰返しなしの複数のカレンダ・レコードにファンニングし、各インスタンスには繰返しパターンで定義される日付に発生するように開始日があります。コネクタでは、この操作をハブから抽出する必要があります。

注意: Oracle Fusion Middleware 11gリリース1のBDSSでは、EXRULEはサポートされていません。

C.8.1.3 ファンニング

次の各項では、ファンニングに関連するコネクタ規定について説明します。

C.8.1.3.1 抽出

コネクタでは、システムからカレンダ・レコードを抽出するとき、ICAL RFCに準拠した、レコードのICAL表現を作成する必要があります。

すでに繰返しパターンをファンニングしたコネクタでは、次回にレコードが同期化されるときに、すべてのファンニング済インスタンスを、元の繰返しパターンを含む単一のICAL表現に結合する必要があります。ファンニング済レコードから繰返しパターンを再作成するとき、コネクタ実装では次の処理を実行します。

1. PIM内のファンニング済インスタンスへの変更がICALの例外に変換され、「Calendar Hub Domain Schema」セクションにリストされた要件ごとに個別のVEVENTとして表されていることを認識します。

2. PIM内のファンニング済インスタンスの削除が、マスターVEVENTのEXDATEに変換されます。

3. ファンニング済インスタンスが単一のICALメッセージに結合され、ExtractResponseはレスポンスにファンニング済インスタンスを含みません。さらに、コネクタでは適切なPIMレコード・バージョンを提供する必要があります。

4. 繰返しパターンが適用されるクライアントを介してPIMユーザーがファンニング済インスタンスを更新した場合、コネクタでは、ファンニング済レコード(ただし、この時点では繰返しレコード)を個別のレコードとして同期化し、抽出の実行時に元のレコードでEXDATEを指定する必要があります。また、抽出したレコードが別のシステムの対応するレコードと競合する場合は、競合を解消するユースケースを考慮する必要があります。この場合、コネクタでは繰返しの予定を削除し、優先するレコード・データに置換します。

5. 各ファンニング済インスタンスに関するメタデータは保持されるため、抽出が実行されるとき、コネクタでは次のことが可能です。

6. • ファンニング済インスタンスのセットを判別します。

   • 各ファンニング済インスタンスをICALに表示する方法(つまり、マスターVEVENT、例外VEVENT)を決定します。これは、コネクタにおいて、複数の同期化セッション間で各ファンニング済インスタンスの状態を追跡する必要があることを意味します。たとえば、セッション1で同期化された3つのファンニング済レコード(レコードA、レコードBおよびレコードC)があるとします。これらのレコードはすべて、繰返しパターンおよび同じ会議IDを持つ単一のICALに結合される必要があります。レコードAに対する更新、およびレコードCの削除がセッション2で同期化されると、ステップ1でレコードAがICALに例外VEVENTとして表示され、ステップ2でレコードCがマスターVEVENTにEXDATEとして表示されます。セッション2で、レコードBは抽出レスポンスに含まれ、レコードAとレコードCは含まれない場合、コネクタでは、レコードBを例外VEVENTとして追加し、レコードAとレコードCは抽出レスポンスに含まれていなくても、レコードAは例外VEVENTとして、レコードCはマスターVEVENTのEXDATEとして提供する必要があります。

     前述したように、コネクタでは、レコードおよび各ファンニング済インスタンスに関するメタデータを格納して、繰返しパターンの再作成に役立てる必要があります。コネクタでは、メタデータを、BDSSデータ・ストアに関連データとして格納することも、PIMレコードの非表示フィールドに格納することも可能です。コネクタに格納される内容はコネクタ実装詳細で、すべてのコネクタで必ずしも同じではありません。

     コネクタでレコード関連データがBDSSデータ・ストアに格納され、ランタイム・ライブラリがエラーを返したとき、リクエストされたすべての関連データについて各ステータス・コードがデータがデータベースになかったために障害が発生したことを示しており、提供された同期状態が空またはNULLの場合、ユーザーは再度初期化されます(ランタイム・ライブラリがエラーを返し、成功を示すステータス・コードと、データベースにデータがなかったために失敗したことを示すステータス・コードがある場合、このエラーはリカバリ不能です)。コネクタでは、このユースケースを考慮して、(会議ID別にレコードを照合して)最初の抽出を実行するときにファンニング済インスタンスを結合します。

C.8.1.3.2 CreateRecord

ハブでCreateRecordがコールされると、コネクタでは受信したICALを検証して、レコードをファンニングする必要があるかどうかを判断します。最初に、すべてのVEVENT間で各RRULE、RDATEおよびEXDATEを検証して、最終的な繰返しパターンを決定します。最終的な繰返しパターンをネイティブで表現できない場合、コネクタではレコードをファンニングして、後続のセッションでパターンをリストアするために必要なすべてのメタデータを格納します。

ファンニング済インスタンスの作成時に障害は発生した場合、コネクタではファンニング済インスタンスの作成を停止し、ファンニングされるレコードに関連して正常に作成されたファンニング済インスタンスをすべて削除し、エラーをハブに返します。コネクタでメッセージを記録することも可能です(同じセッション内で作成および更新操作が発生している場合は、後続のセッションに影響しません)。

C.8.1.3.3 UpdateRecord

ハブでUpdateRecordがコールされると、コネクタでは、更新対象のレコードがすでにファンニングされているかどうかを判別する必要があります。レコードがすでにファンニングされている場合は、受信したICALをファンニング済インスタンスに適用し、場合によっては受信したパターンを再度ファンニングする必要があります(新しいパターンがレコードに適用された場合は、ネイティブで表現できません)。ファンニングが再実行された場合、コネクタでは、最初に古いファンニング済インスタンスを削除してから、新しいインスタンスを作成する必要がある場合があります。また、コネクタでは、後続の抽出でこれらの削除を除外する必要があります。

コネクタですでにファンニングされたレコードに対する更新を取得し、開始日が元のファンニングのファンニング制限外である例外VEVENTがICALにある場合、コネクタでは例外をPIMに作成する必要があります。

コネクタでは、表C-38に示すファンニング関連のユースケースを考慮する必要があります。コネクタで各ユースケースを処理する方法がコネクタ実装詳細です。

表C-38 ファンニングのユースケース

更新するパターンはサポート対象か	レコードはファンニング済か	コメント
True	True	同期化セッション間でサポート対象外のパターンがサポート対象のパターンに変更されたことを示します。
True	False	通常の更新です。ファンニングはありません。
False	True	同期化セッション間でサポートされていないパターンを示します。

既存のファンニング済インスタンスの更新時に障害が発生した場合(つまり、削除や再ファンニングではなく、ファンニング済インスタンスを実際に更新した場合)、コネクタでは更新を停止し、更新されるレコードに関連して正常に更新されたファンニング済インスタンスをリストアして、エラーをハブに返す必要があります。コネクタでメッセージを記録することも可能です。このような更新-更新-リストア操作が同じセッションで発生すると、後続のセッションに影響を与えます。

C.8.1.3.4 DeleteRecord

ハブでDeleteRecordがコールされると、コネクタでは、削除対象のレコードがすでにファンニングされているかどうかを判別する必要があります。その場合、コネクタではすべてのファンニング済インスタンスを削除する必要があります。

既存のファンニング済インスタンスの削除時に、すべて削除される前に障害が発生した場合、同期状態は保存されないため(コネクタが削除を停止してエラーをハブに返す場合)、コネクタでは正常に削除されたファンニング済インスタンスをリストアする必要はなく、後続のセッションで削除が再試行されます。

C.8.2 Exchange 2007 PIMトランスポートのカレンダ・サポート

PIMトランスポート・コンポーネントでは、次のことをサポートします。

• 開催者および参加者

• レコード関連データおよびExchangeメタデータ

• サポート対象の繰返しパターン

• タイムゾーン

• 日時値

• PIMレコードID

• ExtractDomain

• CreatePIMRecord

• UpdatePIMRecord

• DeletePIMRecord

C.8.2.1 開催者および参加者

Exchangeでは、不完全な名前を参加者としてリストできます。したがって、Exchange 2007コネクタでは、メタデータから取得した参加者のリストをExchangeレコードの「To」、「CC」および「BCC」フィールドに直接書き込みます。

BDSSの必須参加者はExchangeの「To」フィールド、任意参加者はExchangeの「CC」フィールド、リソースはExchangeの「BCC」フィールドに書き込まれます。

PIMトランスポートでは、指定のユーザーの会議に対する更新リクエストを受信して、そのユーザーが参加者または開催者として表示されていない場合に、エラーをスローします。

C.8.2.1.1 参加者の解決

PIMトランスポートでは、Exchange WebサービスのResolveNamesおよびExpandDLを使用して、参加者および配信リスト・メンバーシップを解決します。

C.8.2.1.2 参加者のキャッシュ

同期化するユーザー用に、ユーザーおよび同期化セッションごとに参加者のキャッシュが作成されます。カレンダ・ドメインの抽出が開始されるとキャッシュが作成され、抽出レスポンスの各カレンダ・レコードが処理されると参加者メタデータがキャッシュに移入されます。指定のカレンダ・レコードの参加者が処理されるとき、コネクタではキャッシュを調べて一致を検索します。一致が存在する場合は、キャッシュ内の情報を使用してレコードのICALが作成されます。一致が存在しない場合は、参加者メタデータがキャッシュに追加され、次にICALに追加されます。

C.8.2.2 レコード関連データおよびExchangeメタデータ

表C-39に示すメタデータは、PIMトランスポートでカレンダの同期化を有効にするために、レコード・レベルの関連データとしてBDSSデータ・ストアに格納されるか、またはExchangeストアの非表示フィールドに格納されます。

表C-39 PIMトランスポートで格納されるPIMメタデータ

名前	値	コメント
BDSSFabricatedId	一意のID	Exchangeカレンダ・レコードを表すために使用されます。コネクタでレコードがファンニングされている場合は、このIDを使用してファンニング済レコードのコレクションを表します。 BDSS - PIMレコードIDとして格納されます。 Exchange - Exchangeの各ファンニング済インスタンスでは、このIDが非表示フィールドに書き込まれます。

C.8.2.3 サポート対象の繰返しパターン

表C-40に、サポート対象の繰返しパターンおよび各パターンの例を示します。各サンプルでは、パターンのICAL以外の記述に続いて、パターンを表すICAL RRULE値を示します。この表には、可能なすべてのパターンがリストされているわけではありません。

表C-40 サポート対象の繰返しパターン

Exchangeパターン	ICAL RRuleプロパティ値の例
Daily	毎日、2日ごと、無期限 FREQ=DAILY,INTERVAL=2,WKST=SU 毎日、毎日、10回 FREQ=DAILY;COUNT=10;INTERVAL=1;WKST=SU 毎日、5日ごと、7月末まで FREQ=DAILY;UNTIL=20090731T173000Z;INTERVAL=5;WKST=SU 毎日、すべての平日、無期限 FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR;WKST=SU 毎日、すべての平日、10回 FREQ=DAILY;COUNT=10;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR;WKST=SU 毎日、すべての平日、7月末まで FREQ=DAILY;UNTIL=20090731T1730000Z;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR;WKST=SU
Weekly	隔週の月曜、水曜および金曜、無期限 FREQ=WEEKLY;INTERVAL=2;BYDAY=MO, WE, FR;WKST=SU 隔週の月曜、水曜および金曜、10回 FREQ=WEEKLY;COUNT=10;INTERVAL=1;BYDAY=MO, WE, FR;WKST=SU 3週間ごとの月曜、水曜および金曜、7月末まで FREQ=WEEKLY;UNTIL=20090731T1730000Z;INTERVAL=3;BYDAY=MO, WE, FR;WKST=SU
Absolute Monthly	隔月の15日、無期限 FREQ=MONTHLY;INTERVAL=2;BYMONTHDAY=15;WKST=SU
Relative Monthly	毎月最後の平日 FREQ=MONTHLY;INTERVAL=3;BYDAY=MO, TU, WE, TH, FR;BYSETPOS=-1;WKST=SU 毎月最後の週末 FREQ=MONTHLY;INTERVAL=1;BYDAY=SU, SA;BYSETPOS=-1;WKST=SU 毎月1日、10回 FREQ=MONTHLY;COUNT=10;INTERVAL=1;BYDAY=SU, MO, TU, WE, TH, FR, SA; BYSETPOS=; WKST=SU 隔月の第4木曜、2010年10月末まで FREQ=MONTHLY;UNTIL=20101028T183000Z;INTERVAL=2;BYDAY=4 TH;WKST=SU 毎月第3木曜 FREQ=MONTHLY;COUNT=10;INTERVAL=1;BYDAY=3 TH;WKST=SU 3か月ごとの第4月曜 FREQ=MONTHLY;INTERVAL=3;BYDAY=4 MO;WKST=SU
Absolute Yearly	毎年7月4日 YEARLY;INTERVAL=1;BYMONTHDAY=4;BYMONTH=7;WKST=SU
Relative Yearly	毎年7月2日、10回 RRULE:FREQ=YEARLY;COUNT=10;INTERVAL=1;BYDAY=SU, MO, TU, WE, TH, FR, SA; BYMONTH=7;BYSETPOS=2;WKST=SU 7月最後の週末、2018年まで FREQ=YEARLY;UNTIL=20180729T190000Z;INTERVAL=1;BYDAY=SU, SA;BYMONTH=7; BYSETPOS=-1;WKST=SU

C.8.2.4 タイムゾーン

ExchangeのCalendarItemTypeには、タイムゾーン関連のプロパティとしてTimeZoneおよびMeetingTimeZoneがあります。TimeZoneプロパティは読取り専用で、カレンダ・レコードのタイムゾーンのテスト専用の記述です。MeetingTimeZoneプロパティは、新規カレンダまたは更新されたカレンダ・アイテムに設定されるプロパティです。

PIMトランスポートでは、カレンダ・レコードの作成または更新時にICAL VTIMEZONE値を同等のMeetingTimeZone値に変換し、抽出時にはこの逆に変換する必要があります。

C.8.2.5 日時値

Exchange Webサービスでは、すべての日時値が協定世界時(UTC)で格納されます。コネクタでは、ICALの日時値の書式を確認して、必要な場合はUTCに変換する必要があります。ICALでもVTIMEZONE情報が必要になるため、これによって処理が単純になります。

C.8.2.6 PIMレコードID

Exchange 2007サーバーでは、ユーザーが特定のカレンダ・レコードを更新すると、そのレコードに新しいPIMレコードIDが付けられる場合があります(詳細は、http://support.microsoft.com/のMicrosoftサポートを参照)。したがって、PIMトランスポートでは、作成または抽出するすべてのカレンダ・レコードについて、レコード・レベルの関連データとしてItemIdTypeおよびMeetingIdの両方を保存する必要があります。

PIMトランスポートでExchangeレコードの抽出、更新または削除を行うときは、特定のカレンダ・レコードに対してExchangeが実行するこのレコード再作成プロセスによって指定の操作に失敗する場合があることを考慮する必要があります。

通常、PIMトランスポートでは、最初に、使用可能なItemIdTypeを使用して指定の操作を実行しようとします。操作に失敗し、Exchangeストアにレコードが存在しないため操作に失敗したことが結果コードで示された場合、コネクタでは、このエラーが発生したのは、エンド・ユーザーが実際にレコードを削除したためか、またはExchangeのレコード再作成プロセスのためかを判断する必要があります。コネクタではこれを判断するために、Exchangeに対して、更新レコード・コールに付随するメタデータで提供されたレコード関連データに含まれるのと同じMeetingIdが含まれるカレンダ・レコードのItemIdTypeを問い合せます。問合せで一致が返された場合はExchangeでレコードが再作成されており、そうでない場合はユーザーがレコードを削除しています。Exchangeでレコードが再作成されている場合は、問合せで返された新しいItemIdTypeを使用して操作が再試行されます。

次の各項では、Exchangeに対してレコードの抽出、作成、更新および削除を行うときにPIMレコードIDが変更されることについて、Exchange PIMトランスポートで実行する必要がある処理の追加詳細を説明します。

C.8.2.7 ExtractDomain

Exchange PIMトランスポートでは、ランタイム・ライブラリ内にあるGetAssocDataIdOfAssociatedDataメソッドを使用すると、ItemIdTypeからBDSSデータ・ストアに格納されたPIMレコードIDへの必要な変換を実行できるため、DeleteUnawareインタフェースを実装しないように更新できます。PIMトランスポートで削除の検出を実行するように設定すると、Exchangeサーバーへの追加問合せが不要になります。

コネクタでは、他のドメインと同じロジックに従ってドメインを抽出します。ただし、以前にファンニングされたインスタンスを、単一のICALメッセージを含む単一のPIMUpsertRecordに結合する追加ステップを実行する必要があります。

C.8.2.7.1 ファンニングのロジック

抽出レスポンスにファンニング済インスタンスが含まれる場合、抽出されなかったファンニング済インスタンスは前のセッションで更新または削除されている場合があるため、コネクタでは、関連するすべてのファンニング済インスタンス(抽出レスポンスに含まれるものと含まれなかったものの両方)をすべて識別し、元の繰返しパターンが設定された単一のICALメッセージに各ファンニング済インスタンスを表示する方法を決定する必要があります。

コネクタでは、再作成プロセスの中で、元のレコード・データおよび元の繰返しパターンを含むマスターVEVENTが必要です。コネクタでは、1つのレコードのファンニング済インスタンスをすべて取得して単一のICALに結合する必要があるため、FanningStateが「Fanned」(これはファンニング済レコードの初期状態を示します)のファンニング済インスタンスを使用することもできます。ただし、変更が実行された各ファンニング済インスタンスの場合、この方法は失敗します(各インスタンスの例外が含まれる繰返しパターンと同じです)。このため、PIMトランスポートでは、マスターVEVENTをレコード・レベルの関連データとして格納します。

たとえば、セッション1で、パターンが「3か月ごとの初日、4回」のレコードのCreateRecordをエンジンがコールし、Exchangeでこのパターンをサポートしていないとします。PIMトランスポートでは、3か月ごとの初日に該当する繰返しなしの4つのインスタンスにこのパターンをファンニングします。セッション2の前に、Outlookユーザーが1番目のファンニング済インスタンスの開始日を変更し、2番目のファンニング済インスタンスを削除します。セッション2が開始されると、コネクタではRRULEパターンが「3か月ごとの初日、4回」になるようにICALを再作成し、抽出レスポンスには、日付が変更されたカレンダ・レコードを含む1つのアップサート、および削除されたレコードを含む1つの削除が含まれます。マスターVEVENTはレコード関連データまたはExchangeレコードのいずれかから取得され、アップサートは例外VEVENTとしてICALに表示されます。削除は、マスターVEVENTのEXDATEとしてICALに表示されます。セッション3の前に、3番目のファンニング済インスタンスを更新して、レコードの開始時間を変更したとします。セッション3が開始されると、抽出レスポンスには3番目のファンニング済インスタンスのみが含まれますが、セッション2で行われた変更がパターンに反映されるように他のインスタンスも取得する必要があります。コネクタでは、Exchangeに対して他のレコードを問い合せて、マスターVEVENTに2番目のインスタンスのEXDATE(これはセッション2で削除されたため)、および2つの例外VEVENT(日付が変更された1番目のファンニング済インスタンスの例外、および時刻が変更された3番目のファンニング済インスタンスの例外)が含まれるように、パターンを再作成する必要があります。

ユーザーが繰返しパターンをファンニング済インスタンスに追加した場合、コネクタではそのファンニング済インスタンスを元のパターンの削除インスタンスとして処理し、レコードは結合されたICALに含めるのではなく、抽出レスポンスに個別のレコードとして保持します。受信コネクタでは、EXDATEがあるため元のパターンのインスタンスを非表示にし、ファンニングされた例外レコードに対して新しい繰返しレコードを作成します。

注意: ICAL RFCでは、VEVENTには任意の数のRRULE、RDATE、EXRULEおよびEXDATEを含めることができると規定されています。繰返しルールを含む例外を表すのは簡単ですが、例外が含まれた繰返しパターンを含む例外を表すのは困難です(それ自体に例外パターンを持つ繰返しパターンが含まれるこのような例外は無限に繰り返される可能性があります)。

C.8.2.7.2 変更されたPIMレコードIDのロジック

ExchangeではPIMレコードIDを変更できるため、コネクタでは、抽出レスポンスに含まれる特定のPIMレコードIDが変更されたかどうかを判断する必要があります。これを行うには、抽出されたファンニング済インスタンスのItemIdType値を、指定した元の開始日にBDSSレコード関連データとして格納されているItemIdTypes(Exchangeレコードの非表示フィールドにも関連データとして格納されています)と対比して不一致を検出します。IDの変更が検出されると、コネクタでは、新しいItemIdTypeを含むようにレコード関連データを更新する必要があります。

C.8.2.8 CreatePIMRecord

次の各項では、CallPIMRecordメソッド・コールによって発生するプロセスについて説明します。

• ファンニングのロジック

• 変更されたPIMレコードIDのロジック

C.8.2.8.1 ファンニングのロジック

PIMトランスポートでは、カレンダ・レコードの各VEVENTに含まれるRRULE、RDATEおよびEXDATEプロパティをすべて評価して、レコードをファンニングする必要があるかどうかを決定します。

ファンニングが必要な場合、コネクタでは、ファンニング済レコードのコレクションの単一の一意IDをBDSSに提供するように要求されます。PIMトランスポートでは、原則として、他のドメインに対してこの処理を行う場合に指定のレコードのPR_SOURCE_KEYを提供するため、コネクタでは、1番目のファンニング済インスタンスのPR_SOURCE_KEYをPIMレコードIDとして提供して、ファンニング済レコードのコレクションを表します。

Exchangeで作成された各ファンニング済インスタンスには、次の非表示フィールドがあります。

• OriginalStartDate: ファンニング済インスタンスの開始日が格納されます。この値は、レコードの有効期間中に変更されることはありません。

• BDSSFabricatedPIMRecordId: BDSSにPIMレコードIDとして提供されるレコードIDが格納されます。前述したように、これは1番目のファンニング済インスタンスのPR_SOURCE_KEYです。

  
  

  注意: 1番目のファンニング済インスタンスにこの非表示フィールドの値は含まれません。コネクタでは、関連するファンニング済レコードを単一のインスタンスに結合するときに、この違いを考慮する必要があります。

  
  

• 場合によってはマスターVEVENTデータ(保留中のオープンな問題)。

• MeetingId: Exchangeレコードの会議ID。

非表示のExchangeフィールドに加えて、PIMトランスポートには、作成されたレコードIDに関連付けられたレコード・レベルの次の関連データがあります。

• FannedState: 各ファンニング済インスタンスの関連データ。

• OriginalStartDate: 各ファンニング済インスタンスの関連データ。

• ItemIdType: 各ファンニング済インスタンスの関連データ。

• 場合によってはマスターVEVENTデータ。

PIMトランスポートでは、レコードをファンニングする必要がある場合に、ファンニング制限の構成値に基づいて各インスタンスの開始日を計算し、受信するパターンを表すレコードのコレクションを作成します。

PIMトランスポートでは、次の場合にレコードをファンニングします。

• サポート対象の繰返しパターンではRRULEのコレクションを表すことができない場合。

• RDATEがICALに存在する場合。

C.8.2.8.2 変更されたPIMレコードIDのロジック

レコード作成の場合、メソッドでレコードが作成されるまでExchangeにレコードが存在しないため、PIMレコードIDの変更はコネクタに影響を与えません。ただし、レコードの変更および抽出時に抽出コードによってExchangeでPIMレコードIDを変更したかどうかを判別できるように、レコード・レベルの関連データを提供する必要があります。

カレンダ・ドメインの場合、他のすべてのドメインと同様に、Exchange PIMトランスポートでは、指定のレコードのPR_SOURCE_KEY値をPIMレコードIDとして提供し、Exchange WebサービスIDまたはItemIdTypeをレコード関連データとして格納します。コネクタでは常に、Exchangeレコードと相互作用する場合はItemIdTypeを指定し、BDSSと相互作用する場合はPR_SOURCE_KEYを指定する必要があります。

C.8.2.9 UpdatePIMRecord

この項では、UpdatePIMRecordメソッド・コールで発生する次のプロセスについて説明します。

• ファンニングのロジック

• 会議ID処理

• 変更されたPIMレコードIDのロジック

C.8.2.9.1 ファンニングのロジック

PIMトランスポートでは、UpdateRecordのコール時にレコード関連データに提供された関連データを検証して、更新対象のレコードがすでにファンニングされているかどうかを判別します。

PIMトランスポートでは、RRULE、RDATEおよびEXDATE属性のコレクションを検証して、受信したICALをネイティブでExchangeに表示できるかどうかを判別します。

表C-41に、カレンダ・レコードの更新時にPIMトランスポートで実行する処理を示します。

表C-41 PIMトランスポートの更新処理

更新するパターンはサポート対象か	レコードはファンニング済か	処理
True	True	同期化セッション間でサポート対象外のパターンがサポート対象のパターンに変更されたことを示します。 ファンニング済インスタンスを削除します。 サポート対象のパターンを使用して新規レコードを作成します。 削除のエコーが抽出レスポンスから削除されるように、後続の抽出用にファンニング済インスタンスに関連する古いassocdataを保持します。 作成されたレコードに、作成済IDが非表示フィールドとして含まれていることを確認します。
True	False	更新を実行します。
False	True	同期化セッション間でサポートされていないパターンを示します。 元の繰返しパターンが変更された場合は、次の処理が実行されます。 ファンニング済インスタンスを削除します。 新しいファンニング済インスタンスを作成します。 後続の抽出用にファンニング済インスタンスに関連する古いassocdataを保持し、FannedStateをRefannedに設定します。 作成された各レコードにエコー・フラグを設定します。 各ファンニング済インスタンスに、更新でPIMレコードIDとして提供された同じ作成済IDが含まれていることを確認します。 元の繰返しパターンが変更されなかった場合は、次の処理が実行されます。 受信したICALの例外を既存のファンニング済インスタンスに関連付け、そのファンニング済インスタンスを例外データで更新します。 繰返しパターン・データを除くマスターVEVENTデータを、残りのファンニング済インスタンスに適用します。 更新した各ファンニング済インスタンスにエコー・フラグを設定します。
False	False	同期化セッション間でサポート対象のパターンがサポート対象外のパターンに変更されたことを示します。 繰返しレコードを削除します。 新しいファンニング済インスタンスを作成します。 古いassocdataを削除します。 ファンニング・メタデータを保持する新しいassocdataを作成します。

PIMトランスポートで更新を受信し、パターンがすでにファンニングされて指定のファンニング済インスタンスにはRecurringExceptionのFannedStateがあるが、関連データに格納された元の開始日と一致するEXDATEがマスターVEVENTにないことを確認すると、コネクタでは競合が発生してExchangeデータが失われたとみなす必要があります。この場合、コネクタでは、RecurringExceptionのFannedStateがあるファンニング済レコードを削除して、関連データを更新する必要があります。この削除は後続の同期化セッションで他のコネクタに伝播され、繰返しパターンを持つファンニング済例外のために個別に同期化された繰返しレコードが削除されます。

C.8.2.9.2 会議ID処理

コネクタでは、ICALに含まれるMeetingIdを更新された各レコードの非表示のExchangeフィールドに格納し、既存のカレンダ・レコードのMeetingIdは更新しません。抽出が実行されると、非表示フィールドのMeetingId(レコード上のではなく)がICALに配置されます。非表示フィールドに格納されるMeetingIdは、会議のレコードに格納された実際のMeetingIdと同じ場合とそうでない場合があります。同じ場合は、BDSSまたはExchangeクライアントのいずれかでレコードが作成されたことを意味します。異なる場合は、更新された結果、競合が発生してExchangeデータが失われたことを意味します。いずれの場合も、コネクタでは後続のセッションの更新時にICALに含まれるMeetingIdをハブに返すため、問題はありません。MeetingIDを返すことによって、Exchange自体またはExchangeクライアントが実行する会議管理をコネクタが誤って破損することはありません。

C.8.2.9.3 変更されたPIMレコードIDのロジック

PIMトランスポートでは、第C.8.2.6項「PIMレコードID」の説明に従って更新を実行します。

C.8.2.10 DeletePIMRecord

Exchange PIMトランスポートでは、常にレコードの作成済ID(PR_SOURCE_KEYとも呼ばれます)を指定しますが、Exchangeで削除を実行するときはItemIdTypeを指定する必要があるため、任意のドメインに対して削除操作を実行するときは、常にBDSS RTLからレコード関連データを取得する必要があります。

C.8.2.10.1 ファンニングのロジック

レコードがすでにファンニングされている場合、PIMトランスポートでレコードのファンニング済インスタンスをすべて削除するには、レコードのレコード関連データを取得して各インスタンスを削除します。

C.8.2.10.2 変更されたPIMレコードIDのロジック

PIMトランスポートでは、第C.8.2.6項「PIMレコードID」の説明に従って削除を実行します。