リックソフトのドキュメントサイトをクラウド移行してみた : Comala Document Management アプリ編

こんにちは。リックソフト ヘルプデスク の南澤です。

普段はヘルプデスクの業務だけではなく、ヘルプデスクで利用しているお問合せシステム(Jira Service Management)や、サポートドキュメントサイト(Confluence)の製品管理者も担当しています。

リックソフトでは、Atlassian(アトラシアン)製品をはじめとした製品ナレッジを記載したサポートドキュメントサイトを提供しています。
これまではAtlassian製品のConfluence Serverを使っていましたが、2022年4月にConfluence Serverから Confluence Cloudへ全コンテンツを移行しました。
その時に得た移行方法・ノウハウ等を、ブログで皆様にお伝えしたいと思います。

現在のサポートドキュメントサイトはこちらです。
(一部サポート購入対象者向けの閲覧限定コンテンツがございます)

今回は、ドキュメントレビューや公開処理に欠かせないComalatech社のComala Document Managementアプリケーション関連のCloud移行に絞ってお伝えします。
Comala Document Managementアプリを今までどのように活用していたのかについては、過去ブログをご参照ください。

■事前チェック

Server版からCloud版の移行で気になるランキング1位,2位に入るであろう アプリの対応有無について、私が調べたステップを紹介します。

【Confluence Cloud Migration Assistant(CCMA)でアプリを評価する】

Server版(オンプレミス)で使っていたアプリがCloudに対応しているか？データ移行はできるか？は気になりますよね。

Atlassianが提供しているConfluence Cloud Migration Assistant(以下、CCMA)を利用して、ConfluenceにインストールされているアプリのCloud対応状況を一括で確認できます。

※CCMAは、Confluence Server/Confluence Data CenterからConfluence Cloudへ移行するためのツールです。オンプレ版からのデータインポート、クラウド版へのデータエクスポートを自動で一括で行います。

CCMAの「Assess your apps」機能を使ってインストールされているアプリのCloud移行できるか否かを一括で確認します。

結果は以下のようになりました。

今回話題にしている、Comala Document Managementアプリは、「Exists in Cloud(Cloud 対応有無)」「Can be migrated(データ移行可否)」はともにOKでした。

安心するのはまだ早いです。

アプリによっては、Server版とCloud版とで機能差が大きいものもあり、また移行対象でないデータもある可能性があるからです。
結果画面のView Differenceリンクを見て、双方の違いをしっかり確認しましょう。

【アプリベンターのドキュメントを確認する】

●CloudとServer版の機能差を確認する

アプリベンダーのドキュメントを見て、CloudとServer版の機能差を事前に把握しておきます。
Comalaアプリのベンダーは以下のように比較ページを用意しています。

Differences Between Comala Document Management and Comala Document Management Cloud

●Cloud移行対象データを確認する

移行対象データや移行ガイドの詳細もドキュメントに掲載されていることが多いです。
Comalaアプリのベンダーは、移行ステップを詳細に紹介したページを用意しています。

Comala Document Managementアプリは、ページのステータスとアクティビティ(最新の履歴のみ)データを移行できます。

Check what is migrated to Confluence Cloud

【アプリベンダーへ問い合わせる】

事前確認の部分でわからないところがあれば、積極的にアプリベンダーへ英語で問い合わせてみましょう。
Comalaアプリの場合は、移行用の問合せに役立つデータを収集できるメニューがあります。

■Server&Cloud移行検証

【Confluence Cloud側の事前準備】

Confluence Cloud Premiumプランの場合はSanbox環境を作成できます。Sandbox環境にComalaアプリをインストールし、移行検証をしました。

移行操作の前にComalaアプリのConfiguration画面でEnable migrationsを有効にしておきます。

【Confluence Server側の手順】

●ComalaアプリとCCMAのバージョンアップ

Comala Document ManagementアプリとCCMAを最新バージョンへバージョンアップしました。

特に、CCMAは頻繁に更新がありますので、なるべく新しいバージョンにしておいたほうがいいです。
(逆に不具合も多いアプリなので、リリースしたてのCCMAバージョンは避けたほうがよい)

●CCMAを利用して移行を実施

CCMAを実行します。
※詳細手順は今回は省き、アプリに関するところだけ記載します。

Assess your appsでComala Document Managementアプリを「Needed in Cloud」に設定します。

Agree to app migrationではPolicyを開いてAgreeして先に進みます。

まずスペースやユーザーグループ情報を移行処理が走り、それらが完了後にアプリデータの移行が始まります。

アプリデータを移行工程(App data migration in progress)は、2スペース(計20ページ)で20分くらい時間がかかりました。
(所要時間は、ネットワークの状態やサーバースペック等、環境によって異なります)

■Cloud での動作検証

次のステップは 移行後のConfluence Cloudでのアプリの動作検証をします。

確認した内容は以下です。
Comalaアプリの場合は、Server版と比較するとCloud版アプリは機能がかなり減ります。
移行データのほかに、機能差をいかにカバーできるかも合わせて確認しました。

【移行対象データの確認】

移行対象のデータが移行できているかを確認します。

Comala Document Managementアプリは、ページのステータスとアクティビティ(最新履歴のみ)が移行対象データですので、それぞれ確認します。

●ステータスを比較

