service-omni-supervisor-users-create

service-omni-supervisor-users-create

Salesforce 組織に、従来の Omni-Channel Supervisor Configuration（OmniSupervisorConfig）用のスーパーバイザーユーザーを N 人作成します。この設定は、名前付きユーザーレコードを OmniSupervisorConfigUser 経由で関連付けます。ユーザー名には決定論的な supervisor{i}.<suffix>@example.com 形式を使用するため、コーディネーターは実行をまたいでユーザーを再検出できます。これは service-omni-agent-users-create のスーパーバイザー版であり、検出、パスワード、冪等性のモデルを共有しています。異なるのは、ユーザー名／エイリアスのプレフィックスとデバッグログのマーカーのみです。これらのユーザーを設定に関連付ける処理（service-omni-supervisor-config-deploy）と、スーパーバイザーアクセスを付与する処理（service-omni-supervisor-permset-assign）は、別のリーフです。

入力

最初に一度だけ確認します。

• org-alias（必須、デフォルトなし） — sf org display で解決できる必要があります。
• スーパーバイザー数（任意、デフォルトは 1、範囲は 1..5。コーディネーターは通常 1 人を指定します）。
• プロファイル名（任意、デフォルトは Standard User）。コーディネーターはこれを Service Cloud プロファイルに上書きし、スーパーバイザーが Service Cloud ライセンスを使用するようにします。スーパーバイザーアクセス自体は、後で割り当てる標準の ContactCenterSupervisor 権限セットによって付与されます。

ユーザー名とパスワードをオペレーターから受け取ることはありません。どちらも生成されます（ユーザー名は組織のサフィックスから、パスワードは Anonymous Apex で生成されます）。

前提条件と安全性

• 対象組織が sf CLI で認証済みであること（My Domain URL を使用し、.lightning.force.com は使用しない）、Service Cloud ライセンスが存在すること、sf CLI が 2.139.6 以降であること。
• 実行ユーザーに PermissionsModifyAllData と PermissionsManagePasswordPolicies があること（標準では System Administrator に設定されています）。
• 本番環境向けの安全対策： 検出スクリプトは、IsSandbox OR TrialExpirationDate != null OR OrganizationType が {Developer Edition, Base Edition} の場合に safe_to_write を true と判定します。これが false の場合、スキルはオーバーライドを認めずに処理をブロックします。CDO、スクラッチ組織、開発組織は許可されます。

パスワードの取り扱い（フェイルクローズ）。 パスワードは Anonymous Apex の System.setPassword で設定されます（sf user password generate は Apex で挿入されたユーザーを対象にできません）。パスワードのリテラルはインラインの executeAnonymous デバッグログに表示され、実行ユーザーに対してデバッグログの TraceFlag が有効な場合に限り、クエリ可能な ApexLog にも表示されます。そのためラッパーは、最初の System.setPassword の前にフェイルクローズします。SOQL でフィルタリングした Tooling API クエリ（ExpirationDate > now）を使い、有効な TraceFlag が存在しないことを証明します。安全性を確実に証明できない場合、パスワードは一切設定されません。ユーザーは ACTIVE のままになり、password_status:"reset_required" のフラグが設定され、その理由を security_warning で説明します。ログは削除しません。パスワードを設定できなかったユーザーは ACTIVE のまま保持され、リセットが必要なフラグが設定されます。無効化されることはありません。

実行

# read-only preview (never writes)
bash scripts/detect-and-create.sh plan <org-alias> [count] [profile-name]
# detect, enforce safe_to_write, then insert only the missing supervisors
bash scripts/detect-and-create.sh run  <org-alias> [count=1] [profile-name="Standard User"]

detect-and-create.sh が正規のエントリーポイントです。このスクリプトは検出を再実行し、本番環境向けのガードを適用してから挿入します。ガードが適用されない内部スクリプトのため、scripts/run-create.sh を直接呼び出さないでください。

動作

検出。 検出処理は Organization.Id から8文字のサフィックスを導出し、名前でプロファイルを特定してから、supervisor{i}.<suffix>@example.com に該当する User を照会し、使用済みのスロットをアクティブな existing_users と非アクティブな inactive_users に分けます。

