付録H.13 アプリケーション呼び出し情報ファイル
アプリケーション呼び出し情報ファイルの詳細について説明します。
- 〈この項の構成〉
(1) アプリケーション呼び出し情報ファイルの概要
アプリケーション呼び出し情報ファイルには,RESTアプリケーションのURLなどを設定します。
(2) アプリケーション呼び出し情報ファイルの設定個所
アプリケーション呼び出し情報ファイルは,ビジネスプロセス定義を作成する開発環境で作成し,実行環境にコピーしてください。
アプリケーション呼び出し情報ファイルの配置例を次の図に示します。
なお,アプリケーション呼び出し情報ファイルは,ref識別子単位に作成します。各アプリケーション呼び出し情報ファイルには,呼び出し対象のref識別子に対応するファイル名を付けてください。
作成したアプリケーション呼び出し情報ファイルの格納先として,共通設定ファイルのBpmnCallInformationFileDirプロパティで指定したディレクトリ内に,サブディレクトリ(ope)を作成します。
次に示すアプリケーション呼び出し情報ファイルのファイル名を付けて,該当するサブディレクトリにファイルを格納してください。
<BpmnCallInformationFileDirの指定値>/ope/<ref識別子の値>.properties
- 重要
-
-
「図H-12 アプリケーション呼び出し情報ファイルの配置例」のOperationRef1のように,複数のビジネスプロセス定義(BP1,BP2)で同じref識別子を定義している場合,共通で使用するOperationRef1.propertiesファイルをopeフォルダの下に配置してください。
-
大文字と小文字だけが異なる同じ名称のref識別子は使用しないでください。
-
(3) アプリケーション呼び出し情報ファイルの記述規則
アプリケーション呼び出し情報ファイルの記述規則を次に示します。
-
java.util.Propertiesクラスが扱えるフォーマットで記載してください。
-
文字コードは,UTF-8を使用してください。ただし,BOM付きUTF-8では記述できません。
-
プロパティの各キーは,大文字と小文字が区別されます。
-
プロパティの各キーは,1つだけ指定してください(同一のキーは複数指定できません)。同一のキーを複数指定した場合,どの設定値が有効になるかは不定です。
-
プロパティの記載順は任意です。また,プロパティが読み込まれる順番は不定です。
-
プロパティのキーに,アプリケーション呼び出し情報ファイルで使用できるプロパティで定義されていないキー名を指定した場合,アプリケーションの呼び出し時にエラーが発生します。
-
プロパティでファイルパスを指定する場合,パスの区切り文字には"/"を使用してください。
-
プロパティの値の先頭に"$$"を記載した場合,"$"に変換されます。
-
プロパティの値の先頭に"@@""を記載した場合,"@"に変換されます。
-
プロパティの値が空の場合,エラーが発生します。
アプリケーション呼び出し情報ファイルが次に示すケースに該当する場合,アプリケーション呼び出しサービスは,該当するref識別子のアプリケーション呼び出しを中止します。
-
指定必須のプロパティのキーが指定されていない
-
プロパティに不正な値が指定されている
(4) アプリケーション呼び出し情報ファイルで使用できる組み込み変数
組み込み変数は,CSCIWで管理する案件や作業の属性値を指定するための変数です。アプリケーション呼び出し情報ファイルに記載した組み込み変数は,呼び出し元の案件や作業の属性値に変換されます。
- 使用できる組み込み変数
-
項番
組み込み変数
説明
1
@PIID
案件ID
2
@PIName
案件名
3
@PICreator
案件投入者
4
@PIDeadline
案件処理期限
5
@PDefName
ビジネスプロセス定義名
6
@WIID
作業ID
7
@WDefName
作業定義名
8
@NULL
null値
- 組み込み変数の使用規則
-
アプリケーション呼び出し情報ファイルで組み込み変数を使用する場合は,次の規則に従ってください。
-
組み込み変数名の前後に,ほかの組み込み変数名やその他の文字列を連続して記載することはできません。また,半角空白などで文字列を区切ることもできません。
誤った記載例(通常の文字列として扱われる)
abc@PIName
誤った記載例(エラーが発生)
@PIName@PIID
ただし,rest.request.urlプロパティの値の中では,特定の文字で区切ることで,組み込み変数の前後にほかの組み込み変数や文字列を連続して記載できます。
-
プロパティの値の先頭に"@"を記載し,上記の表「使用できる組み込み変数」の「組み込み変数」列以外の文字列を指定した場合は,アプリケーションの呼び出し時にエラーが発生します。
誤った記載例
@ABC
@PINameABC
-
プロパティの値の先頭に"@@"を記載した場合は,組み込み変数ではなく通常の文字列として扱われます。
-
組み込み変数の対象となる属性の値がnullの場合,null値として扱われます。ただし,rest.request.urlプロパティの値の中に含まれている場合は,空文字として扱われます。
-
案件処理期限は,"1970/01/01 00:00:00 GMT"を起点とした通算秒に置き換えられます。
- ヒント
-
rest.request.urlプロパティについては,「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(c) rest.request.url」を参照してください。
-
(5) HTTPヘッダを記述したファイルの指定方法
HTTPヘッダを記述したファイルとは,RESTアプリケーションを呼び出す際のリクエストのHTTPヘッダに指定する内容を記述するファイルのことです。HTTPヘッダを記述したファイルを作成した場合は,HTTPヘッダを記述したファイルのファイルパスを,アプリケーション呼び出し情報ファイルのrest.request.header.filepathプロパティに指定してください。
- ヒント
-
rest.request.header.filepathプロパティについては,「付録H.13(9) アプリケーション呼び出し情報ファイルに指定する内容」の「(d) rest.request.header.filepath」を参照してください。
HTTPヘッダを記述したファイルの指定規則を次に示します。
-
java.util.Propertiesクラスが扱えるフォーマットで記載してください。
-
文字コードはUTF-8を使用してください。ただし,BOM付きUTF-8では記述しないでください。
-
ファイル中に記載する要素の数や種類は,HTTPヘッダの仕様に合わせてください。複数回指定できない要素を2行以上指定しているなど,HTTPヘッダの仕様と異なる記述をした場合の動作は保証しません。
HTTPヘッダの記述例を次に示します。
Accept=application/xml
(6) アプリケーション呼び出し情報ファイルの読み込みタイミング
アプリケーション呼び出し情報ファイルは,対応するref識別子のアプリケーション呼び出しが最初に実行されるタイミングで,読み込まれます。一度読み込まれたファイルの内容は,アプリケーション呼び出しサービス内で保持されます。
また,アプリケーション呼び出し情報の一部として読み込まれた次のファイルについても同様に,一度読み込まれたファイルの内容は,アプリケーション呼び出しサービス内で保持されます。
-
RESTアプリケーション用のHTTPヘッダファイル
-
RESTアプリケーション用のスキーマ変換に使用されるスタイルシート(リクエストボディ用)
ファイルの再読み込みについては,「6.2.8(1) ファイルに格納した設定情報を変更する」の,アプリケーション呼び出し情報ファイル,RESTアプリケーション呼び出し用ヘッダファイル,またはRESTアプリケーション呼び出しスキーマ変換用スタイルシートの内容を変更した場合についての説明を参照してください。
(7) アプリケーション呼び出し情報ファイルとリクエストボディの関係
アプリケーション呼び出し情報ファイルに記述した内容に従って,対応する値がリクエストボディに渡されます。リクエストボディは,RESTアプリケーションに渡されます。
アプリケーション呼び出し情報ファイルの記述例を次に示します。この例では,1行目でrest.request.body.key.userdescriptionの値として案件名を指定しています。
rest.request.body.key.userdescription=@PIName rest.request.body.key.offset=0
アプリケーション呼び出し情報ファイルを上記の例のとおり記述した場合の,RESTアプリケーションにリクエストボディが渡されるまでの流れを,次の図に示します。
- <説明>
-
アプリケーション呼び出し情報ファイルの内容に従って,対応する値がリクエストボディに渡されます。リクエストボディは,RESTアプリケーションに渡されます。
(8) アプリケーション呼び出し情報ファイルに指定するパラメタの一覧
- 指定するパラメタの一覧(アプリケーション呼び出し情報ファイル)
-
アプリケーション呼び出し情報ファイルに指定するパラメタの一覧を示します。
表H‒5 指定するパラメタの一覧(アプリケーション呼び出し情報ファイル) 項番
パラメタ名
指定内容
1
アプリケーション呼び出しの種類(REST)
2
RESTアプリケーションのメソッド
3
RESTアプリケーションのURL
4
HTTPヘッダを記述したファイルのファイルパス
5
リクエストボディ用スキーマ変換スタイルシートのファイルパス
6
RESTアプリケーションの呼び出し時の読み込みタイムアウト値
7
RESTアプリケーション呼び出し時の接続タイムアウト値
8
リクエストボディに格納する値
9
RESTアプリケーションがべき等性を保証しているかどうか
- 注※
-
key要素値とは,REST アプリケーションの呼び出し時に使用されるボディデータ(リクエストボディまたはレスポンスボディ)の,data要素中のkey要素の値です。
次に示すボディデータの記述例の"aaa"に該当する値です。
<data> <key>aaa</key> <value>bbb</value> </data>
(9) アプリケーション呼び出し情報ファイルに指定する内容
- アプリケーション呼び出し情報ファイルの格納先ファイルパス
-
RESTアプリケーションの呼び出しについて設定する,アプリケーション呼び出し情報ファイルの格納先ファイルパスを,次に示します。
<BpmnCallInformationFileDirプロパティの指定値>/ope/<ref識別子の値>.properties
- アプリケーション呼び出し情報ファイルの記述例
-
RESTアプリケーションの呼び出しについて設定する場合の,アプリケーション呼び出し情報ファイルの記述例を次に示します。
type=REST rest.request.method=POST rest.request.url=http://hostname/app/function rest.request.header.filepath= /home/csciw/header.properties rest.request.body.key.offset=0 rest.request.body.key.userdescription=@PIName
(a) type(REST)
- キーの説明
-
アプリケーション呼び出しの種類を指定します。このキーは指定必須です。
- 指定値の説明
-
"REST"を指定してください。
RESTタイプのアプリケーションにアクセスします。
- 注意事項
-
大文字と小文字は区別します。
(b) rest.request.method
- キーの説明
-
RESTアプリケーションのメソッドを指定します。このキーは指定必須です。
- 指定値の説明
-
呼び出し対象のRESTアプリケーションのメソッド名を指定します。次のどれかを指定してください。
-
GET:リソースを取得するリクエストの場合
-
POST:リソースを追加するリクエストの場合
-
PUT:リソースを更新するリクエストの場合
-
DELETE:リソースを削除するリクエストの場合
-
- 注意事項
-
大文字と小文字は区別します。
(c) rest.request.url
- キーの説明
-
RESTアプリケーションのURLを指定します。このキーは指定必須です。
- 指定値の説明
-
呼び出し対象のRESTアプリケーションのURLを指定します。
記述例
http://host1:80/apppath1/apppath2
URLの次の部分には,組み込み変数を記述することもできます。
-
パスのディレクトリ名およびファイル名
-
クエリパラメタのキーおよび値
記述例
http://host1:80/apppath1/apppath2/@PIName?processid=@PIID&workid=@WIID
-
- 注意事項
-
-
このプロパティに指定した組み込み変数の値は,次のとおりURIエンコードされます。なお,URIエンコードの文字コードはUTF-8とします。
・半角スペースは"%20"にエンコードされる
・半角スペース以外の文字はjava.net.URLEncoderクラスの仕様に従いエンコードされる
-
組み込み変数の値以外は,自動ではURIエンコードされません。RFC 2396で定義されている文字を使用し,必要に応じてURIエンコードした値を指定してください。
-
(d) rest.request.header.filepath
- キーの説明
-
アプリケーション呼び出しサービスのリクエストにHTTPヘッダを含める場合に指定します。
指定を省略した場合,ヘッダ部が空のリクエストを送信します。
- 指定値の説明
-
HTTPヘッダを記載したヘッダファイルのパスを,絶対パスで指定します。
ヘッダファイルについては「付録H.13(5) HTTPヘッダを記述したファイルの指定方法」を参照してください。
- 注意事項
-
OSがUNIX,かつ,rootユーザ以外の任意のOSユーザがCSCIWの業務アプリケーションを実行する場合,このプロパティに指定したファイルの所有者,およびグループもあわせて変更してください。
(e) rest.request.stylesheet.filepath
- キーの説明
-
アプリケーション呼び出しサービスのリクエストボディの,XMLスキーマ変換をする場合に指定します。
指定を省略した場合,スキーマ変換をしません。
- 指定値の説明
-
XSLTで記述されたスタイルシートのファイルパスを,絶対パスで指定します。
- 注意事項
-
OSがUNIX,かつ,rootユーザ以外の任意のOSユーザがCSCIWの業務アプリケーションを実行する場合,このプロパティに指定したファイルの所有者,およびグループもあわせて変更してください。
(f) rest.request.read.timeout
- キーの説明
-
RESTアプリケーション呼び出し時の読み込みタイムアウト値を変更する場合に指定します。
指定を省略した場合,タイムアウト値はCosminexusのJ2EEサーバ単位の通信タイムアウトを設定するejbserver.javaee.jaxrs.config.client.readTimeoutキーの設定に従います。
- 指定値の説明
-
RESTアプリケーション呼び出し時のクライアントソケットの読み込みタイムアウト値を,0〜2,147,483,647の範囲で指定します。単位はミリ秒です。
タイムアウトしない設定をする場合,0を指定してください。
- 注意事項
-
RESTアプリケーション呼び出しのタイムアウト値をCosminexusの設定に従わせる場合は,このプロパティを設計および指定する必要はありません。
(g) rest.request.connect.timeout
- キーの説明
-
RESTアプリケーション呼び出し時の接続タイムアウト値を変更する場合に指定します。
指定を省略した場合,タイムアウト値はCosminexusのJ2EEサーバ単位の通信タイムアウトを設定するejbserver.javaee.jaxrs.config.client.connectTimeoutキーの設定に従います。
- 指定値の説明
-
RESTアプリケーション呼び出し時のクライアントソケットの接続タイムアウト値を,0〜2,147,483,647の範囲で指定します。単位はミリ秒です。
タイムアウトしない設定をする場合,0を指定してください。
- 注意事項
-
RESTアプリケーション呼び出しのタイムアウト値をCosminexusの設定に従わせる場合は,このプロパティを設計および指定する必要はありません。
(h) rest.request.body.key.<key要素値>
- キーの説明
-
アプリケーション呼び出しサービスのリクエストボディに格納する値を指定します。
rest.request.methodがPOSTまたはPUTの場合に指定できます。
指定を省略した場合,リクエストボディが空のリクエストを送信します。
- 指定値の説明
-
リクエストボディに渡すvalue要素の値を指定してください。指定された<key要素値>をkey要素の値に,また指定されたプロパティの値をvalue要素の値に持つdata要素を,リクエストボディに追加します。
XMLスキーマについては「付録H.10(3) ボディデータスキーマ(XML)」を参照してください。
このプロパティの値には組み込み変数を記述できます。
- 注意事項
-
プロパティ値に値がnullの組み込み変数を指定した場合,value要素のないリクエストボディが作成されます。
(i) rest.request.idempotency
- キーの説明
-
RESTアプリケーションがべき等性を保証していない場合にfalseを指定します。
指定を省略した場合はtureが指定され,RESTアプリケーションがべき等性を保証しているものとして,アプリケーション呼び出しサービスがRESTアプリケーションを複数回呼び出すことがあります。
- 指定値の説明
-
RESTアプリケーションがべき等性を保証しているかどうかを指定します。
- trueの場合
-
べき等性を保障している場合に指定します。アプリケーション呼び出しサービスがRESTアプリケーションを複数回呼び出すことがあります。
- falseの場合
-
べき等性を保障していない場合に指定します。アプリケーション呼び出しサービスがRESTアプリケーションを複数回呼び出すことはありません。
- 注意事項
-
通常,このプロパティを設定しないでください。このプロパティにfalseを指定する場合の注意事項を次に示します。
-
RESTアプリケーションの呼び出しで障害が発生した場合,呼び出し回数が0回になることがあります。
-
RESTアプリケーションの呼び出しで障害が発生した場合,ciwchgapworkコマンドを使用して,作業の状態を変更する必要があります。RESTアプリケーションを再実行する場合,作業を実行開始可能状態に戻してください。RESTアプリケーションを再実行しない場合,作業を完了させ案件を遷移させてください。再実行するかどうかはRESTアプリケーションの実行結果を基に決定してください。
-
アプリケーション呼び出し制御情報のリトライ回数とリトライ間隔は有効になりません。
-