「データの編集」ステップ

「データの編集」ステップでは、自由書式の領域が表示され、スクリプト処理を制御するコマンドを指定できます。

「データ・テキストの編集」フィールドにスクリプト・コマンドを入力します。横にあるアイコンをクリックすると、「データの編集」ステップを定義するためのスペースが大きく確保されたウィンドウが開きます。

一般的に、「データの編集」内で使用できる構文は、明示的なステップ・タイプ内で使用できるコマンドと似ています。ただし、「データの編集」内でのみ使用可能なコマンドもいくつかあります。たとえば、 ForとIfの2つの構成済コマンドです。

注意: ビジネス・プロセス・アシスタントのすべてのステップ・タイプで「データの編集」構文の使用がサポートされているわけではありません。データの編集のコマンドおよび例の詳細は、後述の詳細を参照してください。

この項のトピックでは、「データの編集」ステップ・タイプでサポートされている構文の詳細を示します。

内容

コメント

一時変数

コンテキスト変数

move文

go to文

条件付き分岐文

if文

for文

リスト処理

リストを処理する関数

スキーマ・ベースのオブジェクトの宣言および起動

システム変数およびグローバル変数

スクリプトの実行および転送

navigate文

マップの起動文

ビジネス・オブジェクト・グループを使用したビジネス・オブジェクトの宣言

編集マップの生成文

terminate文

Groovyコードの起動

ビジネス・プロセス・アシスタント・スクリプトのデバッグ

有用なヒントとコツ

コメント

「データの編集」ステップの最初の2文字に二重スラッシュ表記//を使用して、スクリプトにコメントを配置できます。例:

// 
// quit with error
//
if ("not(customer/securityEnabled)")
terminate with error (8000, 1001 %1="customer/id" %2='not allowed');
end-if;

一時変数

一時変数は、すべてのタイプのスクリプト内で宣言できます。先頭の単一ドル記号('$')で参照します。ただし、一時変数は様々なスクリプト・タイプで動作が異なります。

  • ビジネス・プロセス・アシスタント・スクリプトでは、あるビジネス・プロセス・アシスタント・スクリプトから別のビジネス・プロセス・アシスタント・スクリプトに一時変数が永続的に残り(「スクリプトの実行文および管理の転送文」を参照)、これは一時変数を使用してビジネス・プロセス・アシスタント・スクリプト間で通信できることを意味します。

  • 一時変数は、ビジネス・プロセス・アシスタント・スクリプトからサービスまたはプラグイン・スクリプトに渡すことはできません。これらのタイプのスクリプト間では、データ領域の要素のみを渡すことができます。

  • サービスおよびプラグイン・スクリプト内では、一時変数は、変数を宣言した特定のスクリプトの存続期間中のみ永続的に残ります。これは、プラグイン・スクリプトとサービス・スクリプトの間では一時変数を受渡しできず、これらのタイプのスクリプト間ではグローバル変数、コンテキスト変数およびデータ領域の要素のみを受渡しできることを意味します。

一時変数の宣言/初期化/デフォルト設定

一時変数を使用する場合は、使用する前に適切な値で宣言または初期化する必要があります。変数を宣言する典型的な方法は、たとえば、move文でデータを単純に移動することです。

move "0" to $index;
ファストパス: move文での一時変数の暗黙的な宣言の詳細は、「一時変数への移動」を参照してください。

前述のとおり、ビジネス・プロセス・アシスタント・スクリプトでは、あるビジネス・プロセス・アシスタント・スクリプトから別のビジネス・プロセス・アシスタント・スクリプトに、一時変数を渡すことができます。したがって、以前のビジネス・プロセス・アシスタントによって初期化されたビジネス・プロセス・アシスタントの一時変数を参照することは一般的です。ただし、一時変数がなんらかの理由で以前のビジネス・プロセス・アシスタントで初期化されなかった場合は、その一時変数を参照するとエラーが発生します。したがって、作成または初期化されていない一時変数を初期化するdefault文を使用することをお薦めします。

  • 次の文は、一時変数$InputActionが初期化されていない場合にのみ、この一時変数を初期化します。

    default $InputAction;

  • 次の文は、一時変数$InputActionが初期化されていない場合にのみ、この変数の値を'read'に設定します。

    default $InputAction as 'read';
注意: スクリプトには、予約されているキーワードを使用して変数を定義しないように注意してください。次の表に、予約されているキーワードのリストを示します。
キーワード
add
as
asError
bpa
branch
data
declareBO
declareBS
declareDA
declareMap
declareSS
default
delete
edit
element
else
end-edit
end-for
end-if
error
escape
evaluate
fastAdd
fastUpdate
for
goto
if
in
invokeBO
invokeBS
invokeMap
invokeSS
label
map
move
navigate
navigateAndReloadDashboard
null
page
performScript
popup
read
readWithoutVersion
replace
suppress
target
terminate
to
transferControl
update
using
warn
with

コンテキスト変数

コンテキスト変数はサービス・スクリプト内のみで使用できます。コンテキスト変数は、サービス・スクリプトが実行されている間、起動したすべてのスクリプトで使用できます。したがって、サービス・スクリプト内でコンテキスト変数を使用して、下位レベルのサービス・スクリプトまたはスキーマに情報を伝達できます。先頭の2つのドル記号('$$')で参照します。

注意: コンテキスト変数は下位レベルのスクリプトで使用できるため、グローバル変数またはグローバル・コンテキスト変数と呼ばれることもあります。しかし、コンテキスト変数をグローバル変数と混同しないでください。

コンテキスト変数の宣言/初期化/デフォルト設定

コンテキスト変数を使用する場合は、使用する前に適切な値で宣言または初期化する必要があります。変数を宣言する典型的な方法は、たとえば、move文でデータを単純に移動することです。

