R2132: Questetra Form JavaScript API

Avatar
Hirotaka NISHI
  • 更新
フォローする
 

タスク処理画面（入力フォーム）にて、入力フィールドから値を取得したり、値を更新したりする際に利用できる API です。イベントハンドラを登録することもできます。
なお、製品特性として「DOMツリーの構築」には一定の時間を要してしまいます。イベント発火のタイミングは、ご配慮いただく必要があります。

 

 

1. 入力フィールドの値の取得／更新

1-1. Script の形式

値の取得

qbpms.form.get(フィールド名)
  • フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
  • フォームでの編集許可設定が、「読み書き」「表示のみ」で利用できます

値の更新

qbpms.form.set(フィールド名, データ型に応じた形式の値)
  • フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
  • データ型に応じた形式の値: （下記、「値の取得／更新時のオブジェクト」参照）
  • フォームでの編集許可設定が、「読み書き」で利用できます
  • フォームの表示上の値を変更するだけで、タスクの保存や完了をしない限りサーバ上の値は更新されません

 

1-2. 値の取得／更新時のオブジェクト

件名・文字型

  • 取得：文字列
    • 値が未設定の場合、「読み書き」では "空文字列" 、「表示のみ」では null となります
  • 更新：文字列
    • null をセットすると値がクリアされます

数値型

  • 取得：Big オブジェクト
    • 値が未設定の場合、null となります
  • 更新：Big オブジェクト / 文字列 / Number オブジェクト / 数値
    • 文字列の場合、設定値がそのまま入力フィールドにセットされます
    • 文字列以外の場合、設定値がデータ項目定義のフォーマットに従って変換された文字列が入力フールドにセットされます
    • null をセットすると値がクリアされます

Big オブジェクトについて

  • new Big("文字列") でオブジェクトを生成できます
  • toString() メソッドにて、文字列形式での値を取得できます
    • 文字列の形式：小数点ピリオド、桁区切り文字なし（例："1234.56"）
  • 詳細は、big.js のドキュメントを参照ください

選択型

  • 取得：選択肢オブジェクトの配列
    • 選択肢オブジェクトは、value（選択肢ID）、display（表示ラベル）のプロパティを持ちます
    • 未選択の場合、空の配列となります
  • 更新：文字列、または文字列の配列
    • 文字列は、選択肢ID
    • 単一選択（チェックボックス以外）で複数要素の配列を渡した場合は、先頭の値がセットされます
    • 空の配列、または null をセットすると値がクリア（選択が解除）されます

日付型

  • 取得：Date オブジェクト
    • 値はワークフロー基盤（システム）のタイムゾーンの時刻として解釈されます
    • サブタイプの設定によって入力されない年月日フィールドについては「2000-01-01」の値で補完されます
      • 時刻は「00:00:00」
      • 例：年月の値「2022-08」は、「2022-08-01 00:00:00」を表す Date オブジェクトとして扱われます
    • 値が未設定の場合、null となります
  • 更新：Date オブジェクト / 文字列
    • Date オブジェクトの場合、ワークフロー基盤（システム）のタイムゾーンに変換された値が入力フィールドに設定されます
    • 文字列の場合、そのままの値が入力フィールドに設定されます
      • フォーマットに合致しない場合、空が設定されます
    • null をセットすると値がクリア（空が設定）されます

日時型

  • 取得：Date オブジェクト
    • 処理されるフォームに応じて、値は次のタイムゾーンの時刻として解釈されます
      • 通常のタスク処理フォーム（ヒューマンタスク）：処理担当ユーザのアカウント設定に基づいたタイムゾーン
      • 公開フォーム（メッセージ開始イベント（フォーム）／受信タスク（フォーム））：ワークフロー基盤（システム）のタイムゾーン
    • 値が未設定の場合、null となります
  • 更新：Date オブジェクト / 文字列
    • Date オブジェクトの場合、次のタイムゾーンに変換された値が入力フィールドに設定されます
      • 通常のタスク処理フォーム（ヒューマンタスク）：処理担当ユーザのアカウント設定に基づいタイムゾーン
      • 公開フォーム（メッセージ開始イベント（フォーム）／受信タスク（フォーム））：ワークフロー基盤（システム）のタイムゾーン
    • 文字列の場合、そのままの値が入力フィールドに設定されます
      • 日時型データのフォーマットに合致しない場合、空が設定されます
    • null をセットすると値がクリア（空が設定）されます

ユーザ型

  • 取得：ユーザを表すオブジェクト
    • id (数値)、name (名前：文字列)、email (メールアドレス：文字列) を属性として持ちます
    • 未選択の場合、null となります
  • 更新：文字列
    • 文字列は、メールアドレス
    • 指定されたメールアドレスを持つユーザが値にセットされます
    • null をセットすると値がクリア（選択が解除）されます

組織型

  • 取得：組織を表すオブジェクト
    • id (数値)、name (名前：文字列)、email (メールアドレス：文字列) を属性として持ちます
    • 未選択の場合、null となります
    • 保持されている値が削除済みの組織の場合は、id が null となります
  • 更新：文字列
    • 文字列は、組織名（名前）
    • 指定された名前を持つ組織が値にセットされます
    • null をセットすると値がクリア（選択が解除）されます

