カスタム アクション

このセクションでは、Connector を [カスタム アクション] ステップで使用するための設定方法について説明します。

ロボットで Connector を使用する前に、[RoboServer 設定] アプリケーションの [セキュリティ] タブで [Connector の使用を許可] を選択します。[RoboServer 設定] は、Windows のスタート メニューから起動できます。詳細については、『Tungsten RPA 管理者ガイド』を参照してください。

ロボットのローカル デバイスでカスタム Connector を使用するには、ローカル デバイス RoboServer の [RoboServer 設定] アプリケーションで [Connector の使用を許可] オプションを選択します。

デフォルトでは、ロボットはコネクタが処理を完了して結果を取得するまで待機します。デフォルトの [カスタム アクション] ステップのタイムアウト値は 240 秒に設定されています。

コネクタがこの時間を超えることが予想される場合は、非同期またはバックグラウンド スレッドで処理を実行するようにコネクタを変更し、コネクタに (部分的な) 結果と完了をポーリングする 2 番目の [カスタム アクション] ステップを追加することをお勧めします。このようにして、ロボットはコネクタと並行してステータスの問い合わせを迅速に実行し、結果を処理します。

この処理が実行されない場合は、タイムアウトをより高い値に設定します。この設定を行うには、installation\bin フォルダ内の common.conf ファイルを編集します。次の行を追加します:

• wrapper.java.additional.<nr>=-Dhub.action.connector.seconds=<timeout>

<nr> を、ファイル内にすでに存在する wrapper.java.additional 設定の次のシーケンス番号に置き換えます。

<timeout> を必要なタイムアウト値 (秒) に置き換えます。

JSON 要素

manifest.json ファイルの最上位の設定に、次の JSON 要素が含まれています。

フィールド	ステータス	説明
アクション	必須	アクションの配列。
名前	必須	カスタム アクション ステップで表示されている Connector の名前。
python	任意	String デフォルト: python Python アクションで実行する実行可能ファイルを設定します。この設定はすべてのプラットフォームに適用されますが、デフォルトを上書きできます。 manifest.json ファイルの最上位にある python 要素の 1 つを使用して、別の名前またはパスでこの設定を上書きします。
python-windows	任意	String 記述されている場合、Windows プラットフォームで Python アクションに対して実行する実行可能ファイルを指定します。
python-linux	任意	String 記述されている場合、Windows プラットフォームで Linux アクションに対して実行する実行可能ファイルを指定します。
python-support	任意	整数 使用される Python のメジャー バージョンを指定します。 たとえば、Python バージョン 3.x の場合、値は 3 です。

アクション要素

次のフィールドには、アクション設定のアクション要素が含まれています。

アクション形式

フィールド	ステータス	説明
名前	必須	アクションの名前。
タイプ	必須	アクションのタイプ。次のいずれかである必要があります。 program shell node python Python インタープリターをカスタマイズするには、manifest.json ファイルで最上位の JSON 要素として python 設定します。
parameters	任意	カスタム アクション ステップで入力フィールドとして表される一連のパラメータ。
レスポンス	任意	カスタム アクション ステップで出力フィールドとして表される一連のレスポンス。このフィールドを省略すると、アクションの定義に応じてデフォルトのレスポンス セットが使用されます。デフォルトのレスポンスは次のとおりです。 shell および python アクションの場合、returncode タイプの整数が追加されます。 stdout および/または stder アクションの場合、対応するテキスト フィールドが結果セットに追加されます。 node および python アクションの場合、result および error という 2 つの文字列フィールドが追加されます。 shell および program アクションの場合、wait フィールドを false に設定して、レスポンスを受け取らないようにできます。 この場合、アクションはバックグラウンドで開始および実行されます。 node または python アクションをレスポンスなしに設定することはできないことに注意してください。
commandline	必須	要求コマンドのパラメーターを表す文字列のセット。program アクションの場合、最初のパラメータは実行可能ファイルになります。 パラメーターは ％n エスケープを使用して挿入できます (パラメーター配列から n th番目の値を挿入します)。 %% を使用して、パーセント記号を挿入します。 パラメータ置換後に空の要素は削除されます。 node および python 要求の場合、完全なスクリプトを送信できます。
prune	任意	ブール値 空の文字列に展開された要素をコマンド ライン配列から削除することを示します。 デフォルト: true
wait	任意	ブール値 ロボットがアクションの終了を待つことを示します。node アクションおよび python アクションの場合、またはアクションにレスポンス配列がある場合、この設定は無視されます。 デフォルト: true
stdout	任意	ブール値 変数にある program または shell アクションからの標準出力ストリームのキャプチャを有効にします。 wait が false の場合、このフィールドは無視されます。 デフォルト: false
stderr	任意	ブール値 変数にある program または shell アクションからの標準エラー ストリームのキャプチャを有効にします。 wait が false の場合、このフィールドは無視されます。 デフォルト: false