ページのステータスが移行されているか確認します。

＜Server版＞

＜Cloud版＞

●アクティビティ(Workflow History)を比較

最新の履歴が移行されているか確認します。

＜Server版＞

＜Cloud版＞

【クラウド版でのワークフロー検証】

この工程が一番苦戦しました。

Comala Document Managementアプリの要となるワークフロー情報は移行対象ではありません。
そのため、Cloud版に新しいワークフローを作成する必要があります。

●Cloud対応のワークフロー作成

Server版アプリ設定したワークフローのJSONデータをそのままコピーしてCloud版で利用することはできません。
JSONの記述ルールが双方で異なります。

Workflow Builderでも作成はできますが、こちらも双方に機能差があります。

Comalaアプリのドキュメントを確認しながらCloud版アプリのワークフロー設定を学び、Server版と同じワークフローを作成しました。

＜Server版＞

＜Cloud版＞

●ワークフロー操作検証

作成したワークフローが正常に動作するか確認します。うまく動作しない場合は、ワークフローの内容を見直します。

レビュー依頼をするときのレビューワーの指定の範囲、承認した後にステータスが動くか、却下したときもステータスが動くかを中心に確認しました。

※ワークフローの詳細は、過去ブログ をご参照ください。

●通知検証

ワークフローのTriggersに通知メールの発信タイミングや、送信先、メールの内容を指定できます。

Triggersの指定内容の形式もServer版とは異なるので、Comalaのドキュメントを参考に設定しなおします。

＜Server版＞

レビュワーアサイン時のメールカスタマイズができ、日本語化や本文のレイアウトも指定できた。

＜Cloud版＞

デフォルトの英語メールの形式で固定化される。

■レポート検証

レポートについてもServer版とは異なります。

Server版ではプロファイル画面&Document Actionsで、全スペースを対象に自分がアサインされているComalaワークフロー関連のレビュータスクを確認できていました。

Cloud版にはこの機能はありません。
そのため、代替案・・妥協案は以下の通りです。
欠点をカバーする方法が見つかっておらず、まだ通知メールで自分のレビュワーアサイン状況を把握するようにしています。
今後、この運用については改善していきたいと考えています。

●各スペース&Workfklow Report

スペースごとに各ページのステータスを把握でき、
My pending approvalsで自分の未完了レビューを抽出できます。→欠点：複数スペースをまとめて見られない

●ラベル別コンテンツマクロ

ページにラベルがあれば、ラベル別コンテンツマクロを利用して、特定のステータスのドキュメントを抽出できます。
→欠点：ページにラベルを付ける運用にしていないと利用できない

●REST APIを使用して取得

ConfluenceのREST API(Search content by CQL)でcw_state="ステータス"やcw_approvers="ユーザーID"で絞込してJSON形式でレビュー状況を取得できます。
→欠点：Confluence上でJSON形式から見やすい形式に変換する方法が標準機能にない。
（サードパーティ製アプリを導入すれば実現可能）

例

https://rs-support-doc.atlassian.net/wiki/rest/api/content/search?cql=cw_state=%22%E5%85%AC%E9%96%8B%E6%B8%88%22&limit=25

■本番移行

検証を十分に実施したため、アプリの移行、アプリに関する設定、テストは正常に実施できました。

■Cloud 移行のポイント (アプリ編)

【Cloud移行前に事前検証は大事！】

事前にテスト環境で Cloud 版アプリの設定、動作確認を入念に実施すると、本番移行をスムーズにできます。
(本番移行の記述の短さでわかっていただけたと思います)

不明点、気になる点はアプリベンダーが提供しているCloud版アプリドキュメントを読み、積極的にお問合せもして、疑問点や不安な内容をクリアにしましょう。

【Serverと同じようにはいかない! 少しの妥協は必要】

アプリだけに言えることではないですが、Server版ではできていたことが、Cloud版ではできないという機能もあります。

その機能が絶対にないと困るものなのか、組織に不可欠な機能なのか等、優先度を決めて、移行戦略を考えてみましょう。

Marketplaceを見て代替アプリがあるか調査する、Confluence Cloudの標準機能で実現ができるか調査する、現アプリで少し目をつぶって利用する、選択肢はいくつもあります。

【アプリベンダーのドキュメントやサポートを活用しよう】

Comalaアプリはドキュメントが充実しており、ワークフローや通知の設定のカスタマイズの例も多数掲載されていて、ワークフロー設定の助けになりました。
Server&Cloud移行関連のナレッジも多数あり、機能差や移行パスも記載されています。

また、移行にあたり、アプリベンダー(Comalatech社)のサポートへ問い合わせをしましたが、サポートの質もすごくよかったです。
例えば、Cloud側のワークフローがうまく実行できない時に私が設定したJSONファイルを渡したら、ベンダー側で修正したものを提供してくれ、無事にワークフローが動いたケースもありました。
Server版との挙動の違いも明確に回答をいただき、その後Cloudの場合の運用方針を決めやすくなりました。
サポートに感謝しています。

リックソフトでアプリのサポートを購入されている方は、アプリのCloud移行についてのご質問をリックソフトで対応できます。
ぜひご活用ください。

Comala Document ManagementアプリのConfluence Cloudでの活用事例については、また別のブログで紹介する予定です。
楽しみにお待ちください！