【ServiceNow】REST Messageを使用してFlow DesignerからAPI連携する方法

はじめに

初めまして、株式会社ウイズ・ワン、ServiceNow担当のH-Oです。
業務内でREST メッセージとフローを使用したAPI連携機能を作成しました。
今回は、開発初心者の私がフローのアクションでREST メッセージを使用した際に学んだことをまとめたいと思います。

REST API連携を知ることで、以下のような外部連携の実現につながります。

• Googleカレンダーの予定を取得し、ServiceNowで使用する
• インシデントが記録されたときに、Teamsなどの社内SNSに通知する

本記事は次のような方におすすめです。

• REST メッセージの基本的な使い方を知りたい
• スクリプトからREST メッセージを呼び出す際に困ったことが知りたい

・本記事は2025/10/30時点での情報です
・使用環境：PDI環境(Yokohama)
・導入プラグイン：日本語翻訳用の
「I18N: Japanese Translations[com.snc.i18n.japanese]」のみ

1. 実装構造

大まかに以下のような仕組みでAPI連携を実現しました。

【用意したもの】

1. APIへのリクエストおよびレスポンスの情報を保持するレコード
2. APIを使用してレコード更新するフロー
3. フローのアクションで使用するREST メッセージ

今回は図中赤枠のREST メッセージの部分について学んだことを紹介していきます。

2. REST APIの設定方法

今回APIを連携するために使用したのは 「REST メッセージ」 というモジュールです。
プラグインは不要で、インスタンスにはあらかじめ入っている機能となります。

本記事では説明のために、無料で公開されている「JSON Placeholder」という開発者向けのダミーAPIサービスを使用して設定していきます。

JSON Placeholderについては以下の使用例ガイドを参照
・https://jsonplaceholder.typicode.com/guide/

使用するモジュール
[システム Web サービス] > [アウトバウンド] > [REST メッセージ]

2-1. REST メッセージの設定

REST メッセージの設定では以下を実施します。

2-1.1. REST メッセージの名前の設定

この名前は後ほどスクリプトで呼び出す際に使用します。英語名が推奨です。

2-1.2. REST メッセージのエンドポイントの設定

今回はJSON Placeholderのデフォルトのエンドポイントとして以下のURLを指定しておきます。

2-1.3. REST メッセージの認証情報の設定

REST APIで認証を行う場合は、使用する認証情報を設定します。
今回使用するJSON Placeholderでは認証が不要 なので、そのままにしておきます。

私の業務では「基本認証」が必要でしたので、接続するためのユーザー名とパスワードを指定しました。

2-1.4. 使用できるスコープ範囲の設定

他のスコープからこのRESTメッセージを呼び出す場合は、アクセス可能フィールドを 「すべてのアプリケーションスコープ」 にしておく必要があります。

レコードを保存すると 「HTTP メソッド」関連リスト が表示されるので、続けて使用するメソッド分作成していきます。

自動で「Default GET」レコードが作成されます。
すべて新規で作成したい場合は削除しても問題ありません。

2-2. HTTP メソッドの設定

HTTP メソッドの設定では以下を実施します。

2-2.1. 名前の設定

この名前は後ほどスクリプトで呼び出す際に使用します。英語名が推奨です。

2-2.2. HTTP メソッドの設定

GETやPOSTなど、使用するメソッドの種類を選択します。
業務ではPOSTメソッドとGETメソッドを使用したので、その分作成することになりました。
今回は「Creating a resource」POSTメソッドに接続したいのでPOSTを選択しました。

2-2.3. REST エンドポイントの設定

使用するエンドポイントを設定します。
REST メッセージ側でも設定しましたが、HTTP メソッドで設定したエンドポイントが優先して使用されます。
REST メッセージのエンドポイントを使用する場合は空にします。
今回は「Creating a resource」で使用するパスを入力します。

2-2.4. 「認証」の設定

認証情報を設定します。
REST メッセージで設定した認証情報を使用する場合は 「親から継承」 を選択することで同じ認証情報を使用できます。
今回の例では認証不要です。特に変更せずに、デフォルト値の「親から継承」のままにしておきます。

2-2.5. 「HTTP要求」の設定

HTTPヘッダーとHTTPクエリパラメーターを設定します。
今回の「JSONPlaceholder」の使用例はJavaScriptで書かれているので、必要な情報をREST メッセージで使用できるよう少々考えて入力する必要があります。

