platform-trial-org-create

このスキルでできること

sf CLI で SignupRequest sObject を挿入し、Salesforce の トライアル組織を作成します。これは、Trialforce／開発者向けのWeb 登録フォームが内部で発行するリクエストと同じものです。専用の登録エンドポイントはありません。登録とは、認証済みのホスト組織（トライアル組織の作成権限が付与された Trialforce Source Org／Env Hub／パートナー組織）に対して SignupRequest（キーのプレフィックスは 0SR）を挿入することです。

このフローは2 回の CLI 呼び出しで行います。（1）SignupRequest を作成し、（2）作成結果を読み取って割り当てられた組織 ID を取得します（作成は非同期で、挿入後まもなく組織 ID が表示されます）。

前提条件 — 実行前に確認

1. 認証済みのホスト組織 — 必ず、どの組織かを明示的に確認してください。 匿名で登録するのではなく、認証済みのホスト組織から登録します。sf CLI は、あらかじめログインした組織（sf org login web または sf org login）に対して動作します。

   すべてのコマンドで明示的な --target-org（-o）を指定してホスト組織のエイリアスまたはユーザー名を渡し、作成前にユーザーに対象を確認してください — デフォルト組織が設定されている場合も同様です。SignupRequest の作成は実際のプロビジョニング操作です。現在のデフォルト組織に対して実行されることがないようにしてください。

   • デフォルト組織へのフォールバックに頼らないでください。 -o を指定しない場合、CLI は --target-org → SF_TARGET_ORG 環境変数 → ローカル、次にグローバルの target-org 設定の順に対象を解決し、いずれも設定されていなければエラー（NoDefaultEnvError）になります — 接続済み組織の中から自動的に選ばれることはありません。そのデフォルト組織は無関係な開発組織やスクラッチ組織の可能性があるため、-o を省略すると別の組織に対して実行されるか、処理が失敗します。絶対に省略しないでください。
   • ユーザーは複数の組織で認証済みの場合があります。 sf org list を実行し、対象のホスト組織が不明確な場合、または指定されていない場合は、どのエイリアス／ユーザー名を使うかユーザーに確認してください。推測しないでください。
   • 作成前に、選択した組織が sf org list で Connected と表示されていることを確認してください（古いリフレッシュトークンや期限切れの証明書は、Connected ではなくエラー状態として表示されます）。
   • 認証情報を捏造しないでください。

2. ホスト組織にはトライアル組織を作成する権限が必要であり、実行ユーザーにはその組織で十分なアクセス権が必要です。 このスキルでは、権限の確認を別途実行しません。sf data create record の呼び出し（ステップ 1）が確定的な判定となり、権限確認で用いるのと同じ API による強制適用が行われます。組織に権限がない場合、SignupRequest エンティティは公開されず、status がゼロ以外で、name／code が NOT_FOUND（「The requested resource does not exist」）または INVALID_TYPE（「sObject type 'SignupRequest' is not supported」）のエラーが発生して作成に失敗します。このケースはステップ 1 のエラーテーブルで扱います。

   このエラーが発生した場合は、処理を中止してください（CLI からは再試行できません）。ユーザーには、（a）CLI が返した未加工の CLI エラーをそのまま — 正確な name／errorCode と message を一字一句そのまま — と、（b）トライアル組織の作成を有効にするため Salesforce サポートに問い合わせてから再試行する必要があることを伝えてください。不足している権限を診断したり、どの権限が不足しているかを述べたりしないでください — 未加工のエラーをそのまま示し、サポートに問い合わせるよう案内するだけにしてください。

必須入力項目 — 作成前に実行ユーザーから収集

以下の項目をユーザーに尋ね、すべてそろうまで先に進まないでください。値を作り出してはいけません。各項目を必ず尋ねてください。ユーザーが項目に迷っている場合は、先に進む前に「ユーザーが迷っている場合」の列を参考に案内してください。

常に必須（5 項目） — SignupRequest エンティティでは required="true" になっています（FirstName は尋ねるときの便宜上ここに記載していますが、任意です）。

