intra-mart Accel Platform IM-LogicDesigner チュートリアルガイド 第12版 2023-10-01

5.4.4.2. 初期サンプルから見るユーザ定義(JavaScript)の詳細

この章では、JavaScriptを利用したユーザ定義の作成方法を、IM-LogicDesignerが提供する初期サンプルをもとに説明します。

5.4.4.2.1. 初期サンプルについて

本章で扱う「初期サンプル」とは、「ユーザ定義(JavaScript)の作成画面への遷移手順」に基いて「JavaScript定義編集」画面に遷移した際、初めから定義されているJavaScriptコード、および、入力値/出力値のことを指します。
../../../../_images/about_first_sample.png

図:初期表示時に、サンプルとしてJavaScriptが定義されている

実際に定義されている初期サンプルのJavaScriptコードは以下の通りです。
/**
 * run.
 *
 * @param input {Object} - task input data.
 * @return {Object} task result.
 */
function run(input) {

    Debug.console(input.param1, input.param2);

    return {
        message: 'hello world.' + input.param1 + '/' + input.param2
    };
}
初期サンプルのJavaScriptは、非常に単純なものですが、その中にはこれからユーザ定義(JavaScript)を作成する開発者にとって抑えるべきポイントが全て含まれています。

5.4.4.2.2. 入力値/出力値

初めに、作成するユーザ定義を呼び出す際の入力値と、呼び出しが完了した際に返却する出力値の定義について説明します。
ユーザ定義(JavaScript)の作成において入力値/出力値は、開発者が定義したJavaScriptに紐づく形に手動で定義する必要があります。
../../../../_images/sample_input_output.png

図:初期サンプルの入力値、および、出力値

5.4.4.2.2.1. 入力値

ユーザ定義(JavaScript)の入力値は、定義したJavaScriptの関数(function)の引数と紐付きます。
初期サンプルでは入力値として以下の値を定義しています。
  • param1<string>
  • param2<string>
定義された入力値は、「スクリプト」に定義されている「エントリーポイント」となる関数の引数に紐付きます。
(初期サンプルの7行目)
/**
 * ...
 */
function run(input) {
    //...
}
入力値は引数の直下に階層構造を保って紐づきます。利用方法は通常のJavaScriptのプロパティアクセスと同じです。
(初期サンプルの9行目)
function run(input) {
    // ...
    Debug.console(input.param1, input.param2);
    // ...
}

5.4.4.2.2.2. 出力値

ユーザ定義(JavaScript)の出力値は、定義したJavaScriptの関数(function)の戻り値と紐付きます。
初期サンプルでは出力値として以下の値を定義しています。
  • message<string>
定義された出力値は、「スクリプト」に定義されている「エントリーポイント」となる関数の戻り値と紐付きます。
(初期サンプルの11行目~13行目)
function run(input) {

    // ...

    return {
        message: 'hello world.' + input.param1 + '/' + input.param2
    };
}
出力値を扱う上で注意すべき点として、必ず出力値のキー名に合わせた形で戻り値を定義してください。
以下の様に定義した場合、出力値との紐付けは正しく行われません。
function run(input) {

    // ...

    return 'hello world.' + input.param1 + '/' + input.param2;
    // ここで返される文字列は、出力値として定義した"message<string>"とは紐付かない。
}

5.4.4.2.3. スクリプト

次に、実際に処理を行うJavaScriptの定義方法と留意点を説明します。

5.4.4.2.3.1. JavaScript

ユーザ定義(JavaScript)では、通常のスクリプト開発モデルと同様にJavaScript、および、スクリプト開発向けim-BizAPIが利用可能です。
初期サンプルでは、im-BizAPIのうちデバッグ情報の表示を行う「Debugオブジェクト」を利用しています。
(初期サンプルの9行目)
function run(input) {
    // ...
    Debug.console(input.param1, input.param2);
    // ...
}

5.4.4.2.3.2. エントリーポイント

ユーザ定義(JavaScript)が実際に処理を行う際に、一番初めに実行する関数(function)はシステムで決まっています。
この処理開始時に一番最初に呼び出される関数をIM-LogicDesignerでは エントリーポイント と呼びます。
IM-LogicDesignerは定義されたスクリプトの中から、名称が「run」である関数を自動的に検出し、エントリーポイントとします。
初期サンプルでは、唯一存在する関数の名称に「run」を指定しています。
(初期サンプルの7行目)
/**
 * ...
 */
function run(input) {
    //...
}

コラム

エントリーポイントが無い場合

ユーザ定義(JavaScript)のスクリプト上に、エントリーポイントに該当する関数が定義されていない場合でもエラーとは判断されません。

5.4.4.2.3.3. 入力値/出力値

入力値/出力値」で説明したとおり、ユーザ定義(JavaScript)のスクリプトと入力値/出力値はエントリーポイントを介して紐付いています。
留意点としてエントリーポイントの引数、および、戻り値をIM-LogicDesignerでは以下のように扱います。
  • 入力値に定義された値は、全てエントリーポイントの第一引数と紐付きます。
    • エントリーポイントに複数の引数が定義されていた場合、第二引数以降はundefinedとして扱われます。
    • 入力値を必要としないユーザ定義(JavaScript)の場合、引数のないエントリーポイントの定義も可能です。

5.4.4.2.3.4. 利用が制限されているJavaScriptについて

ユーザ定義(JavaScript)では、いくつかのim-BizAPIについて利用制限を行っています
詳細は「参考:ユーザ定義(JavaScript)における制限」を参照してください。

5.4.4.2.4. ユーザ定義(JavaScript)を作成する。

最後に、これまでの内容を踏まえてユーザ定義(JavaScript)を作成します。
  1. 「JavaScript定義編集」画面を表示します。

  2. ユーザ定義の基本情報となる各項目に以下の値を入力します。

    • ユーザ定義ID「tutorial_ud_javascript

    • バージョン「1」(固定)

    • ユーザ定義名
      • 標準 - 「ユーザ定義[JavaScript]
      • 日本語、英語、中国語(中華人民共和国) - 入力なし
    • カテゴリ
      • カテゴリID - 「tutorial_user_category
    • ソート番号「2001

    ../../../../_images/implement_ud_javascript1.png

    図:基本情報の入力

  3. 入力値、および、出力値を「入力値/出力値」をもとに確認します。

    ../../../../_images/implement_ud_javascript2.png

    図:入出力値の確認

  4. スクリプトを「スクリプト」で提示されているJavaScriptをもとに確認します。

    ../../../../_images/implement_ud_javascript3.png

    図:スクリプトの確認

  5. 登録」をクリックします。

    ../../../../_images/implement_ud_javascript4.png

    図:登録

以上で、ユーザ定義(JavaScript)の作成が完了しました。