テーブル型

  • 取得：List オブジェクト
    • 値が未設定の場合、「読み書き」では "空（行数が 0）の List オブジェクト" 、「表示のみ」では null となります
  • 更新：List オブジェクト
    • List オブジェクトを新規に作成することはできません。qbpms.form.get() で取得した値を必要に応じて更新して使用してください。
    • 他のテーブル型データ項目で取得した List オブジェクトを使用することはできません。更新対象のテーブル型データ項目で取得した List オブジェクトを使用してください。
    • 行内の自動計算や、テーブル全体の集計値は、再計算されます。また、テーブル集計値を参照している数値型データ項目の値も更新（再計算）されます。

List オブジェクトについて

  • 新規に作成することはできません。qbpms.form.get() で取得したオブジェクトを利用してください。
  • 次のメソッドを利用して、値の参照や更新を行います
    • size()
      • テーブルの行数を返す。集計行は含まない。
    • getRow(rowIndex)
      • 指定した行インデックス（0 はじまりの数値）の行オブジェクトを返す
      • 存在しない行インデックスが指定された場合、null を返す
    • getSummary()
      • 集計行の行オブジェクトを返す
      • 集計行が存在しない場合（集計設定されたテーブル項目がない場合）、null を返す
      • 集計設定されていないカラムの値は null
    • updateRow(rowIndex, rowObject)
      • 行インデックス（rowIndex）で指定した行を、行オブジェクト（rowObject）で更新する
      • 行オブジェクトに含まれるカラムのみ更新する
        • 行オブジェクトのプロパティに含まれていないカラムは更新しない
        • 但し、式が設定されているカラムは再計算されて更新される
      • 行オブジェクトのプロパティ値は、テーブル項目のデータ型に応じたオブジェクト、または文字列で指定する
        • 文字型：String
        • 数値型：Big オブジェクト / 標準形式（小数点ピリオド、桁区切り文字なし)の数値文字列
        • 日付型：Date オブジェクト / "yyyy-MM-dd" 形式の文字列
        • 選択型：選択肢オブジェクト（選択肢ID のみ参照される） / 選択肢ID の文字列
    • addRow(rowObject)
      • 指定した行オブジェクトを、最終行に追加する
    • removeRow(rowIndex)
      • 指定した行インデックス（0 はじまりの数値）の行を削除する
      • 集計行があれば、集計値は更新される

行オブジェクトについて

  • 行オブジェクトは、テーブル項目の「フィールド名」がプロパティ名である各カラムの値を持つオブジェクトです。
  • 「フィールド名」が設定されていないテーブル項目は含まれません。値の取得・更新のためにはフィールド名設定が必要です。
  • プロパティの値は、テーブル項目のデータ型に応じて次の形式となります。詳細は、各データ型の値のオブジェクトを参照してください。
    • 文字型：String
    • 数値型：Big オブジェクト
    • 日付型：Date オブジェクト
    • 選択型：選択肢オブジェクト

ファイル型　（Ver. 14.2〜）

  • 取得：ファイルオブジェクトの配列
    • ファイルオブジェクトは次の属性を持ちます
      • id: ファイルID（数値）
      • processDataInstanceId: ファイルが関連付けられているプロセス/データ項目を表すID（数値）
      • name: ファイル名
      • contentType: ファイルの Content Type
      • length: ファイルサイズ（バイト、数値）
      • lengthText: ファイルサイズの表記用文字列。サイズにより bytes / KB / MB などの単位が付けられる。
      • image: 画像かどうかを表すフラグ（boolean 値）
      • inline: 別画面表示可能かどうかを表すフラグ（boolean 値）
    • ファイルオブジェクトには、ファイルの実体は含まれません
      • ファイル実体を取得することはできません
    • フォーム画面にて削除ボタンにて非選択状態になったファイルは配列には含まれません
    • ファイルが存在しない場合は空の配列となります（null ではない）
  • 更新：未対応
    • ファイルを追加したり、ファイル情報を更新したりすることはできません

* ［メッセージ開始イベント（フォーム）］ではファイル型データ項目の情報を取得することはできません

掲示板型 / （ガイドパネル型）

（利用いただけません）

 

1-3. Scriptのサンプル

件名

値取得のサンプル

let title = qbpms.form.get("title");

値更新のサンプル

let strTitle = "プロセスの件名";
qbpms.form.set("title", strTitle);

 

文字型

値取得のサンプル

let string = qbpms.form.get("q_string");

値更新のサンプル

qbpms.form.set("q_string1", "文字列");
qbpms.form.set("q_string2", "複\n数\n行\nの\n文字列");  //複数行

 

数値型

値取得のサンプル

let strNum = "null";
let obj = qbpms.form.get("q_numeric");
if (obj !== null) {
  strNum = obj.toString();
}

値更新のサンプル

qbpms.form.set("q_numeric1", "1001.101");
qbpms.form.set("q_numeric2", new Number("1002.102"));
qbpms.form.set("q_numeric3", new Big("1003.103"));
qbpms.form.set("q_numeric4", 1004.104);

 

