Edit Data Steps

Contents

Comments

Temporary Variables

Context Variables

Move Statement

Go To Statement

Conditional Branch Statement

If Statement

For Statement

List Processing

Functions for Processing a List

Declare and Invoke Schema Based Objects

System and Global Variables

Perform Script and Transfer

Navigate Statement

Invoke Map Statement

Declare BO with BO Group

Generate Edit Map Statements

Terminate Statement

Invoking Groovy Code

Debugging a BPA Script

Useful Tips and Tricks

Comments

You can place comments into your script using the double slash notation // in the first two characters of the edit data step. Example:

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

Temporary Variables

Temporary variables can be declared within all types of scripts. They should be referenced by a leading single dollar sign ('$'). However, temporary variables behave differently in the various script types:

• In BPA Scripts temporary variables remain persistent from one BPA script to another (refer to the Perform Script and Transfer Control statements), which means that you can use temporary variables to communicate between BPA scripts.

• Temporary variables cannot be passed from a BPA script to a service or plug-in script. Only data area elements can be passed between these types of scripts.

• Within service and plug-in scripts, temporary variables remain persistent only for the life of the particular script that declared the variable. This means that temporary variables cannot be passed between plug-in scripts and service scripts, only global variables, context variables and data area elements can be passed between these types of scripts.

Declaring / Initializing / Defaulting Temporary Variables

When using a temporary variable, it should be declared or initialized with an appropriate value before using it. A typical method for declaring a variable is to simply move data to it in a move statement, for example.

move "0" to $index;

For BPA scripts, as mentioned above, temporary variables may be passed from one BPA script to another. As such, it is common to reference a temporary variable in a BPA that should have been initialized by a previous BPA. However, if there is any reason that a temporary variable did not get initialized by a previous BPA, a reference to it will cause an error. It is good practice, therefore, to use the default statement that will initialize temporary variables that are not already created / initialized.

• The following statement will initialize the temporary variable $InputAction – but only if the temporary variable has not yet been initialized:

  default $InputAction;

• The following statement will set the value of the temporary variable $InputAction to 'read' – but only if the variable has not yet been initialized:

  default $InputAction as 'read';

Context Variables

Context variables are only available within service scripts. The context variable will be available for the duration of the service script and all that it invokes. Therefore, you can use a context variable within a service script to communicate information to a lower level service script or schema. They should be referenced by leading double dollar signs ('$$').

Declaring / Initializing / Defaulting Context Variables

When using a context variable, it should be declared or initialized with an appropriate value before using it. A typical method for declaring a variable is to simply move data to it in a move statement, for example.

move 'context variable' to $$contextVariable;

Move Statement

The move statement copies a source value to a target. The following table highlights various options supported in the move statement.

move "acct/totalBalance" to 
"parm/formattedValue";

move "concat(person/firstName, ',', 
person/lastName)" 
to "parm/fullName";

move "substring-before(parm/fullName,',')" 
to "person/firstName";

move "substring-after(parm/fullName,',')" 
to "person/lastName";

move "substring(parm/date,1,4)" 
to "parm/year";

move 'okay for mailing' 
to "account/preferences[type="mail"]/text";

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 "account/custInfo" to "person";

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

move "count(Person/names/personName) 
+ count(Person/ids/personId)" 
to $PersonChildCount;

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

move 'context value' 
to $$contextVariable;
// 
// here, we move from a context variable.
move $$contextVariable 
to "MarketMessage/sender";

move 'literal' 
to evaluate("schemaLocation"); 
//
move "schemaLocation" 
to evaluate($Variable);

move evaluate("schemaLocation") 
to $Variable;
// 
move evaluate($Variable) 
to "schemaLocation";

move escape("schemaLocation") 
to $Variable;
// 
move escape($Variable) 
to "schemaLocation";

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 Statement

The edit data step supports functionality analogous to the Go To step type. The syntax is goto label; where the label represents another location within the edit data text field (identified by this label) or represents another step in the script.

The following is an example of going to another location in the same step identified by the label addSpouse.

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

The following is an example of going to a different step within the same script. The step sequence is the reference used as the label.

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

Conditional Branch Statement

