作業変数の使い方【xoBlos クライアント】

概要

作業変数とは、業務ファイル（xobファイル、xbtファイル）の内部で作成できる変数です。
以前のバージョンではあらかじめ「業務の設定」から業務変数を定義できましたが、値は固定でかつ、業務が始まる前に値が決まってしまうので定数のようにしか使えませんでした。

作業変数は作業変数を定義する手順によって定義されます。
定義された作業変数は今までの業務変数と同じように使用できます。
ただし、作業変数を定義した手順よりも後に実行される手順でしか使えません。

技術者向けに言えば、作業変数とはプログラムのローカル変数です。

作業変数の定義

説明

作業変数はJSONから定義することができます。
手順の名前は「代入（JSONファイル→変数）」です。
JSONは、手順の設定に直接JSON文字列を書き込むか、JSONファイルから読み込めます。

JSONのどこから値を取り出すかというのは「JSONPath（JSONパス）」で指定します。
JSONPathについては後述します。

手順設定内容

• 1.入力設定
  • a. 読み込むJSON文字列
    • 読み込むJSON形式の文字列を指定します。
  • b. 読み込むJSONファイル
    • 読み込むJSON形式のファイルを指定します。
    • 「a. 読み込むJSON文字列」が優先されます。
• 2.基本の設定
  • a. 作業変数定義
    • ここで上記で読み込んだJSONから、どの値を取り出して作業変数とするかを定義できます。
    • 1つのJSONから複数の作業変数が定義可能です。

設定例

読み込むJSON

{
	"product": {
		"id": "ID0001",
		"name": "productA",
		"price": 150
	},
	"description": "サンプルの説明文です。"
}

こんな感じのJSONとします。

作業変数定義の設定

今回は下記の作業変数作成することとします。

• PRODUCT_ID
  • JSONデータの product > id の値を入れます。
    
• DESCRIPTION
  • JSONデータの description の値を入れます。
    

結果

このように、指定した値が入りました。

作業変数の使用

作業変数は業務変数と同様に設定に埋め込むことができます。
ただし、作業変数を定義した手順よりも後に実行される手順でしか使えません。

作業変数「DESCRIPTION」を使用したい場合：

$(tmp:DESCRIPTION)

※業務変数は「$(val:変数A)」のように val というキーワードでしたが、作業変数は tmp というキーワードになっています。

また、通常の業務変数と同様、値の編集エディタの下部に「作業変数」タブの作業変数一覧をダブルクリックすることで、エディタに上記文字列が挿入されます。

JSONへの出力

作業変数とは直接関係ありませんが、作業変数機能を追加するに当たって、こちらの機能も追加されました。

説明

手順「出力（JSON）」は、JSONファイルを出力することができます。
出力するJSONファイルの内容は、手順の設定に直接JSON文字列を書き込むか、JSONファイルから読み込めます。

使用用途としては、JSONファイル出力が必要な際に使用します。
また、その他にも、きちんと業務変数が受け渡せているか、業務変数や作業変数の値の確認、などに使うことができます。

手順設定内容

• 1.入力設定
  • a. テンプレートJSON文字列
    • 出力するJSON形式の文字列を指定します。
  • b. テンプレートJSONファイル
    • 出力するJSON形式の文字列が記載されたファイルを指定します。
    • 「a. テンプレートJSON文字列」が優先されます。
• 2.基本の設定
  • a. 出力ファイル（必須）
    • 出力するJSONファイルを指定します。
  • b. 出力設定
    • 上記で読み込んだテンプレートJSONのどこに値を出力するかを設定します。
    • 出力するJSONファイル1つにつき、複数の出力設定が定義可能です。

設定例

テンプレートJSON

{
	"product": {
		"id": "ProductID_ReplaceWord",
		"name": "",
		"price": 0
	},
	"description": ""
}

出力設定

• 作業変数 PRODUCT_ID の出力
  • JSONテンプレートの product > id の値「ProductID_ReplaceWord」を置き換えて出力します。
    
• 作業変数 DESCRIPTION の出力
  • JSONテンプレートの description に出力します。
    

結果

{
	"product": {
		"id": "ID0001",
		"name": "",
		"price": 0
	},
	"description": "サンプルの説明文です。"
}

product > id に作業変数 PRODUCT_IDが入りました。
これは出力位置指定の方法を「キーワード（値で置き換え）」としました。
そのため、単純に「ProductID_ReplaceWord」が置き換えられて出力されました。
このやり方ではもし、JSONに使えない文字やダブルクォートが入っていた場合、出力されるJSONデータが不正になってしまいます。

description に作業変数 DESCRIPTION が入りました。
こちらは前述の置き換えではないため、出力する値に指定した作業変数 DESCRIPTION の値がしっかりとエスケープ処理されて、JSONに埋め込んでも問題ない形にします。

JSONPathについて

作業変数の定義やJSONへの出力の手順でも JSONPath が度々出てきます。
この JSONPath によって高度な値の指定が可能となります。

サンプルJSON

{
	"books": [
		{
			"category": "参考書",
			"author": "参考書太郎",
			"title": "C#入門",
			"price": 3000
		},
		{
			"category": "絵本",
			"author": "絵本花子",
			"title": "くまさんとありさん",
			"price": 800
		},
		{
			"category": "絵本",
			"author": "童話次郎",
			"title": "日本の昔話",
			"price": 1200
		}
	],
	"bookCount": 3
}

JSONPath の例

先頭の本のタイトルを指定

$.books[0].title

最後の本の値段を指定

$.books[-1:].title

本のタイトルが「C#入門」の著者を指定

$.books[?(@.title=='C#入門')].author

本の値段が1000円以下のカテゴリを指定

$.books[?(@.price<=1000)].category

このほかにも様々な文法が使用できます。
JSONPathについては下記サイトを参考にしてください。
https://goessner.net/articles/JsonPath/ （英語サイト）
※全ての機能が使えるわけではありません。

作業変数を定義する際の高度な機能

値のチェック

作業変数を取得するに当たってExcel関数を使って値のチェックを行うことができます。
例えば、先ほどの作業変数の定義手順の PRODUCT_ID に

とします。
「#」は同設定内で JSONPathにて指定した値そのものが入ります。
これは JSONPath で指定した値が "ID_0002"か？ という検証です。

すると、値は “ID_0001” なので、以下のようなエラーとなります。

また、「b. 検証エラー時の動作」を「エラーを無視してデフォルト値をセットする」を選択すると、「d. 検証エラー時のデフォルト値」の値が入ります。

値の編集

値のチェック同様、こちらもExcel関数で値を編集することができます。

このような設定します。
これは JSONPath で指定した値が “ID_0001” なら 1 を、それ以外なら 2 を入れる処理です。
指定した JSONPath は PRODUCT_ID と同じJSONPath です。

今回定義した、PRODUCT_CAT は “ID_0001” だったため、 1 が入っています。