まだプログラマーですが何か？

プログラマーネタとアスリートネタ中心。たまに作成したウェブサービス関連の話も http://twitter.com/dotnsf

こちらの続きです：
ノーツデータベースの設計変更履歴を git で管理する（１）

↑のブログエントリを書いた時点では未完成だったインポート機能が使えるようになったので、続きのエントリとして紹介します。

上述の記事内で紹介した dxl_export.vbs ツールでエクスポートした XML データを元の NSF ファイルにインポートするのがもう一つのファイルである dxl_import.vbs です。以下のようにして使います（XML ファイルはフルパス指定が必要な点に注意してください）：
> c:\Windows\SysWOW64\CScript //nologo dxl_import.vbs C:\Users\username\dev_mydb.nsf\mydb.xml

成功すると指定した XML ファイルと同じフォルダ内に拡張子が .xml から .nsf になったノーツデータベースが復元されます。復元元のデータ（設計要素と文書）は XML ファイルです：
2023051601


復元されたデータベースをドミノデザイナーで開くと、設計要素も元の（dxl_exporter.vbs でエクスポートされる前の）状態で復元されているはずです：
2023051600


このツールの便利なところは XML データを git でバージョン管理できるという点にあります。つまり元のデータベースが変更される度に dxl_exporter.vbs を実行しておくことで、 git の履歴（ログ）を見て、必要に応じて過去のコミットに戻り（チェックアウトし）、過去の状態の NSF データベースに復元することもできるようになる、という点です。この dxl_importer.vbs が正しく動くようになったことでこちらの機能も動くようになりました。





タグ ：
notes
nsf
vbs
design
dxl
importer
exporter

（以下 2023/05/15 追記）
このブログエントリで紹介している DXL Import 機能は正しく動くようになりました。記録として残しておきますが、現状は問題なく動作します。
（以上 2023/05/15 追記）


自作ツール dxl.vbs を紹介する目的で先日こんなブログエントリを書きました：
ノーツデータベースの設計変更履歴を git で管理する

このツール（dxl_export.vbs）は HCL Notes のデータベースをテキスト(XML)化することで、本来はバイナリデータであるデータベースファイルの設計変更履歴（ちょっとカスタマイズするとデータも含めた変更履歴）を git で管理できるようにする、というものです。テキストデータになっていれば変更差分の履歴や、変更一回ごとに限らず任意の２つのタイミングでの変更差分を比較する、といったことも（git の機能として）可能になる、というものでした。

実はこの dxl.vbs にはもう１つ dxl_import.vbs というツールがあります。Export と Import ということで、なんとなく機能の想像がつくかもしれませんが「XML 化されたデータから Notes データベースを復元する」ためのものです。git で変更履歴を管理しつつ、どこかのタイミングで使っていた設計状態に git checkout して、その状態を作成した時のノーツデータベースを復元する、というためのものです。が、残念ながら現時点ではこちらは期待通りに動きません。その点に関する解説ブログエントリとして記載します。

もともとこのツールは LotusScript および Java の API として用意されている DXL Import/Export の機能を使って実装しています。ツールそのものは VBS で、いわゆる ActiveX/COM を使って NotesSession オブジェクトを生成し、そこからこれらの機能を呼び出すことで Export で XML 化し、Import で復元を実装しています。この Import 部分がどうも正しく動いていないように見えるのでした。

少し補足をすると、DXL Export を実行すると指定されたデータベースが XML 化されます。実はここにも一点問題があって、「データに日本語が含まれている場合、XML には encoding 指定のない（つまり UTF-8 ）データが出力されるが、実際にはシフト JIS の日本語データが含まれる」というものです。この時点で XML データとしての不整合が生じてしまっています。そのため本ツール（dxl_export.vbs）では、この XML データを書きだす前に強制的に encoding="Shift_JIS" を追加してから出力することで不整合を回避しています。

で、改めて dxl_import.vbs ですが、現状ではこのツールを実行することでノーツデータベースファイル（.nsf ファイル）を（日本語文字列含めて）復元することまではできています（※）。が、この復元結果をノーツクライアントから開こうとするとこのようなエラーが発生してしまって正しく開くことができないのでした：
20230508

↑左のアイコンがある方が元のデータベースで、これを dxl_export してから dxl_import したものが右のアイコンがない方。アイコンは復元できていないが、（日本語の）データベースタイトルは復元できている。でも開くことはできない。