The edit data step supports functionality analogous to the Conditional Branch step type. The syntax is branch (“xpath”) goto label else label; where:

• The XPath condition in the branch statement must evaluate to a Boolean value of True or False.

• The targets for the goto and else statements are labels that represent another location within the edit data text field (identified by this label) or represent another step in the script.

The following example uses labels for addSpouse and addAccount

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

If Statement

The if statement is similar to the conditional branch statement. Either can be used to structure the logic of your script. This statement may optionally include an else statement but it should always end with an end-if statement.

The syntax is if (“xpath”) else end-if;. The XPath condition must evaluate to a Boolean value of True or False. The following are some examples.

Example where the XPath contains a simple logical condition.

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

Example where the XPath contains a complex condition.

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;

Example of a stacked set of statements used to evaluate multiple possible values of a field.

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;

The following XPath shows Boolean based on the existence of the node. In this example, if the node exists in the XML instance document being processed, the statement will evaluate to True. If no element is found, the statement evaluates to 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 Statement

The for statement creates a list of nodes or values depending on your XPath expression. If you specify a list node then every child node of the list, along with its contents, will be available within the loop. If you specify a child node directly, then a list of values only will be available within the loop.

The syntax is for ($variable in "xpathList") end-for;. The XPath condition must evaluate to a Boolean value of True or False.

The following examples are based on this sample schema:

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

Example that specifies the list node in the XPath expression where all child nodes are available for processing.

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; 

Example that specifies a child node within the list node in the XPath expression. Only values of that node are available for processing.

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

Example that shows that a filter can be used to limit the rows selected by the for loop.

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

Example that shows the use of a filter when specifying child nodes.

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

List Processing

This section provides details about processing lists. The examples in this section reference the following schema:

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

Referencing a List Element. You can move a value to a particular list instance by referencing an identifying node in the list within a filter. The syntax is move "xpath" to "xpathList[filter]/element"; Example:

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

Creating a New List Instance. A special notation can be used within a move target statement to indicate a new list instance should be created. The "+" indicates to the script processor that a new instance of a list should be initiated for the target element. The syntax is move "xpath" to "+xpathList"; Example:

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

Deleting a List Instance. An XML list entry can be deleted from the database by moving an action attribute of 'delete' to the element name. To cause a database delete of a list entry requires an attribute of action="delete" in the target node and a subsequent update BO interaction. The syntax is move 'delete' to "xpathList@action"); Example:

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;

The following shows the resulting XML.

<root>
  <CCList>
    <id>9876538976</id>
    <balance>309.98</balance>
  </CCList>
  <CCList action="delete">
    <id>4321125899</id>
    <balance>87.45</balance>
  </CCList>
</root>

Functions for Processing a List

XPath provides several functions that are useful to process elements of a list including count, sum and last.

The following examples are based on this sample XML document:

<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>

The following is an example of a sum. The syntax is move "sum(xpathList/element)" to $variable; The example sums the total balance.

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

The following is an example of a sum using a filter to get a subtotal. The example sums the balance of the entries that have the ‘tax’ category.

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

The following is an example of a count. The syntax is move "count(xpathList)" to $variable; The example finds the count of the number of FT entries in the list.

move "count(ft)" to $TranCount;

The following is an example of ‘last’, which is used to locate the last entry. The syntax is move "last(xpathList)" to $variable; The example finds the last amount in the FT list.

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

Declare and Invoke Schema Based Objects

You can invoke a business object, business service or service script within the edit data step. To support the dynamic invoke, a dynamic data area name can be declared.

The schema being declared may be a business object (BO) schema, a business service (BS) schema, a service script (SS) schema, data area (DA) schema or a UI map schema. The declare statement will differ based on the type of schema, but the syntax is analogous.

• 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';

When invoking a BO, BS or SS, the name of the object can be specified as a literal or it can be a value contained within an element or a variable. For every Invoke, you must supply an XPath reference to a group name.

When invoking a business object, an action must be supplied. The syntax is invokeBO 'BO Name' | $variable | "xpath" using "xpath" for action;. The valid actions are as follows:

• read. This action reads the current view of the BO data.

• add. This action will add the object and read and return the resulting view of the BO.