入力例

コンテンツの部分がBodyになるのですが、使用例でシングルクォーテーションだった部分をダブルクォーテーションに直しました。
また、変数を使用したかったので内容の部分は「${}」で囲ったプレースホルダーにしておきました。(次の手順で使用します)

私は初心者だったので、API仕様書を見ながらこの設定を入力するのに少々躓きました。
業務で使用した仕様書では「Content-Type: application/json」というリクエストの形式を指定するヘッダー項目が省略されており、気づくまで接続がうまくいきませんでした。

2-2.6. 「変数の自動生成」の実施

GETのエンドポイント内や、POSTのHTTPクエリパラメーターで「${○○}」というプレースホルダーが含まれている場合実施します。
レコード内の「変数の自動生成」関連リンクを押下することで、「REST メッセージ関数パラメーター」へ自動で変数を作成することが出来て便利です。

今回はコンテンツ内に作成した3つ分の変数が自動で作成されました。

ー 値を入力すると接続をテストできる ー
「REST メッセージ関数パラメーター」の「値」列はテスト用です。
値を入力して「テスト」関連リンクを押せば接続確認が可能です。

・値にテストデータを入力

・「テスト」関連リンクを押下した際の結果

2-3. フローアクションのスクリプトステップでREST メッセージを呼ぶ方法

スクリプトで先ほど設定したREST メッセージを呼び出し、取得した値を使用する方法を紹介します。

フロー用に「REST ステップ」というAPIを使用するステップがありますが、これには別途プラグインが必要なので、今回はスクリプトでの呼び出しを採用しました。

REST メッセージを呼び出す基本的なスクリプト

//REST メッセージの呼び出し
var r = new sn_ws.RESTMessageV2('[REST メッセージのスコープ名].[REST メッセージ名]', '[使用するHTTPメソッド名]');

//HTTP メソッドの関数に値を代入する
r.setStringParameterNoEscape('[関数名]', [代入する値]);

//REST メッセージの実行
var response = r.execute();

特に、REST メッセージを他のスコープからも呼び出せるようにしたい場合「[REST メッセージのスコープ名]」の部分が重要になります。

REST メッセージレコードのアクセス可能フィールドを「すべてのアプリケーションスコープ」にしておいても、この部分が無いと呼び出すことが出来ません。

業務では他スコープで使用する想定で作成していたのですが、同じスコープであればこの部分が無くてもREST呼出しができてしまう ので、他スコープからの利用確認をするまで仕様に気づくことができませんでした。

また、業務で使用したAPIのレスポンスはJSON形式でしたので、以下のようなコードでレスポンス情報を抜き出しました。

REST メッセージから返ってきたJSON形式の情報を取り出すスクリプト

//レスポンス情報を取得
var responseBody = response.getBody(); // ← JSON文字列

//JavaScriptオブジェクトに変換する場合
var responseObj = JSON.parse(responseBody);

JSONから特定の項目を取り出すスクリプト

//単純なキーの場合
var name = responseObj.name;

//ネストされている場合
var city_name = responseObj.city.name;

//配列の中にある場合
var item = responseObj.items[0]; //←配列位置を指定
var itemName = item.name;

私はJSON形式のデータを扱うのも初めてだったので、ネストされていたり、配列の中にあるデータを取る方法は勉強になりました。

ーその他、業務の際にスクリプトで工夫した点ー
・レスポンス本文の他に次の値も取り出して接続結果による分岐や確認に使用した

//javascript:HTTPステータス
var status =  response.getStatusCode();

//エラーメッセージ(HTTPステータスが正常ではない場合出力される)
var error = response.getErrorMessage();

※RESTResponseV2 - スコープ対象、グローバル参考

・REST Messagev2呼び出しスクリプト内でエラー終了すると呼び出すフロー自体の動作が止まってしまうため、try/catchで囲むようにした

・スクリプトからREST メッセージを呼び出したタイミングを監視できるように「gs.info()」でスクリプト内で実行開始ログを出力するようにした

3. 実践例

以上をふまえて、先ほど作成した「demo_POST」POSTメソッドを呼び出し、返った値をoutputに代入するアクションを作成してみます。

使用するモジュール
[プロセス自動化] > [Workflow Studio]

Workflow Studioの「新規」ボタンからアクションの新規作成を開始できます。

※スクリプトステップはユーティリティにあります。

設定内容は以下の通りです。