パラメータ形式

次のフィールドにはパラメータ形式が含まれています。

パラメータ形式

フィールド	ステータス	説明
名前	必須	パラメータの名前。この名前は、カスタム アクション ステップに表示されます。
タイプ	必須	パラメータのタイプ。このタイプは、string または number のいずれかである必要があります。 number パラメータは整数に制限されることに注意してください。
デフォルト	任意	パラメータのデフォルト値。 デフォルト: パラメータのタイプに応じて、「」または 0。
最小	任意	数値 パラメータの最小許容値。この属性は、number パラメータでのみサポートされています。他のタイプでは無視されます。 デフォルト: -2147483648
最大	任意	数値 パラメータの最大許容値。この属性は、number パラメータでのみサポートされています。他のタイプでは無視されます。 デフォルト: +2147483647
任意	任意	ブール値 オプションのパラメータは、ロボットに割り当てられていないか、空のままにすることができます。 デフォルト: false
エスケープ	任意	ブール値 値を引用符で囲み、特殊文字をエスケープします。この属性は現在、node および python 文字列パラメータでサポートされています。他のすべての状況では無視されます。 デフォルト: true

数値パラメータの場合、デフォルト値は最小値と最大値の間にある必要があります (両端を含む)。3 つの設定はすべて、-2147483648 から +2147483647 の範囲内である必要があります。

レスポンス形式

次のフィールドにはレスポンス形式が含まれています。

レスポンス形式

フィールド	ステータス	説明
名前	必須	レスポンスの名前。この名前は、カスタム アクション ステップに表示されます。
タイプ	必須	レスポンスのタイプ。タイプは、string または number のいずれかである必要があります。number タイプのレスポンスは整数に変換されます。
任意	任意	ブール値 出力にレスポンスが存在する必要がないことを示します。レスポンスが省略された場合、変数にはデフォルト値が入力されます。 デフォルト: false
デフォルト	任意	パラメータのデフォルト値。 この値は、オプションのパラメータがレスポンスから省略された場合に使用されます。 デフォルト: パラメータのタイプに応じて、「」または 0。

アプリケーションのレスポンスの浮動小数点数値は整数に変換されます。

マニフェストの例

次の manifest.json の例では、対応する関数を呼び出して 2 つの数値を加算するさまざまなコネクタ (shell、node、python、program) を使用しています。

関数パラメータは、この関数に渡される順序で定義されます(例: First number および Second number の順序)。

計算の結果は、Sum 値に割り当てられた変数に格納されてロボットに戻されます。

出力値は、コネクタごとに異なった方法で割り当てられます。

Python の例: 「Fibonacci」

次のコード例では、manifest.json ファイルの最上位 JSON 要素に Python コネクタを指定します。