入力	備考	ユーザーが迷っている場合
LastName	管理者ユーザーの姓です。最大 80 文字です。	新しい組織の管理者ユーザーの姓を指定します。管理者の連絡先名にすぎないため、ユーザー自身の姓を使用してください。
FirstName	任意です。 管理者ユーザーの名です。尋ねてください。ただし、ユーザーが指定しない場合は省略して進めてください。	任意です。迷っている場合は空欄にしてください。管理者ユーザーに必須なのは LastName のみです。
Username	管理者のログインユーザー名です。メールアドレス形式で、すべての Salesforce 組織を通じて一意である必要があります。最大 80 文字です。保存時に小文字化されます。	実在する受信トレイである必要はありません。メールアドレスのような形式で、一意であれば問題ありません。admin@<company>-<something-unique>.com のような形式を提案してください。重複した場合は、作成時にユーザー名重複エラーが返されるため、別の値を選んでください。
SignupEmail	管理者ユーザーの実際のメールアドレスです（ウェルカムメール／ログインメールの送信先です）。	このアドレスはユーザーがアクセスできる有効な受信トレイである必要があります。Username とは異なり、実際に使えるアドレスを指定してください。
Company	会社名／組織名です。最大 80 文字です。	トライアル組織に表示する組織名です。説明的な名前であれば何でもかまいません。
Country	ISO 国コードです。最大 3 文字です。例：US、GB、IN、DE。実行時に許可されたコードと照合され、禁輸対象または無効なコードは拒否されます。	国の 2 文字の ISO コードを使用してください（例：米国は US、英国は GB）。自由記述の国名ではありません。

次のいずれか一方のみ（必須。どちらかを選択し、両方は指定しないでください）：

入力	備考	ユーザーが迷っている場合
TemplateId	Trialforce テンプレート ID（キーのプレフィックスは 0TT、15 文字）です。トライアル組織の製品／コンテンツを定義します。	特定の事前構築済みの製品／コンテンツセットが必要な場合は、テンプレートを使用してください。利用可能なテンプレートを確認するには、ホスト組織に対して次のクエリを実行します：sf data query -o <HOST_ORG> -q "SELECT Id, TemplateName FROM TrialforceTemplate" --json。一般的なトライアル組織でよければ、代わりに Edition を使用してください。
Edition	テンプレートを使わない一般的なトライアルの組織エディションです。一般的な値：Developer、Group、Professional、Enterprise（ServiceProfessional、SalesEnterprise も使用できます）。パートナー／Trialforce エディションは権限によって制御されます。	「いろいろ試すための開発者組織」が必要なだけなら、Developer を使用してください。パートナーエディション（PARTNER_*、TRIALFORCE_*）は、ホスト組織にパートナー／TMC 権限がある場合にのみ使用できます。権限がない状態で使用すると、noPartnerAccess エラーが返されます。

ユーザーには、TemplateId または Edition のどちらか一方を選ぶよう尋ねてください。両方を選ばせてはいけません。

• どちらも指定されていない場合 → 停止して尋ねてください。テンプレートもエディションも指定せずに作成すると、missingEdition（ApiErrorCodes.INVALID_SIGNUP_OPTION）で検証に失敗します。
• 両方が指定された場合 → どちらか一方を選ぶよう尋ね、選択されたフィールドだけを送信してください。両方を組み合わせると redundantTemplateId で失敗します。どちらもクローン／ソース組織のフィールドと組み合わせることはできません。

このスキルでは、ユーザーから収集する項目を上記のフィールド（常に必須の 5 項目と任意の FirstName）に限定しています。他のフィールドを尋ねたり、提示したりしないでください。SignupRequest エンティティは、その他の任意フィールドや権限によって制御されるフィールド（TrialDays、Subdomain、PreferredLanguage、SignupSource、OAuth の戻り値のペアなど）もサポートしていますが、ここでは対象外であり、サーバーのデフォルト設定に任されています。これらは参考情報として references/signup_request_fields.md に記載されていますが、このスキルから送信しないでください。

ステップ 1 — SignupRequest を作成

収集した入力を使って作成スクリプトを実行します。このスクリプトは「TemplateId と Edition のどちらか一方のみ」というルールを適用し、--values ペイロードを組み立てて引用符で囲み、挿入を実行し、成功時には割り当てられた 0SR… ID を出力します。スキルディレクトリ内のスクリプトは、絶対パス（<skill_dir>/scripts/…）で指定してください。ユーザーの作業ディレクトリを基準に解決される ./scripts/ は決して使用しないでください。

テンプレートを使用する場合：

