【ServiceNow】インポートセットを使って表データファイルをServiceNowへインポートしてみる。

# 概要
　ServiceNowではExcelやCSVといった表データをServiceNowに取り込む機能が複数存在します。この記事ではServiceNowのプロジェクトで会得したノウハウをもとに、下記で説明する「Import set」を使用したServiceNowへの表データのインポート方法とその際の注意事項を記載します。

##インポート機能の紹介
まずは、ServiceNowに複数存在する一般的なインポート機能を紹介します。

１.【Easy import】[^1]
現在のスコープ内のテーブルと他のアプリケーションの書き込み許可がされているテーブルにデータをインポートすることができます。インポート先のテーブルに合わせたデータを用意することで、レコードの挿入または、更新を行うことができます。インポート用の表データのテンプレートを作成できるため、簡単にインポートを行うことができます。

2.【XMLインポート】[^2]
XML形式のファイルをインポートできる機能。別インスタンスのレコードの移行やレコードデータのバックアップに用いられることがメインになります。基本的にはServiceNowで作成したデータをServiceNowへ移行する機能になります。

３.【Import Set】[^3]
この記事で紹介する機能です。インポートファイルを対象のテーブルに挿入、更新が行える機能であり、Easy importと似ていますが、その違いは以下になります。

- インポートファイルを対象のテーブルに合わせた形に加工せずとも、変換マップを作成し、そのマップに合わせてフィールドに値を入れてくれる。
- 一連のImport setを作ってしまえば、同じファイル形式である限り、作成したImport setを利用して簡単にインポートが可能
- インポート中にスクリプトの制御が可能。
- Easy import同様レコードに更新も可能。

##Import setとは？
Import setのイメージ図は以下のようになります。
![import set_イメージ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/687ab8b0-515d-aebf-57b5-79dc96535847.png)

各用語について紹介します。

| 用語 | 説明 |
|:-:|:-|
| データソース  |ファイル形式または、JDBC、LDAP等のサーバにあるデータにアクセスし、インポート用のデータをServiceNowに落とし込む領域。|
| インポートセットテーブル  | データソースからインポートされたレコードのステージング領域 |
| 変換マップ  |  インポートセットテーブルから『ターゲット』テーブルにデータを移動するための指針となるもの。インポートセットテーブルのフィールドとターゲットテーブルのフィールドをマッピングすることで、フィールド間でデータが直接移動される。 |
| ターゲットテーブル  | 変換後のデータを配置する既存のテーブル。 |

今回のServiceNowのインポートの流れとしては、

1. インポート用のファイルを作成。
1. システムプロパティの作成。
1. インポートセットの作成（ファイルをデータソースへと登録し、データソースからインポートセットテーブルを作成する。）							
1. インポートセットテーブルとターゲットテーブルの変換マップを作製し、インポートデータの紐付けをする。
1. ターゲットテーブルにインポート。

という手順になります。


# 環境、使用する物
Version : Quebec
Role : import_admin
使用言語 : 日本語
インポートセット


# 実践！

##インポート用のファイルを準備する。
インポート用の表データを作成していく。以下の形式で作成するのが望ましいです。

###作成方法
 - **ファイル形式：xls形式**
    xlsx形式ではセル内にフリガナのデータが入っているため、このフリガナも一緒にインポートされてしまうことを回避するため。フリガナデータを削除した場合にはxlsx形式でインポートしても構いません。

 - **ヘッダー**
    - インポートファイルの構成は1行をヘッダー行とし、それ以降の行には1行1レコードとしてデータを記載します。
    - ヘッダー行には、移行したい情報に対応する、ターゲットテーブルのフィールドの列名または列ラベルを記載します。
    - ヘッダー行は**フィールドの列名を記述すること**をお勧めします。変換マップを作成する際に、自動マッピングが綺麗に行われるため、手動で設定する手間が省けるからです。

 - **インポートするデータの型に対応する書式設定**
   データは1行1レコードで記載します。インポート先のフィールドクラス(型)によっては記述に以下の注意点があります。ここで一般的に使用されるフィールドクラスを記載します。

