service-omni-agent-users-create

service-omni-agent-users-create

Anonymous Apex を介して Salesforce 組織に N 人のエージェントユーザーを作成し、Omni-Channel が作業を割り当てるエージェントを用意します。ユーザー名は組織ごとに決定的なパターンに従い、検出には SOQL を使用します。このスキルは不足しているユーザーのみを挿入するため、安全に再実行できます。service-omni-base-settings-configure が Omni-Channel を有効にした後、service-omni-channel-setup-coordinate によって呼び出されます。権限セットの割り当て（service-omni-permission-set-assign）とキューへのユーザーの追加（service-omni-queue-members-assign）は、それぞれ別のリーフです。スーパーバイザーユーザーは service-omni-supervisor-users-create で作成します。

入力

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

• org-alias（必須、デフォルトなし）— sf org display で解決できる必要があります。
• ユーザー数（任意、デフォルトは 3、範囲は 1..10）。
• プロファイル名（任意、デフォルトは移植性を考慮して Standard User）。コーディネーターはこれを Service Cloud プロファイルに上書きし、エージェントが Service Cloud ライセンスを使用するようにします。多くの CDO では Salesforce ライセンスプールが枯渇している一方、Service Cloud には空き枠があります。

ユーザー名とパスワードをオペレーターから受け取ることはありません。どちらも生成されます（ユーザー名は組織のサフィックスから、パスワードは Anonymous Apex で生成）。オペレーターが指定した認証情報では、再実行時の検出が機能しなくなり、脆弱な、または漏えいしたシークレットのリスクが生じます。

前提条件と安全性

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

パスワードの取り扱い（フェイルクローズ）。 パスワードは Anonymous Apex の System.setPassword で設定されます（sf user password generate は Apex で挿入されたユーザーを対象にできず、NamedOrgNotFoundError で失敗します）。パスワードのリテラルはインラインの executeAnonymous デバッグログに表示され、実行ユーザーに対してデバッグログの TraceFlag が有効な場合に限り、クエリ可能な ApexLog にも表示されます。そのためラッパーは、最初の System.setPassword より前にフェイルクローズします。SOQL でフィルタリングした Tooling API クエリ（ExpirationDate > now）を使い、有効な TraceFlag が存在しないことを証明します。安全性を確実に証明できない場合（実行ユーザーを解決できない、クエリが失敗する、解析できない、または有効な TraceFlag が存在する場合）は、パスワードを一切生成しません。ユーザーは ACTIVE のまま残り、password_status:"reset_required" が設定され、理由を説明する security_warning が記録されます。ログを削除することはないため、平文が ApexLog に保存されることはなく、無関係な監査ログにも影響しません。ユーザーに対する System.setPassword 自体が失敗した場合、そのユーザーは 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 users
bash scripts/detect-and-create.sh run  <org-alias> [count=3] [profile-name="Standard User"]

detect-and-create.sh が正式なエントリーポイントです。検出を再実行し、本番環境のガードを適用した後にのみ挿入します。scripts/run-create.sh を直接呼び出さないでください。これは内部用であり、それ自体ではガードを適用しません。

動作

検出。 検出器は Organization.Id から8文字のサフィックス（substring(10,18)、小文字化）を導出し、名前でプロファイルを特定してから、agent{i}.<suffix>@example.com を持つ User を検索し、count 個のスロットインデックスのうち使用済みのものを特定します。安定した決定論的パターンにより、再実行が冪等になります。サフィックスがタイムスタンプや UUID になることはありません。

挿入。 Apex は assets/create-users.apex.template を読み込み、__COUNT__／__PROFILE_ID__／__SUFFIX__ を置き換え、不足しているインデックスのみを挿入します。トランザクション内で既存ユーザーを再確認するため、単一の実行で二重に挿入されることはありません。ただし、同時実行間では、どちらかがコミットする前に両方が事前クエリを通過する可能性があるため、トランザクション内の確認は保証になりません。その場合の重複防止は、グローバルなユーザー名一意制約と DUPLICATE_USERNAME の再試行に依存します（references/apex-template-notes.md を参照）。ユーザーが Omni でオンラインになれるよう、Service Cloud 機能（UserPermissionsSupportUser=true）を有効にします。プロファイルのライセンスで許可されていない場合は、Apex がこのフラグを除去して再試行します（ユーザーは作成されますが、Omni の全機能を利用するには Service Cloud ライセンスのプロファイルが必要です）。作成された各ユーザーは AGENT_USER_CREATED|<id>|<username>|<email> で報告されます（マーカーにパスワードは含まれません。パスワードは別個の System.setPassword の送信処理で設定されます）。