SR_ID=$(bash "<skill_dir>/scripts/create_signup_request.sh" \
  --target-org <HOST_ORG> \
  --last-name <LAST_NAME> --email <EMAIL> --username <UNIQUE_USERNAME> \
  --company "<COMPANY>" --country <ISO> --template-id 0TT... \
  --output-dir force-app/main/adk-eval-output)

エディションを使用する場合（テンプレートなしの汎用トライアル）： --template-id 0TT... を --edition Developer（または Enterprise など）に置き換えます。ユーザーが指定した場合に限り、--first-name <NAME> を追加します。このスキルでは、ほかのオプションフィールドは送信しません。このスクリプトは、--template-id と --edition の両方が指定された場合、またはいずれも指定されなかった場合にエラーを返します。

--output-dir を渡してください（存在する場合は force-app/main/adk-eval-output を使用します）。これにより、作成が拒否された場合でも、スクリプトは作成拒否の結果と未加工のエラーをそのまま記録した <output-dir>/signup-request-result.json を書き込みます。組織が作成されない場合でも、これは実行時の出力アーティファクトになります。成功時は、代わりにステップ 2 の読み戻し処理でこのファイルを書き込みます。

成功時、スクリプトは 0SR… の SignupRequest ID を出力します（これを SR_ID として取得してください）。代わりに --json を渡すと、組織ではなくハンドルを含む未加工の sf 作成エンベロープが取得されます：

{ "status": 0, "result": { "id": "0SRxx0000000000", "success": true, "errors": [] } }

作成エラー（同期的なフィールド検証）への対処。 作成が拒否されると、スクリプトはゼロ以外の終了コードで終了し、未加工の CLI エラー（name／code と message）を標準エラー出力に表示します。これをそのまま伝え、以下の表に従って対応してください。--output-dir が指定されている場合、スクリプトは作成拒否のアーティファクト（{ "outcome": "create-rejected", "error": {…}, "CreatedOrgId": null, "Status": null }）も <output-dir>/signup-request-result.json に書き込みます。このファイルを手作業で作成しないでください。これはフィールド検証による拒否であり、即座に返されます。ステップ 2 の非同期 ErrorCode とは異なります。これらはサーバー側での拒否です（レコードは組織に到達し、挿入時にプラットフォームによって拒否されます）。ユーザーに「クライアント側」のエラーとして説明しないでください。CLI はメールアドレスや国の形式、選択リストの値、フィールドの長さをローカルでは検証しません。作成に失敗した場合はポーリングを行わず、ステップ 2 に進まないでください。

失敗	意味 → ユーザーに伝える内容
missingEdition / INVALID_SIGNUP_OPTION	TemplateId も Edition も送信されていません。どちらかを指定して再試行するよう伝えてください。
redundantTemplateId	TemplateId と Edition の両方が送信されています。どちらかを削除して再試行してください。
noPartnerAccess / NO_PARTNER_PERMISSION	パートナー／TSO エディションがリクエストされましたが、ホスト組織に必要な権限がありません。汎用エディション（Developer など）を使用するか、権限を取得してください。
重複または無効な Username（INVALID_EMAIL_ADDRESS）	Username がメールアドレス形式ではないか、全体で一意ではありません。別の値を指定して再試行するよう伝えてください。
INVALID_SIGNUP_COUNTRY	Country が有効または許可された ISO コードではありません。修正して再試行してください。
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST	Edition がホスト組織の制限付き選択リストで受け入れられる値ではありません（例：Ultimate）。有効な汎用エディションを選択して再試行してください。
STRING_TOO_LONG	フィールド値が最大長を超えています（メッセージにはフィールド名と max length が示されます。例：LastName が 80 文字を超過）。短くして再試行してください。
subdomainInUse / 無効なサブドメイン	選択した Subdomain はすでに使用されているか、無効です。別のものを選択してください。
NOT_FOUND（"The requested resource does not exist"）または INVALID_TYPE（"sObject type 'SignupRequest' is not supported"）	SignupRequest エンティティが公開されていません → この組織にはトライアル組織を作成する権限がありません。再試行しても解決しません。 処理を停止し、CLI の生のエラーをそのまま（name／errorCode と message）表示してから、組織を有効にするためSalesforce サポートに問い合わせるようユーザーに伝えてください。不足している権限の名前を挙げたり、原因を診断したりしないでください。
INSUFFICIENT_ACCESS_OR_READONLY	エンティティは公開されていますが、ユーザーにレコードを作成するアクセス権がありません。これは上記の組織の権限付与の問題とは異なる、ユーザー権限の問題です。ユーザーの権限を修正して再試行してください。