|フィールドクラス|説明|
|:-|:-|
|文字列型[String]|特になし。|								
|整数型[Integer]	|半角数字で記載してください。|							
|選択肢型および選択肢を持つフィールド[Choice]|選択肢の"値"もしくは選択肢ラベルを正確に記述してください。|									
|日付型[Date]|そのセルデータの表示形式を【yyyy/mm/dd】に変更してください。|									
|日付/時刻型[Date/Time]|そのセルデータの表示形式を【yyyy/mm/dd `hh:mm:ss`】に変更してください。|									
|参照型[Reference]|参照するレコードのラベルもしくはSysIDを記述してください。|							
|リスト型[List]|参照するレコードのラベルもしくはSysIDを記述してください。値と値の間は[**,**]を入れてください。<br>例：	田中太郎,佐藤次郎,鈴木三郎|				
|True/False型[True/False]|0もしくは1で記述してください。|

##インポートセット作成前の事前準備

###システムプロパティを設定する
インポートセットを作成する前にシステムプロパティの**[com.glide.loader.verify_target_field_size]**を確認します。
インポートデータからインポートセットテーブルを作成する際に、テーブルに作成するフィールドの最大長はインポートデータ内の最初の20レコード分をサンプルとして取り、最大長を決めます。ここで、サンプリングされたすべてのレコードでフィールドが空の場合は、デフォルトの長さ40が使用されます。しかし、インポートデータが20レコード未満だと自動的にすべてのフィールドの最大長が40に設定されてしまいます。
**最大値が40になってしまうと、全角半角含め40文字のデータしかインポートすることができなくなってしまうため、4１字以降のデータは切り捨てられてしまいます。**[^4]						
この最大値の自動設定を取り払うために**[com.glide.loader.verify_target_field_size]**を設定します。これを設定することで、インポートデータ内の各フィールドの最大文字数をそれぞれの最大長として設定します。

- 設定方法

1. フィルターナビゲーターで**[sys_properties.list]**で検索
1. 名前で**[com.glide.loader.verify_target_field_size]**で検索し、ヒットするか確認する。（デフォルトでは作成されていないプロパティなので、基本的にヒットしません。）
1. 新規をクリックし、以下のようにシステムプロパティを作成する。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/4cb6efb8-2cbf-30dc-d98a-d54777b12102.png)




 
##インポートセットテーブルの作成
インポートセット機能を利用するためにフィルターナビゲーターから[インポートセット]>[データのロード]モジュールを利用するのが便利です。
このモジュールでは、データのロード、データソースの作成、インポートセットテーブルの作成、変換マップの作成、ターゲットへのインポートの一連の作業を行う事ができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/447571ca-a704-efcf-c231-3c2f034a738c.png)

上記画面ではインポートセットテーブルの作成とデータソースのロードを行う事ができます。

| フィールド名 | 説明 |
|:-|:-|
| テーブルの作成  | 新規でインポートセットテーブルを作成する。  |
| 既存のテーブル  | 既存のテーブルを使用してインポートをする。  |
| ラベル  | 新規でテーブルを作成する場合、テーブルのラベル名を設定する。(英数字を推奨します)  |
| 名前  |  テーブルの名前を設定する。ラベル名の半角小文字英数字が反映されます。 |
| ファイル  | インポートファイルを使用してインポートする。  |
| データソース  | データソースを使用してインポートする。  |
| シート番号 | インポートファイルのシート番号を指定する。  |
| ヘッダー行  | インポートファイルのヘッダー行を指定する。  |

###新規でインポートセットテーブルの作成してインポートするには
1. テーブルの作成を選択
1. ラベル名を任意の名前で選択
1. ファイルを選択
1. シート番号とヘッダー行を選択したファイルに合わせて入力し送信をクリック

