platform-role-hierarchy-apply

ロール階層の再構築

アーティファクトの内容を、管理者が承認した 1 つのマニフェストで適用し、多数の UserRole を変更します。

管理者が既存のロールやその階層について尋ねているだけの場合は、managing-roles に引き継いでください。クエリを実行せず、ステップ 0 の質問もせず、送信もしないでください。

入力

• テキストを選択できる組織図の PDF、role_name と parent_role_name を含む .xlsx／.csv（親が空の場合は最上位）、または 1 行につき Role: Parent のペアを 1 つ記載したプレーンテキスト。
• または、{roleName, parentRoleName} オブジェクトの解析済みリスト。
• 組織図内の名前が組織の Name または DeveloperName と一致しない場合は、任意でマッピングのヒントを指定できます。

フロー

0. クエリの実行前に確認する

未解決の点があれば、すべて質問してください。推測してはいけません。

• 範囲。 デフォルトは選択したブランチです。アーティファクトに含まれないロールはそのまま残ります。「階層全体」の場合も、管理者が各ロールの削除を求めていない限り、それらのロールは削除しません。
• ユーザーの再割り当て。 デフォルトでは行いません。明示的な許可なしに AssignUser や MoveUser を出力しないでください。
• 曖昧な識別情報。 すべてのロールとユーザーを 1 回のバッチで解決します。ステップ 2 を参照してください。
• 競合。 1 つのロールに親が 2 つある場合、またはロール自身を親に指定している場合は、管理者が選択するまで停止します。

アーティファクト内のロールのうち、現在のツリーと一致するものが 20% 未満の場合は停止し、グリーンフィールドでの置き換えか、ファイル違いか、マッピングの問題かを確認してください。管理者がグリーンフィールドでの置き換えを確認するまで、マニフェストを作成しないでください。20% 以上 50% 未満の場合は、プレビューに割合を表示して続行します。

1. 現在の階層を読み込む

SELECT Id, DeveloperName, Name, ParentRoleId
FROM   UserRole
LIMIT  10000

アーティファクト内のロールは、まず DeveloperName、次に大文字と小文字を区別しない Name で照合します。

2. アーティファクトを解析し、識別情報を解決する

{roleName, parentRoleName, users?} に正規化し、差分を提示する前に、そのリストを管理者に表示します。テキストを選択できない PDF は解析できません。Role: Parent 形式のプレーンテキストのリストを依頼してください。

ロール：完全一致の DeveloperName、次に大文字と小文字を区別しない Name。あいまい一致は行いません。複数のロールが一致する場合は、各候補の DeveloperName と Id を列挙して回答を待ちます。1 つを選んではいけません。未解決の名前はステップ 0 に戻します。

ユーザーの照合は、再割り当てが確認された場合にのみ行います。

1. 005 で始まる 18 文字の ID → User.Id
2. メールアドレス → User.Email
3. ユーザー名 → User.Username
4. 表示名 → User.Name。一致する有効なユーザーが 1 人だけの場合に限ります

IsActive = false は一致しないものとして扱います。1 人のユーザーが 2 つのロールに記載されている場合は競合です。そのユーザーをどのロールに割り当てるか、または再割り当てを取りやめるかを質問してください。管理者の回答を得るまで送信しないでください。

対象グラフに循環がある場合は停止します。たとえば A → B → C → A のように経路を示し、アーティファクトの修正版を依頼してください。送信しないでください。

3. マニフェストを作成する

各変更には、operationId、operationType、dependsOnOperationIds、およびネストされたペイロードが含まれます。重要なのはdependsOnOperationIdsの順序です。

operationType	ネストされたオブジェクト	使用するケース
CreateRole	createRole	ロールがアーティファクトには存在するものの、組織には存在しない場合です。roleReference、developerName、name、およびparentRoleIdまたはparentRoleReferenceを設定します。アーティファクトで指定されていない場合は、3つのアカウント所有者アクセス項目に組織のデフォルト値を設定します。
ReparentRole	reparentRole	ロールが存在し、親が異なる場合です。targetRoleIdまたはtargetRoleReference、expectedParentRoleId、およびdesiredParentRoleIdまたはdesiredParentRoleReferenceを設定します。
RenameRole	renameRole	同じロールで、表示名または開発者名が異なる場合です。変更前と変更後の名前項目を設定します。
DeleteRole	deleteRole	管理者が、空のロールの削除を依頼した場合です。targetRoleId、expectedParentRoleId、expectedAssignedUserIds、およびexpectedDirectChildRoleIdsを設定します。
AssignUserまたはMoveUser	userRoleAssignment	再割り当てが確認済みの場合です。userId、expectedCurrentRoleId、およびdesiredRoleIdまたはdesiredRoleReferenceを設定します。

DeleteRoleが適用されるのは、実行時にロールに直接の子も割り当て済みユーザーもいない場合に限ります。それらの子ロールを付け替え、ユーザーを移動する変更を先に行い、そのoperationIdをdependsOnOperationIdsに指定します。その後、削除対象の想定ユーザーリストと子ロールリストは空になります。管理者が再割り当てを拒否した場合、ユーザーが残っているロールを削除しないでください。

