見出し画像

Jira Cloud からConfluenceページを生成する方法：実装テクニック - 後編

Gen

こんにちは、Genです！

さて、前回の続きです。


前編では2つの方法を紹介してきました：

①Jiraチケット画面>[Confluenceページの作成] メニュー

②Jiraの自動化ルールでConfluenceページを自動作成


前編はこちらの記事をご覧ください：

しかし人間の欲望は尽きない…
もっと…便利にしたい…


Jira Cloud と Confluence Cloud はここまで連携できるようになったのか！と感心。

…しかし人間の欲望は尽きません…もっと…便利にしたい…

例えば、

  • Jiraのフィールドの内容に基づいてページのテンプレートや作成先の親ページやスペースを変えたい

  • 作成されたページのリモートリンクをJiraチケットにつけたい


ここからは３番目の柔軟な分岐が可能な高度なConfluenceページの自動作成処理を伝授します。


JiraチケットからConfluenceページを作成 [高等テクニック編]

構成概念

今回実装する自動ページ作成処理のプロセスは以下です：

①Jiraのチケット上から自動化ルールを発動させます
②自動化ルールの処理内で「Webhookの送信」を使って、Confluence CloudのAPIをコールします。
③コールされたAPIによって、テンプレートページをコピーして新規ページを自動で立ち上げます。
④自動で作成されたページの情報をAPIのレスポンスデータから拾って、自動化ルール内の後続処理でルールを発動したチケットのフィールドに自動ででPageID と Page URL を自動入力させます。

それでは作ってきましょう！


Step0. APIトークンの準備 (Atlassian Account)

それではAPIをコールする際に必要なキーである「APIトークン」というものを取得してきましょう。

https://id.atlassian.com/manage-profile/security/api-tokens にアクセスします

このようなページが表示されるので、上部にあり[ APIトークンを作成する ] を選択します。

ポップアップ画面が出るので、API トークン名として用途がわかるような名前を付けます。そして、API トークンの有効期限を選択します。

これは最近のアップデートですね。

今までは無期限のトークンが発行できたのですが、セキュリティ強化の一環として最大１年間に制限されました。
＊これは新規のトークンからの変更で、仕様変更前の既存のトークンは無期限のまま利用できます。

トークンの有効期限を 1 ～ 365 日の中で指定し、[作成] を選択します。

作成されるとトークンが表示されるので、右側のボタン[コピー] を選択し 、トークンをスクリプトに貼り付けるか、安全な場所に保存してください。

＊このトークンは公開された場所に貼らないように十分注意してください。

APIトークンは生成時に表示されるこのポップアップの時だけです。
[終了] をクリックするとポップアップが落ちて、同じAPI トークンを再度取得できなくなるので必ずどこかに控えておいてくださいね。（パスワード マネージャー等に保存することをお勧めします。）

これで「APIトークン」を取得できました。しかし、このまま自動化ルールの中で使うことができません。もうひと手間が必要です。

次に行うことはこのトークンをエンコードします。

＊エンコードとは「暗号化」という意味で、データを一定の形式であるランダムの文字列に変換します。そうすることで、受送信時にちゃんとデータが届くようにします。例えば、何か物を送るときにそのままで送ると途中で壊れてしまったり、相手が自分宛ての荷物だとわからないかもしれないですよね。なので、ちゃんと届くように梱包して送るっていう感じでしょうか。


それではエンコードしていきましょう。

まず、エンコードができるオンラインツール（Base64 Encode など）にアクセスします。

そこでinputとして "$emailAdress:$apiToken" の形式で入力します。
$emailAdress → トークンを発行したユーザーのアドレス
$apiToken → 先ほど取得したトークン

そうすると、下のOutputにエンコードされた文字列が出てきます。

この文字列をトークンと同様に安全な場所に保存してください。（トークンと分けて、encoded token として分かるようにして保存しておくことをおススメします）自動化ではこのエンコードされたトークンを使用します。


はい、これでひとまず最初の下準備は完了です！



Step1. カスタムフィールドの準備 (Jira Cloud)

次に、この後に実装する自動化で使用するフィールドを用意します。

利用するカスタムフィールド

対象サイトに存在しない場合はカスタムフィールドを作成していきましょう。

  • Parent Page ID（フィールドタイプ：テキスト, 一行）
    →Confluenceページ作成時の作成先ページを指定します

  • Original Page ID（フィールドタイプ：テキスト, 一行）
    →コピー処理でページ作成する際にコピー元のページを指定します

  • Page URL（フィールドタイプ：URL）
    →生成したConfluenceページのリンクを差し込む先の項目です