エラーコードとプレフィックスの全一覧 → references/error_codes.md。

• 必須／任意フィールドの全一覧、型、権限によって制限されるフィールドについては、references/signup_request_fields.md を読み込んでください。
• TemplateId をクローン／ソース組織のフィールドと一緒に送信しないでください（redundantTemplateId エラーになります）。ホスト組織にパートナー／TMC 権限がない場合は、パートナー／Trialforce エディションをリクエストしないでください。

ステップ 2 — 組織 ID を取得したらリクエストを読み取る（作成は非同期）

挿入後、プロビジョニングは非同期で行われるため、割り当てられた組織 ID を取得するにはレコードを再読み取りします。読み取りスクリプトを実行します。このスクリプトは、内部で固定された上限付きの読み戻しポリシーを適用し、CreatedOrgId が設定された時点、またはステータスが終端状態になった時点で停止します。無期限にポーリングすることはありません。レコードを JSON として出力し、--output-dir が指定されていれば出力アーティファクトを書き込みます。その後、スクリプトの終了コード（以下）に従って対応します。再試行回数と遅延はスクリプト独自の決定論的なロジックです。説明文で再実装したり、数え直したりしないでください。組織 ID がまだ取得できない場合、スクリプトは 3 で終了するため、リクエスト ID をユーザーに伝えられます。

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" [--output-dir <DIR>]

スクリプトは SignupRequest レコード（sf エンベロープの result）を JSON として出力します。以下のフィールドを確認してください。

• CreatedOrgId — 新しいトライアル組織の ID（00D…、15 文字）。組織が割り当てられるとすぐに設定されます（多くの場合、Status がまだ InProgress の間に設定されます）。これがスクリプトの停止条件です。
• CreatedOrgInstance — 新しい組織をホストするインスタンス（後続の呼び出し先）。
• Username — レコード上の管理者ログインユーザー名。生の入力値ではなく、レコードから読み戻した値を報告してください。保存時に小文字に変換されるため、保存された値がユーザーに伝える正確な値です。
• Status — ライフサイクルの状態。New → InProgress → Success | Error（大文字・小文字を区別せず照合）。
• LoginUrl — 作成時に IsSyncLogin が設定されている場合にのみ存在します（権限による制限あり）。
• AuthCode — ConnectedAppConsumerKey と ConnectedAppCallbackUrl が設定されている場合にのみ存在します。
• ErrorCode — Status = Error の場合にのみ設定されます。これは非同期プロビジョニングのエラーです（ステップ 1 の同期的な作成時検証とは異なります）。以下のプレフィックスが付与されます。
  • C- 組織作成エラー · S- サインアップデータエラー · T- テンプレートエラー（例：T-0002 = テンプレートが見つかりません） · SH- 組織形状エラー · VR- バージョン選択エラー · X-0001/X-0002 致命的エラー／本来発生しないはずのエラー。

スクリプトの終了コードに従って対応してください。**組織 ID の検索が最初に実行されます。スクリプトが戻るまで、ユーザーには何も報告しないでください。**レコードに実際に存在する情報のみを報告し、Status を作り上げたり別の状態として伝えたりしないでください。

• 0 — CreatedOrgId が設定されています。ステップ 3 に進み、レコードの実際の Status と Username とともに組織 ID を報告します。
• 3 — 組織 ID はまだ取得できません（エラーではありません）。組織はまだ割り当てられていません。スクリプトは上限付きの読み戻しをすでに最後まで実行しています。ポーリングを続けるために、ループ内でスクリプトを再実行してはいけません。****SignupRequest ID（0SR…）、レコードから返されたとおりのStatus、および Username を報告してください。組織 ID はまだ取得できないことをユーザーに伝え、後で再確認してもらいます（ステップ 3 を参照）。
• 1 — Status = Error（停止し、ErrorCode とそのプレフィックスの意味を references/error_codes.md に従って報告します。組織は作成されていません）、または読み取り自体が失敗しました（認証の期限切れ、0SR ID が見つからない）。生の CLI エラーを提示して停止してください。

