JDBC アクティビティを作成する

カスタム JDBC アクティビティを作成して、ワークフローからリレーショナル データベースへの SQL コマンドおよびストアド プロシージャ呼出しを自動化します。

始める前に

必要なロール：activity_admin、activity_creator

このタスクについて

JDBC アクティビティテンプレートを使用すると、ターゲットデータベース上で ANSI SQL ステートメントまたはストアド プロシージャを実行できます。IN、OUT、および INOUT パラメーターを使用するストアド プロシージャのサポートは、Yokohama で利用できます。これらのパラメーターを設定する方法については、「JDBC ストアド プロシージャのパラメーター」を参照してください。

注:

外部データソースからバルクデータを ServiceNow インスタンスに転送する場合は、インポートセットのキーコンセプトを使用してください。JDBC アクティビティを使用すると、ワークフロー内で外部データソースと ServiceNow の間でデータを転送できます。これは、データソースの一括インポート機能に置き換わるものではありません。

手順

1. JDBC 認証情報を作成または検証します。
   JDBC 認証情報には、ターゲットデータベースに対する権限と、対応する JDBC 接続に対する適切な構成が必要です。JDBC アクティビティを作成する前に、認証情報を設定する必要があります。
2. JDBC 接続を作成または検証します。
   JDBC アクティビティを作成する前に、有効な JDBC 認証情報を設定した JDBC 接続を構成する必要があります。
3. カスタムアクティビティを作成します。
   このアクションにより、テンプレートを使用してカスタムアクティビティが作成されます。
4. 一般的なプロパティを設定し、入力変数を作成した後、JDBC 実行コマンドを構成します。

   オプション	説明
   JDBC 接続	データベースに適切な JDBC 接続を構成するか、参照します。選択した接続によって、アクティビティに次の情報が提供されます。 ターゲットデータベース情報 (サーバー名とデータベース名) 接続 URL ターゲットデータベース ポート (標準ポート番号と異なる場合) データベース インスタンス名
   認証情報	JDBC 接続に使用する JDBC 認証情報。
   SQL ステートメント	JDBC ターゲットデータベースで実行する ANSI SQL を入力します。 注: このフィールドは、[ストアド プロシージャ] チェック ボックスがオンになっているときは非表示になります。 作成した入力変数をマップして、SQL ステートメントを構成できます。デフォルトでは、次の SQL ステートメントを実行できます。 select insert update delete show 作成 describe セキュリティ対策を強化するために、この JDBCOrchestrationProbe が実行する操作を MID サーバープロパティによって制御します。これにより、使用する SQL コマンドが制限されます。このプロパティは、データベースの削除など、破壊的な可能性のあるコマンドからシステムを保護します。mid.property.jdbc_operations には、MID サーバープロパティ コントロールが含まれています。 注: 異なるタイプの複数のステートメントを実行することはできません。たとえば、select ステートメントと update ステートメントを一緒に実行することはできませんが、2 つの insert ステートメントを実行することはできます。ただし、このアクティビティで複数の select ステートメントを実行することはできません。
   最大行	データベースから取得するレコードの最大数。デフォルトは 1,000 です。
   最大ペイロード サイズ (KB)	データベースから取得するデータの最大ペイロード サイズの制限を設定できます。デフォルトは 64 キロバイトです。
   接続タイムアウト	アクティビティが接続の確立を待機する時間。このフィールドはデータソースから自動的に入力されますが、このアクティビティに合わせて変更することができます。
   クエリ タイムアウト	クエリを実行してからデータが返されるまで待機する経過時間。このフィールドはデータソースから自動的に入力されますが、このアクティビティに合わせて変更することができます。
   必要な MID サーバー機能	JDBC のクエリに使用する MID サーバー (機能別)。デフォルトでは、JDBC 機能を備えた MID サーバーが選択されます。
   ストアド プロシージャを使用	これをオンにすると、プロシージャ名とパラメーターを入力することにより、MySQL、Oracle、または SQL Server データベース上でストアド プロシージャを実行できます。「JDBC ストアド プロシージャのパラメーター」を参照してください。

   注:

   テストペイロードのパラメーター値を、[出力] タブの変数に自動的にマッピングできます。「出力変数を自動マッピングする」を参照してください。

次のタスク

• JDBC アクティビティ入力をテストする
• 自動マッピングを使用して出力および解析ルールを生成する (JDBC で推奨)
• 自動マッピングを使用しない場合は、手動で出力変数を作成し、解析ルールを作成できる

関連タスク

• カスタムアクティビティデザイナーテンプレートを使用してカスタムアクティビティを作成する

オーケストレーション アクティビティ用の JDBC 接続を作成する

JDBC 接続 [jdbc_connection] テーブルによって、カスタム JDBC オーケストレーションアクティビティがさまざまなターゲットデータベースに接続するために使用する情報を提供します。

始める前に

インスタンスに付属するかどうかに関係なく、適切な JAR ファイル、またはカスタム JAR ファイルが必要です。

注:

