ServiceNowのビジネスルールを文書化し、管理する #ServiceNow小ネタ

はじめに

これは別にビジネスルールに限った話ではないのですが、とりわけServiceNowにおいてはビジネスルールで顕著な悩みが、これです。

仕様などを書き残しておきたいのに書く場所がない
ネーミングで区別したくても名前の文字数制限が厳しすぎる

これから取り上げる内容はすでにご存じの方も多かろうとは思いますが、万が一ご存じないとなると困るので、今日は敢えて取り上げてみたいと思います。

説明欄を表示する

ビジネスルールを作ると、こういう画面が出てくるんですが（少し入力してしまった項目もあります）、初めての人にとって不便なのは、ビジネスルールが何をするためのものなのかを書いておく欄がないことです。

名前を説明的にしてわかりやすくしたいと思っても、名前欄はわずか40文字しか入力できないので、説明できることはあまりありません。プロジェクト管理の都合で、プロジェクトの識別子を入れたいという方もいらっしゃるかもしれませんが、それもこの字数ではどうにもならず。

隠しフィールドの追加

というわけで、まず絶対覚えておくべきなのは、デフォルトで非表示になっている「説明（description）」欄を表示させることです。左上の三本線のアイコンをクリックして、「Configure > Form Layout」を開きます。（フォームデザイナーでもいいんですが、あまり使いたくない理由はそのうちお知らせします）

スラッシュバケットの左側に「Description」があるので、右側に持っていきましょう。おすすめは末尾のWeb Servicesの下に|- end_split -|という項目があるので、これをいったん挟んで、その下にDescriptionを持ってくることです。これで左右カラムぶち抜きの大きな欄として表示できます。

出来上がりはこんな感じですね。ちなみにこの説明欄4000文字まで入力できるので、必要なメモをしっかり残しておきましょう。

ちなみに説明欄に何を書くか

こういう実装に近接した文書化機能（一番わかりやすいのがコードの中に書くコメントですね）に何を書くかは意見が割れます。

過去の経緯を全部書いておくべしという人もいますが、それをやると4000文字でも枯渇します。保存したビジネスルールにはバージョンという関連リストが表示されて、過去の変更履歴を参照することができます。巷の開発環境のような軽快さはないですが差分表示もできます。したがって、開発の経緯みたいなものは、更新セットに書いておいて、バージョンから辿って見るというのも一つのやり方です。

処理内容の説明を書くことにも賛否が分かれます。処理内容は実装を見れば（わかる人なら）わかるためです。微妙な表現ですが、個人的には、何をするためのものなのかを業務的な観点から書いておけばよいと思っています。何をしているのかではなく、何をしたかったのかを書くべきだという言い方もできます。要するに、そのルールが要求されていることがらを書いておくことによって、動作が要求通りではない時に、実装に間違いがある言えるようにしておくということです。仕様というのはそういうものです。

変更の理由になった要求のチケット番号などを書くというのもアリです。が、それも更新セットのほうに書いておくほうが良いかなとも個人的には思っています。この辺りはいろいろな意見があるところなので、自組織にとって最適な方法を探ってみてください。ただ、あまりにも面倒なのはやめたほうが良いです。具体的には、よそからテンプレをコピーしてこないといけないようなのはダメです。そんなの誰もやらなくなります。わたしはやりませんよそんな面倒なこと。

同じテクニックが使えるアプリケーションファイル

ビジネスルール以外にも同じように隠し（？）説明フィールドがあるアプリケーションファイルはいくつかあります。まずこの4つは必須。

説明フィールドを設定で表示できるテーブル
- ビジネスルール(sys_script)
- UIポリシー（sys_ui_policy） ¹
- スクリプトアクション（sysevent_script_action）
- ビュールール（sysrule_view）

そもそもそんな必要もなく、最初から説明フィールドがあるアプリケーションファイルも多々あります。