move 'context variable' to $$contextVariable;
ファストパス: 詳細は、「コンテキスト変数を使用した移動」を参照してください。

move文

move文はソース値をターゲットにコピーします。次の表に、move文でサポートされている様々なオプションを示します。

文 例の説明 例の構文
要素への移動

move "xpath" to "xpath";

注意: XPath式は二重引用符で囲みます。
 単純なXPath参照を使用したmove文。 
move "acct/totalBalance" to 
"parm/formattedValue";
XPath concatenate関数を使用したmove文。 
move "concat(person/firstName, ',', 
person/lastName)" 
to "parm/fullName";
XPath substring-before関数を使用したmove文。 
move "substring-before(parm/fullName,',')" 
to "person/firstName";
XPath substring-after関数を使用したmove文。 
move "substring-after(parm/fullName,',')" 
to "person/lastName";
XPath substring関数を使用したmove文。 
move "substring(parm/date,1,4)" 
to "parm/year";
要素への移動

move 'literal' to "xpath";

注意: リテラル値は一重引用符で囲みます。
 リテラル文字列を使用したmove文。 
move 'okay for mailing' 
to "account/preferences[type="mail"]/text";
要素への移動

move 'Boolean' to "xpath";

ブールをリテラル文字列として使用したmove文。 
if ("account/balance > 0") 
  move 'true' 
  to "account/hasDebitBalance"; 
end-if;
式を移動すると、結果はブールになります。次の例のフィルタは、グループ・ノードに配置されていることに注意してください。 
<schema>
  <account>
    <hasDebitBalance type="boolean"/>
    <balance/>
  </account>
</schema>

move "boolean(account[balance>0])" 
to "account/hasDebitBalance";
グループへの移動

move "xpath" to "xpath";

あるグループから別のグループに一連の要素を移動します。

システムにより、ソース・スキーマからターゲット・スキーマに対して、要素名の最初のレベルとグループ名またはリスト名が照合されます。リストおよびグループの場合、デフォルトの動作は、ソースのグループまたはリスト内のすべての要素をターゲットのグループまたはリストに移動することです(これらがターゲットのグループまたはリストで定義されていない場合も同様)。

移動をより詳細に制御できるように、ビジネス・サービスF1-MoveByNameを使用できます(個々のmove文を定義する必要がありません)。

 
move "account/custInfo" to "person";

この文は次の文と同等です。

move "account/custInfo/*" to "person/*";

一時変数を使用した移動

一時ローカル変数に移動する場合は、一時ローカル変数を二重引用符で囲みません。

move "xpath" to $variable; 

move "count(Person/names/personName) 
+ count(Person/ids/personId)" 
to $PersonChildCount;
一時変数から移動する場合は、その変数を二重引用符で囲みます。

move "$variable" to "xpath"; 

move "$AccountBalance" 
to "parm/formattedValue";

コンテキスト変数を使用した移動

move "xpath" to $$variable;

move $$variable to "xpath";

ソースまたはターゲットのコンテキスト変数は二重引用符なしで参照します。 
move 'context value' 
to $$contextVariable;
// 
// here, we move from a context variable.
move $$contextVariable 
to "MarketMessage/sender";
動的な場所を使用した移動

move "xpath" | 'literal' to evaluate("xpath" | $variable);

move evaluate("xpath" | $variable) to "xpath" | $variable;

evaluate文を使用して、移動元または移動先の場所を変数またはスキーマ要素の場所から動的に取得できます。 
move 'literal' 
to evaluate("schemaLocation"); 
//
move "schemaLocation" 
to evaluate($Variable);
move evaluate("schemaLocation") 
to $Variable;
// 
move evaluate($Variable) 
to "schemaLocation";
move escape

move escape("xpath" | $variable) to "xpath" | $variable;

move escapeはサービス・スクリプトおよびプラグイン・スクリプトにのみ使用できます。escape文は、HTMLコンテンツのソース・テキスト値をスキャンしてテキスト値をエスケープします。つまり、HTMLのような文字をHTMLレンダリングからエスケープされる特殊文字に置換します。このようにすることで、HTML要素の一部として表示される場合に、テキストがプレーン・テキストとして表示されます。
注意: この関数は、テキストをHTML要素の一部として表示する際に、そのテキストにHTMLのような文字またはHTMLとしてレンダリングしない必要がある不当なHTMLが含まれている疑いのある場合にのみ使用してください。HTML以外の要素を使用して不適切に表示された場合は、特別なエスケープ文字(ある場合)がテキストの一部として表示されます。HTMLコンテンツを表示するための要素の定義方法の詳細は、「UIマップ属性および関数」を参照してください。
 
move escape("schemaLocation") 
to $Variable;
// 
move escape($Variable) 
to "schemaLocation";
move null

move null to "xpath";

move nullという特殊な構文を使用して、XMLインスタンス・ドキュメントから情報を削除できます。ノード名をXPath式に指定するか、グループ名を指定できます。グループを指定すると、グループおよびそのすべての子要素が処理から消去されます。

ノードおよびそのすべての子ノードを削除します。

if ("boolean(customer/securityEnabled)")
  goto updateInfo;
else
  move null to "customer"; 
end-if;   

'/*'のサフィックスが付いたグループ・ノードのすべての子ノードを削除します。

if ("boolean(customer/securityEnabled)")
  move null to "customer/*";
end-if;

go to文

「データの編集」ステップでは、「移動先」ステップ・タイプに似た機能をサポートしています。構文はgoto label;で、labelは(このラベルで識別される)「データ・テキストの編集」フィールド内の別の場所またはスクリプトの別のステップを表します。