アクションの入力

スクリプトステップの入力変数

スクリプトステップの出力変数

スクリプト

実践例スクリプト

(function execute(inputs, outputs) {

    try {
        //REST メッセージの呼び出し
        var r = new sn_ws.RESTMessageV2('x_1083861_article.demo API', 'demo_POST');
        //HTTP メソッドの関数に値を代入する
        r.setStringParameterNoEscape('title', inputs.title);
        r.setStringParameterNoEscape('body', inputs.body);
        r.setStringParameterNoEscape('userId', inputs.userId);

        //開始ログ
        gs.info("「demo_POST」メソッドを呼び出します");
        //REST メッセージの実行
        var response = r.execute();

        //レスポンス情報を取得
        var responseBody = response.getBody(); // ← JSON文字列
        //JavaScriptオブジェクトに変換する場合
        var responseObj = JSON.parse(responseBody);
        //HTTPステータスを確認する
        var status = response.getStatusCode();
        //エラーメッセージがあるか確認する
        var error_code = response.getErrorMessage();

        //正常値の場合はエラーメッセージを取り出さない
        if (status == '201') {
            //結果ログ
            gs.info("「demo_POST」メソッド呼び出しは正常に完了しました: "+ JSON.stringify(responseObj));
            //POSTが返した内容を取り出す
            var post_title = responseObj.title;
            var post_body = responseObj.body;
            var post_userId = responseObj.userId;
            var post_id = responseObj.id;

            //アクションのoutputに代入
            outputs.reg_title = post_title;
            outputs.reg_body = post_body;
            outputs.reg_userid = post_userId;
            outputs.reg_id = post_id;
            outputs.status =status;
        }

        //正常値以外ならエラーメッセージを取り出す
        else {
            //結果ログ
            gs.info("「demo_POST」メソッド呼び出しは"+ status + "ステータスでエラー終了しました");
            //アクションのoutputに代入
            outputs.status = status;
            outputs.error_code = error_code;
        }
    } catch (ex) {
        // 例外が発生した場合の処理
        gs.error("「demo_POST」メソッド呼び出しで例外が発生しました: " + ex.message);
        outputs.error_code = "例外: " + ex.message;
    }
})(inputs, outputs);

テスト/結果確認

テストして結果を確認します。
・入力値

ー テキストボックスに入力できない場合 ー
このテキストボックス含め、フローデザイナーを使用していると全角入力できないテキストボックスに遭遇します。
その場合は全角文字を含む文字列を別の場所からコピーペーストすると入力できます。

・テスト結果とログ：正常ステータス

・テスト結果とログ：異常ステータス

スクリプトステップでREST APIから取得した結果を出力データに定義することができました。

Step Up : データをフロー/サブフローで使用するには

これらのデータをフロー/サブフローで使用するためには、アクションの「出力」ステップで使用するデータを定義する必要があります。

・アクションの「出力ステップ」に、スクリプトステップの出力を定義する

・フロー/サブフロー内でアクションを使用したときに、データピルとして出力データ使用することができる

ー 補足：「HTTP ログレベル」について ー
REST メッセージでAPI接続をした結果は 「送信 HTTP ログ[sys_outbound_http_log]」 に記録されています。

使用するモジュール
[システム Web サービス] > [アウトバウンド] > [送信 HTTP 要求]

このログは初期設定だと 「Basic」 というログレベルになっており、あまり詳細な内容を確認できない状態です。

開発環境では接続内容を詳細に確認したかったので、以下の方法でログレベルを変更しました。

1. ログレベルを変更したいHTTP メソッドレコードを開く
2. 「HTTP ログレベルを設定」関連リンクを押下
   

ログレベルは次の3種類から選択できます。
・Basic / Elevated / All

※各レベルで取得できる内容はDocsを参考
・送信ログの構成

おわりに

今回は私がREST メッセージをスクリプトで呼び出した際に学んだことをまとめました。
開発経験も浅く、API仕様書の読み方から調べるという状況で大変でしたが、多くの学びがあったと思います。

業務ではこの方法でメッセージ送信APIと連携したことで、任意のメッセージを携帯端末に送信することができました。

機会があればレコードの画面設計や、REST メッセージをフローで使用して困った点なども記事にまとめたいと考えています。

本記事が同じように初めてREST メッセージを使用する方の参考になれば嬉しいです。

本記事は2025/10/30時点での情報です