※厳密には dxl_import.vbs 実行時に以下のようなエラーが発生しています。エラーにはなるけど .nsf ファイルは出力されている、という状況です：
2023051402


なお、この復元された（？）ノーツファイルを Domino Designer で開くと、フォームなどの設計要素が空になっています。という意味ではやはり DXL Import に失敗しているとみるべきなのだと思っています：
2023051401


XML の encoding 設定を勝手に書き換えたのがよくなかったのか、、と思ってやり直してみても結果は同じ。というわけで DXL Import がおかしいのか、あるいはその前の DXL Export の時点で何か間違っているのか、その両方なのか・・・　この辺りはもう手が出せないのでこれ以上の対応が難しいのですが、ここがなんとかなればこの１対のツールとしても完成すると思っています。


タグ ：
hcl
notes
dxl
xml
import
export

ノーツのデータベース（アプリケーション）はノーツクライアントやドミノサーバーが無いと開くことができないため、内容を確認したりデータ文書を追加したり、あるいはデータベースそのものの設計を変更したりする際には、原則的にこれらがセットアップ済みの環境が必要です。

特に設計に変更を加える場合、ドミノデザイナーという専用クライアントアプリが必要になります。Eclipse RCP をベースとしたツールとして提供されていますが、データベースそのものがバイナリファイルになっていることもあり、（例えば git などを利用してソースコードの変更履歴管理をする場合と比較して）設計の変更履歴を管理することが難しいのでした。

そんな背景の中、「じゃあノーツデータベースの変更履歴を git で管理できるようにならないか」というアイデアネタを思いつき、実現可能性のありそうな方法を見つけて試しに作ってみました。まだ理想形には至っていないのですが、当初の目的であった「git による変更履歴管理」はできそうな目途が立っているので公開します：
https://github.com/dotnsf/dxl.vbs

で、↑このページ内でも（英語で）使い方の説明をしているのですが、このブログエントリでは図を含めて日本語で紹介します。


【前提条件】
上記コードは MIT ライセンスのオープンソースとして公開しますが、正しく動作させる上での前提条件がいくつかあります：
  • Windows 64bit 環境（32bit でも多分動くが未検証）
  • Windows 版 git がインストール済み
  • ノーツがセットアップ済み
  • 対象データベースに対する設計者以上の権限がある

前提条件について補足します。まずこのツール自体が VBScript で出来ています。実現可能性や使っていただく上での条件をいろいろ考慮した結果、最もハードルが低そうなものを選択しました（これはこれで文字コードが Shift-JIS になってしまう制約があって苦労しました。が、他よりはマシだったと思っています）。この VBScript を動かすため Windows 環境が必要となります。変更管理ツールとしての git も Windows 環境下で動かす必要があります※。

※ WSL を併用している場合であれば、このツールを使って出力した結果のフォルダに WSL のターミナルを移動して WSL の git を使う、ということができないわけではありません。ただこのツール自体が Windows の CLI で動くものなので、コマンドプロンプトを起動して、ツールを実行して、実行結果をそのまま git で管理する、、という使い方が便利で、その場合は（WSL の git ではなく）Windows 環境で動く git 環境が必要です。　また Windows 版で GUI を提供する git もあるようですが、今回のツールを使う場合はコミット ID を指定しての差分比較などを行えることが便利だと思っていて、そういった操作までができる GUI 版 git であればいいのですが、私が軽く調べた限りではそこまでの GUI を持ったものがなかったので、CLI 版の利用をお勧めします。

また「ノーツが不要」というわけではありません。ツールを使って設計をテキストにエクスポートした後は git だけで使えますが、ツール利用時にはノーツが必要で、かつ対象となるデータベースに対して設計者権限または管理者権限がないと設計内容にアクセスできません。設計変更履歴を管理しようとすると何回もこのツールを利用することになると思っていますが、仮に「１回だけ利用して中身をテキスト化する」という目的であったとしても、実行時にはセットアップ済みノーツ環境が必要です。


【ツールの使い方】
ツールは Github のこのリポジトリで公開しています。git clone するか、zip download で README.md ごと取得してください：
https://github.com/dotnsf/dxl.vbs


リポジトリには dxl_export.vbs と dxl_import.vbs の２つのツールが含まれています。が、dxl_import.vbs はまだ開発途中で、期待通りの挙動は実現できていないので、2023年５月の現時点では実質的に dxl_export.vbs だけがリリースされている、とご理解ください。