自動入力・編集する場合は以下の点に注意：

  • 作成時→画面に対象のフィールドがないと自動化で編集できないので作成画面に配置してください

  • 編集時（作成後）→画面にフィールドがなくてもアクターが「Automation for Jira」の場合、特権で編集することが可能です。アクターが個別ユーザーの場合は編集時も編集画面に対象フィールドがないと自動化で編集することはできません。

フィールドが用意できたら、次にページの自動生成先の場所やテンプレートを用意します。



Step2. テンプレートページや作成先のスペースや親ページの準備 (Confluence Cloud)


自動生成させたいページの既定内容を検討しましょう。
テンプレートとするページを作ります。

そしてページを自動生成する先のスペースも用意します。

テンプレートのページが作成できましたら、
そのページのIDを控えておいてください。

ページIDは作成したページの表示ビューのURLでhttps://yoursitename.atlassian.net/wiki/spaces/spacekey/pages/xxxxxxxx のxxxx部分がIDになります。

＊自動化ルールでの値指定で使用します。

URLヘッダーにある、この赤枠のところね

複数のテンプレートページを作成して異なるIDを取得すれば、入力されるOriginal Page ID に基づいて異なるテンプレートの新規ページを自動作成させることが可能です。



Step3. ページ自動生成ルールの構成 (Jira > Automation)

トークンを発行→カスタムフィールドを準備→作成先スペースの準備→作成先の親ページやテンプレートページのIDを取得

という流れで準備をしてきました。ここからいよいよ自動化の実装に入っていきます。


3-1: トリガーの作成

まず、トリガーを決めます。
今回は「手動トリガー」を使いましょう。

3-2: 「条件」の追加

後続処理でAPIコールするので、必要な情報が載っているフィールドが空欄だったり二重処理が起きるとエラーの原因になってしまうので、ルールでの条件としてフィールド値のチェックをするように条件を入れてきます。

条件の追加でフィールド条件> 「“Page ID” が空欄であること」　を追加します。
＊生成されると入力される構成にするので、空欄であることを条件にすることで二重実行を防止します。


3-3: 「アクション」の追加（①Confluenceページ自動作成）

次にConfluenceページを生成するAPIを叩くアクションを追加します。
アクションは「Send WebRequest（Webリクエストを送信）」を使用します。

このアクションでは以下の項目にデータを入れていきます。

①WebリクエストURL：ここには実行したいAPIのエンドポイントURLを入れます。

②HTTPメソッド：システムにおけるデータ処理において、基本操作機能を果たすための方法です。
データを操作する際の基本的な機能は
1: Create（作成）
2: Read（参照）
3: Update（更新）
4: Delete（削除）
の4つであり、これらを頭文字を取ってCRUD と総称します。
CRUDの中から作りたい機能に必要なメソッドを選択します。
メソッドはいくつかありますが、ここではGET/POST/PUT/DELETE/PATCH/HEAD の6つから選択します。

③Webリクエスト本文：ここには処理をする際に必要な情報を記載します。更新する場合は書き換える内容、作成する場合は作成内容のデータを記載します。（JSON形式で書きます）

④ヘッダー：APIを呼び出す際のメタデータです。


①WebリクエストURL

今回の処理はテンプレートページを「コピー」してタイトルを書き換えてページの新規作成をする処理です。なので、Copy single page（/wiki/rest/api/content/{id}/copy）のAPIを使用します。


書き方としては「https://yoursitename.atlassian.net/wiki/rest/api/content/{{コピー元のページID}}/copy」という形で入力します。

②HTTPメソッド

このAPIでは「POST」を選択します。

③Webリクエスト本文

ここにはコピー元のページの情報、作成先の親ページの情報、タイトル名などを定義します。

まず、データタイプとして「カスタムデータ」を選択します。

選択すると入力欄が追加されるので以下の内容を設定してきます：

{
  "copyAttachments": true,
  "copyPermissions": false,
  "copyProperties": true,
  "copyLabels": true,
  "copyCustomContents": true,
  "destination": {
    "type": "parent_page",
    "value": "{{issue."Parent Page ID"}}"
  },
  "pageTitle": "{{issue.key}} - {{issue.summary}}"
}

その下にチェックボックスがあると思います。
ここは「API呼び出しをしてレスポンスが返ってくるまでこのルールでの後続処理を待ちます」という設定なのでチェックをしておきましょう。

これがチェックされていないとページが作られてそのPage IDが返ってくる前にそれを必要とする処理が先に動き始めてしまい、エラーになってしまいます。

④ヘッダー

ヘッダーは3項目設定してきます：

  • Authorization
    ⇨「Basic xxxxxxx」 *xxxのところに最初に取得したエンコード済みのAPIトークンを入れます。

  • Accept
    ⇨「application/json;charset=UTF-8」

  • Content-Type
    ⇨「application/json」