もともと説明フィールドがあるテーブル
- スクリプトインクルード（sys_script_include）
- UIアクション（sys_ui_action）²
- クライアントスクリプト（sys_script_client）
- データポリシー（sys_data_policy2）
- 通知（sysevent_email）
- イベント登録（sysevent_register）³
- アクセス制御（sys_security_acl）⁴

あと、どうしようもないもの。こういうのに限って事情を残しておきたいのが悔しいところです。

それでも説明フィールドがないテーブル
- スケジュールスクリプト実行（sysauto_script）⁵
- 関係性（sys_relationship）

文書化のためにフィールド長を伸ばしたりカスタムフィールドを追加するのは是か非か

あるいは、既存のフィールドを伸ばしたり、翻訳フィールドにしたりしたいという方もいらっしゃるかも知れませんが、このような環境間で移送する対象になるテーブルのレイアウトを変更するのはできれば避けたいところです。

テーブルレイアウトが拡張されていないインスタンスには持っていくと文書情報がカットされるというのは意外と不便なことだと思います。共通ライブラリ的に作った機能をいろんなインスタンスに配布したいなどということがあると、特殊フォーマットのアプリケーションファイルは配布できないことになってしまいます。もちろん、自社のインスタンスでしか使わなくて、真っ先にそこを拡張しているから問題ない、というケースもあるかもしれませんが。この件はもっと拡張したいフィールドにまつわる話があるので、別の日に。

タグを使った整理

実は、この目的でもうひとつ、簡単に使えて、最初に習う割には使う人が居ない機能があります。タグです。

おさらいですが、タグには以下の3種類があります。

プライベートタグ
- 自分だけが使えるタグ
共有タグ
- 所定のグループに所属している人だけが使えるタグ
グローバルタグ
- すべてのユーザーに表示されるタグ

このうち、ServiceNowの開発者が使うべきは「共有タグ」です。開発技術者を登録したらまず追加する技術者用のグループを作ります。この技術者グループ内で使える共有タグを定義します。

例えば、このタグをビジネスルールにつけると、ビジネスルールの中からプロジェクトに関係のあるものを検索することができるようになります。

タグの機能が文書化フィールドより優れていると思われる点はいくつかあります。

複数つけることができる。例えば、リリースごとのタグをつけておけば、複数のリリースに関係しているものを識別できます。
OOTBのレコードにもつけられるので、例えばOOTBを変更したものを識別することにつかえます。ある業務目的にOOTBの変更と新規のスクリプトの両方があるとき、横断的に同じタグをつけられるメリットがあります。
タグの情報はタグをつけた対象とは別の、Label Entryというテーブルに記録されるので更新セットにも入らず、開発インスタンスで完結した管理として扱えます。

惜しむらくは、アプリケーションファイルに限って、タグをつけられないように制限されているテーブルがあることで、上に列挙したもので言うと、スケジュールスクリプトやスクリプトアクション、そしてテーブル定義の情報にはタグが付けられません。

逆にいうと、その他のスクリプト系のテーブルには付与できます。また、更新セットにタグをつけられるということも覚えておくと便利です。

まとめ

ビジネスルールなど、いくつかのテーブルでは、本来使えるはずの説明フィールドが表示されていません。表示して利用することの価値が高いので、利用していなければぜひ利用しましょう。
また、開発の文書化においては、タグが実は利用価値が高いです。簡単に使えるのでぜひ活用しましょう。

UIポリシーはShort Descriptionのフィールドが結構長くて（255文字）、ビジネスルールよりも用途限定で作られることが多いことと相まって、なくても困らない傾向があります。 ↩
名称が説明ではなく「コメント（comment）」になりますが、同等の用途に使えます。 ↩
ただし100文字しか書けません。そして、このテーブルはEvent nameフィールドがスコープの識別名込みで40文字しか使えないという別の問題があります。 ↩
自動でDescriptionフィールドの内容を生成するビジネスルールがあるのですが、その内容に頼らず、自分で必要な情報を文書化することをお勧めします。そうでなくても重要な要素です。 ↩
いま手元のOOTBだと「スクリプトの実行を予定」という意味のわからない和訳になっているので、一旦スルーします。 ↩