挿入。 Apex は assets/create-supervisors.apex.template を読み込み、__COUNT__／__PROFILE_ID__／__SUFFIX__ を置換して、不足しているインデックスのみを挿入します。1回の実行内で二重挿入されないよう、トランザクション内でも再確認します。並行実行間ではこの確認は保証になりません（どちらもコミット前に事前照会を通過する可能性があります）。そのため、この場合の重複防止は、グローバルなユーザー名一意制約と DUPLICATE_USERNAME の再試行に依存します（references/apex-template-notes.md を参照）。作成されたユーザーには Service Cloud 機能（UserPermissionsSupportUser=true）が設定されます。プロファイルのライセンスでこれが許可されていない場合、Apex はこのフラグを削除して再試行します（その場合、ユーザーが適切なライセンスを持つまで権限セットの割り当てはブロックされます）。作成された各ユーザーは SUPERVISOR_CREATED|<id>|<username>|<email> で報告されます（マーカーにパスワードは含まれません。パスワードは別途 System.setPassword を送信して設定されます）。

非アクティブなユーザーが占有するスロット。 スーパーバイザー用スロットを占有している非アクティブなユーザーは、再利用できるスーパーバイザーではなく、再作成もできません（ユーザー名はグローバルに一意です）。そのユーザーは手動での再有効化が必要な対象として表示され、要求されたスロット数には決して算入されません。算入すると、構成に必要な数を満たせなくなるためです。

検証。 挿入後、検出処理を再実行し、missing_count == 0 であることを確認する必要があります。

出力仕様

detect-and-create.sh は、status が created | partial | reused | action_needed | blocked のいずれかである単一の JSON オブジェクトを出力します。さらに、detect、create（何も作成されなかった場合は null）、created_count、reused_count、total_present_after、users_needing_password_reset、action_required、safe_to_write を含みます。

• created — 不足していたインデックスがすべて作成され、パスワードも有効です。
• partial — 一部は作成されたものの、すべては作成されなかった場合、System.setPassword が失敗した場合（ユーザーは ACTIVE のままで、users_needing_password_reset に記載されます）、または再有効化が必要な非アクティブなユーザーがスロットを占有している場合です。
• reused — 要求されたスロットがすべて既に存在し、DML はありません。
• action_needed — プランモードのみです。
• blocked — 前提条件を満たしていません。

create.created_users[].password が設定されるのは、この実行で作成され、System.setPassword に成功したユーザーのみです。create.rolled_back_users は常に空です（このスキルはユーザーを無効化しません）。生成されたパスワードは秘密情報です。返される JSON のみに含まれます。標準出力を保存する呼び出し元は、制限付きの CREDENTIALS.json（モード 0600）にのみ書き込み、他の場所では伏せ字にして、配布後に削除する必要があります。コーディネーターはこれを自動的に行います。

制限事項

• ユーザー名のパターンと組織のサフィックスは固定されており、オペレーターは変更できません。この決定性によって、冪等な再実行が可能になります。
• 作成するのはスーパーバイザーユーザーのみです。以前の実行で残された孤立したスーパーバイザーを含め、ユーザーの削除や無効化は行いません。
• 一般的な User エラー（DUPLICATE_USERNAME、INVALID_EMAIL、LICENSE_LIMIT_EXCEEDED）は、そのまま表示せず、オペレーターにわかりやすいメッセージに変換されます。

参照資料

ファイル	読むタイミング
references/apex-patterns.md	Apex を実行する前 — Apex の構造、User フィールドのデフォルト値、パスワードポリシー、プロファイルのローカライズに関するリスク
references/apex-template-notes.md	作成時に重複、ライセンス、パスワード、またはトレースの安全性に関するエラーが返された場合
assets/create-supervisors.apex.template	スーパーバイザーユーザーの作成が必要な場合に、scripts/run-create.sh が読み込みます
scripts/detect-existing.sh	読み取り専用で組織、プロファイル、安全性、既存ユーザーを確認するために、scripts/detect-and-create.sh が読み込みます
scripts/run-create.sh	ガードチェックの通過後にのみ、scripts/detect-and-create.sh が読み込む内部書き込みスクリプト