ツールはコマンドラインツールなので、実行する上では Windows のコマンドプロンプトを使います（管理者権限は不要です）。コマンドプロンプトを開き、dxl_export.vbs を保存したフォルダに移動します：
2023051101


ここで CScript.exe （VBScript のコマンド）を実行して del_export.vbs を動かします。パラメータの最後に設計変更履歴を管理したいノーツデータベースを相対パスで指定します（下の例だと dev/mydb.nsf というデータベースを指定しています）。注意点として CScript.exe は必ず指定のフルパス（c:\\Windows\\SysWOW64\\CScript）を指定して実行する必要があります（64bit Windows ではパスを指定せずに CScript を実行すると 32bit 版の VBScript が実行されてしまいます。64bit 版 Windows では 64bit 版 VBScript を実行するためにこのフルパスを指定して実行してください：
> c:\Windows\SysWOW64\CScript //nologo dxl_export.vbs dev/mydb.nsf

このようなダイアログが表示された場合は、表示されているノーツ ID のパスワードを入力してください（一度入力しておくと次回からしばらくパスワードなしで使えるはずです）：
2023051001


dxl_export.vbs が正しく実行されると以下のような出力になります（この例だと dev_mydb.nsf/mydb.xml にエクスポート結果が出力されていることになります）：
2023051001


この出力された XML がパラメータで指定したデータベースファイル（dev/mydb.nsf）の設計情報を DXL(Domino XML Language) というフォーマットで出力したファイルになっています：
2023051001


本ツールでは、このバイナリデータベースが XML でテキスト化された状態を git でコミットすることを想定しています。具体的にはこんな感じ：
> git add dev_mydb.nsf\mydb.xml

> git commit -m "first comment"

これでこの状態の設計情報が（テキスト形式で）git に格納され、コミットされました。git はコミット単位で履歴を追ったり、比較できるようになるツールなので、まずはその履歴の１つが記録された状態になりました。

その後、このノーツデータベースになんらかの設計変更が加わったとします。例えば "myForm" という名前のフォーム要素を新たに追加したとします：
2023051101


何らかの設計変更が加わった状態で、再度この dxl_export.vbs ツールを実行します（コマンド自体は最初に実行したものと全く同じです）：
> c:\Windows\SysWOW64\CScript //nologo dxl_export.vbs dev/mydb.nsf

するとこの時点での設計情報が dev_mydb.nsf\\mydb.xml ファイルに記録（正確には上書き）されます。この結果をやはり同様に git でコミットします：
> git add dev_mydb.nsf\mydb.xml

> git commit -m "myForm added"

コミットの履歴は "git log" で確認することができます。↓の例では１回目の "first commit" というコメントの付いたコミットと、２回目の "myForm added" というコメントのついたコミットの２つを確認することができます：
$ git log

2023051102


２つのコミットログを並べて "git diff" を実行すると、コミット間の差分を表示することができます（以下の例では "myForm" に相当する設計要素が追加されたことがわかります：
$ git diff （変更前のコミットID） （変更後のコミットID）

2023051103


同様にしてデータベースに設計を加え、ツールを使って XML ファイルにエクスポートして、git でコミットし、git diff で比較することができます。以下の例では LotusScript プログラムの内容が表示できていることわかり、そのプログラムに後からコメントを追加している様子がコミット間比較によって視覚化されています：
2023051104


このように、
・データベースの設計を変更
・dxl_export.vbs ツールを実行
・git で差分をコミット
を繰り返すことで、バイナリデータであるノーツデータベースの設計変更履歴を git で管理することができるようになります。

（2023/05/12 追記　裏技の紹介）
dxl_export.vbs は VBScript なのでテキストファイルです。テキストエディタで開くことでカスタマイズもできます。

例えば 76 行目の
nc.SelectDocuments = selDocs           'Documents

となっている部分。これは「（データベースからエクスポートする要素として）各文書データは対象外とする」ことを指定しています。なので dxl_export.vbs をそのまま使った場合、設計要素のみが対象となって、文書データはエクスポート対象外となります。

ここを、
nc.SelectDocuments = True           'Documents

と無理やり変更して保存すると、文書データもエクスポート対象に含まれるようになります（ただし文書データも含めてエクスポートする場合はメモリ不足のエラーが発生する確率が高くなります）。テキストファイルとして読める形でアーカイブしておきたい場合などに使ってください。


（2023/05/16 追記）
続きはこちらです：
ノーツデータベースの設計変更履歴を git で管理する（２）


タグ ：
notes
nsf
vbs
design
dxl
importer
exporter

このページのトップヘ