選択型

値取得のサンプル

let array1 = qbpms.form.get("q_radioButton");
let display1 = array1[0].display; //表示ラベル

let array2 = qbpms.form.get("q_checkBox");
let value2 = array2[1].value; //2つ目の選択肢の選択肢ID

値更新のサンプル

qbpms.form.set("q_radioButton", "true");
qbpms.form.set("q_selectBox", ["true", "false"]); // ひとつ目 "true" がセットされる
qbpms.form.set("q_checkBox", ["true", "false"]);

 

日付型

値取得のサンプル

let date = qbpms.form.get("q_YMD");
let dateStr = date.toDateString();

値更新のサンプル

qbpms.form.set("q_YMD", new Date());
qbpms.form.set("q_YM", "2022-08");

 

日時型

値取得のサンプル

let datetime = qbpms.form.get("q_datetime");

値更新のサンプル

qbpms.form.set("q_datetime1", new Date(datetime.getTime() + (60 * 60 * 1000))); //60分後
qbpms.form.set("q_datetime2", "2022-08-08 11:11");

 

ユーザ型

値取得のサンプル

let userName = qbpms.form.get("q_user").name;

値更新のサンプル

qbpms.form.set("q_user", "yamada@example.com");

 

組織型

値取得のサンプル

let orgId = qbpms.form.get("q_org").id;

値更新のサンプル

qbpms.form.set("q_org", "営業部");

 

テーブル型

値取得のサンプル

let table = qbpms.form.get('q_table1');
let table_size = table.size();
let row1 = table.getRow(1); //行番号「1」の行オブジェクト
let selected = row1.select.display; //選択型テーブル項目の値（表示ラベル）

値更新のサンプル

let rowObject = {
  "str":"行更新1",
  "num1":"1111.11",
  "num2":new Big("2222"),
  "select":{"value":"a"},
  "date":"2022-08-08"
};
let table = qbpms.form.get('q_table1');
table.updateRow(1, rowObject);
qbpms.form.set('q_table1', table);

 

ファイル型　（Ver. 14.2〜）

値取得のサンプル

let files = qbpms.form.get("q_file");
let fileName = files[0].name; //ひとつ目のファイルの名前

（値更新には未対応）

 

掲示板型 / （ガイドパネル型）

（利用いただけません）

 

2. イベントハンドラの登録と削除

* Questetra で利用しているものとの競合を避けるため、独自の関数の名前／要素の ID は "user_" ではじまるように定義してください

2-1. フォーム全体のイベント

2-1-1. Script の形式

イベントハンドラの登録

qbpms.form.on(イベントタイプ, イベントハンドラ)

イベントハンドラの削除

qbpms.form.off(イベントタイプ, イベントハンドラ)
  • イベントタイプ: "ready"
  • イベントハンドラ: function（パラメータは一つでイベントオブジェクト）

 

2-1-2. イベントタイプ

ready

  • フォームが表示され、フォーム API が利用できる状態になれば発火する
  • フォーム表示後に登録した場合は、即座にイベントハンドラが実行される
  • イベントオブジェクトは固定

 

2-1-3. Script のサンプル

処理フォーム画面表示時にメッセージダイアログに「Hello world!」を表示

function user_readyHandler(e) {
  window.alert("Hello world!");
}

qbpms.form.on('ready', user_readyHandler);

 

2-2. データ項目のイベント

2-2-1. Script の形式

イベントハンドラの登録

qbpms.form.on(イベントタイプ, フィールド名, イベントハンドラ)

イベントハンドラの削除

qbpms.form.off(イベントタイプ, フィールド名, イベントハンドラ)
  • イベントタイプ: "change"
  • フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
  • イベントハンドラ: function（パラメータは一つでイベントオブジェクト）

 

2-2-2. イベントタイプ

change

  • 読み書き（編集可）のデータ項目で、入力フィールドの値が変更されたら発火する
  • 手動での値変更に加え、qbpms.form.set() で値を更新した場合にも発火する
  • ［メッセージ開始イベント（フォーム）］のファイル型データ項目では change イベントは発火しません
  • 対応しているデータ型
    • 件名 / 文字型 / 数値型 / 選択型 / 日付型 / 日時型 / ユーザ型 / 組織型 / テーブル型 / ファイル型*
    • *: Ver. 14.2〜
  • イベントオブジェクトのプロパティ
    • type: "change"
    • varName: フィールド名
    • value: 更新後の値（qbpms.form.get() で取得されるものと同じ）

 

2-2-3. Script のサンプル

対象のデータ項目の値が変更されたときにメッセージダイアログを表示

function user_addedQbpmsEvent(e) {
  window.alert("値が更新されました：" + e.value);
}

qbpms.form.on('change', 'q_string1', user_addedQbpmsEvent);

 

Notes

参照：選択した社員の情報を複数のデータ項目に自動入力する―Questetra Professional エディションで実現する場合

このセクションの記事

もっと見る

コメント

0件のコメント

記事コメントは受け付けていません。

関連記事