検証。 挿入後、検出器を再実行し、missing_count == 0 となることを確認する必要があります。そうでない場合、このスキルは失敗します（Apex は成功を報告したものの、ユーザーが永続化されていません）。

出力仕様

detect-and-create.sh は、status ∈ created | partial | reused | action_needed | blocked に加え、detect（検出器の結果を反映）、create（挿入処理の結果を反映し、何も作成されていない場合は null）、トップレベルの reused_users、created_count、reused_count、total_present_after、users_needing_password_reset、action_required、safe_to_write を含む単一の JSON オブジェクトを出力します。コーディネーターは reused_users と新規作成ユーザーを組み合わせ、混在した実行でも、要求されたエージェントセット全体にプレゼンスとスキルを設定します。

• created — 不足していたすべてのインデックスでユーザーが作成され、使用可能なパスワードが設定されました。
• partial — 一部のユーザーは作成されたものの全員ではない場合、ユーザーに手動でのパスワードリセットが必要な場合、または非アクティブな占有ユーザーが見つかった場合です。
• reused — 要求されたユーザーがすでにすべて存在し、作成されたユーザーはいません。
• action_needed — 計画モードのみです。書き込みを行わず、不足しているインデックスを報告します。
• blocked — 前提条件を満たしていません（safe_to_write=false、プロファイル／サフィックスを解決できない、または何も挿入されなかった）。

create.created_users[].password が設定されるのは、今回作成され、System.setPassword が成功したユーザーのみです。password_status:"reset_required" は、ユーザーが ACTIVE であるものの、まだ使用可能なパスワードを持っていないことを意味します。終了コードは created／partial／action_needed／reused では 0、blocked では 1 です。

生成されたパスワードは秘密情報です。返される JSON だけに含まれます。標準出力を永続化する呼び出し元は、制限された CREDENTIALS.json（モード 0600）にのみ書き込み、他のすべての成果物からパスワードを伏せ字にし、配布後に削除する必要があります。コーディネーターはこれを自動で行いますが、単独で呼び出す場合は呼び出し元が責任を負います。再利用されたユーザーのパスワードは取得できません。Setup → Users → Reset Password から復旧してください。

制限事項

• ユーザー名のパターンと組織サフィックスは固定されており、オペレーターが設定を変更することはできません。この決定性によって、再実行が冪等になります。
• 指定されたプロファイルでエージェントユーザーのみを作成します。既存ユーザーの削除、無効化、変更は行いません。
• 一般的な User エラー（DUPLICATE_USERNAME、INVALID_EMAIL、LICENSE_LIMIT_EXCEEDED）は、そのまま表示するのではなく、オペレーターにわかりやすいメッセージに変換されます。

参考資料

ファイル	読むタイミング
references/apex-patterns.md	Apex を実行する前 — Apex の構造、User フィールドのデフォルト値、パスワードポリシー、プロファイルのローカライズに関するリスク
references/apex-template-notes.md	ユーザーの作成時に重複、ライセンス、またはパスワードのエラーが返された場合 — テンプレートの置換と再試行の動作を説明しています
assets/create-users.apex.template	作成が必要なエージェントユーザーを挿入する際に、scripts/run-create.sh によって読み込まれます
scripts/detect-existing.sh	正規のエントリーポイントによって読み込まれ、読み取り専用の組織、プロファイル、安全性、既存ユーザーのチェックを行います
scripts/tests/test_user_create_security.py	ユーザー作成スクリプトを変更した後に実行し、本番環境での拒否とパスワード処理の仕様を検証します