This chapter covers the following topics:
You can add functionality to a graphical script at runtime by defining commands in the Script Author.
This section includes the following topics:
Commands can be defined for a graphical script in the Script Author in the following ways:
Associated with Script Author objects using various action types
Associated with "questions" (also referred to as answer definitions) using the data dictionary
Associated with panel text using an embedded value
Associated with a Shortcut button in the Shortcut button bar (for agent interface operations only)
Associated as the return value or parameter of another command
Commands can also be defined for a wizard script by selecting options in the Define Question Detail wizard window. All commands are associated at the question within a panel level. Commands available from the wizard script include the following:
Constant command (referred to as the "Default Value" the question)
Validation that an answer is provided at runtime (for example, was any input provided by the user)
Validation for an integer provided as an answer at runtime (validation includes verifying that the answer provided is an integer only, or is an integer within a provided range, or is a valid date, or is a valid date not in the past)
Action types provide a way to associate a Script Author command with a graphical object in the script (a panel, group, block, branch, or the global script itself). Commands are associated with Script Author graphical objects using various action types, based on the object.
Using an action type, you can associate an existing command from the command library, or create a new command. Action types include actions, delete actions, pre-actions, post-actions, and application programming interface (API) actions.
Actions execute at runtime when the object is reached. Actions are properties of branches only, and represent the only command occurring for the branch, other than routing the script to the next object according to properties of the branch type. Actions can include any command type except an API action.
Delete actions execute at runtime when the object containing the delete action is reached. The delete action causes a row to be deleted from the database, based on what is currently selected in the Scripting cursor. Nothing else in the script or transaction is deleted.
Pre-actions execute at runtime when the object containing the pre-action is reached and prior to:
Displaying any panel objects (text, graphics, or questions);
Collecting any answers, for a panel;
Executing any commands associated with the group or block and contained in the object;
Displaying subgraphs contained in groups or blocks.
Post-actions execute at runtime when the object containing the post-action is reached, and after:
Answers are retrieved and written to the blackboard (for a panel), and prior to reaching or processing the next object in the script;
Commands associated with a group or block and contained in the object are executed, and prior to reaching or processing the next object in the script;
Subgraphs contained in groups or blocks are reached and processed by the script, and prior to returning flow to the calling parent graph.
Delete actions execute at runtime when the object containing the delete action is reached. The delete action causes a row to be deleted from the database, based on what is currently selected in the Scripting cursor. Nothing else in the script or transaction is deleted.
API actions are associated with blocks only and execute at runtime immediately following the execution of any pre-actions to the API block, and prior to the display of any panel content or execution of any objects contained within the API block.
The table below indicates which action types are associated with each object, and describes when that command is executed for each object.
| Object | Action Type | Description |
|---|---|---|
| Default branch | Action | Command executes at runtime upon reaching this branch in the flow of the script. |
| Distinct branch | Action | Command executes at runtime upon reaching this branch in the flow of the script. |
| Conditional branch | Action | Command executes at runtime upon reaching this branch in the flow of the script. |
| Indeterminate branch | Action | Command executes at runtime upon reaching this branch in the flow of the script. |
| Global script | Pre-action | Command executes at runtime prior to displaying any objects in the user interface or evaluating any commands associated with objects in the script. |
| Global script | Post-action | Command executes at runtime immediately following the display of the last panel or object reached in the flow and prior to ending the interaction. |
| Panel | Pre-action | Command executes at runtime prior to displaying any panel content or answers contained in the panel. |
| Panel | Post-action | Command executes at runtime immediately following action by the user to continue to the next panel in the flow, and prior to evaluation of the next object. |
| Group | Pre-action | Command executes at runtime prior to display of any panel content or execution of any object contained in the group. This is true even if reaching the group via a shortcut. |
| Group | Post-action | Command executes at runtime immediately following the display of any panel content or execution of any object contained in the group. and prior to evaluation of the next object in the flow of the script. |
| Block | Pre-action | Command executes at runtime prior to display of any panel content or execution of any database or API actions contained within the block. |
| Block | Post-action | Command executes at runtime immediately following the display of any panel content or execution of any database or API actions, and prior to evaluation of the next object in the flow of the script. |
| Block | API action | Command executes at runtime immediately following the execution of any pre-actions to the API block, and prior to the display of any panel content or execution of any objects contained within the API block. |
Actions can be performed on branches anywhere in a script, except between the Start node and the first object in the script.
Delete actions can be included in a script as an action to a branch, or as a pre-action or post-action to any other object in a script.
Pre-actions and post-actions can be performed on panels, blocks, groups, or the global script.
API actions can be associated with a block of type API block.
Related Topics
For more information, see the Defining Commands section in the Oracle Scripting User Guide.
You can create the following types of commands for a graphical script in Script Author:
Using a Java command, you can execute any public method in an appropriately referenced Java class. The Java command is executed when the appropriate object is reached in the flow of the script at runtime.
Guidelines
Commands are associated with objects using several approaches. For more information on where Java or other commands can be placed into a script, see Section 1.1.1, "Where Commands Are Defined in the Script Author".
You can reference existing best practice Java methods (see Section 2.3, "Best Practice Java Methods"), or create custom Java methods.
Java commands that invoke Oracle Scripting APIs require the server proxy bean as a parameter. Check the requirements of a specific API.
No provision is made to create or compile custom Java methods in the Script Author. All custom Java must be created by certified, trained and knowledgeable individuals using external applications or utilities.
The Java class you reference must have the appropriate import statements to access Oracle Scripting-specific classes. For more information, see Section 1.2.1.5, "Importing Scripting Classes into Java Source Files".
The method within the Java class that you reference in the Script Author must be fully qualified. For more information, see Section 1.2.1.1, "Referencing Java Methods in Script Author".
For Java commands to execute as intended, the referenced Java class and method must be appropriately compiled, packaged, and available to the class loader of the Java Virtual Machine (JVM) in the Scripting session where it will be executed.
You can deploy custom Java archives to the applications database using the Scripting Administration console, where the code archive can be made globally available to all scripts, or mapped to one or more specific scripts, resulting in the referenced methods being available at script runtime.
For specific instructions on defining a Java command in the Script Author, see Invoking a Public Method in a Java Class in Oracle Scripting User Guide Release 11i.
To specify a Java command in the Script Author, you must enter appropriate values in the Command Info area of the Command Properties window:
In the Name field, enter the command name.
This is the name Oracle Scripting uses to reference this command. If stored in the database as a reusable command, this is the name that identifies this specific Script Author command.
In the Command field, enter the command path.
This is a string that includes the Java class name for the command (including the fully qualified class path), followed by two colons, and the specific Java method of the class.
Fully Qualified Class Paths
If the class is written as part of a package, this path must be fully qualified. To fully qualify a class path, begin with the top level of the package, adding a period between each package level and between the last level of the package and the class name.
Example
For example, if the package is myprojects.myclasses, the class is TestClass, and the method name is testMethod, the values required to specify this command in the Command Info area of the Command Properties window are testMethod (for the Name field) and myprojects.myclasses.TestClass::testMethod (for the Command field).
Oracle Applications includes Java methods written specifically for Oracle Scripting to quickly enable frequently requested script runtime functionality. These best practice Java methods are organized into three classes: ScriptUtil, NodeDefault, and NodeValidation. Each is in a package (oracle.apps.ies.bestpractice), and must be fully qualified.
Example
For example, if the package is oracle.apps.ies.bestpractice, the class is NodeValidation, and the method name is checkNullValue, the values required to specify this command in the Command Info area of the Command Properties window are checkNullValue (for the Name field) and oracle.apps.ies.bestpractice.NodeValidation::checkNullValue (for the Command field).
To illustrate this concept, consider a custom Java method that checks for a null value. This Java method, checkNullValue, is useful to ensure that a value is returned for an executed PL/SQL command.
In the first example, this Java method is written in custom code with no package. The checkNullValue method is in the NodeValidation class file. The Command field to specify this command is NodeValidation::checkNullValue.
To use the same method from the best practice Java, the value of the Command field must be fully qualified to reference the Java method in its package. Thus, the Command field to specify this command using best practice Java is oracle.apps.ies.bestpractice.NodeValidation::checkNullValue.
This fully qualified class path ensures the Java class loader has access to the NodeValidation class and all its methods, including checkNullValue.
Thus, best practice Java methods enable an enterprise to substantially reduce or even eliminate writing, deploying and testing custom Java. This reduces development time and costs, providing a faster time to market and enabling code reuse, while additionally reducing the requirement for Apache Web server configuration file customization.
Guidelines
Do not attempt to modify APPS.ZIP to include custom Java methods. This could impact the behavior of Oracle Scripting and other Oracle applications.
Best practice Java methods can be used to support all Oracle Scripting graphical scripts, whether executed in the agent interface or as a Web-based survey.
When using best practice Java methods to extend Oracle Scripting functionality, review the Java method signature, which includes:
Scope modifier
Return type
Java method name
Arguments or parameters (if any)
You will also need to know what exceptions are thrown, if any. This information is available in the documentation for the best practices Java methods.
Arguments needed by best practice methods can be passed as parameters to a command in the Script Author. An example showing how to do this is described in Referencing Best Practice Java in a Command.
When developing or referencing custom Java code, many commands require you to pass the server proxy bean. The server proxy bean is the object that serves as a proxy on behalf of custom code, allowing the custom code to invoke Scripting APIs.
The proxy bean is instantiated within the same Java Virtual Machine (JVM) as the session object. This Java bean can be referenced by Java command objects created as part of a script (which are also instantiated within the JVM of the Session object). Thus, the proxy bean can be used by these Java command objects to call APIs on the Session object.
The proxy bean and its APIs and events serve as the sole interface between an external application and the Scripting Engine, which resides (in the Apache mid-tier architecture) in the Apache JServ.
You must include the proxy bean as a parameter for any Java command using Oracle Scripting APIs. Use this procedure to pass the server proxy bean as a parameter to a Java command in a graphical Script Author script.
Prerequisites
Identify the name and location in a graphical script of the appropriate Java method.
The Java method must require the proxy bean to invoke an Oracle Scripting API.
Responsibility
Scripting Administrator
Steps
Using the Script Author, open a new or existing graphical script.
Navigate to the object containing the appropriate Java command.
Open the Command window.
In the Parameters area, verify that this command does not already pass the server proxy bean. If you see Command parameter: Proxy, this procedure is not required.
From the Parameters area, click Add.
The Parameters window appears.
Enter the appropriate information to invoke the server proxy bean.
In the Parameters window, in the Name field, type Proxy in exact case.
Note: You do not need to specify a class or value. However, the value you type into the Name field of the Parameters window is case-specific. Ensure the P is upper case and the remaining letters are in lower case.
In the Parameters window, click OK.
The Parameters window closes.
In the Command window, click OK.
Save your work.
Guidelines
Some custom Java methods call or instantiate the server proxy bean as pb, other methods as Proxy. Regardless, you can pass this particular parameter by referencing only the bean name (Proxy).
Oracle recommends that you adhere to standard Java naming and usage conventions. For example:
Package names are all lower-case. To fully qualify a class path, begin with the top level of the package, adding a period between each package level and between the last level of the package and the class name.
Class names begin with an upper-case letter. If the name is a concatenated string of words, the initial letter of each subsequent word is capitalized. The remaining characters are lower-case.
Since a class is a set of related Java methods that share common characteristics, one manner of naming the class is to describe those characteristics. For projects with a single class, you may wish to name the class after the function of the script or the name of the campaign.
Method names begin with a lower-case letter. If the name is a concatenated string of words, the initial letter of each subsequent word is capitalized. The remaining characters are lower-case.
The method name should reflect what the method does. If a procedure, using a verb-plus-object name is standard (for example, setValue). If a function, the same is true, usually descriptive of the return value (for example, getName).
Variables and return values, like method names, typically begin with a lower-case letter. If the name is a concatenated string of words, the initial letter of each subsequent word is capitalized. The remaining characters are lower-case.
Variable names and return value names are typically short and descriptive (for example, columnName or firstName). Variables may be listed with their data type.
Note: Some of the Best Practice Java methods described in this section do not follow standard Java naming conventions in this release. In the near future, updated best practice Java methods will be included in APPS.ZIP that follow these standards. This document will be updated at that time, listing only the most recent set of best practice methods. However, to ensure compatibility, the older set of methods will continue to be included in shipped code, but decremented. Look for update information on My Oracle Support.
Whether creating custom Java or using best practice Java provided by Oracle, you must have the appropriate import statements in your Java source file. When the compiled class file contains the appropriate references, the methods in the class have access to existing Java classes created to support Oracle Scripting. The methods and objects in the referenced files are imported and made available to the class loader as if the definitions were included in your Java file. Only import public Java classes; referencing private classes is not supported.
Following is a recommended minimum set of import statements to include in Java source files used for Oracle Scripting. This is typically placed in the source file after the package designation (if any) and before the designation for the class to begin.
import oracle.apps.ies.integration.common.*; import oracle.apps.ies.integration.common.exception.*;
If creating custom Java beans to be used as replacements for panels, you can also include:
oracle.app.ies.integration.client oracle.app.ies.integration.client.external
Add to your import statements any Java classes you need to import in addition, such as:
import java.text.*; import java.util.*;
The above Java classes are an example only, and may not be required to support your code. Additionally, other classes may be required, as appropriate. Reference JDK documentation for information on appropriate Java classes and inheritance.
Using a PL/SQL command, you can execute any procedure or function stored in a database table. The PL/SQL command is executed when the appropriate object is reached in the flow of the script at runtime.
Guidelines
You can interact with database tables using PL/SQL commands or by using a Script Author block object. Blocks can query, insert, or update database tables, in addition to providing a clearly identifiable location for inserting an API into a script. For information on defining blocks, see Using Oracle Scripting > Using the Script Author > Defining Blocks.
PL/SQL commands in graphical scripts require connection information to be defined in the command. This tells Oracle Scripting how and where to connect to the appropriate database tables to access the stored procedure or function. For information on connection information, see Using Oracle Scripting > Using the Script Author > Deploying the Script > Connecting to the Database.
Commands are associated with objects using several approaches. For more information on where PL/SQL or other commands can be placed into a script, see Section 1.1.1, "Where Commands Are Defined in the Script Author".
No provision is made in the Script Author to write, test, or deploy to the database stored PL/SQL procedures or functions. All PL/SQL code must be created by certified, trained and knowledgeable individuals using external applications or utilities.
When defining a PL/SQL command in the Script Author, you must assign parameters (using the Parameters area of the Command Properties window) to match all parameters in the stored function or procedure, whether they are IN, OUT, or IN/OUT type. Both OUT and IN/OUT parameters will be passed back into the Scripting blackboard as key/value pairs. The blackboard key for each parameter is identical to the name used when the parameter is defined in the Script Author.
The Scripting blackboard is a virtual memory space where information is stored in key/value pairs. This information is only retained for the duration of a single Oracle Scripting interaction.
Using a blackboard command, you can retrieve values from a specific script interaction, and display the value at runtime, or use the value for processing within the script.
This section describes the three methods of providing values to the Scripting blackboard.
When an answer is provided by the script end user at runtime, this information is written to the blackboard. The key to access this information is the "question" (or "answer definition") name entered into the Name field of the Answer Entry window in the Script Author when the panel answer was defined. The answer provided by the script end user at runtime is the value.
For example, if you create an answer definition in the Script Author named lastName, then at runtime, as soon as that answer is provided by the script end user (Mr. Lincoln) in the corresponding text field, the Scripting blackboard is populated with the key value pair of (lastName, "Lincoln"). This value persists until the script terminates, or the panel is refreshed and populated with a different value.
Using the Scripting API setBlackBoardAnswer in a Java command, information can also be written explicitly to the blackboard without interaction by the script end user. This takes two parameters: the blackboard key (entered as a string) and the value you wish to set (a serializable value). The return type for this API is void.
Regardless of the method of populating information to the blackboard, a blackboard command for which you specify the key will return the requested value.
Launching a script from either of two integrated business applications, Oracle TeleSales or Oracle Collections, results in that application invoking Scripting APIs to set a distinct set of values from the business application to the Scripting blackboard.
For more information, see the section Parameters Passed to the Scripting Blackboard in the Oracle Scripting Implementation Guide.
Using an embedded value containing a blackboard command, you can display information known to the Scripting Engine for the current session to display that value in a panel.
You can also use a blackboard command as a parameter to another command. In this way, you can pass a required value stored in the blackboard for the current script session to its parent command to execute. For example, if you need to pass the name of the current customer as a parameter to a PL/SQL command, you can then retrieve specific information for that customer into the script.
Another example of using a blackboard command as a parameter to another command is to pass blackboard parameters to a Java command, and use the Java code to evaluate whether specific information has been collected. Based on whether the indicated keys are null, you can route the flow of the script (for example, to a group that collects the information and routes the script accordingly). This can provide dynamic features to the script at runtime based on the set of requirements indicated in Script Author commands.
The blackboard maintains state for the key/value pairs it stores, relative to the flow of the script. In this way, if there is a change in the value assigned to the key, this can be reflected based on the method or API you use to evaluate the key/value pair.
Take the example of a particular blackboard key in a given script (firstName). In this scenario, there is only one manner in which a value is provided: the script end user enters his first name (Juan) in a text field in the second panel.
If you display the key/value pair prior to the answer being provided, the result is "firstName", null. If you display the key/value pair after the answer is provided, the result is "firstName", "Juan". If later in the script the end user returns to this panel and changes the answer to "John," then the result of displaying this key/value pair will be "firstName", "John."
Guidelines
Commands are associated with objects using several approaches. For more information on where blackboard or other commands can be placed into a script, see Section 1.1.1, "Where Commands Are Defined in the Script Author".
Blackboard commands do not require the ServerProxyBean to be passed as a parameter. You simply need the blackboard key. (Note that this may not be true when using blackboard APIs that require the proxy bean to be in the Interaction state.)
When defining a blackboard command, there are two values in the Command Info area of the Command Properties window: Name, and Command. The Command field is crucial, and must specify the blackboard key. The Name field is optional. Many script developers use the same value (the blackboard key) for this field. If that is not clear, you may use a different value. The Name field can also be left blank, but this is not recommended.
If attempting to access a blackboard value that was entered by the script end user responding to a multiple-selection answer type (a checkbox group or multi-select list box), then the command you create in the Script Author must know that the response or responses are stored in a vector. Thus, this blackboard command would be nested in a parent command. For the nested blackboard command, select the option Add Value as Command? When the command executes at runtime, the Scripting Engine attempts to evaluate each parameter of a command. If the parameter is marked as an Iterating Parameter, the Scripting Engine verifies that the value of the parameter is a vector. Then it iterates through the vector, executing the command once for each element in the vector. Each element in the vector is passed to the command at the same place in the list of parameters as the iterating parameter.
Information stored in the Scripting blackboard is only retained for the duration of a single Scripting interaction. This interaction begins with the instantiation or launch of a specific script, and ends either when an agent terminates the script manually or when the script has concluded. A script is concluded when the termination node on the root graph or top level of the canvas is reached in the flow of the script.
Using a variety of Scripting APIs, information can be written explicitly to the blackboard, or manipulated from the blackboard. To explicitly write values to the blackboard, you must use blackboard APIs as Java commands.
Using Scripting blackboard APIs, you can enable selection and dynamic presentation of appropriate questions based on answers previously provided by the script end user (or by evaluating blackboard information explicitly pulled into the script from database tables).
The table below lists Oracle Scripting blackboard APIs, including the method name, a description of the method, the return type, and any parameters passed.
| Method Name | Description | Return Type | Parameters |
|---|---|---|---|
| getRelativeBlackBoardAnswer | Returns the answer for the specified blackboard key relative to the point in the script that the command is executed. Returns null if no value is associated with the key. | Serializable | Proxy String key |
| getLastBlackBoardAnswer | Returns the last answer saved to the blackboard for the specified key, regardless of the point in the script that the command is executed. Returns null if no value is associated with the key. | Serializable | Proxy String key |
| getAllBlackBoardAnswers | Returns a vector containing all the answers in the blackboard for the specified key. Returns null if no value is associated with the key. | Vector | Proxy String key |
| setBlackBoardAnswer | Sets the value for the specified blackboard key. This API is not recommended to be used to set a value identical to a key created by using an answer definition name in a script. | void | Proxy String key Serializable value |
| removeAllBlackBoardAnswers | Removes all answers in the blackboard for the specified key. Recommended only for removing values placed by using the setBlackBoardAnswer API in a Java method. This API is not recommended to remove values for a key created using an answer name. | void | Proxy String key Serializable value |
Using forms commands in graphical scripts created with the Script Author, you can accomplish the following:
Get a value from forms-based Oracle applications to use in a script
Set a value in forms-based Oracle applications from a script
Launch other forms-based applications from a script
Launch a specified URL in a Web browser from a script
Invoke custom PL/SQL in response to a forms command
Call business application-specific APIs customized for use with Oracle Scripting
The forms command is executed when the appropriate object is reached in the flow of the script at runtime.
Business Rules Apply
When developing a script using forms commands, you must understand and work within the business rules enforced by the forms-based application. Although the forms command automates a process that would otherwise be performed by an agent in the application, requirements for following those business rules stand. Ignoring these requirements can negatively impact either the data the script must retrieve or set, or the ability of the script to retrieve or set those values each time a script is executed.
For example, if trying to obtain a customer’s last name from a forms-based customer profile, you must ensure that the customer profile is populated. As another example, if a forms-based application requires you to provide information in form A prior to accessing form B, results may be unpredictable unless your script provides the prerequisite values for form A prior to getting or setting data in form B.
In general, using forms commands in the Script Author, you can get or set values in any form directly accessible from the Navigator (a top-level form) with high confidence. Business rules still apply as if the agent were physically accessing the application. For example, the user must have the appropriate responsibility to open an item from the Navigator and may require specific roles, usages, or group memberships.
Second and subsequent level forms (nested forms accessed through the top-level form) are likely to have prerequisites or dependencies for data or agent interaction that may not be required at the top level. The further a form is nested (the more interaction required by the agent to reach the form in the application from the Navigator), the more likely it is to have such dependencies. When you automate the process in a script, you must ensure those requirements are met as surely as if the agent were clicking in the business application.
Thus, scripts getting or setting forms values should be thoroughly and rigorously tested to ensure expected results.
Guidelines
Forms commands are used to integrate scripts with Oracle Forms-based applications. This requires appropriate installation and implementation of those applications and a working Forms server.
To set a value in a form, two conditions must prove true:
The form must be able to be invoked by APP_NAVIGATE.EXECUTE or FND_FUNCTION.EXECUTE forms commands. All appropriate parameters for each of these specific commands must be provided.
The Scripting form must be part of the same forms window or set as the form in which you want to set a value. Forms applications that are part of the Scripting Workbench object group own some of Scripting’s objects, including bean_area, window, and canvas, and can more freely exchange information. At time of publication, of the three business applications integrated with Oracle Scripting, only the Customer Support module of Oracle TeleService currently meets this definition.
Note: Based on the information above, you cannot get or set values in integrated Forms-based applications such as Oracle TeleSales or Oracle Collections, unless changes are made to those applications to be part of the Scripting Workbench object group.
To get a value from a form (whether you wish to display the value in a script, use the value for evaluating logic to control the script flow, or write that value elsewhere) the form must be open. If the value of the form field is null, you must ensure the logic in your commands considers a null condition prior to attempting to display the value in the script, or the script will hang (pause and halt processing) and the agent will need to close the script manually, losing all information in the current Oracle Scripting session.
When defining a forms command in a graphical script, in the Command Info area of the Command Properties window there are two fields: the Name field and the Command field.
While the name value is not critical to the execution of the command, you should provide a meaningful value in this field. Some developers choose to use the same precise string for both the Name and Command values. Others elect to use the name field to designate the purpose for the command. If designated, ensure the values you provide meet established naming conventions or guidelines.
The command value generally contains the function for the command. Thus, if using the APP_NAVIGATE.EXECUTE command, type this string in the Command field.
Command parameters to a forms command must consist of the block name and the form field. These are entered into the parameter window in the Value field using the syntax <block name>. <field name>. (The block is a block defined in the same form that contains the Scripting Window.) The Name field of the parameter is not critical. As a general rule, the same value can be used for both fields. However, you must ensure consistency with designated project guidelines, if any.
Forms commands must contain a return value as a parameter if the intention of the command is to return a value. This is true regardless of whether the value is shown as an embedded value in the panel layout editor, or whether the value is saved to the Scripting blackboard.
The following are Oracle Scripting APIs that can be called as Forms commands.
| Command Name | Description | Parameters | Return Value |
|---|---|---|---|
| getValueFromForm | Returns the answer for the specified field in the containing form, as specified by the BLOCK.ITEM command parameter. Returns null if no value is associated with the specified form field. Requires a return value to be specified. |
BLOCK.ITEM | Required |
| setValueInForm | Sets the contents of the Value command parameter from the Script Author to the specified field in the containing form, as specified by the BLOCK.ITEM command parameter. The Value parameter can be a constant value, or a value returned by executing another command. |
BLOCK.ITEM Value |
None |
| FND_ FUNCTION.EXECUTE | This function opens a new instance of a form. This should be used whenever you need to open a form programmatically. | Function that launches the specific form Any standard parameters associated with that function |
None |
| APP_ NAVIGATE.EXECUTE | This function calls a form function to reuse an instance of the same form that has already been opened. | Function that launches the specific form Any standard parameters associated with that function |
None |
| WEB.SHOW_DOCUMENT | This command allows a script to launch a URL as an action within the script. | Function that launches the specific form Any standard parameters associated with that function |
None |
Use this procedure to get a value from forms-based Oracle applications to use in a script. The getValueFromForm application program interface (API) takes one parameter (the BLOCK.ITEM attribute of the value you wish to retrieve from the form) and one return value (the name you use in the Script Author to reference the value returned from the form).
The value returned by the command is not automatically set to the Scripting blackboard, but is available to the Scripting Engine (after the command is successfully executed) to be used in one of three ways:
To populate an answer control (using the default command specified in the question’s data dictionary).
To display in a panel using an embedded value (using the name provided in the Value field of the return value parameter).
Note: In order to use the retrieved value in any other manner or at any other location in the script, you must first set the return value to the blackboard using the setBlackBoardAnswer API (typically using a Java command), and retrieve it using the blackboard key/value pair.
To use the return value of the forms command as a parameter to another command. In this case, the forms command would be nested in the top-level command, and the Add Value as Command? check box is selected, providing a second command properties window in which to define the forms command.
If retrieving the value to use later in the script with blackboard commands, getValueFromForm API can be associated anywhere a command can be specified.
Prerequisites
The form from which the value is retrieved must be accessible by the responsibility of the current user.
You must know the block and field name for the specific form value you want to retrieve. From an Oracle Forms window, with your cursor in the appropriate field, select Help > Diagnostics > Examine to view the block and field variable names.
You must account for null values to ensure no errors are encountered. Attempting to retrieve null values can cause a substantial delay at script runtime until a timeout for the request is encountered.
Steps
If you want to display the value returned by this forms command in the current panel as an embedded value, then perform the following:
Navigate to the panel layout editor.
Enter the appropriate text you want to appear at runtime.
At the location in the panel text in which you want the return value from the forms command to appear, type any text as a placeholder.
For example, type EV.
Highlight the placeholder text, and from the panel layout editor toolbar, click the EV button to indicate that you wish to create an embedded value.
The Modify Command Properties button in the panel layout editor toolbar enables.
Click the Modify Command Properties button.
The Command Properties window appears.
If you want to display the value returned by this forms command in the answer control of a new panel answer, then perform the following:
Navigate to the Answer Entry Dialog window of the designated panel answer.
In the Name field, type a name for this question (also known as an answer definition).
For example, type contactPersonFirstName.
From the UI Type area, define the question user interface control type.
For example, to provide the value of the contact person’s first name in a text field, select Text Field.
Optionally, if you want the question control to contain a label in the script at runtime, in the Label for reporting field, type a value.
For example, type Contact person first name:
Click Edit Data Dictionary.
The Edit Data Dictionary window appears. The last tab selected during this Script Author session is selected.
Click the General tab.
In the General area, for the Default Command field, click Edit.
The Command Properties window appears.
From the Command Type area, select Forms Command.
Tip: If defining several similar forms commands, you may want to define the first command in the command library. Subsequently, when accessing the Command Properties window, you can click Use Command Library, select the appropriate script and click OK, and then modify properties as required.
In the Command Info area, in the Name field, type a name for this command.
Note: The value for the Name field is not critical, but the field must not be null. Some developers use the getValueFromForm API name here as well as the Command field; others enter a description of the parameter; others combine both, such as getValueCONT_ PER_FIRST_NAME. Ensure you follow any designated project guidelines or naming conventions.
For example, type getContactPersonFirstNameFromForm.
In the Command field, type getValueFromForm.
Note: This value is case-sensitive.
In the Parameters area, click Add.
The Parameters window appears.
Note: The parameters window for a command parameter appears the same as the parameters window for a return value. Ensure you enter the command parameter value in the correct field.
In the Parameters window for this command parameter, perform the following:
Leave the Class field blank.
In the Name field, enter a name for this command parameter.
For example, for the contact person first name, enter CONTACT_HEADER_ BLK.CONT_PER_FIRST_NAME.
Note: The value for the Name field is not critical, but the field must not be null. Some developers use the BLOCK.ITEM value here as well as in the following Value field; others enter a description of the command parameter. Ensure you follow any designated project guidelines or naming conventions.
In the Value field, enter the BLOCK.ITEM value for the form value you want to retrieve using this command parameter.
For example, for the contact person first name, enter CONTACT_HEADER_ BLK.CONT_PER_FIRST_NAME.
Click OK.
The Parameters window for the command parameter closes.
The Command Properties window displays the Name value of the command parameter in the Parameters area.
In the Return Value area, perform the following:
Click Edit.
The Parameters window for this return value appears.
Note: The parameters window for a return value appears the same as the parameters window for a standard Script Author command parameter. Ensure you enter the return value parameter in the correct field.
In the Parameters window, in the Name field, enter any meaningful value.
For example, enter the BLOCK.ITEM value, or a simplified version such as ContPerFirstName or FirstName.
Leave the Value field empty.
Click OK.
The Parameters window for the return value parameter closes.
The Command Properties window displays the Name value of the parameter in the Return Value area.
Click OK to save the properties you defined and to close the Command Properties window.
Save your work.
When executed from the Customer Care component of Oracle TeleService, this script will retrieve the populated value of the selected field name to the script do display in the panel text or answer control, as appropriate.
Guidelines
Values returned from a form can be displayed in a panel using an embedded value using the procedure described above.
Values returned from a form can be displayed as the default command of an answer control using the procedure described above.
Values returned from a form can be used as parameters in another command.
Before values returned from a form can be used as parameters in any other Script Author command, you must save them to the blackboard using the setBlackBoardAnswer API as a Java command.
This will not function with Oracle TeleSales or Oracle Collections.
Use this procedure to set a value in forms-based Oracle applications from within a script. The setValueInForm API takes two command parameters (the BLOCK.ITEM attribute of the value you wish to set in the form, and the Value parameter which specifies the value to set). No return values are required.
Prerequisites
In order to set a value in a form from a script, the form must be open and the field must be modifiable.
The script user must have the appropriate responsibility to access the specified field.
Steps
From an appropriate location in a script, access the Command Properties window.
From the Command Type list, select Forms Command.
Tip: If defining several similar forms commands, you may want to define the first command in the command library. Subsequently, when accessing the Command Properties window, you can click Use Command Library, select the appropriate script and click OK, and then modify properties as required.
In the Command Info area, in the Name field, type a name for this command.
Note: The value for the Name field is not critical, but the field must not be null. Some developers use the setValueInForm API name here as well as the Command field; others enter a description of the parameter; others combine both, such as setValueCONT_ PER_FIRST_NAME. Ensure you follow any designated project guidelines or naming conventions.
For example, type setContactPersonFirstNameInForm.
In the Command field, type setValueInForm.
Note: This value is case-sensitive.
In the Parameters area, click Add.
The Parameters window appears.
Note: The parameters window for a command parameter appears the same as the parameters window for a return value. Ensure you enter the command parameter values in the correct field.
In the Parameters window for this command parameter, perform the following:
Leave the Class field blank.
In the Name field, enter a name for this command parameter.
For example, for the contact person first name, enter CONTACT_HEADER_ BLK.CONT_PER_FIRST_NAME.
Note: The value for the Name field is not critical, but the field must not be null. Some developers use the BLOCK.ITEM value here as well as in the following Value field; others enter a description of the command parameter. Ensure you follow any designated project guidelines or naming conventions.
In the Value field, enter the BLOCK.ITEM value for the form value you want to set using this command parameter.
For example, for the contact person first name, enter CONTACT_HEADER_ BLK.CONT_PER_FIRST_NAME.
Click OK.
The Parameters window for the command parameter closes.
The Command Properties window displays the Name value of the command parameter in the Parameters area.
In the Parameters area, click Add to begin adding the second command parameter.
The Parameters window appears.
In the Parameters window for this command parameter, perform the following:
Leave the Class field blank.
In the Name field, type Value.
In the Value field, type the value you want to pass to the form.
For example, to enter a contact person first name of Norman, type Norman.
Click OK.
The Parameters window for the command parameter closes.
The Command Properties window displays the Name value of the command parameter in the Parameters area. Two parameters are listed.
Click OK to save the properties you defined and to close the Command Properties window.
Save your work.
When executed from the Customer Care component of Oracle TeleService, this script will set the specified value into the designated field as identified by the BLOCK.ITEM parameters.
Guidelines
Values can only be passed to a form in a modifiable field.
The form must be open to successfully set the value.
This will not function with Oracle TeleSales or Oracle Collections.
You can launch a form from Oracle forms-based applications from within a script. Use this procedure to define a Shortcut button in the button bar to open a specific form. When the script is executed in the Scripting Engine agent interface at runtime, you can click a button in the shortcut button bar to open the specified form in a separate window.
Prerequisites
The function you wish to associate with the shortcut button must be accessible to the Oracle Applications responsibility of the user that will execute the script.
Note: It is not sufficient for the Oracle Applications user to be assigned the responsibility required to execute the function. The user executing the script must do so from the required responsibility for the form to open successfully.
More than one window may be associated with the same form.
Steps
Using the Script Author, open a new or existing graphical script.
Double-click on an empty area of the canvas, or select Script Properties from the File menu, to access properties of the global script object.
In the script properties menu, select the Shortcut Panel attribute.
Shortcut Panel properties appear.
Click Add.
The Shortcut Info Entry window appears.
Enter Shortcut information as appropriate.
In the ID field, enter a unique identification name for this shortcut.
For example, if launching the Find/Enter customers form, type LF/E.fmx.
In the Label field, enter label that you want to appear on the shortcut button.
For example, type Launch Find/Enter Customers Form.
In the Tooltip field, enter the contents of the tooltip, which will appear in the Scripting Engine agent interface when the agent’s cursor rests on the button.
For example, type Find or enter customers in Customer Support.
On the Command line, click Edit.
The Command Properties window appears.
Enter the appropriate information to reference the command you want to execute at runtime when the Shortcut button is clicked.
From the Command Type list, select Forms Command.
In the Command Info area, in the Name field, type a name for this command.
Note: The value for this field is not critical. Some developers use the same name as the Parameter Value field; others enter a description of the parameter. Ensure you follow any designated project guidelines or naming conventions.
For example, type the form name, AR_ARXCUDCI_STD.
In the Command field, type the name for the function that launches the specified form.
For example, type AR_ARXCUDCI_STD.
If the specified function required any parameters, then in the Parameters area, click Add, and enter the parameter. Click OK to save the parameter and close the window. Repeat this step as required.
The Command Properties window displays the name value of the parameter.
Click OK to save the Command Properties and close the window.
The Shortcut Info Entry Dialog window displays the name value of the command.
In the Shortcut Info Entry Dialog window, to enable the Shortcut button upon the launch of the script, select Enabled.
A check appears, indicating the button is enabled.
If you want to save your work and continue, click Apply.
To add additional Shortcut buttons, click Add in the Shortcut Panel properties and repeat the required steps.
Click OK to save your work and exit the Shortcut Info Entry window.
Guidelines
The responsibility of the logged-in user governs the functions accessible in Forms-based applications.
When you click a shortcut button in the agent interface to open a form, any forms that are currently minimized (such as the Script Chooser) may also appear.
For command values, use APP_NAVIGATE.EXECUTE only when you want to reuse an instance of a form that has already been opened. In all other instances, use FND_FUNCTION.EXECUTE as the command value.
Use this procedure to define a forms command in a graphical script to launch a specific URL in a Web browser as an action to a command.
Web browsers can also be opened to a specific URL using the setBrowserURL Oracle Scripting API. That API can be used to establish a hypertext link in panel text that the runtime user can select if desired. Using this API as a forms command to a specified action ensures that the browser will launch when the action is triggered in the script, removing the element of choice and obviating the requirement to display a hypertext link.
Prerequisites
The designated URL must be accessible by users of the script. For example, if security such as a firewall is in place, the user must be on the appropriate side of the firewall to access the site through a Web browser in order for the same action to occur successfully using this API from a script.
Steps
From an appropriate location in a script, access the Command Properties window.
From the Command Type list, select Forms Command.
Tip: If defining several similar forms commands, you may want to define the first command in the command library. Subsequently, when accessing the Command Properties window, you can click Use Command Library, select the appropriate script and click OK, and then modify properties as required.
In the Command Info area, in the Name field, type a name for this command.
Note: The value for the Name field is not critical, but the field must not be null. Ensure you follow any designated project guidelines or naming conventions.
For example, type setURL.
In the Command field, type WEB.SHOW_DOCUMENT.
Note: Case is not important for this value.
In the Parameters area, click Add.
The Parameters window appears.
In the Parameters window for this command parameter, perform the following:
Leave the Class field blank.
In the Name field, enter a name for this command parameter.
For example, for a command that launches Oracle’s online support portal My Oracle Support, type https://support.oracle.com.
Note: The value for the Name field is not critical, but the field must not be null. Some developers describe the function of this parameter (for example, launchMetaLink); others include the actual URL in this field. This value appears in the command properties window after defining the parameter. Ensure you follow any designated project guidelines or naming conventions.
In the Value field, enter the URL you want the Web browser to open, including the protocol. For example, for a command that launches Oracle’s online support portal My Oracle Support, type https://support.oracle.com.
Click OK.
The Parameters window for the command parameter closes.
The Command Properties window displays the Name value of the command parameter in the Parameters area.
Click OK to save the properties you defined and to close the Command Properties window.
Save your work.
When this action is reached in the flow of the script, a new instance of the Web browser used to launch the user’s Oracle Applications session will appear in a separate window, displaying the contents of the designated page.
Due to its Java architecture and its ability to communicate with the applications database, Oracle Scripting is a highly extensible application. Using application program interfaces customized for this purpose, applications can easily communicate with Oracle Scripting.
Oracle TeleService is a forms-based business application that includes Oracle Customer Care and Oracle Customer Support. This application includes the ability to log and track service requests.
The Oracle Customer Care component of Oracle TeleService passes information regarding a selected customer record to the Scripting blackboard when you execute a Forms command in the script. A record must be selected in the Customer Care contact center in order for the information to successfully transmit to the Scripting blackboard. The values include information about the customer (customer ID, customer account ID, contact and contact point ID and type), and the interaction ID.
Use this procedure to define a forms command to obtain a value passed to the Oracle Scripting blackboard from the Customer Care component of Oracle TeleService. If the value retrieved is to be used as a parameter for another command, this procedure will be performed as a nested command.
Prerequisites
You must know the TeleService/Customer Care API name.
You must know the correct location in the script in which to define this command.
Steps
If you want to display the value returned by this forms command in the current panel as an embedded value, then perform the following:
Navigate to the panel layout editor.
Enter the appropriate text you want to appear at runtime.
At the location in the panel text in which you want the return value from the forms command to appear, type any text as a placeholder.
For example, type EV.
Highlight the placeholder text, and from the panel layout editor toolbar, click the EV button to indicate that you wish to create an embedded value.
The Modify Command Properties button in the panel layout editor toolbar enables.
Click the Modify Command Properties button.
The Command Properties window appears.
If you want to display the value returned by this forms command in the answer control of a new panel answer, then perform the following:
Navigate to the Answer Entry Dialog window of the designated panel answer.
In the Name field, type a name for this question (also known as an answer definition).
For example, type contactPersonFirstName.
From the UI Type area, define the question user interface control type.
For example, to provide the value of the contact person’s first name in a text field, select Text Field.
Optionally, if you want the question control to contain a label in the script at runtime, in the Label for reporting field, type a value.
For example, type Contact person first name:
Click Edit Data Dictionary.
The Edit Data Dictionary window appears. The last tab selected during this Script Author session is selected.
Click the General tab.
In the General area, for the Default Command field, click Edit.
The Command Properties window appears.
If you want to use the value returned by this forms command as a parameter to another Script Author command, then perform the following:
Navigate to the Command Properties window of the top-level command.
In the Parameters area, define the top-level parameter required for the top-level command.
For example, if the top-level command is a PL/SQL command to write a record to the database, and you want to obtain the contact ID for the selected customer, then in the Name field of the Parameters window, provide an appropriate name (for example, contact_id).
In the top-level command parameter, in the Parameters window, select the Add Value as Command? check box.
The Parameters window refreshes. The Value field now includes an Edit and a Remove button.
In the Value field, click Edit.
The Command Properties window for the nested command appears. It is in this window that you will define your forms command.
From the Command Type area, select Forms Command.
Tip: If defining several similar forms commands, you may want to define the first command in the command library. Subsequently, when accessing the Command Properties window, you can click Use Command Library, select the appropriate script and click OK, and then modify properties as required.
In the Command Info area, in the Name field, type a name for this command.
Note: The value for the Name field is not critical, but the field must not be null. Some developers use the identical API name here as in the Command field; others enter a description of the parameter. Ensure you follow any designated project guidelines or naming conventions.
For example, type GetContactId.
In the Command field, type the exact name of the API. The Oracle TeleService APIs are documented in the Integrating Oracle Scripting section of the Oracle Scripting Implementation Guide.
Note: This value is case-sensitive.
For example, to get the contact ID for the selected customer, type GetContactId.
No command parameters are required.
In the Return Value area, perform the following:
Click Edit.
The Parameters window for this return value appears.
In the Parameters window, in the Name field, enter the name you want to use as the blackboard value.
For example, type GetContactId.
Leave the Value field empty.
Click OK.
The Parameters window for the return value parameter closes.
The Command Properties window displays the Name value of the parameter in the Return Value area.
Click OK to save the properties you defined and to close the Command Properties window.
Save your work.
When executed from the Customer Care component of Oracle TeleService, this script will retrieve the appropriate value and set it to the Oracle Scripting blackboard using the return value name.
Guidelines
Subsequent to execution of the forms command, you can reference the value in the blackboard using the return value name as the blackboard key to the key/value pair.
This can be executed as a parameter to another command in order to provide the value obtained by the forms command as a command parameter to that top-level command.
While Oracle TeleSales and Oracle Collections do not allow Oracle Scripting to get or set values in forms, both business applications do provide pre-built integration. When a script is launched from either of these business applications (in their separate respective methods), over fifteen possible values are sent to the Oracle Scripting blackboard. These values can be used in the script to perform various functions, from branching to display of information and so on, using Oracle Scripting blackboard APIs.
The full list of values that are potentially sent to the blackboard are documented in the Integrating Oracle Scripting section of the Oracle Scripting Implementation Guide. Note that the values must be available to the business application in order to be sent to the blackboard; any values not available will be placed in the blackboard as a null value. Thus, ensure your scripts take possible null values into account when using these values. For example, you can test the value passed by the blackboard key CONTACT_ID and, if null, present the user with the ability to retrieve the contact ID from the applications database.
Related Topics
Oracle TeleService APIs are also documented in the Integrating Oracle Scripting section of the Oracle Scripting Implementation Guide.
Oracle TeleSales and Oracle Collections values sent to the Oracle Scripting blackboard are documented in the Integrating Oracle Scripting section of the Oracle Scripting Implementation Guide.
For more information on APIs developed by business applications to work with Oracle Scripting, see the appropriate product documentation.
Using a constant command provides a constant, predetermined value at runtime. This is often used to provide a default selection for an answer with one or more possible values. You can also use a constant command to provide a default return value as a parameter to another command.
Guidelines
Commands are associated with objects using several approaches. For more information on where constant or other commands can be placed into a script, see Where Commands Are Defined in the Script Author.
Use a constant command to provide a default answer selection or lookup value to an open-ended question at runtime to avoid a null value without using a validation routine. For example, when provided with a text field or text area, you can provide a constant value of "not applicable" that the user can overwrite if applicable.
When used to provide a default answer selection, the answer can be changed at runtime. This is true regardless of whether the answer user interface type is open-ended (text field, text area, password without validation, single or group check boxes, and the multi-select list box can be null) or whether it enforces a value (radio buttons, drop-down list or multi-select list boxes, or a button if more than one lookup is provided for button types.
Since the purpose of the constant command is to return a constant value, remember to provide the desired constant string as a return value in the Command Properties window.
Constant commands do not require the ServerProxyBean to be passed as a parameter.
When defining a constant command, there are two values in the Command Info area of the Command Properties window: Name, and Command. Neither of these fields are crucial, provided you provide the constant value as a return value to this command. Many script developers use the same value (the actual constant value being provided) for both fields. Others use the answer definition name, or if the answer is provided as a constant value for a blackboard key, the blackboard key name. The Name and Command fields can also be left blank, but this is not recommended.
The delete action causes a row to be deleted from the database, based on what is currently selected in the Scripting cursor.
When you execute a database query from a script using a query block, and one or more rows that match your criteria are returned, the cursor holds the first row. All rows are retained in static memory until the next query is executed (or until the interaction ends). Using the delete action will cause that row to be deleted from the database.
The delete action is not strictly a command, but is provided in the same interface to make this functionality accessible to script developers in a manner consistent with the application’s existing paradigms.
Scripting APIs are available to advance the cursor, check if the cursor is valid, and so forth. These can be used in combination with the delete action during the development of a script to determine which row of information should be deleted.
The delete action will delete the row of information in the database last retrieved by a query, regardless of when in the current script interaction the last query took place. Thus, before including a delete action in a script, it is recommended to ensure that the relevant query is successful (that it will always return rows). Ensuring the validity of a query prior to executing the delete action will preclude deletion of a row returned for the previous query if the following query returns no values in a particular set of circumstances.
For ease of maintenance, it is recommended that you insert the delete action as close as possible in the flow of a script to its relevant query.
The delete action takes a single parameter in the Name field. The purpose of this field is to identify the delete action within the Script Author. Regardless of the name, the database row corresponding to the row held in the cursor will be deleted. The Name field can also be left blank, but this is not recommended.