ServiceNow インスタンスでは、mysql-connector-java-5.1.21.jar、sql-server-jdbc-4.0.jar、および ojdbc6.jar の各ファイルが現在のリリースの一部として提供され、MySQL、SQLServer、および Oracle データベースをサポートしています。Sybase や DB2 Universal などの他のデータベースでは、カスタム JAR ファイルを使用する必要があります。このファイルは、JDBC 接続を設定する前にインスタンスにアップロードする必要があります。

必要なロール：activity_admin、activity_creator

このタスクについて

JDBC 認証情報JDBC 認証情報は、アクティビティデザイナーテンプレートによって別々に取得され、CyberArk などの外部認証情報ストレージをサポートします。

手順

1. 次のように移動する。 All (すべて) > オーケストレーション > 認証情報 & 接続 > JDBC 接続 をクリックし、[ 新規] をクリックします。
2. テーブル内のフィールド使用して、フォームに値を入力します。
   [フォーマット] フィールドのデータベース選択により、利用可能なフィールドが決定されます。

   表 : 1. JDBC 接続フィールド

   フィールド	データベース形式	説明
   名前	すべて	この JDBC 接続の一意の名前。たとえば、JDBC MySQLProd を入力します。
   クエリ タイムアウト	すべて	JDBC クエリが応答なしで実行される最大経過時間。
   接続タイムアウト	すべて	ターゲットデータベースへの接続の試行中に JDBC アクティビティが待機する最大経過時間。
   アプリケーション	すべて	このテーブルのスコープ。デフォルトでは、[グローバル] スコープで JDBC 接続 [jdbc_connection] テーブルが実行されます。
   ドメイン	すべて	このテーブルのドメイン。デフォルトでは、グローバル ドメインで JDBC 接続 [jdbc_connection] テーブルが実行されます。
   フォーマット	すべて	この接続のデータベース タイプ。デフォルトの選択肢は次のとおりです。 MySQL Oracle SQLServer なし 適切な JDBC ドライバー JAR ファイルをインスタンスにアップロードして、Sybase または DB2 Universal を選択リストに追加できます。オーケストレーションでは、システムにロードされたときにこれらのドライバーを自動的に認識し、このリストに追加します。
   サーバー	Oracle、MySQL、SQLServer	データベース サーバーのホスト名または IP アドレス。
   Oracle SID	Oracle	Oracle データベース サイトの識別子。デフォルト値は orcl です。
   Oracle ポート	Oracle	Oracle データベースが使用しているポート。デフォルト値は 1521 です。
   データベース名	MySQL、SQLServer	データベースの名前。
   データベース ポート	MySQL、SQLServer	選択したデータベースが使用しているポート。
   インスタンス名	SQLServer	選択した SQLServer のインスタンス名
   接続 URL	すべて	指定したデータベースへの接続に MID サーバーが使用する URL。この URL は、フォームを保存したときに自動的に作成され、デフォルトのデータベースでは読み取り専用になります。 注: 選択した形式がデフォルトのデータベースのものでない場合は、接続 URL を手動で作成して、MID サーバーが接続の作成方法を認識できるようにする必要があります。
   JDBC ドライバー	なし、DB2 Universal、Sybase	デフォルトのデータベースでない場合にこの接続に使用する JDBC ドライバー。 注: Sybase または DB2 Universal Database を追加する場合、このフィールドにドライバー名を入力して、そのドライバー JAR ファイルをインスタンスにアップロードする必要があります。

   図 : 1. Oracle への JDBC 接続の例

   

3. [送信] をクリックします。

関連情報

• JDBC 認証情報

JDBC アクティビティ出力変数を自動マッピングする

ServiceNow アクティビティデザイナーを使用すると、JDBC テストペイロード内のパラメーター値を [出力] タブ内の変数に自動的にマッピングできます。

始める前に

必要なロール：admin

手順

1. JDBC プロバイダー テンプレート フォームで、[入力] タブを選択します。
2. [アクティビティをテスト] をクリックして、入力パラメーターをテストします。
   パラメーターとフィールドの実際の値を追加した場合、指定したターゲットに対してこれらの値が実行され、結果のペイロードが返されます。入力変数をフィールドとパラメーターにマップした場合、これらの変数にテスト値を割り当てるためのダイアログ ボックスが表示されます。
3. 必要に応じてテスト値を入力し、[OK] をクリックしてペイロードを表示します。
   [応答] フォームの [Raw 出力] タブに、ペイロード全体が表示されます。

   

4. 次の自動マッピング オプションのいずれかを選択します。
   • ローカルに自動マップ：値をアクティビティ内で使用するためにローカル変数に直接マップします。
   • 出力する自動マップ：値を出力変数に直接マッピングして、ワークフロー内の他のアクティビティに渡します。出力変数への自動マッピングによって、オブジェクトのアレイが作成されます。それぞれに、クエリ結果からの列名が含まれます。

JDBC ストアド プロシージャのパラメーター

オーケストレーションを使用して、MySQL、Oracle DB、および MS-SQL データベースで、ストアド プロシージャを実行できます。

複数のデータタイプがサポートされますが、次の制限があります。