次の例では、addSpouseというラベルで識別される同じステップの別の場所に移動します。

if ("string(parm/spouse/name) != $BLANK")
  goto addSpouse;
end-if;
addSpouse: invokeBO 'Person' using "parm/spouse" for add;

次の例では、同じスクリプト内の別のステップに移動します。ステップ・シーケンスはラベルとして使用される参照です。

if ("string(parm/spouse/name) != $BLANK")
  goto 110;
end-if;
.
.
.
110: invokeBO 'Person' using "parm/spouse" for add;

条件付き分岐文

「データの編集」ステップでは、「条件付き分岐」ステップ・タイプに似た機能をサポートしています。構文はbranch ("xpath") goto label else label;です。

  • branch文のXPath条件は、TrueまたはFalseのブール値に評価する必要があります。

  • gotoおよびelse文のターゲットは、(このラベルで識別される)「データ・テキストの編集」フィールド内の別の場所を表す、またはスクリプトの別のステップを表すラベルです。

次の例では、addSpouseおよびaddAccountのラベルを使用しています 

branch ("string(parm/spouse/name) != $BLANK") goto addSpouse else addAccount;

if文

if文は条件付き分岐文と類似しています。いずれかを使用してスクリプトのロジックを構築できます。この文には必要に応じてelse文を指定できますが、常にend-if文で終了する必要があります。

注意: これは独立したステップ・タイプとして表されていない文の例です。「データ・テキストの編集」内でのみ使用できます。

構文はif ("xpath") else end-if;です。XPath条件は、TrueまたはFalseのブール値に評価する必要があります。次にいくつかの例を示します。

単純な論理条件が指定されている例。

if ("string(parm/spouse/name) != $BLANK")
  //
  // Create spouse since spouse name present
  goto addSpouse;
else
  //
  // Create account without spouse
  goto addAccount;
end-if;

複雑な論理条件が指定されている例。

if ("string(parm/spouse/name) != $BLANK and string(parm/hasSpouse) = true or boolean(parm/requireSpouse)")
  //
  // Create spouse since spouse name present
  goto addSpouse;
end-if;

フィールドに考えられる複数の値を評価するために使用する一連の文が積み重ねられている例。 

if ("parm/rowCount = 0")
  //
  // no rows found
  goto quit;
end-if;
if ("parm/rowCount = 1")
  //
  // one row found
  goto process;
end-if;
if ("parm/rowCount > 1")
  //
  // more than one row found
  goto quit;
end-if;
quit: terminate;

次のXPathでは、ノードの存在に基づいてブールが示されます。この例では、処理するXMLインスタンス・ドキュメントにノードが存在する場合は、文がTrueに評価されます。要素が見つからない場合、文はfalseに評価されます。

注意: XPathノードをブール変数として取り扱う場合は、空のノードがTrueに評価されることに注意してください。欠落しているノードのみがFalseを返します。 
if ("boolean(parm/spouse/name)")
  goto addSpouse;
else
  //
  // Create account without spouse
  goto addAccount;
end-if;
 
if ("not(parm/spouse/name)")
  //
  // Create account without spouse
  goto addAccount;
else
  goto addSpouse;
end-if;

for文

for文はXPath式に応じてノードまたは値のリストを作成します。リスト・ノードを指定すると、リストのすべての子ノードおよびその内容がループ内で使用可能になります。子ノードを直接指定すると、値リストのみがループ内で使用可能になります。

注意: リストに新しいエントリを作成する方法の詳細は、「新しいリスト・インスタンスの作成」例を参照してください。
注意: これは独立したステップ・タイプとして表されていない文の例です。「データ・テキストの編集」内でのみ使用できます。

構文はfor ($variable in "xpathList") end-for;です。XPath条件は、TrueまたはFalseのブール値に評価する必要があります。

次の各例は、このサンプル・スキーマに基づいています。

<schema>
  <SAList type="list">
    <id/>
    <balance/>
  </SAList>
  <SAContributor type="list">
    <id/>
  </SAContributor>
</schema>

すべての子ノードを処理できるXPath式のリスト・ノードを指定する例。 

move "0" to $AccountBalance;
move "0" to $index;
for ($SAList in "SAList")
    move "$SAList/balance + $AccountBalance" to $AccountBalance;
    //
    // keep track of each SA contributing to the balance in the SA Contributor list
    move "1 + $index" to $index;
    move "$SAList/id" to "SAContributor[$index]/id";
end-for; 

XPath式のリスト・ノード内の子ノードを指定する例。そのノードの値のみを処理に使用できます。 

move "0" to $AccountBalance;
for ($SABalance in "SAList/balance")
    move "$SABalance + $AccountBalance" to $AccountBalance;
end-for;

forループで選択される行を制限するためにフィルタを使用できることを示す例。

move "0" to $AccountDebitBalance;
for ($SAList in "SAList[Balance>0]")
    move "$SAList/balance + $AccountDebitBalance" to $AccountDebitBalance;
end-for; 

子ノードを指定するときにフィルタを使用する例。

move "0" to $AccountCreditBalance;
for ($SABalance in "SAList[Balance<0]/balance")                 
    move "$SABalance + $AccountCreditBalance" to $AccountCreditBalance;                
end-for;

リスト処理

この項では、リストの処理について詳細を示します。この項の各例では、次のスキーマを参照します。

<schema>
  <parm type="group">
    <name/>
  </parm>
  <Person type="group">
    <names type="list">
      <type/>
      <name/>
    </names>
  </Person>
</schema>

リスト要素の参照。フィルタ内のリストの識別ノードを参照することで、特定のリスト・インスタンスに値を移動できます。構文はmove "xpath" to "xpathList[filter]/element";です。次に例を示します。

move "parm/name" to "Person/names[type='main']/name";