• fastAdd. This action will add the object but does not perform a subsequent 'read' to return the resulting view of the BO. This option is better than add for performance purposes if there is no reason to re-read the record.

• update. This action will update the object and read and return the resulting view of the BO. This action executes a 'merge' of the information specified in the invoke statement's request XML document with existing BO data. Using this action allows the script to only indicate the elements that are changing.

• fastUpdate. This action will update the object but does not perform a subsequent 'read' to return the resulting view of the BO. This option is better than update for performance purposes if there is no reason to re-read the record.

• delete. This action deletes the object.

• replace. This action is an alternate to the update action. The replace action completely replaces existing BO data with the information in the request document. Typically, the replace action is used when a BO contains a list because it is easier to simply replace all instances of a list rather than attempt a list merge, which requires special logic to delete a list instance explicitly.

  Note: The replace action must be used when using the UI map functionality to Upload a CSV File.
  Note: The replace action is currently not supported for any maintenance object that is maintained in a 'fixed' page that uses a list metaphor to show all the records in the page at once. Currency is an example of this type of page.

Examples:

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

The syntax of the invoke statements for both a business service and service script are similar. The BS / SS is specified along with the XPath reference to the group name:

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

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

The examples use the invokeBS statement but the statements are similar for the invokeSS statement.

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

BO Warnings. Note that for BPA scripting, the invoke statements may also indicate how to handle warnings.

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

invokeSS 'ServiceScript' using "dataArea" with warn;

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

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

invokeSS 'ServiceScript' using "dataArea";

For BPA scripts, there should also be logic following the invocation to handle errors and warnings (if with warn as popup is used). The system variable $WARNING is set to true if the user has clicked the Cancel button in the warning popup. If a map was shown, the logic should redisplay the map (where the warning message will be redisplayed.) This allows the user to potentially make changes and save again. If no map was shown prior to the warning, then the logic should terminate.

The system variable $ERROR indicates that an error was received. If a map was shown prior to the error, then the logic should redisplay the map where the error will be shown. If no map was shown, then the product provides a BPA Script F1–HandleErr that should be used to display the error. The following is an example of typical error handling logic.

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;

System and Global Variables

The following tables highlight system and global variables available for script writing.

System Variables - All Script Types

The following system variables are available for all script types (service scripts, plug-in scripts, and BPA scripts).

if ("string(parm/spouse/name) != $BLANK")
  goto addSpouse;
end-if;

move "$CURRENT-DATE" to $tempDate;

move "$CURRENT-STD-DTTM" to $tempDateTime;

move "$DEVICE-OS" to $tempDeviceOs;

move "$DEVICE-BROWSER" to $tempDeviceBrowser;

move "$DEVICE-DISPLAY-TYPE" to $tempDeviceDisplayType;

move "$DEVICE-INFO" to $tempDeviceInfo;

System Variables - BPA Scripts Only

The following system variables are only available / applicable for BPA script types.

move "$DOUBLE_QUOTE" to $tempField;

move "$SINGLE_QUOTE" to $tempField;

move "$SPACE" to $tempField;

move "$SYSTEM-DATE" to $tempDate;

System Variables - Server Scripts Only

The following system variables are only available / applicable for service script and plug-in script types.

move "$ADDITIONAL-IP-INFO" to "parm/request/headerIpAddress";

move "$CURRENT-DTTM" to $tempDateTime;

move "$F1-INSTALLATION-TIMEZONE" to $timeZone;

move "$LANGUAGE" to $tempLanguage;

move "$PROCESS-DATE" to $tempDate;

move "$PROCESS-DTTM" to $tempDateTime;

move "$REQUESTING-IP-ADDRESS" to "parm/request/systemIpAddress";

move "$USER" to $tempUser;

Global Variables

BPA scripts and service scripts have access to the values defined in Global Context.

When a BPA script is launched from the user interface, these variables will be automatically initialized. They may be referenced with a single dollar sign in front of the field name. For example if PER_​ID is a supported global variable, then $PER_​ID can be referenced within the BPA script:

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

