This chapter covers the following topics:
The Scripting Engine is the component of Oracle Scripting that executes Script Author scripts at runtime. The Scripting Engine is essentially a collection of base Java classes that process a script, any custom code associated with the script, and script end user interactions. This component includes two interfaces: the agent interface (a forms client) or the Web interface (a Web browser).
This section includes the following topics:
The Scripting Engine processes a script in runtime, including displaying the text, images, questions and prompts in the script, interpreting the flow based on end user responses and custom code.
Scripts developed with Script Author can be executed in one of two Scripting Engine interfaces: the agent interface, a Java window launched from an Oracle business application form, and the Web interface, a sequential interpretation of a script with each panel represented by one JSP page rendered in an Oracle Applications 12 compatible Web browser.
The agent interface is used by customer service or interaction center agents, typically from within Oracle TeleSales or the Customer Support module of Oracle TeleService.
Note: Scripts can also be run in the agent interface in "standalone" mode (still from an active Oracle Applications session). However, this is recommended primarily for script testing.
The full agent user interface (UI) consists of several functional components. At the top of the UI, a toolbar appears, containing back and forward (left and right arrow) buttons.
The Scripting Engine agent interface contains panels (that may contain text and images, and that must contain at least one question per panel). These panels display in the central viewing region at runtime.
In addition, this user interface includes a progress panel. This feature displays the flow path of the current script, and answers provided for the active session. This allows an agent to have an overall view at all times of where they are in the script.
Also specific to this interface are the following:
A programmable script information area, which can contain static or dynamic content (text or timers)
A programmable shortcut button area that can display buttons containing shortcut commands (to navigate through the script to specified locations, or to associate any Script Author API)
A status bar
A programmable Disconnect button.
For suspendable scripts only, a Suspend button appears beside the Disconnect button.
This section includes the following topics:
The largest visible region is the panel display area, where agents see any panel text and question UI controls for the one or more questions programmed into the script.
The Scripting Engine application supports both a single-panel display and multiple-panel display:
Using single-panel mode, only the current (active) panel appears on the screen at any given time.
Under multi-panel display mode, the active panel will have focus, and all text and question UI controls appear as designed on the active panel only.
Panels previously visited appear above, clearly unselected (the lettering in a panel without focus is smaller and gray, similar to a menu item that cannot be selected in a typical Windows-based application).
At any given time, in multi-panel display mode, the agent can scroll up using a scroll bar located alongside the panel display area to see, and click on, previously displayed panels.
Agent interaction is required for each panel to progress to a subsequent panel. This comes in the form of interacting with the question UI control or controls displaying in the current panel. Question UI controls supported in the Scripting Engine include familiar question user interface control types that render in HTML forms: buttons, radio buttons, checkboxes and checkbox groups, dropdown lists and multi-select list boxes, text fields, text areas, and password fields.
After interacting appropriately with the one or more question UI controls on the panel, the agent must click the Continue button, except in the case where the panel UI control type is button, where the following considerations apply:
Panels whose control type is button may display one or more buttons, each of which, when clicked, can direct the script to a specific panel in the script.
Where a button-type panel contains a single button, the button display value does not have to be "Continue"; frequently, but not necessarily, that button directs the script to the next panel.
If several answer choices are defined for a button question UI control, the display value for each answer choice will display as a set of buttons, one of which can be clicked at runtime. Selecting that button will pass the value of the button to the Scripting blackboard as the selected answer, and progress you to the panel associated with the button.
Note: If the script developer uses the button question UI control type in a panel, that panel may contain only a single question.
As the agent progresses through panels in the Scripting Engine agent interface, information for each panel appears, by default, in the progress area. This information includes:
The sequence in which the panels are accessed for the current script transaction (in dynamically numbered panels, beginning from 1).
The label assigned to each panel.
The label assigned to each question in the panel.
The script end user's response at runtime (with the exception of information entered into the Password question UI type, which appears as a series of lower case x's).
The agent interface defaults to the Show Answers setting. Click the Hide Answers option (to the right of the portion of the UI that says Progress) to hide the end user's responses and only display the panel sequence and panel label.
Information appearing in the progress area (panel sequence, questions answered, and responses to each question) is retained in the scripting blackboard for the length of the scripting transaction.
To the right of the progress area, a scroll bar appears (when necessary) when the available frame is filled with data.
The Scripting Engine application supports both a single-panel display and multiple-panel display. Using single-panel mode, only the current (active) panel appears on the screen at any given time.
When using multi-panel display mode, the active panel only has focus, with all text and question UI controls clearly active. Panels previously visited for the current script session appear above, clearly unselected (the lettering in a panel without focus is smaller and gray, similar to a menu item that cannot be selected in a typical Windows-based application).
At any given time, whether the agent interface is set up for single or multi-panel display mode, the agent can scroll up through the panel information in the progress area (if necessary) using the scroll bar, and click on any panel previously displayed during the current script session. Clicking the panel brings it into focus as the active panel. The selected panel again populates in the panel display area. In multi-panel display mode, the selected panel again gains focus. In single-panel display mode, the selected panel again populates the entire panel display area.
By design, when an agent revisits a previous panel and changes the answer, if branching in the script does not change as a result of that resupplied answer, then the script will return focus to the next unanswered question.
For example, imagine a sales script in which panel one provides info on the item being offered, and asks if the customer wants to purchase. This panel has Yes and No radio buttons, and uses distinct branching. Providing a value of No in panel one takes the customer to a collection of panels to offer the customer additional values (panels fifteen through twenty). Providing a value of Yes in panel one uses a series of panels with default branching to collect customer information. Panel two collects the customer's name, panel three collects an address, panel four collects a phone number, and panel five collects a shipping method. If at panel five, the customer decides to have the item shipped to a work address instead of the home address he provided, then the agent can click on panel three and enter the revised address. When the agent clicks continue, the script will then display panel six.
However, if the customer changes his mind and decides not to order, then the agent can click on panel one and click No. In this scenario, the initial flow taken through the script is changed. Panels two through five disappear from the progress area, and panel fifteen is now the active panel in the panel display area.
Note, however, that if the Footprinting and Answer Collection options in the global properties for this script were enabled, that all panels visited (including panels two through five) are still collected in the footprinting information, and will be available for reporting.
Optionally, information may be associated with a script in the area known as the script information area. The script information area can accommodate up to nine separate pieces of information (a string of text or a timer), including a label for each. These fields can contain dynamic information using Scripting APIs. Any information in the script information area is associated as a global script property.
The script information area appears at runtime above the panel display area. If a script does not have information associated with the script information area, this area is empty at runtime.
The script information area was formerly known as the static information panel. The name has changed to reflect the ability of this feature to contain dynamic information. For example, if using timers, you can dynamically enable or disable timers based on conditions programmed into the script, or define buttons (in the shortcut button area) that users can click to enable or disable the timer. Best Practice Java methods supporting this ability (startTimer, stopTimer and resetTimer) are documented in Oracle Scripting Developer's Guide.
The shortcut button area appears at runtime in the Scripting Engine agent interface immediately above the panel display area, and below the script information area. If a script does not have buttons defined, the button bar is empty at runtime. If shortcut buttons are defined, they appear in this area.
Shortcut buttons are so named because they are most often used to "jump" the script end user from the current panel to a specified group elsewhere in the script. To successfully program this function, the script developer must associate a Java command referencing the shortcut with the shortcut button (as a global script command), and associate that shortcut name to the destination group in the script.
However, shortcut buttons are not limited to the shortcut functionality. A shortcut button can be associated to any Script Author command (Java, PL/SQL, Forms, etc.), and thus can be used to invoke any API to do any type of processing at runtime. Other common applications of the shortcut button include launching a Web browser window (set for a specific URL), launching a specific Oracle Form for Forms-based Oracle Applications, or enabling or disabling script timers in the script information area.
The function, display content, and tool tips for buttons are global script properties. In the Scripting Engine agent interface, the shortcut button area appears in every session of that script. Button properties are configured using the Shortcut Panel in the Script Author script properties window.
The following functionalities are documented in Oracle Scripting Developer's Guide:
The jumpToShortcut API
Best practice Java methods enableButton and disableButton, which provide the ability to enable or disable buttons in the shortcut button area.
The procedure to define a shortcut button to launch an Oracle Form.
The procedure to define a shortcut button to open a Web browser window.
A Disconnect button appears on the bottom right of the Scripting Engine window. In Script Author, when you provide the WrapUpShortcut name to the Shortcut property of a group on the root graph, you create a destination to which the script end user is routed when the Disconnect button is clicked at runtime.
If the group contains one or more panels, the first panel in the group appears to the end user immediately after clicking the Disconnect button. You can use panels in this group to capture information from each customer at the close of the script transaction. Typically, if the group contains one or more panels, it is referred to as a Wrap-up group.
If the group contains no panels, and is properly branched to a Termination node on the root graph, then the result at runtime of clicking the Disconnect button is to immediately terminate the script, following the syntactic rules of Oracle Scripting for a complete transaction. Typically, this is referred to as a Disconnect group.
Scripts created using the Script Wizard automatically contain a Disconnect group that is properly terminated, and that contains no panels. This is the only group created by the Script Wizard tool.
For graphical scripts only, if you click the Disconnect button at runtime, and receive an Invalid Shortcut Exception message, the most likely cause is that a destination has not been provided for this shortcut. In other words, a group has not been assigned the WrapUpShortcut shortcut name. In this case, return to Script Author and add this property to a group. Ensure the group is properly terminated (both within the group, and on the root graph).
For suspendable scripts, a Suspend button may appear on the bottom right of the Scripting Engine window, just to the left of the Disconnect button
At runtime, when you click the Suspend button in the agent interface, the script transaction ends. All information from the current script session in its current state is recorded in the database as a suspended script transaction. This transaction is associated with a scripting transaction ID.
When you resume that session in the Scripting Engine agent interface, all state in the script is restored:
The last answered panel appears.
All blackboard answers recorded in the suspended transaction are restored to the scripting blackboard (temporary, dynamic memory).
The state of the shortcut button area is restored to its state at the time the transaction was suspended.
All commands (Java, SQL, Forms, Blackboard, Constant) are re-executed upon resumption.
Display of the Suspend button is controlled in three different ways:
IES : Display Suspend Button on Script Frame system profile (defaults to True).
Suspendable script property (a global property of the Script Author script). Whether created using the Script Wizard or a graphical script, this feature defaults to True.
The global PL/SQL variable GLOBAL.IES_DISPLAY_SUSPEND_BUTTON, used by integrating applications to control display of the Suspend button.
You should only suspend a script if using a business application that provides a method to resume the transaction. At this time, the only application that includes this function in its user interface is Oracle TeleSales (the eBusiness Center).
A toolbar appears at the top of the Scripting Engine window. From here you can navigate back to previously visited panels using the first tool on the toolbar, the Previous panel button. If you have backtracked in a script, you may move forward in the same path one panel at a time using the Next panel button, or skip to the last panel thus far visited using the Last panel button. You may also pop a Web browser using the Toggle Browser button (the same browser used to launch Oracle Applications appears in a separate window by default). The Help button is not implemented.
The Web interface supports obtaining survey data, feedback or opinions from customers who respond to a survey questionnaire. The survey questionnaire is a Script Author script executed as a series of JavaServer pages in a Web browser.
This user interface includes only panel display and number of Oracle Scripting buttons in the Web browser window. There is no progress area, script information area, button bar, or Disconnect button.
Unlike the agent interface, the Web interface does not support multi-panel display mode.
A special Oracle Scripting toolbar appears above the panel display, which contains the following buttons: Back, Save for Later (this button appears only for suspendable scripts in suspendable survey campaigns), Reset to Default, and Next.
Users can use the Oracle Scripting Back button to visit previous panels, and change answers if desired.
Users can use the Reset to Default button to reset each field of the currently displayed panel to either the default value (or blank) for the field or, if the panel was previously displayed and values entered, the last value entered.
Setting up Scripts for the Web Interface
To execute a script in a Web browser, users can access a survey URL. To obtain a valid survey URL, a survey administrator must perform a number of extra setup procedures. In summary, these are:
Set up a survey campaign
Associate the script with the survey campaign
Optionally identify JSP components known as survey resources
Define a cycle and deployment for the survey campaign
Activate the deployment
For more details, see the Oracle Scripting Implementation Guide.
Running Scripts Through the Web Interface
Survey data can be solicited by sending out e-mail invitations and reminders, leveraging Oracle Marketing's list management capabilities and Oracle One-to-One Fulfillment's e-mail template, data field merging, and delivery capabilities. These are known as targeted or list-based survey deployments.
Survey data can also be solicited by links on an enterprise Web site.
Finally, survey data can be solicited by customized links on self-service Oracle Application user interfaces such as Oracle iSupport.
Each of these models relies on a survey URL that defines the Oracle Applications instance, and identifies (at minimum) survey campaign and deployment identification code (dID) parameters. Other potential parameters in the URL include a respondent identification code (rID, which associates an individual with a list record), and any custom parameters to pass information into the Scripting session for evaluation and use during the interaction. Accessing this URL launches the script in the Scripting Engine Web interface.
The Scripting Engine interprets the respondent's responses to questions in the script, processes the script, and executes any custom code, passing metadata and instructions to the Web browser to be interpreted on the respondent's client computer.
The components of the Web interface are as follows:
Panel Display Area
A toolbar containing Back, Reset to Default, Next, and optionally, Save for Later buttons
For more information about these components, see Scripting Engine Web Interface Component Details.
For more information about using the Back, Next, and Save for Later buttons, see the following topics:
This section describes the panel display area and the buttons that appear in the Web interface, and the general usage of each button.
In the Web interface, the panel display area shows the current panel only. Typically, you answer the questions in the panel, then click one of the Oracle Scripting buttons, such as Back or Next, to progress through the script.
The Back button enables you to go back to the previous panel in your script flow. This button is disabled if the displayed panel is the first in the script.
The Save for Later button only appears for scripts running in suspendable survey campaigns. Clicking the button causes the script to be suspended.
The Reset to Default button allows you to discard the answers entered so far in the panel during the current session. If this is the first time that any answers have been entered in the panel, when you click Reset to Default, each field of the panel is set to a default value or blank; for all other cases, the fields are set to the last answers entered in a previous display of the panel.
The Next button is the standard mechanism used to progress through the script. Answers entered on the panel are sent to the Scripting Engine, which processes them, and determines the next panel to display.
To be able to suspend and resume a survey campaign script, both the script and the survey campaign must have been set up as suspendable.
Note: The facility to suspend and resume Oracle Scripting transactions in the Web interface applies mainly to targeted surveys. Oracle applications that launch standard surveys may implement the facility to allow users to suspend and resume scripts launched from those applications.
Suspending a Survey Campaign Script
When you run a script that has been set up in a suspendable survey campaign, the Web interface includes a Save for Later button.
At any time during the Web interface scripting session, you can click the Save for Later button to suspend the script. Any changes you have made on the displayed panel at that point are saved, but not submitted to the Scripting Engine.
There are two further cases where Oracle Scripting suspends a survey campaign script:
Timeouts
If a survey campaign script times out, it will be automatically suspended.
"Always Suspend" Survey Campaigns
Generally, when you reach the end of a script, the script is marked as complete and cannot be suspended subsequently
A survey campaign can be set up with the "Always Suspends" attribute. When you run a script in such a campaign, every termination of that script, whether you time out or reach the end of the script, results in the script being suspended.
In both of these cases, as with the manual case where you click Save for Later to suspend your script, your script answers are saved, but not submitted to the Scripting Engine.
Resuming a Survey Campaign Script
In general, Oracle Scripting has the facility to resume at one of the following panels:
The panel of the survey where the script was suspended
The first panel of the survey: this is to allow you to review and possibly update the answers given previously
The last panel reached in the previous session
Note: Frequently, the last panel is also the panel where the session was suspended. However, in the session where the survey was suspended, the script user could have navigated backwards from the last panel and suspended the survey with an earlier panel displayed.
The resume options available to users depend on how the Oracle application that controls script launching has been set up.
Respondents of a suspended target survey can resume the survey by clicking the same URL that they used to launch the survey originally. Oracle Scripting will present them with a page that displays the date and time that the survey was suspended, and ask if they want to resume the survey from where it was suspended or to start the survey afresh from the beginning.
There are several applications of a script in this interface. In all cases, the primary purpose is to exchange information between parties.
If the purpose is strictly to gather information or opinion, scripts can be executed as online survey questionnaires. In this case, the survey URL is provided to potential survey respondents.
Integrating with Oracle Marketing and Oracle One-to-One Fulfillment, information can be surveyed from a known survey sample (a targeted audience, as represented by a list in Oracle Marketing). This is known as a targeted survey, and requires additional administration steps, as documented in Oracle Scripting Implementation Guide. In this case, all list members (and only list members) are potential survey respondents. If multiple lists are used, each is implemented as a separate deployment.
When scripts are enabled from an Oracle self-service Web applications, they are typically known as Web scripts. This requires modification of the application user interface to embed a valid survey URL.
Execution of a script in the Web interface requires an active, authenticated Oracle Applications session. If the user is already logged into an Oracle Web-based self-service application such as Oracle iSupport, authentication information for the current session is used. If invoking this URL by responding to an invitation or reminder, or by clicking on a link from the polling enterprise's Web site, an Oracle Applications session is initiated over the hypertext transfer protocol (HTTP), using an applications-level guest user login.
Survey resources are files that can display during execution of a script in a Web browser. Header section and footer section pages display on each panel, if included in the survey campaign requirements. The error page or final page resources display upon server-side error conditions, or after the last panel is displayed, respectively.
Scripts are executed in the Scripting Engine Web interface using one of two technology stacks: the deprecated Oracle CRM Technology Foundation (JTT) technology stack, and the new Oracle Applications Framework technology stack. The tech stack executed at runtime is determined by the base tech stack option (a survey campaign level requirement) established by the survey administrator. There are some differences in survey resources and requirements.
For scripts executed in a Web browser using the JTT tech stack, resources are JavaServer Pages (JSP) files. These campaigns require header page, error page, and final page resources. Footer page resources are the only optional resource.
For scripts executed in a Web browser using the OA Framework tech stack, header and footer pages are optional. If you do not designate one, it simply will not be included at runtime.
If you do not designate error or final page resources, a default resource will be provided by the application at runtime, when appropriate. You can also designate a URL redirect for a final page or error page resource.
In order to assign survey resources to a survey campaign, they must first be defined. Survey resources are defined in the Survey Resources tab of the Survey Administration console.
After they are defined, you can assign a survey resource to a survey campaign for execution in the Scripting Engine Web interface. The assigned resources display (as appropriate) at runtime for all active deployments in that survey campaign.
Survey resource administration and survey campaign administration are detailed in Oracle Scripting Implementation Guide.
When defining error and final page survey resources for use with OA Framework technology stack survey campaigns, survey administrators can designate the resource type as URL For Redirect. When a fully qualified URL is invoked at runtime, the Scripting Engine redirects the browser to that URL (either when an error occurs, or at the end of the script, as appropriate).
The following key/value pairs are appended to the URL when the redirect page is called:
| Information | Key | Applicability |
|---|---|---|
| Error information | ERR | For error pages only. |
| Deployment ID | dID | Error and final pages. |
| Transaction ID | tID | Error and final pages. |
| Respondent ID | rID | For targeted surveys only. Error and final pages. |
If the valid URL to which the URL For Redirect survey resource points is a JavaServer Page, the JSP developer can include code within the JSP page to read the parameters passed by the Scripting Engine, and incorporate that information in the display elements of the page.
The main script objects are the panels, and both the agent and Web interfaces display the script panels, though in slightly different ways. For survey respondents using the Web interface, the script content in each HTML page equates to the panel display area for the agent interface.
The Web interface does not contain the progress area, script information area, shortcut button area, suspend button, or Disconnect button, nor the toolbar associated with the agent interface.
The Web interface displays a toolbar with the following buttons: Back, Next, Reset to Default, and, optionally, Save for Later..
The Web interface uses optional survey resources, which have no corresponding match in the agent interface.
While the same script can be used in either interface, information programmed for the script information area or shortcut button area will be ignored in the Web interface. Any wrapup group should be included in the flow of a script intended to be executed in the Web interface, since there is no Disconnect button to jump to that group. Any jumps to groups containing specific functionality should be accomplished with custom code, since survey respondents will not have shortcut buttons to accomplish this purpose.
This section includes the following topics:
Interaction Center agents typically have access to at least one business application from which scripts are executed. Thus, generally, agent users are required to be members of the enterprise database and may require membership in a resource group with a sales role (necessitating importation and group administration using CRM Resource Manager). Therefore, it is recommended that you perform all three user creation and administration tasks for agent users.
Self-Service Web application users typically execute a script by selecting a survey URL link added to the customized Web application. Thus, they gain access to an Oracle Applications session prior to executing the script (when logging into Oracle Applications to use the integrated self-service Web application). From an Oracle Scripting perspective, these users have no special requirements (roles, responsibilities or functions) outside of those required for the self-service Web applications.
Users of the Scripting Engine Web interface who are not using self-service Web applications (survey respondents or Web script users) typically gain access to an Oracle Applications session by entering a survey URL into a Web browser. A valid survey URL provides access to a guest user Oracle Applications account that is restricted to execution of a script only. The guest user is seeded with Oracle Applications; assuming it has not been disabled, this functionality requires no additional setup.
Footprinting is the recording in the Oracle Applications database of which panels in a script transaction were visited by a script end user, in sequence, and the duration of time (in milliseconds) before the next panel is requested. Footprint data is stored in tables IES_PANEL_DATA and IES_FOOTPRINTING_DATA in the Oracle Applications schema.
Answer collection is the recording in the Oracle Applications database of end user responses ("answers") to all answer controls ("questions") that are marked in the script as collectable. Answer collection data is stored in the IES_QUESTION_DATA table in the Oracle Applications schema.
Footprinting and answer collection are both global script properties. For any given script, these features are either on or off. These options can be viewed and set in Script Author by selecting File > Script Properties.
If enabled, footprinting data and answers are collected for each transaction or session of the script running in the Scripting Engine, in either interface.
In order for footprint data to be collected, either the Footprinting option or the Answer Collection option must be selected at the global script level. Otherwise, regardless of which specific answers are marked as collectable, information for each script end user will be discarded at the end of each script session.
Answers are only collected for questions designated as collectable. The Collectable option is a boolean property of a Script Author question, represented by a checkbox. This option is selected by default for all questions defined in Script Author. You can modify any single question so that answers provided at runtime are not collected, by clearing the Collectable option selection in the data dictionary for that question UI control.
Answers are only collected for scripts for which the Answer Collection option is selected. To prevent answers designated as collectable from being collected for all questions in a script, you can clear the Answer Collection option at the global script level. Doing so will prevent survey summary reporting capabilities for scripts with answer collection disabled.
Answer collection requires footprinting. Therefore, regardless of whether the Footprinting option is explicitly selected, footprinting data will be collected for any script with the answer collection option selected.
If the Footprinting option is selected but the Answer Collection option is not, only footprinting data for each session or transaction of that script will be saved to IES_PANEL_DATA and IES_FOOTPRINTING_DATA. If neither option is selected for a specific script, no footprinting or answer collection data is saved.
Saving footprint data whenever answer collection is enabled ensures, for each script session, a link between each response provided at runtime, and between the specific panel instance from which that response was provided. In the answer collection table (IES_QUESTION_DATA), column PANEL_DATA_ID) contains the foreign key reference to IES_PANEL_DATA (the footprinting table).