新しいリスト・インスタンスの作成。新しいリスト・インスタンスを作成することを示すために、ターゲットのmove文で特殊な表記を使用できます。「+」は、ターゲット要素に対してリストの新しいインスタンスを開始することをスクリプト・プロセッサに示します。構文はmove "xpath" to "+xpathList";です。次に例を示します。

move "parm/name" to "Person/+names/name";

リスト・インスタンスの削除。XMLリスト・エントリは、要素名に'delete'の処理属性を移動することで、データベースから削除できます。データベースでリスト・エントリの削除が生じるには、ターゲット・ノードにaction="delete"の属性と、それに続くビジネス・オブジェクトの更新の相互作用が必要です。構文はmove 'delete' to "xpathList@action");です。次に例を示します。

if ("parm/action = 'd'") 
    move "0" to $index;
    for ($CCList in "CCList")
        move "1 + $index" to $index;
        if ("$CCList/id = parm/id")
            move 'delete' to "CCList[$index]@action";
            goto update;
        end-if;
    end-for;
end-if;

次に結果のXMLを示します。

<root>
  <CCList>
    <id>9876538976</id>
    <balance>309.98</balance>
  </CCList>
  <CCList action="delete">
    <id>4321125899</id>
    <balance>87.45</balance>
  </CCList>
</root>
注意: 反復的なビジネス・オブジェクトの相互作用が必要な場合は、処理属性を使用してリスト・インスタンスを削除することは危険です。削除するリスト・インスタンスが含まれているXMLドキュメントは、ビジネス・オブジェクトの相互作用が正常に終了した後も変更されず、つまり、ドキュメントにリスト・インスタンスがすでに存在しない場合も、引き続きリスト・インスタンスが含まれていることになります。この問題を解決するには、'delete'の処理属性が使用されているビジネス・オブジェクトの更新後に、ビジネス・オブジェクトを再度読み取る必要があります。
注意: ここに記載されている削除属性のかわりに、replaceのビジネス・オブジェクト処理を使用できます。置換処理を使用するためにリストを操作すると、ビジネス・オブジェクト更新後の要求ドキュメントの古くなった情報に関連する前述の問題が回避されます。

リストを処理する関数

XPathには、count、sum、lastなど、リストの要素を処理するのに便利ないくつかの関数が用意されています。

次の各例は、このサンプルXMLドキュメントに基づいています。

<xml>
  <ft>
    <type>bill</type>
    <date>20100101</date>
    <amt>30.30</amt>
    <cat>tax</cat>
  </ft>
  <ft>
    <type>adj</type>
    <date>20100301</date>
    <amt>20.20</amt>
    <cat>int</cat>
  </ft>
  <ft>
    <type>bill</type>
    <date>20100201</date>
    <amt>10.10</amt>
    <cat>tax</cat>
  </ft>
</xml>

次にsumの例を示します。構文はmove "sum(xpathList/element)" to $variable;です。この例では合計残高を合計します。 

move "sum(ft/amt)" to $TotalBalance;

次にフィルタを使用して小計を取得するsumの例を示します。この例では'tax'カテゴリがあるエントリの残高を合計します。 

move "sum(ft[cat='tax']/amt)" to $TaxBalance;

次にcountの例を示します。構文はmove "count(xpathList)" to $variable;です。この例ではリスト内の財務取引エントリの件数を見つけます。 

move "count(ft)" to $TranCount;

次に最終エントリの検索に使用するlastの例を示します。構文はmove "last(xpathList)" to $variable;です。この例では財務取引リストの最後の金額を見つけます。

move "ft[last()]/amt" to $LastAmount;

スキーマ・ベースのオブジェクトの宣言および起動

「データの編集」ステップ内では、ビジネス・オブジェクト、ビジネス・サービスまたはサービス・スクリプトを起動できます。動的起動をサポートするために、動的データ領域名を宣言できます。

宣言されるスキーマは、ビジネス・オブジェクト(BO)スキーマ、ビジネス・サービス(BS)スキーマ、サービス・スクリプト(SS)スキーマ、データ領域(DA)スキーマまたはUIマップ・スキーマです。宣言文はスキーマのタイプよって異なりますが、構文は似ています。

  • declareBO 'BO Name' | $variable | "xpath" as 'DynamicDataArea';

  • declareBS 'BS Name' | $variable | "xpath" as 'DynamicDataArea';

  • declareSS 'SS Name' | $variable | "xpath" as 'DynamicDataArea';

  • declareDA 'DA Name' | $variable | "xpath" as 'DynamicDataArea';

  • declareMap 'Map Name' | $variable | "xpath" as 'DynamicDataArea';

BO、BSまたはSSを起動する場合、オブジェクトの名前はリテラルとして指定することも、要素または変数内に格納された値にすることもできます。すべての起動に対して、グループ名へのXPath参照を提供する必要があります。

