🌐
関与度合について
関与度合について
関与度合とは、メンバーが所属する組織ごとに数値を登録することで、主務組織・兼務組織を判定するための設定です。この記事では、YESODディレクトリーサービスにおける「関与度合」の考え方と、APIで関与度合を扱う際の注意点、およびアカウントコントロールの属性同期でこれを利用する際の注意点を説明します。
📋 関連記事 メンバー・グループの基本概念（メンバー項目／グループ関連項目の違いなど）は YESOD ディレクトリーサービスのデータ構造について を前提としています。
関与度合とは
関与度合（属性エイリアス：）は、メンバーと組織の組み合わせごとに設定する数値の関連項目です。
1人のメンバーが複数の組織に所属している（兼務している）場合、この数値が最も大きい組織が「主務組織」、それ以外が「兼務組織」として扱われます。
| 所属組織 | 関与度合 | 判定 |
|---|---|---|
| 営業部 | 1 | 主務組織（数値が最大） |
| 営業管理部 | 0 | 兼務組織 |
| マーケティング部 | 0 | 兼務組織 |
⚠️ 「組織」にのみ適用されます 主務・兼務の判定ロジックは、グループ種別が「組織」の所属にのみ適用されます。会社・事業所・プロジェクトへの所属についてカスタム項目で関与度合の項目を作成をし設定したとしても、会社・事業所・プロジェクトの主務・兼務の判定をすることはできません（例：複数会社に所属している場合の「主務の会社」を関与度合で判定する機能はありません）。
💡 ポイント 標準項目のエイリアスは 、項目ID（Base64形式）は、項目ID（UUID形式）は です。属性式や各種インポートAPIのマッピングで指定する際に使用します。
この値に依存する機能
関与度合は、以下の機能から参照されます。機能によって、関与度合が未設定または同点（最大値の組織が複数ある）場合の挙動が異なるため、あわせて確認してください。
| 機能 | サービス | 関与度合の使われ方 | 未設定・同点時の挙動 |
|---|---|---|---|
| 組織図の兼務組織に「兼」の表示を出す | ディレクトリサービス | 主務組織以外の所属先に「兼」のラベルを表示 | エラーにはならず、同点（未設定で全組織が同じ扱いになる場合を含む）のときはその組織すべてが主務として扱われ、「兼」は表示されない |
| 組織図の「主務のみ表示」／CSVエクスポートの主務のみ出力 | ディレクトリサービス | 主務組織のみに絞り込んでメンバーを表示・出力 | エラーにはならず、主務が一意に決められない場合は該当メンバーの所属を全件表示するフォールバック動作になる |
| 属性同期（属性式の等） | アカウントコントロール | 主務組織・兼務組織を判定し、その組織の属性値を接続先サービスへ連携 | エラーになり同期が停止する（詳細は後述） |
| グループプッシュの「主務・兼務」設定 | アカウントコントロール | 割当対象の組織を「主務のみ」「主務+兼務」「すべて」で絞り込み | エラーにはならず、関与度合が未設定の組織は絞り込み条件に応じて単に対象外になる |
APIを利用する開発者向け：APIを扱う際の注意点
データモデル上の位置づけ
関与度合は、メンバーの組織所属ごとの関連項目として、他の関連項目（役職・社員番号など）と同様にAPIで読み書きできます。エイリアス または項目ID（Base64形式） を指定します。
クエリAPI
json
レスポンスは以下のようになります（会社が登録されており、かつメールアドレスがのメンバーを検索し、姓・名・関与度合を取得した例）。
json
の配列には、所属している組織の数だけ要素が並びます。同じ組織を指す要素はで対応し、その組織のコード・名称・上位組織などの詳細は、レスポンス直下の配列（が一致する要素）から確認できます。は文字列（／）で返却されます。
💡 ポイント このように、関与度合はあくまで数値（文字列）として返却されるだけで、「これが主務組織である」というラベル付けはレスポンスに含まれません。主務組織を特定したい場合は、取得した値を数値に変換して利用側で比較するか、アカウントコントロールの同期する項目で利用する場合は、後述の属性式（等）を使う機能側の判定結果を利用してください。
メンバーインポートAPI
json
💡 ポイント このパターンでは1行につき組織を1つしか指定しないため、・の指定は不要です。1つのセルに複数組織をまとめる場合は、別パターン（指定）になります。詳細は マッピングファイルの記載方法 を参照してください。
トランザクションインポートAPI
トランザクションインポートAPI（ または ）では、1回の操作（1行）につき組織を1つしか指定できません。そのため、新規メンバーの主務組織を登録すると、兼務組織を追加するを、同じCSV（同じAPIリクエスト）の中で行を分けて指定します。
json
1行目ので入社登録と主務組織（関与度合1）を同時に登録し、2行目ので同一メンバーに兼務組織（関与度合0）を追加しています。これは1回のAPIリクエストで完結します（2回に分けてリクエストする必要はありません）。
⚠️ 注意で1つのCSV内に同じメンバー（同じ名寄せキー）に対して複数の組織をまとめて指定することはできません。「主務組織はaddEntityで、兼務組織はmodifyEntityで」という行の分け方が必要です。行を先に、行を後に書いても同じメンバーとして名寄せされますが、意図が伝わりやすいaddEntity→modifyEntityの順で書くことを推奨します。
読み取り時の注意点
- 関与度合が未設定、または同点のデータであっても、API・CSVインポート側ではエラーにならず正常に登録・取得できます。バリデーションは書き込み時ではなく、後述するアカウントコントロールの属性同期などの利用側の機能で発生します。
- 同点が問題になるのは主務組織（最大値）が複数ある場合のみです。兼務組織どうしの関与度合が同点であること自体は問題ありません。主務が一意に決まっていれば、兼務組織側は同じ値でも構いません。
- 例：3つの組織を兼務している場合、組織A（主務・関与度合1）、組織B（兼務・関与度合0）、組織C（兼務・関与度合0）のように、主務だけを他より大きい一意な値にし、兼務側は同じ値のまま運用しても問題ありません。
- そのため、連携先サービスへの属性同期で主務組織の値を使う予定がある場合は、インポート時点で「兼務するメンバーの主務組織の関与度合を、他のどの組織よりも大きい一意な値にする」運用を徹底することを推奨します。
アカウントコントロール属性同期の注意点
| メソッド | 説明 |
|---|---|
| 主務組織の属性値を取得 | |
| 主務組織のフルパスを取得 | |
| 主務組織の上位組織の属性値を取得 | |
| 兼務組織の属性値を関与度合の高い順にリストで取得 | |
| 兼務組織のフルパスを関与度合の高い順にリストで取得 | |
| 兼務組織の上位組織の属性値を関与度合の高い順にリストで取得 |
エラーになるケース
これらのメソッドを使った属性同期は、対象メンバーの組織所属について次のいずれかに該当すると、同期処理がエラーになり停止します。
| 状況 | 実際のエラーメッセージ |
|---|---|
| 所属しているどの組織にも関与度合が設定されていない | |
| 関与度合が最大の組織が複数あり、主務組織を一意に決められない（同点） |
⚠️ 注意 上記はいずれもメンバーインポートやAPIの書き込み自体は成功しているにもかかわらず、その後の属性同期のタイミングで初めて表面化するエラーです。インポート直後は成功して見えても、対象メンバーが兼務している場合は関与度合の設定状況を確認してください。
対処法
- 兼務が発生するメンバーは、所属する全ての組織に関与度合を設定する（最低でも主務組織には必ず設定する）
- 主務組織の関与度合が、他のどの組織とも重複しない（一意に最大となる）ようにする。兼務組織どうしが同じ値になるのは問題ありません
- 等を使った属性式を新規設定・変更する際は、事前に少数のメンバーで動作確認する（属性式について と同様の運用を推奨）
📋 関連記事 関与度合そのものの入力方法（組織図での操作）は メンバーの兼務（組織図での操作） を、属性同期の設定手順は 同期する項目の設定 を参照してください。