{
	"actions": [
		{
			"name": "Fibonacci",
			"type": "python",
			"parameters": [
				{
					"name": "generation",
					"type": "number",
					"min": 1,
					"max": 100,
					"default": 3
				}
			],
			"response": [
				{
					"name": "bunnies",
					"type": "number"
				}
			],
			"commandline": [
				"import fib as f",
				"rpa_return = { 'bunnies': f.fib(%1) }"
			]
		},
		{
			"name": "Run Python (3.x) standard",
			"type": "python",
			"parameters": [
				{
					"name": "script",
					"type": "string",
					"escape": false
				}
			],
			"commandline": [
				"%1"
			]
		}
	],
	"name": "Python 3.x",
	"python-support": 3,
	"python-linux": "python3",
	"python-windows": "python"
}

Python の例: 「Adder」

このコネクタを機能させるには、コネクタを備えたロボットが実行されているコンピュータに最新の Python バージョンをインストールします。

{"actions": [
    {
      "name": "Adder",
      "type": "python",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
        "rpa_return = { 'Sum': %1 + %2 }"
      ]
    }
  ],
  "name": "Adder Function (python)"
}

シェルの例: 「Command Line」

次のコード例では、基盤となる OS にコマンドを渡します。

{
	"actions": [
		{
			"name": "Command Line",
			"type": "shell",
			"parameters": [
				{
					"name": "Command",
					"type": "string"
				},
				{
					"name": "Parameter",
					"type": "string",
					"optional": true
				}
			],
			"commandline": [
				"%1", "%2"
			],
			"wait": true,
			"stdout": true,
			"stderr": true
		}
	],
	"name": "Shell"
}

Linux シェルの例: 「Adder」

次のコード例は Linux 専用であり、Windows では動作しません。

{
  "actions": [
    {
      "name": "Adder",
      "type": "shell",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
	"echo \"{ \\\"Sum\\\": $((%1 + %2)) }\""
      ]
    }
  ],
  "name": "Adder Function (shell)"
}

ノードの例: 「Fibonacci」

次のコード例は Node.js で実行されます。

{
	"actions": [
		{
			"name": "Fibonacci",
			"type": "node",
			"parameters": [
				{
					"name": "generation",
					"type": "number",
					"min": 1,
					"max": 32,
					"default": 1
				}
			],
			"response": [
				{
					"name": "bunnies",
					"type": "number"
				}
			],
			"commandline": [
				"return { bunnies: require('Fibonacci').fib(%1) };"
			]
		},
		{
			"name": "Run JavaScript",
			"type": "node",
			"parameters": [
				{
					"name": "script",
					"type": "string",
					"escape": false
				}
			],
			"commandline": [
				"%1"
			]
		}
	],
	"name": "NodeJS"
}

ノードの例: 「Adder」

{
  "actions": [
    {
      "name": "Adder",
      "type": "node",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
        "return { Sum: %1 + %2 };"
      ]
    }
  ],
  "name": "Adder Function (node)"
}

プログラムの例: 「Adder」

このコネクタは、コネクタによって呼び出される実行可能プログラム「add」を使用します。

{
  "actions": [
    {
      "name": "Adder",
      "type": "program",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": {
      "windows":["./add.exe", "%1", "%2"],
      "linux":["./add", "%1", "%2"],
    }
  ],
  "name": "Adder Function (program)"
}

レスポンスの定義

プログラム

応答として送信される JSON データは、JavaScript Object Notation (JSON) Data Interchange Format 標準 RFC-8259 に準拠する必要があります。プログラム コネクタは、この標準で要求されているように、出力が必ず UTF-8 でエンコードされているようにする必要があります。

プログラムのアクションは次のとおりです。

• アクションに応答配列がある場合、待機フィールドは無視され、プログラムが終了するまでロボットは待機します。プログラムの標準出力はキャプチャされ、JSON 文字列として解析され、変数にはこの文字列の各フィールドが入力されます。プログラムが有効な JSON 文字列を生成しない場合、ロボットは失敗します。
• アクションにレスポンス配列がなく、待機フィールドが false の場合、ステップにはレスポンス変数がありません。
• アクションにレスポンス配列がなく、待機フィールドが true の場合、ステップには次のレスポンス変数があります。
  • rc: プログラムの戻りコード。
  • stdout: プログラムの標準出力ストリーム (stdout が true の場合のみ提供されます)。
  • stderr: プログラムの標準エラー ストリーム (stderr が true の場合のみ提供されます)。