• 返される結果セットは 1 つのみです。
• ストアド プロシージャ パラメーター内の入力データタイプと出力データタイプの順序は、アクティビティ定義と一致している必要があります。
• Binary、Blob、Varbinary、および LongBinary は、base64 でエンコードする必要があります。
• 日付、時刻、およびタイムスタンプの形式は次のとおりです。

  日付形式：yyyy-mm-dd

  yyyy-mm-dd が、サポートされている形式です。

  時間形式：hh:mm:ss[.sss]

  hh：mm：ss [.sss] が、サポートされている形式です。精度はミリ秒単位のみです。マイクロ秒やナノ秒は処理できません。

  注:

  10:30:59 および 10:30:59.999000 は正しい形式ですが、10:30:59. は間違った形式です。

  タイムスタンプ形式：yyyy-mm-dd hh:mm:ss[.ffffff]

  yyyy-mm-dd hh:mm:ss[.ffffff] が、サポートされている形式です。精度はマイクロ秒単位です。

• ResultSet は、データベース サーバーから返される最初の結果セットです。
• MS-SQL は INOUT パラメーターをサポートしていません。INOUT パラメーターを使用すると、アクティビティテンプレートによってそれらが OUT パラメーターに透過的にマップされます。

注:

レガシー動作のように、ストアド プロシージャのパラメーターでデータタイプの検証を行わない場合は、glide.stored_proc.data_type.validation を false に設定します。詳細については、「MID サーバープロパティ」を参照してください。

表 : 2. ストアド プロシージャのパラメーター

フィールド	説明
モード	ストアド プロシージャ パラメーターのタイプ。サポートされているパラメーター： IN OUT INOUT
SQL タイプ	SQL データタイプ。サポートされるデータタイプ： ARRAY BIGINT BINARY BIT BLOB CHAR CLOB DATE DECIMAL DISTINCT DOUBLE FLOAT INT INTEGER JAVA_OBJECT LONGVARBINARY LONGVARCHAR NULL NUMERIC OTHER REAL REF REF_CURSOR SMALLINT STRUCT TIME TIMESTAMP TINYINT VARBINARY VARCHAR
名前/値	ホストに渡す名前と値のペア。これらのパラメーターは手動で作成することも、入力変数をパラメーター フィールドにドラッグ アンド ドロップして値を割り当てることもできます。

注:

すべてのデータベース プロバイダーが JDBC データタイプの領域全体をサポートしているわけではありません。ご使用のインストール環境でサポートされているデータタイプについては、データベース参照マニュアルを参照してください。

JDBC アクティビティテンプレートの入力をテストする

カスタム JDBC アクティビティの入力パラメーターは、ワークフロー コンテキスト内でアクティビティを実行しないで、その開発中にテストできます。

始める前に

入力変数を作成し、それを [実行コマンド] フォーム内のフィールドにマップしたり、これらのフィールドの実際の値を入力したりします。必要なロール：web_service_admin、activity_admin、activity_creator

このタスクについて

このテストでは、エンドポイントに対して入力パラメーターのみが実行され、前処理スクリプトまたは後処理スクリプトは実行されません。テストするためにアクティビティをチェック アウトする必要はありません。

注:

エンドポイントまたはホストに接続してデータを返すために十分な情報をオーケストレーションに提供した場合は、入力変数をテストできます。アクティビティデザイナーのどのステージからでもテストできます。通常、[実行コマンド] ステージが、入力のテストの準備ができているポイントです。

手順

1. JDBC 実行コマンドから、[入力のテスト] をクリックします。
   入力ソース変数のリストが表示されます。これらの変数のデフォルト値を追加した場合、[値を代入] 列にその値が表示されます。必須変数には、赤い星印が付いています。

   注:

   MID サーバーが見つからない場合、またはターゲットに接続できない場合、テストは失敗します。

   図 : 2. JDBC 入力テストの値

   

2. 次のコントロールを使用して、変数リストをフィルタリングします。
   • すべての入力：すべての入力変数が表示されます。このコントロールがデフォルトの表示です。
   • 必須の入力：必須の変数のみが表示されます。
   • デフォルト設定なしの入力：デフォルト値が割り当てられていない入力変数が表示されます。
3. 必要に応じて値をリセットします。
   • デフォルト値をリセット：値が存在する場合、このコントロールは、このフォームで設定されているすべてのテスト値をデフォルト値に置き換えます。
   • 値をクリア：デフォルト値が存在していても、入力変数リスト内のすべての値をクリアします。
4. テスト値が正しく構成されたら、[OK] をクリックします。
   システムによって、指定されたターゲットに対して構成したすべての入力の値が実行され、結果のペイロードが返されます。[応答] フォームのボタンに、ペイロードのさまざまなビューが表示されます。[Raw 出力] ウィンドウに、ペイロード全体が表示されます。

   図 : 3. 入力テストからの応答ペイロード

   

5. ペイロード内の適切なパラメーター値を [出力] ステージに自動的にマップするには、自動マッピング オプションを選択します。
6. ウィンドウの右上隅にある [X] をクリックして、ウィンドウを閉じます。