ビジネス・オブジェクトを起動する際は、処理を提供する必要があります。構文はinvokeBO 'BO Name' | $variable | "xpath" using "xpath" for action;です。有効な処理は次のとおりです。

  • read。この処理はビジネス・オブジェクト・データの現在のビューを読み取ります。

  • add。この処理はオブジェクトを追加し、ビジネス・オブジェクトの結果ビューを読み取って返します。

  • fastAdd。この処理はオブジェクトを追加しますが、ビジネス・オブジェクトの結果ビューを返すための後続する読取りは実行しません。レコードを再読取りする理由がない場合、このオプションは、パフォーマンス向上のためにaddより適切です。

  • update。この処理はオブジェクトを更新し、ビジネス・オブジェクトの結果ビューを読み取って返します。この処理は、既存のビジネス・オブジェクト・データを使用してinvoke文の要求XMLドキュメントに指定された情報のマージを実行します。この処理を使用することで、変更されている要素のみを示すことができます。

  • fastUpdate。この処理はオブジェクトを更新しますが、ビジネス・オブジェクトの結果ビューを返すための後続する読取りは実行しません。レコードを再読取りする理由がない場合、このオプションは、パフォーマンス向上のためにupdateより適切です。

  • delete。この処理はオブジェクトを削除します。

  • replace。この処理は更新処理の代替です。置換処理は、既存のビジネス・オブジェクト・データを要求ドキュメントの情報で完全に置き換えます。ビジネス・オブジェクトにリストが含まれている場合、通常は置換処理が使用されます。これは、明示的にリスト・インスタンスを削除する特別なロジックが必要なリスト・マージを試みるより、リストのすべてのインスタンスを単純に置換するほうがより簡単であるためです。

    注意: UIマップ機能を使用してCSVファイルをアップロードする場合は、置換処理を使用する必要があります。
    注意: 現在、置換処理は、リスト・メタファーを使用してページ内のすべてのレコードを一度に表示する固定ページで保守されるメンテナンス・オブジェクトでサポートされていません。「通貨」はこのタイプのページの例です。

例:

invokeBO 'BusinessObject' using "dataArea" for fastAdd;
 
invokeBO $variableBO using "dataArea" for fastUpdate;
 
invokeBO "daName/boElement" using "dataArea" for replace;

ビジネス・サービスとサービス・スクリプトの両方のinvoke文は構文が似ています。ビジネス・サービスとサービス・スクリプトは、グループ名に対するXPath参照とともに指定されます。

  • invokeBS 'BS Name' | $variable | "xpath" using "xpath";

  • invokeSS 'SS Name' | $variable | "xpath" using "xpath";

この例ではinvokeBS文を使用していますが、invokeSS文の場合も文は同様です。

invokeBS 'BusinessService' using "dataArea";
 
invokeBS $variableBS using "dataArea";
 
invokeBS "daName/bsElement" using "dataArea";

ビジネス・オブジェクト警告。ビジネス・プロセス・アシスタント・スクリプトの場合、invoke文は警告の処理方法も示していることに注意してください。

構文 摘要 例

with warn asError

UIマップに表示されるエラーとして警告を処理することを示します。テキストasErrorはオプションです。 

invokeBO 'BusinessObject' using "dataArea" for add with warn asError;

invokeSS 'ServiceScript' using "dataArea" with warn;

with warn popup

標準フレームワーク・ポップアップで警告を表示することを示します。このシナリオでは、標準の「OK」および「取消」ボタンがユーザーに表示されます。ユーザーが「OK」をクリックした場合は、プロセスを続行することを意味します。ユーザーが「取消」をクリックした場合は、処理が中止されます。これは推奨される設定です。

 
invokeBS "daName/bsElement" using "dataArea" with warn popup;

with warn suppress

警告を抑制することを示します。これはinvoke文に警告構文が追加されていない場合のデフォルトです。

 
invokeBS "daName/bsElement" using "dataArea" with warn suppress;

invokeSS 'ServiceScript' using "dataArea";
注意: サービス・スクリプトでは、サービス・スクリプトから起動されたすべてのオブジェクトにその警告レベルが継承されます。したがって、サービス・スクリプトがwith warnで起動された場合、ネストされたすべてのinvoke文もwith warnで起動されます。

ビジネス・プロセス・アシスタント・スクリプトでは、(with warn popupを使用して)エラーおよび警告を処理するために、起動に続くロジックも存在します。システム変数$WARNINGは、ユーザーが警告ポップアップで「取消」ボタンをクリックした場合にtrueに設定されます。マップが表示されていた場合は、ロジックによってマップが再表示されます(ここに警告メッセージが再表示されます。)これで、ユーザーは変更を加えて再度保存できます。警告の前にマップが表示されていなかった場合は、ロジックが終了します。

システム変数$ERRORは、エラーが受信されたことを示します。エラーの前にマップが表示されていた場合は、エラーを表示する場所となるマップをロジックによって再表示する必要があります。マップが表示されていなかった場合は、製品によって提供されるビジネス・プロセス・アシスタント・スクリプトF1-HandleErrを使用してエラーを表示する必要があります。次に典型的なエラー処理ロジックの例を示します。 

invokeBO "F1-DetermineBo/output/bo" using "boSchema" for update with warn popup;
if ("$WARNING")
   if ("map_schema/action = 'DEL'")  
     terminate;
   else
     goto maintMap;   
   end-if;
end-if;
if ("$ERROR")
  if ("map_schema/action != 'DEL'")
    goto maintMap;
  else
    transferControl 'F1-HandleErr';
  end-if;
end-if;

システム変数およびグローバル変数

次の各表に、スクリプトの記述に使用可能なシステム変数およびグローバル変数を示します。

システム変数 - すべてのスクリプト・タイプ

次のシステム変数は、すべてのスクリプト・タイプ(サービス・スクリプト、プラグイン・スクリプトおよびビジネス・プロセス・アシスタント・スクリプト)に使用可能です。

変数 摘要 例
$BLANK 空のノードを表します。 
if ("string(parm/spouse/name) != $BLANK")
  goto addSpouse;
end-if;
$CURRENT-DATE 現在日を表します。

ビジネス・プロセス・アシスタント・スクリプトの場合、これはブラウザの日付です。