組織にもこのマニフェストで作成されるロールにも存在しないロールを指定する変更は、missing-parentです。そのロールを参照しているロール名を示します。このマニフェストにCreateRoleを追加するか、それらの行をスキップするか、中止するかを確認します。親が存在しない状態で送信しないでください。

dependsOnOperationIdsに循環がある場合、送信はブロックされます。新しい各ロールにroleReference文字列を割り当て、親と割り当てではその文字列を指定します。

4. 検証してからプレビューする

次のいずれかが残っている場合、送信をブロックします。循環、親の欠落、重複するdeveloperName、依存関係の循環、ステップ0で「はい」が確認されていないAssignUserまたはMoveUser、想定ユーザーリストまたは子ロールリストが空ではないDeleteRole、またはグリーンフィールドでの置き換えが確認されていない場合の20％未満の重複です。

developerNameが重複している場合は、該当する両方の行を表示し、管理者がどちらかを選ぶか、いずれかの名前を変更するまで待ちます。

プレビューで警告を表示し、明示的に「はい」と確認された後にのみ続行します。

• 変更対象のロールがTerritory2.UserRoleIdまたは予測階層の上書きで参照されています。
• 変更対象のロールのPortalType != 'None'です。
• 変更対象のロールに500人を超えるユーザーがいます（SELECT COUNT() FROM User WHERE UserRoleId = :id）。

Restructure preview
-------------------
  ReparentRole : 42
  CreateRole   :  3
  RenameRole   :  1
  DeleteRole   :  2
  MoveUser     :  2

  Territory / forecast references : 1
  Portal roles                    : 0
  Roles with more than 500 users  : 2

Approve this restructure? [yes / no]

yesの場合は送信します。それ以外の場合は送信しません。組織に残り、アーティファクトに存在しないロールは、そのまま維持されます。

5. 送信する

POST /services/data/v{version}/sharing/role-hierarchy-restructure
{
  "operation": "Save",
  "mutations": [
    {
      "operationId": "reparent-sales-vp",
      "operationType": "ReparentRole",
      "dependsOnOperationIds": [],
      "reparentRole": {
        "targetRoleId": "00E000000000001",
        "expectedParentRoleId": "00E000000000002",
        "desiredParentRoleReference": "cro"
      }
    },
    {
      "operationId": "delete-legacy-region",
      "operationType": "DeleteRole",
      "dependsOnOperationIds": ["reparent-legacy-children"],
      "deleteRole": {
        "targetRoleId": "00E000000000003",
        "expectedParentRoleId": "00E000000000002",
        "expectedAssignedUserIds": [],
        "expectedDirectChildRoleIds": []
      }
    }
  ]
}

CreateRole、RenameRole、AssignUser、MoveUserでは、ステップ3の対応するネストされたオブジェクトを含む同じエンベロープを使用します。

承認済みのマニフェストを一度だけ送信します。UserRoleレコードを1件ずつ編集しないでください。

6. 応答を読み取る

• Applied — 構造変更と共有変更がコミットされました。
• AppliedSharingPending — 階層は反映済みです。共有は自動的に追いつくため、ポーリングしないでください。
• AsyncExecutionRequired — サーバーがマニフェストをキューに登録しました。ポーリングしないでください。
• RoleOperationInProgress — 別の再構成が実行中です。停止してください。マニフェストをキューに登録しないでください。別の処理が完了した後に管理者に再試行を依頼してください。
• NotApplied — 何もコミットされていません。reasonCodesを表示して停止します。
• 送信時の404 — このクライアント階層ではAPIが有効になっていません。停止して管理者に伝え、再試行せず、レコードごとの/sobjects/UserRole編集にも切り替えないでください。

各operationResults[]エントリーについて、outcomeはApplied、NotApplied、またはDependencyNotAppliedです。Applied以外のエントリーではreasonCodeを表示します。再試行もロールバックもしないでください。

対象外

• ほかに変更を伴わない単一ロールの作成、名前変更、親ロールの変更、および存在するロールやその階層だけを尋ねるリクエスト（managing-roles）。
• テリトリー、アカウント、予測の階層。
• 共有ルールの作成。
• 画像のみの PDF。テキストを依頼してください。
• ロールバック。応答にコミット済みと記載されている内容を報告してください。

---

操作リファレンス

このスキルが使用する操作 — ルーティングと依存関係のリファレンスです。

操作	目的	ステータス	呼び出し	依存先
read-role-hierarchy	読み取り	—	GET /services/data/v68.0/query	—
count-users-per-role	読み取り	—	GET /services/data/v68.0/query	read-role-hierarchy
submit-role-hierarchy-restructure	書き込み	—	POST /services/data/v68.0/sharing/role-hierarchy-restructure	read-role-hierarchy
verify-role-hierarchy-restructure	検証	—	GET /services/data/v68.0/query	submit-role-hierarchy-restructure