This chapter covers the following topics:
Each script created with Oracle Scripting is customized according to specific requirements to achieve a particular set of goals. Oracle Scripting provides a set of best practice Java methods, best practice survey scripts, and building blocks (pre-built graphical script fragments) to assist you in customizing a script to extend its functionality using existing components.
If Oracle Scripting does not meet documented functionality, you can seek the assistance of Oracle Support Services (OSS). However, Oracle does not support customization or custom code. Use of the Script Author component of Oracle Scripting requires the appropriate training, skill set, technology, and experience.
For interaction center agents using the Scripting Engine agent interface, Oracle recommends that you become familiar with any new script prior to using the script in production. Based on the complexity of the script, this process can take between five minutes and a few hours.
For script developers, implementation staff, scripting administration, and survey campaign administration, Oracle suggests that you attend one or more of the Oracle Scripting training classes available through Oracle University.
Training and certification in the requisite technologies is also a prerequisite.
Skill sets required for Oracle Scripting vary on components to be used at the enterprise and the degree of complexity required. Scripting may require script developers, script administrators, survey campaign administrators, integration with other Oracle applications, custom code development, JSP developers and HTML developers.
Oracle strongly recommends contracting Oracle Consulting Services (OCS) or certified, experienced consulting partners to develop the first several scripts to be used in production in an enterprise.
The Script Author is intended for the functional user with some technical knowledge. Additionally, certification in and knowledge of the related technologies relevant to your scripting project is required. Each Oracle Scripting script is customized to meet specified business needs. These needs, defined as a set of business rules, are incorporated into a script by trained, knowledgeable script developers using the Script Author tool. Each script includes the script metadata, instructions regarding the one or more possible script flows to completion, and references to any required custom code.
To make the Script Author more accessible to non-technical users, Oracle has added a Script Wizard feature to the Script Author Java applet. Users can quickly and easily create simple scripts or surveys by providing script information in a series of windows known as a wizard. This feature can help reduce the time it takes to train a non-technical Script Author user to create and modify simple scripts. While hiding complexity from non-technical users, the Script Wizard feature makes it possible to re-use questions and answers, reduce keystrokes and data entry errors, and reduce some repetitious work needed to create and modify a script.
Nonetheless, wizard scripts require the script developer to have a clear and consistent understanding of the business rules of the script and the business process flow required for the overall interaction. A knowledge of Oracle Scripting's handling of data is absolutely essential to developing successful scripts.
Scripts typically require custom code to extend their functionality. Regardless of the execution method of the script, custom code required may include any one or a combination of supporting technologies. These include Java, PL/SQL, Oracle Forms, Constant commands, and Scripting Blackboard commands. Custom code can be associated only with graphical scripts.
Scripts to be executed as surveys also require custom JSP development in order to customize at least one set of survey resources. These are reusable, and an enterprise may elect to use a single set of resources for all surveys implemented in the enterprise. Alternatively, requirements for each survey campaign may dictate a separate set of JSP resources for each. A set of resources includes three JSP/HTML page fragments or files: a header, a final page, and an error page. These are all simple JSP pages, and seeded examples are shipped in Oracle Applications. Thus, the requirement for JSP is low and may be a one-time setup requirement.
Knowledge of HTML may be required in order to customize the presentation of a panel in a script. When you build a script using the graphical tools of the Script Author, you specify display text (including questions), in the panel layout editor. You have control over font size, typeface, color and weight, using the graphic UI provided by the panel layout editor. You also select a user interface control for each answer, such as a radio button or check box. From these choices you select, HTML is automatically generated to control the display of the specified panel attributes. This HTML includes some dynamic content which is processed and displayed at runtime.
The Script Author allows import and export of panel content layout to fully control its appearance at runtime. If you want to customize the presentation of a panel in a script, you can export and modify panel HTML. You can also generate original HTML following Script Author HTML syntax rules. For example, you may wish to use tables to align a series of radio buttons or text fields, rather than accept the default HTML layout generated by the Script Author. You can then import the customized HTML using the Script Author for a customized look for panel display. This model is appropriate for executing scripts either in the agent interface or as a survey in the Web interface.
HTML can also be modified for wizard scripts, by first graphing the script (creating a copy of the wizard script accessible by the Script Author graphical tools). Note, however, that once a script is graphed, any changes made to it cannot be accessed from the Script Wizard.
Interaction centers using Oracle Scripting in the agent interface may have specific script campaign managers. These individuals must understand the goals and objectives of the campaign and the business rules which must be incorporated into the script to achieve those goals. Typically, these individuals will work closely with script developers to determine detailed script requirements.
Oracle Scripting includes a Scripting Administration console. Users of this JSP/HTML-based user interface include script developers, who launch the Script Author applet from the Home tab, and administer deployed scripts and custom Java archive files from the Administration tab. Interaction center campaign administrators or system administrators (as well as script developers) will also typically access this console to run panel footprint reports to help tune a script’s structure, increase agent performance and reduce average talk time. To access the Scripting Administration console user interface from Oracle HTML-based applications, these users must have the Scripting Administrator responsibility.
Since script developers can deploy, delete, and otherwise affect scripts in production, and can manipulate information in the applications or other enterprise database, Oracle strongly recommends that only trusted users be provided with the Scripting Administrator responsibility.
Enterprises using Oracle Scripting to conduct survey campaigns must have survey campaign administrators. These individuals must understand the goals and objectives of the survey campaign in order to achieve those goals. These survey campaign administrators must:
Identify the sample (target population of individuals whom they want to poll).
Create or work with individuals to create a list of possible survey respondents consisting of the sample.
Work closely with script developers to determine detailed script requirements and enforce the business rules which must be incorporated into the script to achieve those goals.
Work with JSP developers to create appropriate survey resources.
Determine how many cycles are required to conduct each survey and schedule calendar days for execution.
Use the Survey Administration console to input business requirements for the overall survey campaign, specific cycles and deployments, define survey resources, and monitor the progress of an ongoing campaign.
Oracle Scripting includes a Survey Administration console. Users of the JSP/HTML-based survey campaign administrative user interface are non-technical users with access to detailed project requirements. These individuals are typically interaction center survey campaign administrators or system administrators.
To access the Survey Campaign administrative interface from Oracle Personal Homepage (PHP) login, these users must have the Survey Administrator responsibility.
Best practice scripts and Java code and building block components are provided by Oracle on an "as is" basis. Pre-built scripts flows are provided to save you time and serve as examples of how to customize scripts. Building blocks typically use Application Program Interfaces (APIs) to read or write data to other Oracle Applications or access the Oracle database, and can be incorporated into your custom scripts to provide them with this functionality.
When used properly, each pre-built component is tested and fully functional. However, you must fully understand how Oracle Scripting works in order to use, modify and maintain each properly.
For example, some customization components (such as best practice surveys) may be used as stand-alone scripts. Nonetheless, surveys cannot be executed until the Survey component is fully implemented, and a survey campaign is created and deployed successfully. Other customization components (such as the building blocks) are to be used as components to incorporate into your custom scripts. However, a building block may access an application that is not configured or not in use in the enterprise.
The functionality of best practice and building block components is therefore only supported to the degree that they will function in a certified test environment. Customizations are not supported. Use of these components is at your own risk.
APIs Are Public But Not Supported
APIs used with Oracle Scripting are public, but not supported. Use of any components that access APIs is at your own risk. Oracle development teams endeavor to continue supporting the APIs, best practice scripts and code, and building blocks through subsequent releases. However, Oracle cannot guarantee that APIs which worked in a previous release will continue to function in future releases in all cases.
You are therefore responsible for the functionality of any customized scripts, including use and customization of any best practice or building block components.
Commands are used in Oracle Scripting graphical scripts to execute actions at runtime. The Command Properties window is context-sensitive. When you select a command type, the window expands, or fields are disabled, as appropriate.
Use this procedure to determine where in a graphical script to begin defining a command to accomplish specific purposes.
None
Using the Script Author, open a new or existing graphical script.
If you want to associate the command as an action to a branch:
In the branch properties menu, click the Actions attribute.
Click Add.
If you want to associate a command as a pre-action or post-action to an object:
Navigate to the object for which you wish to associate a command.
Double-click on the object to access its properties.
To access properties of the global script object, double-click on an empty area of the canvas, or select Script Properties from the File menu.
You can also right-click any object or branch and select Edit Blob Properties or Edit Branch Properties from the resulting pop-up menu.
Expand the Actions tree in the properties menu to display action attributes.
Select PreAction or PostAction attribute from the Actions tree.
Click Add.
The Command Properties window appears.
If you want to associate the command as an API action for a block object:
Double-click on the block object to access its properties.
In the block properties menu, click the Types attribute.
Select API Block from the list.
Optionally, click Apply.
In the block properties menu, click the Object Dictionary attribute.
The Object Dictionary appears.
Click Add.
The Command Properties window appears.
If you want to associate the command to a text or timer object in the script information area:
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 Static Panel attribute.
Static Panel properties appear. The Static Panel is also referred to as the script information area.
In the Static Panel window, define the text or timer by selecting a position, clicking a static information area object type (Text orTimer), and adding appropriate ID and Label information.
On the Command line, click Edit.
The Command Properties window appears.
If you want to associate the command to a Shortcut button in the Shortcut Panel:
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.
In the Label field, enter label that you want to appear on the shortcut button.
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.
On the Command line, click Edit. The Command Properties window object appears.
If you want to associate a command as a parameter to a parent command:
Define a command.
Under Parameters, click Add.
The Parameters window appears.
In the Name field, type the name of the command parameter.
In the Value field, type the value for the parameter.
If this parameter is required by a Java method, this is identical to the value referenced in the method signature (case-sensitive).
If a string, type the literal string value.
If the value is a boolean, type true or false.
Select Add Value as Command.
The Parameters window will expand.
From the Value field, click Edit.
A child Command Properties window appears. The command you define in this window will be executed prior to the parent command.
Define the command type, and type the name and command values. Define any parameters or return values as appropriate.
Click OK to save these parameters and close the window. You will be returned to the parameters window for the parent command.
If you want to associate a command to a parent command in order to provide the parent command with a return value:
Define a command.
Under Parameter, click Add.
The Parameters window appears.
In the Name field, type the name of the command parameter.
In the Value field, type the value for the parameter.
If this parameter is required by a Java method, this is identical to the value referenced in the method signature (case-sensitive).
If a string, type the literal string value.
If the value is a boolean, type true or false.
Select Add Value as Command.
The Parameters window will expand.
From the Value field, click Edit.
A child Command Properties window appears. The command you define in this window will be executed prior to the parent command.
Define the command type, and type the name and command values. Define any parameters as appropriate.
In the Return Value area, click Edit.
The Parameters window appears. These are return value parameters.
Enter return value parameters as required.
In the Name field, enter any name. This will identify the constant command.
In the Value field, enter the value you wish to be passed as the return value.
Click OK to save these parameters and close the window. You will be returned to the parameters window for the parent command.
In the Command Properties window, enter the appropriate properties for the desired command type. Refer to instructions for a specific command type for detailed information.
Save your work.
Oracle Applications release 11.5.6 and later includes a library of best practice Java methods written specifically for Oracle Scripting. Best practice Java methods provide the ability to incorporate frequently requested functionality into Script Author graphical scripts without writing new Java code.
Using best practice Java methods, you can:
Set, enable, or disable shortcut buttons in the Shortcut button bar (agent interface)
Start or stop a timer in the script information area (agent interface)
Validate a user’s input or response using established validation routines (Web and agent interfaces)
Check for a null value to determine whether to perform a query or request input from user (Web and agent interfaces)
Obtain the time of day to dynamically generate greetings or route script flow to specified paths (Web and agent interfaces)
These are only a few examples. For details, refer to the description of each method below, grouped by class.
The answer validation commands automatically associated with a question within a panel by selecting options in the Define Question Detail wizard window also access best practice Java methods (from the NodeValidation class).
These Java methods are organized into three separate Java classes, grouped by function. These include:
The best practice Java methods are included as compiled Java class files in APPS.ZIP, a compressed archive containing Java classes for Oracle Applications. For enterprises certified to execute Oracle Scripting in the caching architecture, as of release 11.5.7 these classes are also included in IESSERVR.JAR.
To use best practice Java methods, simply create a Script Author command in a script, referencing the best practice Java method and any required parameters or return values.
Oracle does not make source code available. If you wish to understand the parameters used in these Java methods, refer to the descriptive tables for each of the three best practice Java classes below.
As discussed in Standard Java Naming and Usage Conventions, some of the best practice methods listed herein do not adhere to standard Java naming and usage conventions. These will be updated in the near future. When they are, the older best practice Java methods will be decremented. To ensure compatibility, replaced methods will continue to be included in shipped code for a period of time.
Apache Mid-Tier Architecture
Oracle Scripting implementations using the Apache mid-tier architecture can use best practice Java methods more easily than custom Java. In this architecture, the JVM on the Apache Web server references the JSERV.PROPERTIES file on the Web server to locate and identify all Java classes required. Since APPS.ZIP is referenced by this file, all best practice Java commands can be accessed without the requirement to create, compile, or upload custom Java. This speeds development and maintenance, provides for code reuse and eliminates potential Java coding errors for commonly required Scripting Engine functionality.
Caching Architecture
Enterprises upgrading previous Oracle Scripting implementations using the caching architecture may also use best practice Java methods to support Script Author scripts. As of release 11.5.7, the Oracle Scripting best practice Java methods are included in IESSERVR.JAR, one of the three base Java archive files that comprise the Oracle Scripting product. The inclusion of the three best practice classes in IESSERVR.JAR ensures accessibility for enterprises using the caching architecture of Oracle Scripting.
Note: Best Practice Java methods are not available to users of the caching architecture prior to release 11.5.7. If using this architecture you must upgrade to release 11.5.7 or later to use best practice Java.
Typically, when writing custom Java methods to support a script, you must compile your custom Java source code, combine one or more compiled classes into a JAR file, and store the JAR file on the server.
Users of the Scripting Administration console and the Script Author Java applet can deploy custom JAR files to the applications database. This greatly simplifies the use of custom Java code.
If using the older, stand-alone Script Author Java application instead of the integrated applet, then custom JAR files cannot be stored in the database. Based on the architecture in which you are executing scripting, you must then reference the class path of your custom Java in a configuration file (in the JSERV.PROPERTIES file on the Apache Web server for Apache Mid-Tier Architecture operations, or in the APPSWEB.CFG file on the applications server if using the Caching Architecture). Finally, using the Script Author, you must reference each specific Java method in the command field of a Java command.
In contrast, the best practice Java methods are included in APPS.ZIP. The class path for APPS.ZIP is already referenced in the appropriate configuration file. If using best practice Java methods, you do not need to generate, test, or compile Java code, nor do you need to deploy best practice Java code to the apps server or reference the class path in a configuration file. You need only reference each specific Java method in the command field of a Java command using the Script Author.
Caution: Do not, under any circumstances, add custom code to APPS.ZIP. Customization of APPS.ZIP is not supported, and could result in loss of function not only for Scripting but for other Oracle Applications.
Use Best Practice Java Methods with or Instead of Custom Code
If existing best practice Java methods meet all your needs for extending a script, you can use them exclusively. Doing so will eliminate the need to deploy custom code to the database and map the JAR files to a script. Restricting custom Java to the use of best practice Java methods for users of the older stand-alone Script Author application will eliminate the need to write, test, compile and deploy custom Java and to modify JSERV.PROPERTIES or APPSWEB.CFG configuration files to identify the class path of the JAR files on the applications server. You can also use custom code in combination with best practice Java methods in a single script. As long as each command is appropriately referenced, any combination is supported.
The table below describes available Java methods and their parameters.
| Method Name | Description | Return Type | Parameters |
|---|---|---|---|
| jumpToShortcut | Jumps user to group containing the shortcut property shortcutName. Prerequisite: This method requires a group object on the Script Author canvas containing a shortcut value. This group is the destination of the jump. Replaces method JumpToShortcut. Changes include:
|
void | Proxy String shortcutName |
| JumpToShortcut | Decremented. Jumps user to group containing the shortcut property ShortcutName. Prerequisite: This method requires a group object on the Script Author canvas containing a shortcut value. This group is the destination of the jump. |
void | Proxy String shortcutName |
| startTimer | Starts an interaction timer (displays in Agent interface only). Use this method to start an interaction timer in the script information area at runtime. If timing the full interaction, this method must be called prior to the first panel.
Note: Cannot be used as pre-action to the global script. Prerequisite: Requires a timer to be defined as a data element in the script information area (static panel). Replaces method StartTimer. Changes include:
|
void | Proxy String shortcutName |
| StartTimer | Decremented. Starts an interaction timer (displays in Agent interface only). Use this method to start an interaction timer in the script information area at runtime. If timing the full interaction, this method must be called prior to the first panel. Note: Cannot be used as pre-action to the global script. Prerequisite: Requires a timer to be defined as a data element in the script information area (static panel). |
void | Proxy String shortcutName |
| stopTimer | Stops count on interaction timer (displays in Agent interface only). Use this method to stop the count on an active interaction timer in the script information area at runtime. This will have no negative effect if invoked when a timer is not active. Prerequisite: Requires a timer to be defined as a data element in the script information area (static panel). Replaces method StopTimer. Changes include:
|
void | Proxy String shortcutName |
| StopTimer | Decremented. Stops count on interaction timer (displays in Agent interface only). Use this method to stop the count on an active interaction timer in the script information area at runtime. This will have no negative effect if invoked when a timer is not active. Prerequisite: Requires a timer to be defined as a data element in the script information area (static panel). |
void | Proxy String TimerName |
| resetTimer | Resets to 0 seconds the count on an active interaction timer in the Agent interface. Has no effect if invoked when a timer is not active. Prerequisite: Requires a timer to be defined as a data element in the script information area (static panel). Note lower case initial capitalization of parameter timerName, following standard parameter naming conventions. |
void | Proxy String timerName |
| getUser | Returns the user name of the individual running the script in a string called User | String | Proxy |
| checkReturnStatus | Boolean expression that checks to see if the status of a command returns a value of S indicating success. If S, returns True; otherwise, returns False. | boolean | Proxy |
| getCursorColumn | Returns the corresponding value of the column in the cursor, based on the index that is passed in the i parameter for an integer. | String | Proxy integer "i" |
| findAndSetCurrentRecord | Finds the current record in the scripting cursor and sets the pointer to that record, based on what was selected in the question. By default, any access to the scripting cursor points to the first record. After calling this method, any future access to the cursor record will return values from the new row where the pointer is located. Parameter rowid changed to rowID to follow standard parameter naming conventions |
void | Proxy String rowId String columnName |
| setCursorColumnToBB | Sets the corresponding value of the cursor column specified in the columnName parameter to the Blackboard variable specified in the parameter key. | void | Proxy String key String columnName |
| getIndexforColumn | This method returns the numeric index (0,1, 2....) in the cursor for the columnName parameter passed. | int | Proxy String columnName |
The table below describes available Java methods and their parameters.
| Method Name | Description | Return Type | Parameters |
|---|---|---|---|
| getTimeOfDayForGreeting | Returns the string morning, afternoon, or evening derived from the current time (based on SYSDATE) so that you can set up a greeting as an embedded value. | String | |
| getTimeOfDayForClosing | Returns the string day, afternoon, or night derived from the current time (based on SYSDATE) so that you can set up a closing using an embedded value. | String | |
| currentDate | Returns current date in format MM/dd/yyyy. | String | |
| currentTime | Returns the time in format hh:mm:ss am/pm. | String | |
| setStaticInfo | Allows you to set values in the script information area (displays in Agent interface only). Requires you to pass the fieldID and its value value as parameters. Replaces method SetStaticInfo. Changes include:
|
void | Proxy String fieldID String value |
| SetStaticInfo | Decremented. Allows you to set values in the Script Information panel (displays in Agent interface only). Requires you to pass the FieldID and its value as parameters. |
void | Proxy String FieldID String value |
The table below describes available Java methods and their parameters.
| Method Name | Description | Return Value | Parameters |
|---|---|---|---|
| validateForDateFormat | Boolean expression that checks for a date in format MM/dd/yyyy. If a different format is found, returns an error message asking the user to enter the date in the correct format. Private static parameter dateFormat changed to DATE_FORMAT to follow standard parameter naming conventions. |
boolean | String answer |
| validateForTimeFormat | Boolean expression that checks for time in format hh:mm:ss am/pm. Returns an error if not in the correct format. Private static parameter timeFormat changed to TIME_FORMAT to follow standard parameter naming conventions. |
boolean | String answer |
| validateDateNotInPast | Boolean expression that checks to see that the date entered (in format MM/dd/yyyy) is in the future. If false, provides an error message to the user with a prompt to enter a valid date not in the past. Private static parameter dateFormat changed to DATE_FORMAT to follow standard parameter naming conventions. Changed error message from Please enter a valid date/time... to Please enter a valid date.... |
boolean | String answer |
| validateIntegerEntered | Boolean expression that checks to see if a blackboard key has an invalid value. Returns True indicating an invalid value if blackboard value is null, blank, contains only spaces, or is a string of -1 indicating an exception. Otherwise returns False indicating a valid value. | boolean | String answer String label |
| validateIntegerInRange | Boolean expression that allows you to enter a minimum and maximum range, and subsequently checks that the user's entry is within that range. | boolean | String answer String minStr String maxStr String label |
| validateRequiredField | Boolean expression that checks to see if a value is entered for the designated field. If null or empty, provides an error message to the user with a prompt to enter a value for that field. | boolean | String answer String label |
| checkNullValue | Boolean expression that checks to see if a blackboard key has a null value. Returns True if null; otherwise returns False. | boolean | String answer |
| checkInvalidValue | Boolean expression that checks to see if a blackboard key has an invalid value. Returns True indicating an invalid value if blackboard value is null, blank, a space, or is a string of -1 indicating NotInInteractionException or InvalidCursorException. Otherwise returns False. | boolean | String answer String bbkey |
| enableButton | Enables a button on the shortcut bar (displays in Agent interface only). Replaces method EnableButton. Changes include:
|
void | String answer buttonID |
| EnableButton | Decremented. Enables a button on the shortcut bar (displays in Agent interface only). |
void | String answer ButtonID |
| disableButton | Disables a button on the shortcut bar (displays in Agent interface only). Replaces method DisableButton. Changes include:
|
void | String answer buttonID |
| DisableButton | Decremented. Disables a button on the shortcut bar (displays in Agent interface only). |
void | String answer ButtonID |
In Script Author graphical scripts, commands are associated with a branch or with an object (panel, group, block, or the entire script object itself). Commands are defined in the Command Properties window and execute the specified action at runtime, affecting the objects to which they are associated.
Use this procedure to define a Java command in the Script Author that references best practice Java methods included with Oracle Scripting release 11.5.6 and later.
Prerequisites
Script Author release 11.5.6 or later.
Oracle Applications release 11.5.6 or later.
Identify the name and location of the appropriate Java method you wish to reference in the command.
Steps
Using the Script Author, open a new or existing graphical script.
Navigate to the object for which you wish to associate a command.
Open a Command window.
From the Command Type list, select Java Command.
In the Name field, enter a unique name for this Java command.
In the Command field, enter all of the following, concatenated and with no spaces:
The fully qualified Java class name, including package path.
Two colons.
The specific Java method you are referencing for this command.
Thus, if the class you are referencing is in the package oracle.apps.ies.bestpractice, the class is named SampleClass, and the method is SampleMethod, the full value to enter in the Command field is:
oracle.apps.ies.bestpractice.SampleClass::SampleMethod
If the signature for the desired Java method indicates that parameters are required, do the following:
Under Parameters, click Add.
In the Name field, type the name of the command parameter.
If the method includes the ServerProxyBean as a parameter, type "Proxy" (case-sensitive) in the Name field. No other values are required for this parameter.
In the Value field, type the case-sensitive value for the parameter referenced in the Java signature.
If a string, type the literal string value.
If the value is a boolean, type True or False.
If you want to add the value as the return value of an executed command:
Select Add Value as Command.
From the Value field, click Edit.
Enter the parameters for the new command, save, and click OK to save the command.
Click OK to save the values entered as parameters.
If you want to add a return value to the top-level command:
Click Edit in the Return Value area.
The Parameters window appears.
Enter appropriate return value parameters, save, and exit.
Click OK to save the values entered in this command.
Save your work. When deployed, the specified Java method will be called at runtime.
When executing scripts in the Scripting Engine Web interface, you can pass parameters into an Oracle Scripting session from external applications. These parameters are stored in the Scripting blackboard, and are available for use throughout the script session. This method is appropriate regardless of whether you run scripts as surveys, or from a self-service Web application such as Oracle iSupport.
Using methods appropriate to your source application, pass each parameter to the Scripting blackboard by concatenating each key and value to the runtime survey URL required to initiate a script session.
After the last parameter required as part of the URL to initiate the script transaction, pass in values from external applications by concatenating an ampersand (&), the key name, an equal sign (=), and the key value to the URL required to initiate the survey.
Thus, if you want to pass an Oracle iSupport transaction ID (for example, 999) to a Web script launched from iSupport, you can append to the survey URL the key value pair transaction_id=999. This will then be accessible as a blackboard value from the script with and the key/value pair (transaction_id, 999).
Initial URL May Differ
The initial runtime survey URL used in your environment may differ based on method of execution for your environment. For example:
The initial JSP page called may be IESSVYMENUBASED.JSP if hosted on a Web-based application.
The initial JSP page called may be IESSVYMAIN.JSP if executed as a survey.
Each Scripting Engine transaction using the Web interface requires at least one parameter, dID (deployment ID). List-based surveys also require a unique rID (respondent ID) parameter.
Syntax and Examples
The appropriate syntax follows. This includes two additional parameters (Keyname 1 and Keyname 2):
http://<hostname>:<port>/OA_HTML/<hosted or stand-alone survey jsp>?<Deployment ID>&<Respondent ID>&<Keyname1=<Value1>&<Keyname2>=<Value2>
An example of a list-based stand-alone survey URL passing a customer ID of 12345 and a customer name of Smith appears as follows:
http://server1.company.com:7777/OA_HTML/iessvymain.jsp?dID=263&CUSTOMER_ID=12345&CUSTOMER_NAME=Smith
An example of a hosted survey URL passing a Party ID of 1000 and a customer name of Chan appears as follows:
http://server2.company.com:8888/OA_HTML/iessvymenubased.jsp?dID=374&PARTY_ID=1000&CUSTOMER_NAME=Chan
The limit to parameters that can be passed is restricted by the Web browser's supported limit of URL characters.
This section describes various tasks you may wish to perform to provide additional functionality to a script at runtime. Some tasks involve manipulating aspects of the Scripting Engine agent interface. As such, these tasks are not applicable to scripts developed for execution in the Web interface. If a task is applicable to the agent interface only, this information is clearly described.
Shortcut buttons display in the agent interface at runtime, and present as a horizontal row of buttons immediately above any panels rendered. In order for a Shortcut button to function, the script must have a group with the appropriate Shortcut property.
Clicking on a shortcut button executes any Script Author command associated with the button. For example, you can jump in the script to a destination group anywhere in the script (identified by the Shortcut property of a group). A button can also call any other Script Author command For example, a button can be programmed to execute the Forms Goto URL command to access a web page in a new browser window.
Use this procedure to define a Shortcut button in the button bar to execute any Script Author command.
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.
In the Label field, enter label that you want to appear on the shortcut button.
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.
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.
Click OK to save the Command Properties and close the window.
To enable the Shortcut button upon the launch of the script, select Enabled.
A check appears, indicating the button is enabled.
Note: You may also use Java command to enable a Shortcut button at a later time during the flow of the script, or to disable a Shortcut button at a specified point in the flow.
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.
Use this procedure to define the Java code and a shortcut button to jump to a group. This can be accomplished using the JumpToShortcut Java method in the best practice ScriptUtil class, or by writing a custom Java method using the jumpToShortcut Scripting API.
Sample Code
The following sample Java method establishes a destination group by its Shortcut property.
public void shortcut1(ServerProxyBean pb, String DestinationGroup)
{
try
{
pb.jumpToShortcut(DestinationGroup);
}
catch (Exception e)
{
e.printStackTrace();
}
}
In this example, Shortcut 1 is the method to associate with a Shortcut button. When shortcut1 is evaluated, the flow of the script will jump to the group with the Shortcut name DestinationGroup. The first panel in that group will display at runtime.
Prerequisites
Create the group intended as the destination of the jump. Ensure you provide a Shortcut property. The group must be syntactically correct:
It must contain a Start node, Termination node and appropriate branching between all objects.
Any panels in the group must have answers defined. If distinct branching is used, one answer definition in that panel must be set to trigger as the default for distinct branching.
Write the code for the Java method, following the guidance above. The method must name the destination group by its Shortcut name.
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.
In the Label field, enter label that you want to appear on the shortcut button.
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.
On the Command line, click Edit.
The Command Properties window appears.
From the Command Type list, select Java Command.
In the Name field, enter a unique name for this Java command.
To define a shortcut button using the JumpToShortcut method in the best practices Java:
In the Command field, type
oracle.apps.ies.bestpractice.ScriptUtil::JumpToShortcut
Under Parameters, click Add.
The Parameters window appears.
In the Name field, type Proxy.
No other values are required for the ProxyServerBean parameter.
Click OK to save the Proxy parameter and close the window.
Under Parameters, click Add.
The Parameters window appears.
In the Name field, type the name of the command parameter.
Type the value ShortcutName. This is the string used as a parameter by the JumpToShortcut method.
In the Value field, type the value of the shortcut property associated with the group you wish this button to jump to.
For example, to jump to a group with the shortcut property Group1, type Group1 in the Value field.
Caution: This field should contain the value of the Shortcut property, not the name of the group.
Click OK to save the Proxy parameter and close the window.
To define a shortcut button using a custom Java method invoking the jumpToShortcut API as in the sample code above, then do the following:
In the Command field, type the fully qualified name of the custom Java class, two colons, and the Java method, concatenated and without spaces.
For example, assuming the method in the example above is in the class CustomCode and is appropriately deployed to the database in the path <JAVA_TOP>/ies_custom, type the following in the command field.
<JAVA_TOP>.ies_ custom.CustomCode::shortcut1
Under Parameters, click Add. The Parameters window appears.
In the Name field, type Proxy. No other values are required for the ProxyServerBean parameter.
Click OK to save the Proxy parameter and close the window.
Since the value of the shortcut group is determined by the custom Java method, no additional parameters are required unless required by the custom method.
Click OK to save the Command Properties and close the window.
To enable the shortcut button upon the launch of the script, select Enabled.
A check appears, indicating the button is enabled.
Note: You may also use Java command to enable a Shortcut button at a later time during the flow of the script, or to disable a Shortcut button at a specified point in the flow.
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.
A Shortcut is the property of a Group in the Script Author. Using Java commands, the flow of a script in runtime can jump to a "target" group containing a Shortcut of a specified name. The group contains the panels that are the destination that result when clicking the Shortcut button. Three typical uses of a Shortcut are to associate a target for a Shortcut button in the Shortcut button bar (for the agent interface only), to enable the Disconnect button (for the agent interface only), and to associate a target for a group containing specific functionality which must be accessed after meeting a specified condition in a script (for either runtime interface).
Use this procedure to define a group as the target of a jump.
Prerequisites
Insert a group.
Steps
Using the Script Author, open a new or existing graphical script.
In the tool palette, click the Toggle Select Mode tool.
On the canvas, double-click a group.
The Properties window appears.
In the Group tree, select Shortcut.
In the Shortcut field, type the name of the shortcut.
For example, to define a group as the target after clicking Disconnect in the agent interface, type WrapUpShortcut.
Click Apply to save your work and continue, or click OK to save your work and exit the Properties window for the group.
If you want to jump to the Shortcut in runtime from a Shortcut button, define the Shortcut button.
If you want to jump to the Shortcut in runtime based on values or other criteria, define that criteria and associate the criteria with one or more commands in the script.
If you created this group to enable the Disconnect button in the agent interface, you must ensure the subgraph created by the group is appropriately terminated, with (at minimum) a default branch from the Start node to a Terminal node.
The Disconnect button appears at the bottom right of the Scripting Engine agent interface, in the outermost frame of the window. The purpose of this button is to allow agents using Oracle Scripting to bring the flow of the script to a close from any point in the script. When this button is clicked at runtime, the agent is "jumped" in the flow of the script to a specified destination group.
For scripts created using the Script Wizard, the Disconnect button is created automatically, by placing a group named Disconnect on the canvas. This subgraph represented by this group contains default branching to a Termination node, and does not contain any panels. The Shortcut property contains the WrapUpShortcut designation.
For graphical scripts, the Disconnect button is not enabled until you create a destination group (or designate an existing group as the destination group), provide the appropriate content for that group (optional objects and mandatory termination), and provide the appropriate Shortcut property designation.
Note: Unlike other instances of jumping the end user to a specified group, enabling the Disconnect button does not require any Java to be created.
The destination group routed to from the Disconnect button must:
Be placed on the root graph of the script.
Contain the shortcut name WrapUpShortcut (this is case-sensitive).
Be properly terminated on the root graph, with a default branch leading to a Termination node on the root graph.
Be properly terminated in the child graph within the destination group.
To immediately end the script session, include no panels in the destination group. Simply add a Termination node and default branching. Alternatively, to capture information required for every session, include panels, blocks, or child groups within the destination group. For example, for an inbound script, you can include a panel that thanks the user for calling, and inquiring how the caller heard about this particular promotion. For outbound scripts, you may wish to establish callback information in the group.
Based on the approach taken (including wrap-up information, or immediately ending the script session), this destination group is generally referred to either as the WrapUp group or the Disconnect group. Use this procedure to define a group as the destination target for when an agent clicks Disconnect in runtime.
Prerequisites
None
Steps
Using the Script Author, open a new or existing graphical script.
If you want to create a new group as the target destination of the Disconnect button, then do the following:
In the tool palette, click the Group Insertion Mode tool.
On the root graph of the canvas, click where you want to insert the group.
In the tool palette, click the Toggle Select Mode tool.
Double-click the group you just created.
The Properties window appears.
If you want to designate an existing group as the target of the Disconnect button, then do the following:
In the tool palette, click the Toggle Select Mode tool.
On the root graph of the canvas, double-click a group.
The Properties window appears.
In the Group tree, select Properties.
Properties field for the group display.
In the Name field, type a meaningful name.
For example: if clicking Disconnect at runtime must immediately end the current script session, type Disconnect; if clicking Disconnect at runtime must result in displaying panels wrapping up the transaction, type WrapUpGroup.
Click Apply to save your work and continue.
In the Group tree, select Shortcut.
In the Shortcut field, type WrapUpShortcut.
Note: This value is case-sensitive and must be entered precisely.
Click OK to save your work and exit the Properties window for the group.
Click OK to save your work and exit the Properties window for the group.
Click OK to save your work and exit the Properties window for the group.
If the destination group on the root graph is not yet connected via default branching to a Termination node, do the following:
In the tool palette, click the Termination Point Insertion Mode tool.
On the root graph of the canvas, click where you want to insert the Termination node.
In the tool palette, click the Default Branch Mode tool.
When the pointer is over the canvas, the pointer is a cross hair (+).
On the canvas, drag the pointer from the destination group to the Termination node.
If clicking Disconnect at runtime must immediately end the current script session, do the following:
In the tool palette, click the Toggle Select Mode tool.
On the root graph of the canvas, click once to select the group.
The Properties window appears.
In the tool palette, click the Go down into child graph tool.
The subgraph representing the target group appears.
In the tool palette, click the Termination Point Insertion Mode tool.
On the canvas, click where you want to insert the Termination node.
In the tool palette, click the Default Branch Mode tool.
When the pointer is over the canvas, the pointer is a cross hair (+).
On the canvas, drag the pointer from the Start node to the Termination node.
In the tool palette, click the Go up to parent graph tool.
The canvas refreshes, displaying the root graph.
The subgraph representing the target group appears.
If clicking Disconnect at runtime must result in displaying panels wrapping up the transaction, and if this functionality does not already exist in the WrapUp group, do the following:
In the tool palette, click the Toggle Select Mode tool.
On the root graph of the canvas, click once to select the group.
The Properties window appears.
In the tool palette, click the Go down into child graph tool.
The subgraph representing the target group appears.
Add panels, groups, or blocks appropriately to provide the desired functionality for the WrapUp group at runtime.
In the tool palette, under the last appropriate object, click the Termination Point Insertion Mode tool.
On the canvas, click where you want to insert the Termination node.
In the tool palette, click the Default Branch Mode tool.
When the pointer is over the canvas, the pointer is a cross hair (+).
On the canvas, drag the pointer from the last appropriate object in your WrapUp group to the Termination node.
In the tool palette, click the Go up to parent graph tool.
The canvas refreshes, displaying the root graph.
The subgraph representing the target group appears.
Save your work.
Upon defining a Shorctut button, you can choose whether to enable it immediately or at a later point in the script using a Java command. In the same manner, at any point in the script, you can use a Java command to disable a Shortcut button.
Use the following procedure to enable or disable a shortcut button using the best practice Java methods enableShortcutButton and disableShortcutButton in the class ScriptUtil.
Prerequisites
For this procedure to have any effect, a Shortcut button must be programmed to display in the Shortcut button bar in the agent interface at runtime.
You must know the ID of the Shortcut button.
Steps
At the appropriate location in a graphical script, navigate to a Command Properties window.
In the Command Type area, select Java Command.
In the Command Info area, type in the Name field a unique name for this Java command.
In the Command field, type the fully qualified Java command of the appropriate Java method.
If you want to enable a Shortcut button, enter
oracle.apps.ies.bestpractice.ScriptUtil::enableShortcutButton.
If you want to disable a Shortcut button, enter
oracle.apps.ies.bestpractice.ScriptUtil::disableShortcutButton.
In the Parameters area of the Command Properties window, click Add.
The Parameters window appears.
In the Class field, leave this value blank.
In the Name field, type Proxy in exact case.
In the Value field, leave this value blank.
In the In/Out list, make no selection. This field is not configurable at this time.
In the Add Value as Command checkbox, leave this unselected.
Click OK.
The Parameters window closes and the new command parameter is listed as a parameter to this command.
In the Parameters area of the Command Properties window, click Add.
The Parameters window appears.
In the Class field, leave this value blank.
In the Name field, type shortcutPanelID in exact case.
In the Value field, enter the ID of the Shortcut button.
In the In/Out list, make no selection. This field is not configurable at this time.
In the Add Value as Command checkbox, leave this unselected.
Click OK.
The Parameters window closes and the new command parameter is listed as a parameter to this command.
Click Apply to save your work and continue, or click OK to save your work and exit the Command Properties window.
If explicitly defined in a script, the script information area appears immediately below the Oracle Applications toolbar in the Oracle Scripting agent user interface.
The script information area is also known as the Static Information Panel or the Static Panel, although information displayed may contain dynamic information. The script information area is a global script property of a graphical script, and displays for all sessions of a script in which it has been defined. There are no facilities for creating a script information area in a wizard script.
A script executed in the agent interface at runtime can display up to three rows of
information. Each row has a left, middle, and right position, for a total of nine possible data element locations. Optionally, each data element may contain a label. Data element types include text or timer.
Text Data Elements
For text data elements, the value can be passed to the script information area at runtime in two ways:
You can provide a constant value using a Constant command.
You can dynamically pass a value from the Blackboard. This allows you to hard-code a value or insert a value retrieved using a PL/SQL query.
Timer Data Elements
Timers defined in the script information area will need to be activated elsewhere using a Java command. If using the best practice Java methods, use the StartTimer method in the ScriptUtil class. This command must not be a pre-condition to the script. You can start the timer in one of two ways:
You can start the timer by referencing the appropriate Java method prior to the first panel, in order to display the timer beginning with the first panel displayed.
Any commands associated as an action with the outgoing branch of the Start node will also be ignored. Any other location where a command can be defined is appropriate. For example, you can reference the method as a precondition to the first panel, or in a Block referencing an API as the action.
You can start the timer by referencing the appropriate Java method at a later point in the script, in order to time a specific portion of the script.
More than one timer can be used in the Script Information panel. The best practices methods include a StopTimer method which can be associated as a command to a button on the Shortcut button bar or as an action anywhere in the script. To use best practice Java to start the timer, use the following command
oracle.apps.ies.bestpractice.ScriptUtil::StartTimer
Use this procedure to define the script information area with text, timers, and labels.
Prerequisites
None
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 Static Panel attribute.
Static Panel properties appear as a matrix (up to three rows, each with a left, center, and right position). Each cell represents the position where a defined set of data elements appears at runtime.
Note: To reduce the amount of screen space consumed by the script information area on an agent’s desktop, define your data elements in rows. Unused rows will not display in runtime, providing more viewing area for interaction center agents.
Click in any cell to define a data element in that position at runtime.
The Text and Timer buttons are enabled.
Click Text or Timer, as appropriate.
The matrix refreshes, indicating the selected region and data type. The data fields below the matrix are enabled.
Enter parameters for this data element as appropriate.
In the ID field, enter a unique identification value.
The Oracle Scripting API requires this ID.
In the Label field, enter the name you wish to appear as the label for this data element, if any.
If you want to pass a command to this data element, in the Command field, click Edit.
The Command Properties window appears.
Note: Do not associate a Java command with a timer data element. The Java command required to start the timer must not be defined as a global script property.
Define the command as appropriate. When complete, click OK to save the command and return to the Static Panel properties.
Click OK to save changes to the Command Properties window.
The matrix in the Static Panel properties displays the data element.
To save your work and define additional script information area attributes, click Apply in the script properties window.
To save your work and exit the script properties window, click OK.
Related Topics
For information on passing a constant value to the script information area in the agent interface at runtime, see Setting a Constant in the Oracle Scripting User Guide.
For information on using a Java command to start the timer, see Invoking a Public Method in a Java Class in the Oracle Scripting User Guide.
Follow this procedure to define a constant command in a graphical script.
Note: Providing an entry in the Default Value field of the Define Question Detail window of a wizard script will automatically provide a constant command for a panel question at runtime.
Prerequisites
None
Steps
Using the Script Author, open a new or existing graphical script.
At the location where you wish to provide a constant value as a command, access the Command Properties window. For more information, see Determining Where to Define a Command.
The Command Properties window appears.
From the Command Type list, select Constant Command.
In the Command Info area, type the name of the command in the Name field.
In the Return Value area, click Edit.
The Parameters window appears.
In the Class field, leave this value blank.
In the Name field, leave this value blank.
In the Value field, enter the value you wish to pass as a constant.
For example, type Customer Service Follow-Up.
In the In/Out list, make no selection. This field is not configurable at this time.
In the Add Value as Command check box, leave this deselected.
Click OK.
The Parameters window closes and the new command parameter is listed as a return value to this command.
Click OK to save changes to the Command Properties window.
The value entered as a return value to this command will be passed at runtime. For example, if you passed the value of Customer Service Follow-Up as a label in the script information area, this value appears in the script information area of the agent user interface at runtime.
Using the indeterminate branch and an associated Java method, you can route the flow of a graphical script at runtime based on conditions tested for in your custom code. You can jump to a sibling object on the graph, or to a group on any graph in the script based on its shortcut property.
Like all commands, the expression associated with the indeterminate branch is evaluated at runtime when the corresponding Script Author object is reached in the flow of the script. When a condition tests true, the target destination provided by the return statement becomes the next object processed in that script interaction.
Jumping to a Sibling Object
A sibling object is any Script Author object appearing on the same graph. If you have only one graph in a script (the root graph), every object is a sibling object. With the indeterminate branch, you can use any configurable object (a panel, group, or block) as the destination, using the name of the object. Only panels contain elements that are displayed at runtime, but if a group or block is the destination, the processing associated with that group or block then occurs. If a panel is the destination object, that panel’s display objects (any panel layout content, and at least one answer control) appear to the script end user.
Jumping to a Group
To jump to a group on a different graph using the indeterminate branch, you must designate a shortcut within the target group, and return the shortcut name in the associated expression.
Oracle recommends using this feature sparingly, because it breaks rules that all other branches (default, distinct, and conditional) follow, and introduces great complexity in debugging script flow issues. Using the indeterminate branch to jump to a group in a different graph of the script is similar in approach and result to using a GoTo statement in other programming languages. Oracle Scripting script development follows a strong paradigm of flow based on expected conditions, and any other instance of script flow is easily traceable, whereas using this approach is not.
Indeterminate Branch Exceptions
Graphs that contain an Indeterminate branch introduce two exceptions to general Script Author syntax rules:
A graph with an Indeterminate branch need not adhere to the requirement for a Termination node in order to pass a syntax check. This assumes the Indeterminate branch is the last object that will be evaluated on that graph.
When using an Indeterminate branch, you may use panels or groups that have no incoming branches, assuming these objects are to be reached no other way than as the destination of a jump.
If an object breaks incoming branch requirements because it is the destination of an indeterminate branch jump, standard syntax and branching rules for all subsequent objects still apply (beginning with the outgoing branch from the destination object).
For more information on understanding graphs, see the Oracle Scripting User Guide.
Sample Expressions Using Return Statement
The following are sample expressions using a return statement. The jumpToDestination Java method evaluates the contents of a string populated in the argument "answer" and routes the script accordingly.
public String jumpToDestination(ServerProxyBean pb, String answer)
{
if (answer.equals("condition_A"))
{
return "destination_A";
}
if (answer.equals("condition_b"))
{
return "destination_B";";
}
else
{
return "destination_C";
}
}
If the first condition is found (if the value of the string answer is equal to condition_A), the flow of the script will continue with the processing of the destination_A object.
If the second condition is found (if the value of the string answer is equal to condition_A), the flow of the script will continue with the processing of the destination_B object.
If the third condition is found (if the value of the string answer is equal to any value other than those tested in the previous conditions), the flow of the script will continue with the processing of the destination_C object.
If a listed destination is a sibling object (is on the same graph as the Indeterminate branch), it can be a panel, group, or block.
If a listed destination is on any other graph in the script, it must be the Shortcut name of a group in order to evaluate correctly at runtime.
The above method is just a sample. While this sample tests the contents of a variable, any condition can be tested for and evaluated.
Prerequisites
Any panel, group or block object must exist on the canvas in order to use the indeterminate branch.
Write the code for the expression (typically a Java method), following the guidance above. The expression must name the destination object or objects, based on each condition tested.
Steps
Using the Script Author, open an existing graphical script.
Navigate to an object for which you want to define an Indeterminate branch.
This object must currently have no outgoing branches
In the tool palette, click the Indeterminate Branch Mode tool.
On the canvas, click on the source object and drag outwards about two inches in any direction.
The Indeterminate branch appears.
Double-click on the branch object or right-click the branch and select Edit Branch Properties.
The properties window for the Indeterminate branch appears.
Optionally, in the Indeterminate tree, select Properties.
In the Properties pane, two fields appear.
In the Name field, enter a meaningful name for this branch.
In the comments field, enter any descriptive comments if desired.
Click Apply to save your changes.
In the Indeterminate tree, select Expression.
In the Expression pane, click Edit. The Command window appears.
Define the indeterminate expression as a command.
The command must return the name of a sibling object (a panel, block or group on the same graph as the source object) and the shortcut name associated with a group on any hierarchical level of the script.
Click OK to exit the Command window.
Click Apply to apply your work or click OK to save your work and exit the Properties window.
The Command Parameter window for graphical scripts has an Iterating Parameter check box. Selecting this parameter enables the Scripting Engine to retrieve answers from a vector. This is required when retrieving answers from one of the new multiple-selection answer UI types (check box group or multi-select list box) and passing the answers to a predefined API.
The business rules governing iterating parameters include:
Each command can contain at most only a single iterating parameter.
The iterating parameter can only be used with Script Author commands that take arguments (Java, SQL, and Forms commands).
The single iterating parameter can be a parameter to the top-level command or to a nested command (a command passed as the parameter to another command).
A Parameter can only be marked as an iterating parameter if both of the following conditions are true:
The parameter is a nested command (Add Value as Command? is selected).
The nested command can return a vector.
The following command types are supported: Blackboard, Java, SQL (with iterating parameter), and Forms commands (with iterating parameter).
These rules are enforced in the Script Author, either via the Command and Parameter windows or by the Syntax Checker.
The following describes the behavior of the iterating parameter in the Runtime Scripting Engine:
During script runtime, the Scripting Engine (regardless of execution interface) attempts to evaluate each parameter of a Script Author command. If the parameter is marked as an iterating parameter, the Engine verifies that the value of the parameter is a vector. Upon confirmation, the Engine 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.
If the iterating parameter's nested command does not return a vector at runtime, an exception is generated.
If the iterating parameter's nested command returns an empty vector at runtime, the command is not executed at all, and no error or exception is generated.
Just as the answer to a multi-select node is stored in the blackboard as a vector of individual selected items, setting the default value of a multi-select node must be done with a vector. Each element of the vector is matched with the value of the lookup choices of the node. If a match is found, that lookup choice is selected.
Using a block designated as a query, you can obtain data stored in any database tables accessible at runtime and display the information in a script.
After any successful query, values returned are stored temporarily in the scripting cursor. This data does not persist beyond the next query, or the end of the interaction, whichever comes first. Prior to the next query, you can retrieve data from the cursor to display in a script, or write that data to the Scripting blackboard.
You can access data retrieved by a database query in the following ways.
Displaying returned values as panel text
Displaying returned values as panel answer lookup values
Writing returned values to the scripting blackboard
Displaying the single record referenced by the cursor as panel text
Displaying all records retrieved by the query as lookup values to an answer
Writing retrieved records to the scripting blackboard
Some of these ways are documented below.
Information stored in the cursor as the result of a query can be displayed in a panel as an embedded value using a blackboard command. If a database query contains one or more constraints designed to ensure a single row is returned, you need only reference the column name in the Command field of a blackboard command in order to display the value. If more than one row is returned by a query you may be required to advance through the rows, testing the values until you ascertain the one which you wish to display. This requires custom Java commands executing cursor APIs. For more information on storing and referencing information returned by a query, see Understanding the Scripting Cursor.
Information stored in the cursor as the result of a query can be used to populate panel answers.
To populate a single-value UI type, you must ensure that your query is structured to return only a single row, because regardless of how many records are returned as a result of a query, the cursor will only point to the first row. This applies to the password field or standard boolean checkbox UI types, as well as open-ended UI types such as the text field or text area.
Caution: Do not use this procedure to populate the button answer UI type.
To populate multiple-value UI types such as radio buttons, drop-down list boxes, multi-select list boxes, or check box groups, your query should be structured to return one or more values. Typically, users expect at least two values to be provided for these choices. If a query at runtime is expected to populate an answer control, and the query returns no values, the script user will not be able to pass that panel and may not be able to complete the script.
To avoid creating a panel for which no answers can populate, and to preclude other problems, creating validation for each query is strongly recommended.
You can write any validation routine you desire, and use commands in the Script Author to execute validation. For example, you can use the Oracle Scripting API isCursorValid in a Java command to check if records were returned to the Scripting cursor. This API will pass a boolean value of True if the cursor contains records. If used in a conditional branch, the branch should flow to continued execution of the script upon returning True. Whenever a conditional branch is used, a default branch should also be used from the source object to branch the script should the condition evaluated return a value of False.
When a query for a column name returns a value, that value is stored in the cursor as a key/value pair, with the key equivalent to the column name. Prior to the next query (if any), that value can be displayed or evaluated in the script using a blackboard command. The key to access that value is equivalent to the column name. If the same key is subsequently used as an answer name elsewhere in the same script, then you must exercise caution when testing the blackboard value to know where in the flow of the script you request the value. Since the blackboard maintains state, testing the blackboard value after the query will provide one answer, and testing the blackboard after the panel has been reached and answered will return a second answer.
In some scripts, due to limited queries or rigid flow of the script, it is easy to make this distinction. Other scripts involve substantial "jumping" or cycling through various portions of the script. For example, a service script may ask after each customer concern is addressed if there is anything else the agent can assist the customer with. This would result in the same set of panels (typically collected in a group object) being accessed multiple times in a script. In such cases, one possible approach is to explicitly set a second blackboard answer that can be used as a control.
Use the example of the value CUSTOMER_NAME, which in a given script can potentially be populated both from a query and also from a panel answer. You can create a Java command as a post-action to the relevant panel only, that sets blackboard values (for example, the key/value pair of setCUSTOMER_ NAMEFromPanel/Y).
Any time you do a query in the script, you want to check both blackboard values (CUSTOMER_NAME and setCUSTOMER_NAMEFromPanel. If the second blackboard value is null, you know the value of CUSTOMER_NAME came from the initial query. If the second blackboard value is Y, you know the value was populated from the panel.
Prerequisites
You must know the appropriate tables and columns to query and have appropriate database connection information and privileges.
Queries can return zero, one, or more than one rows of information. If using a single-display UI type, you must use a query that will return a single value.
If using a multiple-display UI type, you must use a query that will return at least a single value. It is recommended to use a query that will return at least two values.
Steps
In the Script Author tool palette, click the Block Insertion Mode tool.
When the pointer is over the canvas, the pointer is a pointing finger.
On the canvas, click where you want to insert the block.
The block appears. If the Popup on Blob Creation option is selected, then the Properties window for the object appears.
If the Sticky Mode option is selected, then in the tool palette, click the Toggle Select Mode tool.
On the canvas, double-click the block.
The Properties window appears.
In the Block tree, select Properties.
In the Name field, type the name of the block.
This name should indicate the purpose for the query. For example, type getActiveScripts.
In the Comments field, type a comment if desired.
Comments are optional.
Click Apply to save your work and continue.
In the Block tree, select Types.
This is where you designate whether you want to insert, query, or update the database, or whether you wish to access an API or other command.
From the Types list, select Query.
Click Apply to save your work and continue.
In the Block tree, select Object Dictionary.
Enter appropriate information in the Connection/Tables tab:
In the Connection area, define how Oracle Scripting connects to the database at runtime. To reuse an existing connection:
Select Reuse an existing connection.
From the Existing Connections list, select a connection.
To establish new connection information:
If necessary, clear Reuse an existing connection.
Type the connection parameters.
In the Tables area, for each table you wish to connect to:
Click Add Table.
The Table window appears. The text area will accommodate any length required. Alternatively, you can resize this window if desired.
In the Table Name field, type the name of the table.
For example, type IES_DEPLOYED_SCRIPTS.
Although this field is not case sensitive, it is standard to type table names in all upper-case letters.
Click OK.
Click Apply to save your work and continue.
If you want to access tables that require joins, then, in the Join Condition tab, do the following:
Click Add.
The Join Condition window appears.
Identify primary key and foreign key information in the Master PK Table, Detail PK Table, and Detail FK Table tab.
Click OK.
In the Query Data tab, do the following:
Click the Query Columns tab.
For each table in your query, identify the column as indicated:
Click Add Column.
In the Enter a Key/Value window, type the name of the column.
For example, type DSCRIPT_NAME to query the name of a script in table IES_DEPLOYED_SCRIPTS, and ACTIVE_STATUS to query the active status of the resulting script.
From the Data Type list, select the data type of the selected column.
For example, for DSCRIPT_NAME (which has a VARCHAR2 data type), select VARCHAR, and for ACTIVE_STATUS (which has a number data type) select BIGINT.
Click OK.
Repeat as necessary for other columns
If your query has any constraints, then, in the Query Constraints tab, click Add Constraint.
Enter your constraint just as you would using a SQL statement.
Include all information that would follow the WHERE clause.
Include literal strings within single quotes.
For example, type ANONYMOUS='YES' to include the constraint of "where the anonymous flag is set to yes." (Note the single quotes for the literal string ’Yes’.)
As another example, type ID=1 to include the constraint of "where the specified identification number is equal to one." (Note the lack of single quotes.)
Click OK.
Repeat as necessary for other constraints.
Each constraint added in the constraint window is automatically concantenated together during runtime with AND and prepended with WHERE. Optionally, the user can manually concatenate constraints into a single constraint by including a literal string such as "OR", "AND", or other accepted SQL conventions.
Users can reference blackboard values as query constraints using the syntax <BLACKBOARD KEY>. For example, type customer_id = :PARTY_ID to include the constraint of "where the customer_id is equal to the PARTY_ ID value set in the blackboard for this session."
Note: Due to a limitation in the way blackboard key names are specified, there must be at least one space following each blackboard key name to ensure that your SQL functions. Thus, in the example above, type a space after :PARTY_ID before exiting the constraints field.
Click OK to save properties for this block object.
The block properties window closes. The configured block appears on the canvas.
Define objects (if required), termination point, and appropriate branching within the block.
Panels within a block can be used to specify parameters to be used in the actual SQL procedure. In this example, no parameters are required. However, since a block introduces a child graph, you must provide appropriate branching and termination for the script to be syntactically correct.
If necessary, in the tool palette, click the Toggle Select Mode tool.
On the canvas, click the block you have defined, and then click the Go down into child graph button on the canvas tool bar.
The graph for the block appears.
In the tool palette, click the Termination Point tool.
On the canvas, click where you want to insert the Termination node.
In the tool palette, click the Default Branch Mode tool.
When the pointer is over the canvas, the pointer is a cross hair (+).
On the canvas, drag the pointer from the Start node to the Termination node.
When you release the pointer, the objects are connected.
In the canvas tool bar, click Go up to parent graph.
In the tool palette, click the Panel Insertion Mode Point tool.
On the canvas, click where you want to insert the panel.
This panel will use the results of a successful query (defined above) to populate an answer type.
On the canvas, double-click the panel.
The Properties window appears.
In the Panel tree, select Properties.
In the Name field, type the name of the panel.
Optionally, in the Comments field, enter any comments.
In the Label field, type the label of the panel.
The panel label is the value used to identify specific panels in the Progress Area of the Scripting Engine agent interface at runtime. This does not display in the Web interface.
Click Apply to save your work.
In the Panel tree, select Answers.
In the Answers pane, click Add.
The Answer Entry window appears. Do the following:
In the Answers pane, click Add.
Select the Default for Distinct Branching option.
In the Name field, provide an answer name.
For example, type showDSCRIPT_NAME.
From the UI type list, select an appropriate answer UI type:
For queries returning one value, use Text Field, Text Area, Check Box, or Password, as appropriate.
For queries returning two or more values, use Radio Button, Drop Down, Check Box group, or Multi-Select List Box, as appropriate.
For example, to display a list of active scripts, select Drop Down.
In the Label for reporting area, enter a label, if required.
Click Edit Data Dictionary.
In the data dictionary, click the Lookups tab.
From the Lookups area, select the Cursor Lookup option.
In the Cursor lookup display value field, enter any name.
In the Cursor lookup value field, enter the name of the database column that you want to display in this answer UI type.
For example, type DSCRIPT_NAME.
Click OK to close the data dictionary for this specific answer.
Click OK to close the Answer Entry window.
The Panel Properties window appears, listing the answer you have configured.
Define additional answers if desired.
Click OK to close the Panel Properties window.
Enter other objects into the script if desired.
In the tool palette, click the Termination Point tool.
On the canvas, click where you want to insert the Termination node.
In the tool palette, click the Default Branch Mode tool.
When the pointer is over the canvas, the pointer is a cross hair (+).
On the canvas, connect the block object to the panel object, and the panel object to the Termination node. Connect other objects as appropriate.
Save your work.
The Scripting Cursor is a temporary memory space accessible only for the duration of a single scripting interaction. After any successful query, values returned (if any) are stored in the cursor.
Values retrieved are stored using the column names under which the data was stored in the database table.
Data Persistence
Any values stored in the cursor will be overwritten with values retrieved by any successive query in a single scripting interaction. Additionally, data does not persist in the Scripting cursor beyond a single scripting interaction. Thus, after performing a query, you must either use the required data prior to the next query, or write it to the Scripting blackboard. Writing data to the blackboard will enable you to use the data after any successive queries in that interaction. Note, however, that blackboard data also does not persist beyond the current scripting interaction. You always have the option of writing retrieved data to database tables for later access, if required.
Multiple Values, Single Reference
The full results of a query are stored in the cursor, whether one row is returned or many. By default, the cursor points to the first row in a set of returned values. The cursor can be advanced to the second or subsequent rows using specific cursor APIs.
The Scripting Engine cursor is associated with the results of a SQL query executed on a database. The cursor maintains a current record whose contents can be retrieved and which can be advanced through each record in the result set returned by the query, using cursor APIs.
| Method Name | Description | Return Type | Parameters |
|---|---|---|---|
| isCursorValid | Returns the boolean value True if the cursor contains results from a query; otherwise, returns False. Throws NotInInteractionException. | boolean | Proxy |
| getNumberOfCursorColumns | Returns the number of columns contained by each record in the cursor. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | integer | Proxy |
| getCursorColumnNames | Returns a vector of strings containing the names of all columns in the cursor. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | Vector | Proxy |
| getCursorColumnTypes | Returns a vector of Class objects containing the types of all columns in the cursor. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | Vector | Proxy |
| getNumberOfCursorRecords | Returns the number of records contained in the cursor. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | integer | Proxy |
| isLastCursorRecord | Returns the boolean value of True if the current record in the cursor is the last record of the result set returned by the query or if no records were returned by the query. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | boolean | Proxy |
| nextCursorRecord | Advances the cursor so that the next record in the result set becomes the current record. Throws NotInInteractionException. Throws Last Record Reached Exception if the current record is also the last record. If no results were returned to the cursor, throws InvalidCursorException. | void | Proxy |
| getCurrentRecord | Returns a vector of objects containing the contents of the current record in the cursor. Throws NotInInteractionException. If no results were returned to the cursor, throws InvalidCursorException. | Vector | Proxy |
Use this procedure to replace a graphical script panel with a custom Java bean. The use of Java beans to replace panels in a script is only supported for the Scripting Engine agent interface.
Prerequisites
Create a java bean class that meets the requirements of an Oracle Scripting replaceable java bean.
Package the class containing the Java bean into a Java archive (JAR) file using methods supported by Oracle Scripting (use the JAR utility from the JDK specifying no compression, or create a ZIP file and rename the file to a JAR file format).
Using the Scripting Administration console, upload the Java bean to the applications database. For instructions, see Uploading New Java Archive Files in the Oracle Scripting Implementation Guide.
Designate a panel in the custom script to be replaced with the Java bean.
To load a jar file into the database, you need to use the Scripting Administration console. This requires Oracle Scripting release 11.5.9 or later or Interaction Center Family Pack P or later. The Jar file tab allows you to specify a logical name for the jar file (this needs to match the name given in step 2c). Then specify the file location of the Jar file and upload the file. Note that a Jar/script mapping does not have to be created if the Jar file is only to be used for its Java Beans (and not for other Java Commands).
Steps
Using the Script Author, open a new or existing graphical script.
For a new script, create a panel by doing the following:
In the tool palette, click the Panel Insertion Mode tool.
On the canvas, click where you want to insert the panel.
In the tool palette, click the Toggle Select Mode tool.
Double-click on the appropriate panel.
The Panel Properties window appears.
From the panel properties tree, select Properties.
In the Properties pane, type a name for this panel.
Optionally, in the Properties pane, type comments and a label, if required.
For an existing script, locate the panel you want to replace, and access the panel properties by doing the following:
In the tool palette, click the Toggle Select Mode tool.
Double-click on the appropriate panel.
The Panel Properties window appears.
From the panel properties tree, select Properties.
In the Properties pane, select the Replace with a Java Bean box.
The Bean Name and Jar File Name fields enable.
In the Bean Name field, type the fully qualified class name of the Java Bean to use, including package name.
In the Jar File Name field, type the name of the JAR file containing the appropriate Java bean.
This is the logical name used to associate the Java archive file in the database. If no value was provided in the Name field when uploading the Java bean, this will be identical to the file name.
When uploading a Java archive into the applications database, this value is referenced.
In the Panel Properties window, click OK.
The panel properties are saved, and the Panel Properties window closes.
Save your work.
Guidelines
Replacing panels in a script with custom Java beans is customization. Custom Java beans must be developed by knowledgeable individuals certified in Java and any other appropriate technologies. Problems with customized script are not supported. Ensure you understand return values, methods, and properties used in custom Java bean components.