サービス・スクリプトの場合、これはサーバーの日付です(システム日付の上書きロジックの影響を受けます)。

 
move "$CURRENT-DATE" to $tempDate;
$CURRENT-STD-DTTM 標準時(夏時間/サマー・タイムの調整がないことを意味する)で表された現在の日時を表します。 
move "$CURRENT-STD-DTTM" to $tempDateTime;
$DEVICE-OS ユーザーの設備のオペレーティング・システムを表します。 
move "$DEVICE-OS" to $tempDeviceOs;
$DEVICE-BROWSER ユーザーの設備のブラウザを表します。 
move "$DEVICE-BROWSER" to $tempDeviceBrowser;
$DEVICE-DISPLAY-TYPE ユーザーの設備の画面表示タイプがデスクトップ・サイズであるか、中または小型のサイズであるかを表します。戻り値はoraDesktop、oraTablet、oraPhoneのようになります。 
move "$DEVICE-DISPLAY-TYPE" to $tempDeviceDisplayType;
$DEVICE-INFO 3つの設備プロパティ(DEVICE-OS、DEVICE-BROWSERおよびDEVICE-DISPLAY-TYPE)のすべての組合せを提供し、各プロパティ値はセミコロンで区切られます。 
move "$DEVICE-INFO" to $tempDeviceInfo;

システム変数 - ビジネス・プロセス・アシスタント・スクリプトのみ

次のシステム変数は、ビジネス・プロセス・アシスタント・スクリプト・タイプにのみ使用/適用可能です。

変数 摘要 例
$DOUBLE_​QUOTE 二重引用符を表します。 
move "$DOUBLE_QUOTE" to $tempField;
$SINGLE_​QUOTE 一重引用符を表します。 
move "$SINGLE_QUOTE" to $tempField;
$SPACE 単一の空白値が含まれます。 
move "$SPACE" to $tempField;
$SYSTEM-DATE サーバーの日付を表します。この日付は、システム日付の上書きロジックの影響を受けることに注意してください 
move "$SYSTEM-DATE" to $tempDate;

システム変数 - サーバー・スクリプトのみ

次のシステム変数は、サービス・スクリプト・タイプおよびプラグイン・スクリプト・タイプにのみ使用/適用可能です。

変数 摘要 例
$ADDITIONAL-IP-INFO HTTP要求に、追加のIPアドレス・ヘッダー・フィールドを挿入します。発信元IPアドレスなど、プロキシ・サーバーまたはロード・バランサで使用可能な情報がある場合は、実装で移入されます。 
move "$ADDITIONAL-IP-INFO" to "parm/request/headerIpAddress";
$CURRENT-DTTM 現在の日時を表します。 
move "$CURRENT-DTTM" to $tempDateTime;
$F1-INSTALLATION-TIMEZONE インストール・オプションで定義されているゾーン・コードを表します。 
move "$F1-INSTALLATION-TIMEZONE" to $timeZone;
$LANGUAGE スクリプトが使用している言語コードを表します。通常、これはユーザーのデフォルト言語です。 
move "$LANGUAGE" to $tempLanguage;
$PROCESS-DATE 処理日を表します。処理日は実行されているプロセスの期間全体で一貫しているため、現在日とは異なります。たとえば、サービス・スクリプトに複数のビジネス・オブジェクトが格納されている場合、処理日はサービス・スクリプトの実行開始時に初期化され、各ビジネス・オブジェクトは同じ処理日にデフォルト設定されます。現在日、特に現在の日時には実際の処理時間が反映されます。 
move "$PROCESS-DATE" to $tempDate;
$PROCESS-DTTM 処理の日時を表します。処理の日時は特定のプロセスの開始時に初期化され、更新の正確な日時は反映されません。 
move "$PROCESS-DTTM" to $tempDateTime;
$REQUESTING-IP-ADDRESS HTTP要求のIPアドレスを表します。要求がプロキシ・サーバーまたはロード・バランサ経由でルーティングされる場合、このIPアドレスはエンド・ユーザーのIPアドレスではなく、プロキシまたはロード・バランサのIPアドレスになります。詳細は、$ADDITIONAL-IP-INFO変数を参照してください。 
move "$REQUESTING-IP-ADDRESS" to "parm/request/systemIpAddress";
$USER スクリプトを実行しているユーザーのユーザーIDを表します。 
move "$USER" to $tempUser;

ビジネス・プロセス・アシスタント・スクリプトで現在のユーザーのユーザーIDを知る必要がある場合は、「有用なヒントとコツ」を参照してください。

グローバル変数

ビジネス・プロセス・アシスタント・スクリプトおよびサービス・スクリプトは、グローバル・コンテキストで定義された値にアクセスできます。

ユーザー・インタフェースからビジネス・プロセス・アシスタント・スクリプトが起動されると、これらの変数は自動的に初期化されます。フィールド名の前に単一のドル記号を付けて参照されます。たとえば、PER_​IDがサポートされているグローバル変数の場合、ビジネス・プロセス・アシスタント・スクリプト内では$PER_​IDを参照できます。

move "$PER_ID" to "schema/customerId";

サービス・スクリプトでは、ビジネス・プロセス・アシスタント・スクリプトまたはポータルのゾーンからサービス・スクリプトが直接起動された場合にのみ、グローバル変数を参照できます。サービス・スクリプトがビジネス・プロセス・アシスタント・スクリプトまたはポータル・ゾーンから起動されると、UIセッションに移入された一連のグローバル・コンテキスト変数へのアクセス権が付与されます。サービス・スクリプトの場合、グローバル・フィールドには2つのドル記号のプリフィクスを付ける必要があります(ビジネス・プロセス・アシスタント・スクリプトで1つ付けるかわりに)。たとえば、PER_​IDがサポートされているグローバル・コンテキスト変数の場合、サービス・スクリプト内では$$PER_​IDを参照できます。

move $$PER_ID to "schema/customerId";
注意: コンテキスト変数の説明のとおり、サービス・スクリプトでは同じ2つのドル記号構文を使用するコンテキスト変数を宣言する場合があります。