For service scripts, global variables may only be referenced if the service script has been invoked directly from a BPA script or a zone on a portal. When a service script is invoked from a BPA script or portal zone, it will have access to the suite of global context variables populated in the UI session. For service scripting, the global fields must be prefixed by two dollar signs (instead of one like in BPA scripting). For example if PER_​ID is a supported global context variable, then $$PER_​ID can be referenced within the service script.

move $$PER_ID to "schema/customerId";

Perform Script and Transfer Control Statements

The edit data step supports functionality analogous to the Perform script step type and the Transfer Control step type. These are both applicable only to BPA scripts.

Navigate Statement

The edit data step supports functionality analogous to the Navigate to a page step type. This is applicable only to BPA scripts.

In addition, the edit data step supports the ability to indicate that the dashboard should be refreshed when navigating. This is only applicable to BPA scripts.

Declare BO with BO Group

This statement is specific to BPA scripts that plan to use the base script Main BO Maintenance Processing (F1–MainProc) for its Generate Edit Map statements. This script expects that the data used to display in the map is within a boGroup tag.

The following table highlights additional syntax for this statement.

Examples:

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

Invoke Map Statement

The edit data step supports functionality analogous to the Invoke map step type. This is applicable only to BPA scripts.

The following table highlights additional syntax for this statement.

Refer to the Invoke map step type for more information about the target values.

If the UI map is configured to return a value, then it can be evaluated using the $MAP-VALUE variable.

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;

Generate Edit Map Statements

The 'generate edit map' statements are used to dynamically generate and launch a UI edit map based on a schema definition. The schema used may be a BO schema, a BS schema, an SS schema or a DA schema. This is applicable only to BPA scripts. The generate statement will differ based on the type of schema, but the syntax is analogous.

The BO code / BS code / SS code / DA code may be specified using a literal (surrounded by single quotes), as a temporary variable or by referencing an XPath schema location (surrounded by double quotes).

The following table highlights additional syntax for this statement.

The target values indicate where the generated map should be displayed as described in the Invoke map step type. If the UI map is configured to return a value, then it can be evaluated using the $MAP-VALUE variable.

The examples use the generateBOEditMap but the statements are similar for the other schema types.

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 Statement

The edit data step supports functionality analogous to the Terminate step type.

The following is an example of a simple terminate step that will stop the script.

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

The terminate with error statement is only available in a service script.

Example of a simple field:

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

Example of terminate where the element to mark is in a list:

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;

Invoking Groovy Code

If you have a plug-in script or a service script that mixes XPath scripting and Groovy scripting, the edit data step supports the ability to invoke Groovy code using the syntax invokeGroovy 'method'; where 'method' is the name of a method defined in a Groovy Members step within the script. Only methods that do not receive arguments and return void can be invoked in this way. However, the method invoked from the edit data step can be supported by additional Groovy code in other Groovy Members step types.

Example Edit Data step:

invokeGroovy 'invoke';

Example Groovy Members step:

void invoke() {
  initParms()
  readBO()
  initConfig()
  retrieve()
  updateBO()
}

Debugging a BPA Script

If a BPA script has height greater than zero, then selected nodes of the script's data area can be displayed at runtime. The XML data is displayed during script execution within the BPA script's display area. Specify the XPath of an XML node from any of the BPA script's data areas, between the paired characters: '%+' and '+%'.

For example, the entire contents of the schema group node named 'input', and the specific contents of the schema element named 'output/status' will be displayed in the BPA script's display area. The debug text must be entered into the BPA script's text area and not within the script's edit data field. Debug text can be declared for any explicit step of the script.

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

Useful Tips and Tricks

This section provides some suggestions about how to implement some common logic.

Finding the Logged In User in a BPA

For server based scripts, the $USER variable is populated with the current logged in user. This variable is not available for BPA scripts. The BPA can call the service script F1-GetUser if this information is needed.

Issuing an Error from a BPA script

For server based scripts, you use the terminate with error statement to return an error message to display to the user. The BPA can display that error by transferring control to F1–HandleErr as described in the Declare and Invoke Schema Based Objects. This is not supported in a BPA script. A technique that is available to a BPA for issuing an error is to call the business service F1-RethrowError passing the error details. This business service populates the appropriate system error fields needed to issue the error. Then transfer control to 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;