送信クリック後、上記の画面に遷移します。
[Loaded data]を選択するすることで、インポートしたデータを確認しつつ、**[Create transform map]**で変換マップを作成します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/86653cf6-0a7d-3554-d0fe-60db9487b40f.png)




##変換マップの作成
インポートしたデータをインポート先のテーブルに挿入するために変換マップを作成していきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/088e2d43-185c-92f4-bcb4-a588a0e90f58.png)


| フィールド | 説明 |
|:-|:-|
| 名前  | この変換マップの名前を定義する。  |
| ソーステーブル  | インポートセットテーブルを選択する。  |
| ビジネスルールの実行  | ターゲットテーブルにデータが挿入された時に実行されるビジネスルールを実行するようします。  |
| 必須項目を強制する  | ターゲットテーブルに必須フィールドを適用するかどうかを選択します。  |
| 空のフィールドをコピー  | 空のフィールド値をコピーし、既存のターゲットフィールド値を上書きする。  |
| ターゲットテーブル  | 変換されたデータを挿入するテーブル。  |
| スクリプトの実行  | ソーステーブルのフィールド値をターゲットテーブルに変換する際に実行するスクリプトを定義します。  |

基本的には[名前]、[ソーステーブル]、[ターゲットテーブル]を使用します。状況に応じて上記フィールド部分も設定しましょう。
フォームの入力を終えたらコンテキストメニューから**[保存]**をクリックしてください。
※送信を押すと前の画面に戻されてしまいます。

保存を行うと関連リンクに以下の画像のようなリンクが表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/f97b9974-e088-d80f-62be-2b8471fb8798.png)

- **一致フィールドの自動マップ**
インポートセットテーブルのフィールドとターゲットテーブルのフィールドが自動でマッピングされます。
インポートファイルのヘッダーがターゲットテーブルの列名と同じ文字列にすることで綺麗にマッピングされます。

- **マッピング支援**
手動でマッピングを行えます。上記リンクをクリック後、マッピングの確認と手動修正ができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/cea5468d-d279-e826-506d-8bb64c58834a.png)

赤枠がソースのフィールド、青枠がターゲットのフィールドになります。
真ん中のフィールドマップにそれぞれ1行づつ突き合わせることでマッピングされています。

##ターゲットテーブルへのインポート
上記変換マップを作成し保存すると関連リストが以下のように追加されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/cd2655b3-d535-b2b1-95ce-4631ccf333ba.png)

[変換]のリンクをクリックすることで、使用するインポートセットと変換マップを指定して、インポートを始めることができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/83731e8c-e713-57ea-a9b2-8f6b9ff55b3b.png)

この画面では基本的にインポートセットと変換マップが自動で選択されているので、[変換]をクリックすることでインポートを開始することができます。


インポートに成功すると以下の画像の様に[State]成功と表示されます。
[Transform history]をクリックすると今回インポートした結果を表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/d0646576-eb29-0ca2-d9a7-4f174fb4176a.png)

レコードデータの合計と挿入数が同じであれば正常にインポートされています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/425100/dc7d08cd-6da1-4a7e-301d-e0c397c90658.png)




# 結論
今回はServiceNowのImport set機能に関して説明とその方法をまとめてました。
上記のやり方を実行することで、表データを元にServiceNowへデータをインポートすることができます。


# 参考文献
[^1]: 【公式ドキュメント】[Easy import](https://docs.servicenow.com/bundle/rome-platform-administration/page/administer/import-sets/concept/c_EasyImport.html)

[^2]: 【公式ドキュメント】[XML import](https://docs.servicenow.com/bundle/rome-platform-administration/page/administer/development-best-practices/task/t_ImportARecordAsXMLData.html)

[^3]: 【公式ドキュメント】[Import set](https://docs.servicenow.com/bundle/rome-platform-administration/page/administer/import-sets/reference/import-sets-landing-page.html)

[^4]: 【公式ナレッジ】[Missing data when column length is too short for the import](https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0538123)