スクリプトの実行文および管理の転送文

「データの編集」ステップでは、「スクリプトの実行」ステップ・タイプおよび「管理の転送」ステップ・タイプに似た機能をサポートしています。これらは両方ともビジネス・プロセス・アシスタント・スクリプトにのみ適用されます。

構文 有効値 コメント

performScript

 'ビジネス・プロセス・アシスタント・スクリプト名' 実行するスクリプトを明示的に指定します。
$変数 実行するスクリプトは変数内にあります。
"XPath" 実行するスクリプトはXPathが参照する要素内にあります。

transferControl

 performScript文に似ています
注意: performScript文で指定されたスクリプトが終了すると、コール元ビジネス・プロセス・アシスタント・スクリプトに管理が戻ります。transferControl文で指定されたスクリプトが終了した場合は、コール元スクリプトに管理が戻されず、転送先のスクリプトに完全な管理が与えられます。

navigate文

「データの編集」ステップは、「ページに移動」ステップ・タイプに似た機能をサポートしています。これはビジネス・プロセス・アシスタント・スクリプトにのみ適用されます。

構文 有効値 コメント

navigate

 'ナビゲーション・コード' ナビゲーション・オプションを明示的に指定します。
$変数 ナビゲーション・オプションは変数内にあります。
"XPath" ナビゲーション・オプションはXPathが参照する要素内にあります。

さらに、「データの編集」ステップでは、ナビゲートする際にダッシュボードをリフレッシュすることを示す機能がサポートされています。これはビジネス・プロセス・アシスタント・スクリプトにのみ適用されます。

構文 有効値

navigateAndReloadDashboard

 navigate文に似ています

ビジネス・オブジェクト・グループを使用したビジネス・オブジェクトの宣言

この文は、編集マップの生成文の基本スクリプト「メイン・ビジネス・オブジェクト保守処理」(F1–MainProc)を使用する予定があるビジネス・プロセス・アシスタント・スクリプトに固有のものです。このスクリプトは、マップに表示する際に使用されるデータがboGroupタグ内にあることを想定しています。

構文 有効値 コメント

declareBOWithBOGroup

 'ビジネス・オブジェクト名' ビジネス・オブジェクトを明示的に指定します。
$変数 ビジネス・オブジェクトは変数内にあります。
"XPath" ビジネス・オブジェクトはXPathが参照する要素内にあります。

次の表に、この文のその他の構文を示します。

構文 有効値

as

 '動的スキーマ名'

例:

declareBOWithBOGroup 'BusinessObject' as 'newMapSchema';
 
declareBOWithBOGroup $variableBO as 'newMapSchema';
 
declareBOWithBOGroup "daName/boElement" as 'newMapSchema';

マップの起動文

「データの編集」ステップでは、「マップの起動」ステップ・タイプに似た機能をサポートしています。これはビジネス・プロセス・アシスタント・スクリプトにのみ適用されます。

構文 有効値 コメント

invokeMap

 'マップ名' UIマップを明示的に指定します。
$変数 UIマップは変数内にあります。
"XPath" UIマップはXPathが参照する要素内にあります。

次の表に、この文のその他の構文を示します。

構文 有効値 コメント

using

 "データ領域グループ名" マップに関連付けられたHTMLフォームをレンダリングするときに、サーバーとの間で受け渡されるデータ領域を指定します。

target

bpa

page

popup

target値の詳細は、「マップの起動」ステップ・タイプを参照してください。

UIマップが値を返すように構成されている場合は、$MAP-VALUE変数を使用して値を評価できます。

invokeMap 'UI Map' using "dataArea";
 
invokeMap $variableMap using "dataArea";
 
invokeMap "daName/mapElement" using "dataArea" target bpa;
 
// $MAP-VALUE is a variable returned by the invoked map.
if ("$MAP-VALUE='continue' ")
    goto 300;
else
    terminate;
end if;

編集マップの生成文

編集マップの生成文は、スキーマ定義に基づいてUI編集マップを動的に生成して起動するために使用されます。使用されるスキーマは、ビジネス・オブジェクト・スキーマ、ビジネス・サービス・スキーマ、サービス・スクリプト・スキーマまたはデータ領域スキーマです。これはビジネス・プロセス・アシスタント・スクリプトにのみ適用されます。生成文はスキーマのタイプよって異なりますが、構文は似ています。

構文

generateBOEditMap

generateBSEditMap

generateSSEditMap

generateDAEditMap

リテラル(一重引用符で囲む)を使用して、一時変数として、またはXPathスキーマの場所(二重引用符で囲む)を参照することで、ビジネス・オブジェクト・コード、ビジネス・サービス・コード、サービス・スクリプト・コード、データ領域コードを指定できます。

次の表に、この文のその他の構文を示します。

構文 有効値 コメント

using

 "データ領域グループ名" マップに関連付けられたHTMLフォームをレンダリングするときに、サーバーとの間で受け渡されるデータ領域を指定します。

target

bpa

page

popup

target値には、「マップの起動」ステップ・タイプの説明のとおり、生成されたマップを表示する場所を指定します。UIマップが値を返すように構成されている場合は、$MAP-VALUE変数を使用して値を評価できます。

例ではgenerateBOEditMapを使用していますが、その他のスキーマ・タイプの場合も構文は同様です。

generateBOEditMap 'BO Name' using "dataArea";
 
generateBOEditMap $variableMap using "dataArea";
 
generateBOEditMap "daName/mapElement" using "dataArea" target bpa;
 
// $MAP-VALUE is a variable returned by the invoked map.
if ("$MAP-VALUE='continue' ")
    goto 300;
else
    terminate;
end if;

terminate文