一通り入力するとこんな感じになるはずです↓

この「アクション」によって、Confluenceページが自動作成されます。


3-4: 「アクション」の追加（②自動作成されたConfluenceページのIDとURLをJiraチケットで取得）

今の構成のままだとConfluenceページが作成されてもJiraチケット上からだと作成されたかわからないので、
ページ自動作成の後のアクションとして、ルールを発動したJiraチケット上に作成されたConfluenceページのリンクを自動で入力する処理を作っていきます。

APIコールをすると向こう側のシステムからレスポンス（返事）がくるようになっています。
今回使用するAPIのレスポンス内容には作成されたページのIDが含まれているのでそれを取得して、

https://yoursitename.atlassian.net/wiki/spaces/spacekey/pages/ + {{レスポンスデータに含まれるPageID}}（生成されたPage ID）　

という構成でページ生成後にURLを成立させます。

先ほどのConfluenceページの作成APIをコールすると以下のようなレスポンスデータが返ってきます：

{
    "id": "{pageID}（作成されたページのページID）",
    "type": "page",
    "status": "current",
    "title": "作成されたページのタイトル",
    "space": {
        "id": spaceid,
        "key": "{KEY}（作成先のSpaceKey）",
        "alias": "{KEY}",
        "name": "{SpaceName}",
        "type": "global",
        "status": "current",
        "_expandable": {
            "settings": "/rest/api/space/{KEY}/settings",
            "metadata": "",
            "operations": "",
            "lookAndFeel": "/rest/api/settings/lookandfeel?spaceKey={KEY}",
            "identifiers": "",
            "permissions": "",
            "roles": "",
            "icon": "",
            "description": "",
            "theme": "/rest/api/space/{KEY}/theme",
            "history": "",
            "homepage": "/rest/api/content/{homepageID}"
　　　・・・（省略）

このレスポンスデータから作成されたPageIDを取得するためにスマートバリューを利用して「{{webResponse.body.id}}」 から
API「Copy single page（/wiki/rest/api/content/{id}/copy）」のレスポンスデータからのIDを取得するようにします。

アクションコンポーネント「課題の編集」を選択し、2つのフィールドに値を設定します：

  • Page URL：https://yoursitename.atlassian.net/wiki/spaces/{{webResponse.body.space.key}}/pages/{{webResponse.body.id}}

  • Page ID：{{webResponse.body.id}}


設定するとこんな感じ↓


3-5: 動かしてみよう

ここまで出来たら、一回動かしてみましょう。
構成中のルールの名前を設定して一旦公開しましょう。

公開できたら、チケットに移動して自動化をトリガーしてみます。

実行するチケット画面上のParent Page ID とOriginal Page ID に値を設定します。最初のステップで用意したテンプレートページを使って、テンプレートページの下に自動生成してみたいので、テンプレートページIDを2つのフィールドに入力します。

入力できたら、ステータス右側の [ アクション ] を選択して今回実装した自動化ルールを選択して実行します。

ルール実行後に少し待つと…

お！チケットのPageURLとPageIDに自動作成されたConfluenceページの情報が入ってきましたね。

入ってきたリンクをクリックして開くと、

ちゃんとテンプレートページがコピーされて新規のページが作成されています。そして、トリガーしたチケットのキーと要約を使ってタイトルになっています。

大成功です！


はい、今日はここまでにしましょう。

トリガーをステータスの変更などの別の発動条件にしたり、別の自動化でOriginal Page ID や Parent Page ID の設定を法則化すれば、作成先や利用テンプレートを条件分岐させることができるので、かなり柔軟にConfluenceページの自動作成ができるようになるはずです。


これを応用することで様々な業務の場面で活用できます：

  • 製造における文書管理

  • ブログ執筆管理

  • ミーティングの議事録管理
    etc.

ぜひお試しください！！


APIを活用してさらに高度な業務管理の仕組みを作ろう


APIを活用することで、さらに高度な業務管理の仕組みを構築することが可能です。確かにその難易度は高く、管理も複雑になりますが、基本設定では実現できない独自のソリューションを作り出せる点は大きな魅力です。

特にAtlassian製品は、APIのバリエーションが非常に豊富であることが特徴で、拡張性を重視した製品設計がその背景にあります。


「自動化」に猛進しても業務は効率化しない

ただし、業務の効率化を追求する際に「自動化」にばかり注力するのは得策ではありません。重要なのは、まず業務プロセスを洗練させ、そのプロセスの一部を自動化することで、真に効果的な改善が可能になるということです。

美しい業務プロセスを目指しましょう。

次の投稿では「リモートリンク」の自動設定の方法について解説してきたいと思います！

それでは！


いいなと思ったら応援しよう！