Connector の構成に関係なく、標準出力ストリームと標準エラー ストリームは、INFO レベルで Tungsten RPA ログに記録されます。

シェル

応答として送信される JSON データは、JavaScript Object Notation (JSON) Data Interchange Format 標準 RFC-8259 に準拠する必要があります。シェル コネクタは、この標準で要求されているように、出力が必ず UTF-8 でエンコードされているようにする必要があります。

シェル アクションは、Windows では CMD.EXE、Linux では bash を使用して実行されます。

• アクションに応答配列がある場合、待機フィールドは無視され、シェルが終了するまでロボットは待機します。シェルの標準出力はキャプチャされ、JSON 文字列として解析され、変数にはこの文字列の各フィールドが入力されます。プログラムが有効な JSON 文字列を生成しない場合、ロボットは失敗します。
• アクションにレスポンス配列がなく、待機フィールドが false の場合、ステップにはレスポンス変数がありません。
• アクションにレスポンス配列がなく、待機フィールドが true の場合、ステップには次のレスポンス変数があります。
  • rc: シェルの戻りコード。
  • stdout: シェルの標準出力ストリーム (stdout が true 場合のみ提供されます)。
  • stderr: シェルの標準エラー ストリーム (stderr が true 場合のみ提供されます)。

Connector の構成に関係なく、標準出力ストリームと標準エラー ストリームは、INFO レベルで Tungsten RPA ログに記録されます。

JavaScript: NodeJS

コマンド ラインは、関数のコンテキストで実行されます。コマンドは、結果をロボットに返すために return ステートメントを使用する必要があります。

• アクションにレスポンス ブロックがある場合、オブジェクトまたは JSON 文字列を返すことが期待され、変数にはこのオブジェクトの各フィールドが入力されます。例外がスローされ、処理されない場合、ロボットは失敗します。
• アクションにレスポンス ブロックがない場合、ステップには次の 2 つの応答変数があります。

  結果: ステートメントが正常に完了した場合、この変数はステートメントによって返された値を受け取ります。

  エラー: 例外がスローされ、JavaScript コードで処理されない場合、この変数には例外のテキストが含まれます。

Python

コマンド ラインは exec() 関数を使用して実行されます。このコマンドは、ロボットに結果を返すために、グローバル変数 rpa_return に値を割り当てる必要があります。

1. アクションにレスポンス ブロックがある場合、rpa_return はオブジェクトまたは JSON 文字列を含める必要があり、変数にはこのオブジェクトの各フィールドが入力されます。例外がスローされ、処理されない場合、ロボットは失敗します。

1. アクションにレスポンス ブロックがない場合、ステップには次の 2 つの応答変数があります。

   • 結果: ステートメントが正常に完了した場合、この変数は rpa_return の値を受け取ります。

   • エラー: 例外がスローされ、Python コードで処理されない場合、この変数には例外のテキストが含まれます。

実装の詳細

.zip ファイルの次の要素は予約されています。

タイプ	パス	説明
ファイル	/manifest.json	マニフェスト
ファイル	/node	Linux プラットフォーム用の Node.js 実行可能ファイル。このファイルが存在しない場合、Tungsten RPA に含まれている Node.js インスタンスが使用されます。
ファイル	/node.exe	Windows プラットフォーム用の Node.js 実行可能ファイル。このファイルが存在しない場合、Tungsten RPA に含まれている Node.js インスタンスが使用されます。
ディレクトリ	/node_modules	Node.js モジュールの場所。
ディレクトリ	/RPAConnector	内部使用のために予約されています。
ディレクトリ	/node_modules/RPAConnector	内部使用のために予約されています。