プレイブックを作成してバージョンを保存する

プレイブックを作成すると、最初のバージョンも同時に保存されます。内容を更新するときは、新しいバージョンとして保存します。保存したバージョンの内容は固定されるため、以前の案件で使った手順も確認できます。

CLI の publish は、このバージョンを保存する操作です。更新では現在の最新バージョン ID を変更元として指定します。保存後も現在の共有設定が適用されます。目的に合わせて、次の操作を選びます。

入力ファイルを用意する

次の例を作業ディレクトリの playbook.json に保存します。選択中のワークスペース、または個人スペースに、作成者だけが使うプレイブックを作る例です。コマンドを実行する前に、選択中のワークスペースを確認してください。

{
  "private": true,
  "definition": {
    "schemaVersion": 1,
    "title": "AI 活用の試行を評価する",
    "description": "顧客の目標を確認し、試行の評価方法を合意します。",
    "category": "operations",
    "inputSchema": {
      "type": "object"
    },
    "steps": [
      {
        "title": "顧客の目標を確認する",
        "instructions": "合意した範囲、現状値、評価指標、判断者を記録します。"
      }
    ]
  }
}

ワークスペースで作成するときは、初期共有設定として、作成者への共有を表す private: true、チームへの編集権限を表す teamIds、共有設定全体を表す access のいずれか1つを指定します。最初から顧客用チームへ共有するなら、この例の "private": true を "teamIds": ["<client-team-id>"] に置き換え、実際のチーム UUID を指定します。両方は指定しません。

更新時は playbook.json を next-version.json に複製し、最上位の private を削除してから、definition 内の内容を編集します。更新用ファイルの最上位には definition だけを残し、作成時だけの ownerId・private・teamIds・access は含めません。変更元のバージョン ID は、次のコマンドの --base-version-id で指定します。@ は指定した JSON ファイルを読み込む記法です。

入力項目の定義、各手順、参照ツールの書き方はプレイブックを書くを参照してください。

epismo playbook create --request @playbook.json
epismo playbook get <playbook-id>
epismo playbook version publish <playbook-id> \
  --base-version-id <latest-version-id> --request @next-version.json

競合した場合は最新バージョンを取得し、自分の変更を現在の内容に合わせて反映し直します。

下書きで先に試す

内容を試しながら調整するときは、まず下書きに保存します。下書きは何度でも編集でき、保存するたびにバージョンが増えることはありません。内容が固まったら draft publish で新しいバージョンとして保存します。小さな変更なら、下書きを使わず version publish で直接バージョンを作ることもできます。

draft.json は next-version.json と同じ形式で、最上位の definition に変更後のプレイブック定義全体を入れます。--base-revision には draft get で取得した下書きの更新番号を使います。下書きがまだない場合だけ 0 を指定します。

epismo playbook draft get <playbook-id>
epismo playbook draft save <playbook-id> --base-revision <revision> --request @draft.json
epismo playbook draft publish <playbook-id>
epismo playbook draft discard <playbook-id>

--base-revision には最後に読んだ更新番号を指定します（新規下書きは 0）。古い値を指定すると、その間に別の人が保存したという意味なので、読み直してから再試行してください。プレイブックが持てる下書きは1件で、そのプレイブックを編集できる人だけが読めます。draft publish は下書きの内容からバージョンを作り、同時に下書きを破棄します。draft discard はバージョンを作らずに下書きだけを破棄します。

• 共有設定： access: { visibility, grants } を使います。restricted では指定した人やチームに viewer（閲覧）・editor（編集）の権限を付けます。public（一般公開）では誰でも保存済みバージョンを閲覧できます。
• エイリアス：覚えやすい参照名。権限は付与しない。
• 共有 URL：プレイブックのページへ転送し、閲覧時には現在のアクセス権限が適用されます。現在の共有 URL には有効期限も取消操作もありません。
• 下書き：編集権限が必要な、バージョンになる前の編集中の内容。共有 URL は権限を付与しません。

顧客用チームへ共有する

内容をバージョンとして保存したら、使うチームへ共有します。顧客の業務では共有設定を restricted にし、必要なチームへ権限を付けます。先に顧客用チームを用意し、顧客専用の方法にする場合は適したバージョンをコピーします。

コピー先の現在の共有設定を読みます。例えば、社内チームが維持し、顧客用チームには閲覧を許可する場合は次の形です。

epismo playbook access get <client-playbook-id>
epismo playbook access set <client-playbook-id> \
  --access '{"visibility":"restricted","grants":{"<internal-team-id>":"editor","<client-team-id>":"viewer"}}'

これは設定全体の例であり、共有先の追加だけを行うものではありません。取得した設定から必要な他の共有先を残し、少なくとも1件の明示的な編集権限を保持します。顧客チームが更新する場合は editor にします。編集者は下書きの閲覧や共有設定の変更もできるため、保存済みの各バージョン・下書き・参照先が、その共有先に適した内容か確認します。

顧客の参加者が開き、意図した閲覧・編集ができるか確かめます。支援案件は別に共有します。プレイブックの権限は案件に引き継がれません。URL やエイリアスを送るだけでなく、チームへの権限設定が必要です。案件を引き継ぐも参照してください。