ステップ 3 — 詳細を報告し、状況確認方法を案内する

ステップ 2 の照会が返ってきた後に報告します。前もって報告してはいけません。ユーザーが組織の作成（または再確認）を求めた場合は、まず読み戻しを実行して完了を待ち、その後、利用可能な詳細をすべてまとめてユーザーに報告します。記録にある内容だけを報告してください。値を捏造したり、別の意味に置き換えたりしてはいけません。特に Status は、応答オブジェクトに含まれる文字列と完全に一致させてください。

• SignupRequest id — 0SR… 形式のリクエスト ID（ステップ 1 で取得）。必ず報告してください。これはユーザー（または後で確認する際）がリクエストを再照会するための識別子であり、組織 ID がまだ取得できない場合に最優先で伝える情報です。
• CreatedOrgId — 新しいトライアル組織の ID（00D…）。値が設定されている場合に報告します。読み取り時に終了コード 3 が返された場合（組織 ID がまだ取得できない場合）は、リクエストは受け付けられており、組織は現在プロビジョニング中で、まだ共有できる組織 ID がないことを明確に伝えてください。
• CreatedOrgInstance — 値がある場合は、組織をホストするインスタンス。
• Username — レコードに保存されているとおりの管理者ログインユーザー名（保存時に小文字化されています）。必ず報告してください。組織の準備が整った後、ユーザーがログインに使う情報です。
• Status — レコードに記載されている Status の値。応答に含まれる文字列をそのまま伝えてください。対応付けたり、翻訳したり、推測したり、固定リストから選んだりしてはいけません。この時点で処理待ちのステータスでも問題ありません。プロビジョニングはバックグラウンドで完了します。
• LoginUrl / AuthCode — 値がある場合に限ります。

また、新しい組織のログイン情報はメールで届くこともユーザーに伝えてください。プロビジョニングが完了すると、SignupEmail のアドレスにウェルカムメール／ログインメールが送信されるため、ログインを完了できるよう、その受信トレイを確認するよう案内します。このため、SignupEmail には実際に利用できるアドレスを指定する必要があります。

その後、プロビジョニングがまだ進行中の可能性があるため、後で状況を再確認する方法を平易な言葉で案内します。ユーザーは次のように依頼するだけで再確認できます（このスキルがレコードを再読み込みします）。

• 「トライアル組織 00D… の状況を確認して」（組織 ID を指定）、または
• 「サインアップリクエスト 0SR… の状況を確認して」（SignupRequest ID を指定）。

どちらの場合も、同じ SignupRequest レコードに対してステップ 2 の読み取りスクリプトを再実行します（組織 ID はそのレコードから照会されます）。後で確認したときは、レコードに返されたそのままの現在の Status を報告してください。レコードにエラーステータスが返された場合は、ErrorCode と、その接頭辞が示す意味も references/error_codes.md を参照して報告してください。

出力成果物。 ステップ 2 の読み取りスクリプトに --output-dir を渡し、現在の SignupRequest レコードを実行の出力成果物として書き込みます。スクリプトは <output-dir>/signup-request-result.json に書き込みます（必要に応じてディレクトリを作成します）。force-app/main/adk-eval-output が存在する場合は、出力ディレクトリとして使用してください。

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" \
  --output-dir force-app/main/adk-eval-output

これは実行で定義された出力です。書き込み前に許可を求めてはいけません。

参照ファイル一覧

ファイル	読み込むタイミング
references/signup_request_fields.md	フィールドの完全なリファレンス — 必須／任意フィールド、型、デフォルト値、権限で制御されるフィールド、エディション
references/error_codes.md	ErrorCode の接頭辞と、よくある検証エラーの解釈

サンプルファイル

ペイロードや応答の具体的な形式を確認する必要がある場合に限り、これらを読み込みます。サンプルはプレースホルダー ID（0SRxx…、00Dxx…）を使った例であり、送信する値ではありません。

ファイル	読み込むタイミング
examples/create_request.json	作成内容を組み立てる際 — SignupRequest の作成ペイロードのフィールド名と形式を確認するため
examples/success_response.json	作成成功後に読み戻した内容を解釈する際 — CreatedOrgId が設定された後のレコードを確認するため
examples/error_response.json	作成が拒否された場合の解釈 — よくある検証エラー／エラー応答の形式を確認するため