「データの編集」ステップでは、「終了」ステップ・タイプに似た機能をサポートしています。

次の例では、スクリプトを停止する「終了」ステップを示します。

if ("not(parm/spouse/name)")
  terminate;
else
  goto addSpouse;
end-if;

terminate with error文はサービス・スクリプトでのみ使用できます。

注意: ビジネス・プロセス・アシスタント・スクリプトからエラーを発行するには、「有用なヒントとコツ」を参照してください。
構文 属性 コメント

terminate with error (x, y %n= element= )

 xはメッセージ・カテゴリを表します 必須。
yはメッセージ番号を表します 必須。
%n="要素XPath"または%n='リテラル' リテラル値またはXPath参照のいずれかを使用して、メッセージでサポートされている置換パラメータを指定します。置換する値がリスト内の要素であるときは、リスト内の要素のXPathをリスト・オカレンスで修飾したものを使用します。
element='要素XPath'またはelement=$variable (オプション) UIマップ内に要素名を指定して、エラーの一部としてハイライト表示します。エラーの要素がリスト内にあるときは、リスト内の要素のXPathをリスト・オカレンスで修飾したものを使用します。

シンプル・フィールドの例:

if ("string(customer/lastName) = $BLANK")
  terminate with error (8000, 1001 %1="customer/lastName" %2='Last name required' element='customer/lastName');
end-if;

マークする要素がリスト内にある終了の例:

for ($list in "parm/hard/newBusinessObject/listName") 
  if //** check some condition for elementName
      terminate with error (11000, 11000 %1="$list/elementName" element='$list/elementName');
  end-if;
end-for;
ファストパス: UIマップでのエラーの表示に関する詳細は、「エラーの表示」を参照してください。

Groovyコードの起動

プラグイン・スクリプトまたはサービス・スクリプトの中でXPathスクリプトとGroovyスクリプトが混在している場合に、データの編集のステップでは構文invokeGroovy 'method';を使用したGroovyコードの起動がサポートされています。'method'は、スクリプトの中の「Groovyメンバー」ステップで定義されたメソッドの名前です。この方法で起動できるのは、引数を受け取らずにvoidを返すメソッドのみです。ただし、「データの編集」ステップから起動されたメソッドは、その他の「Groovyメンバー」ステップ・タイプの追加のGroovyコードでサポートされます。

「データの編集」ステップの例:

invokeGroovy 'invoke';

「Groovyメンバー」ステップの例:

void invoke() {
  initParms()
  readBO()
  initConfig()
  retrieve()
  updateBO()
}
注意: 「スクリプト内でのGroovyの使用」で説明したように、これがプラグイン・スクリプトで、かつコードがGroovyのみの場合は、前述の手法ではなくGroovyスクリプト・エンジン・バージョンを使用する必要があります。この方法は、XMLインタフェースとの間のデータの変換が回避されるため、より効率的と考えられます。

ビジネス・プロセス・アシスタント・スクリプトのデバッグ

ビジネス・プロセス・アシスタント・スクリプトにゼロより大きい高さがある場合は、スクリプトのデータ領域の選択されたノードを実行時に表示できます。XMLデータは、スクリプトの実行中にビジネス・プロセス・アシスタント・スクリプトの表示領域内に表示されます。ビジネス・プロセス・アシスタント・スクリプトのいずれかのデータ領域からXMLノードのXPathを、'%+'と'+%'の文字のペアの間に指定します。

たとえば、ビジネス・プロセス・アシスタント・スクリプトの表示領域に、'input'という名前のスキーマ・グループ・ノードの内容全体と、'output/status'という名前のスキーマ要素の特定の内容が表示されます。デバッグ・テキストは、スクリプトの編集データ・フィールド内ではなく、ビジネス・プロセス・アシスタント・スクリプトのテキスト領域に入力する必要があります。デバッグ・テキストは、スクリプトの明示的なステップに対して宣言できます。

display input: %+input+% , and output status: %+output/status+%

有用なヒントとコツ

この項では、一般的なロジックを実装する方法についての推奨事項を示します。

ビジネス・プロセス・アシスタントでのログイン済ユーザーの特定

サーバー・ベース・スクリプトの場合は、$USER変数には現在ログインしているユーザーが移入されます。この変数は、ビジネス・プロセス・アシスタント・スクリプトには使用できません。ビジネス・プロセス・アシスタントでこの情報が必要な場合は、サービス・スクリプトF1-GetUserをコールします。

ビジネス・プロセス・アシスタント・スクリプトからのエラーの発行

サーバー・ベースのスクリプトの場合は、ユーザーに表示するエラー・メッセージをterminate with error文を使用して返します。ビジネス・プロセス・アシスタントでそのエラーを表示するには、「スキーマ・ベースのオブジェクトの宣言および起動」の説明に従って制御をF1-HandleErrに渡します。これはビジネス・プロセス・アシスタント・スクリプトではサポートされていません。エラーを発行するためにビジネス・プロセス・アシスタントで使用できる方法は、ビジネス・サービスF1-RethrowErrorをコールしてエラー詳細を渡すというものです。このビジネス・サービスによって、エラーの発行に必要となる該当のシステム・エラー・フィールドにデータが移入されます。その後で、制御をF1-HandleErrに渡します。

  if ("string($assignedToUser) != string(F1-GetUser/user)")
    declareBS 'F1-RethrowError' as 'errorMsg';
    move '11010' to "errorMsg/messageCategory";
    move '11511' to "errorMsg/messageNumber";
    move "$toDoEntryId" to "errorMsg/messageParameters/+parameters/parameterValue";
    invokeBS 'F1-RethrowError' using "errorMsg";
    transferControl 'F1-HandleErr';  
  end-if;