Understanding Survey Campaigns

This chapter covers the following topics:

Survey Campaign Administration Concepts

Using the survey component of Oracle Scripting, enterprises can

The data returned from surveys can then be analyzed and used to improve product lines, target new or improved services, or otherwise improve responsiveness.

The survey component of Oracle Scripting uses Script Author scripts as Web-based survey questionnaires that can be executed in a Web browser (over the Internet or on an intranet).

Note: The survey component of Oracle Scripting was previously known as iSurvey.

A survey respondent participates in a survey questionnaire by accessing a specific survey deployment URL either from an enterprise's Web site, from a self-service Oracle Application such as Oracle iSupport, or from an invitation e-mail message inviting survey participation.

The collection of requirements for conducting such an effort is referred to as a survey campaign. Survey campaigns are set up and managed from the Survey Administration console.

This section consists of the following topics:

References

Survey Campaigns Supported in Two Technology Stacks

Oracle Scripting supports two technology stacks for executing scripts in a Web browser:

When a survey campaign is established using the OA Framework technology stack, the questionnaire script, when executed in the Scripting Engine Web interface as a survey or a Web script, runs using the OA Framework technology stack.

If the technology stack for the survey campaign is Deprecated - JTT, the questionnaire script at runtime executes in a Web browser using the Oracle CRM Technology Foundation (JTT) technology stack.

Note: The technology stack assigned to a survey campaign cannot be changed after the survey definition is saved.

Oracle strongly recommends that all Oracle Scripting customers use the OA Framework functionality. The older JTT technology stack is deprecated and will be obsoleted in a future release.

Survey campaigns using the OA Framework technology stack have more options for administering survey campaign resources than for survey campaigns using the deprecated JTT technology stack, but the customer experience for executing scripts is essentially identical at runtime.

Survey Campaigns

The Survey component relies on the concept of a survey campaign: a focused effort to achieve a particular goal from a targeted population over a specific period of time for a particular business purpose. For example, an enterprise could polling a target market segment or population, analyze the data, and then act on the results.

Typical actions might include the offering of a new product or service, or a change in business processes to improve satisfaction. As part of a self-service application, a survey campaign typically measures satisfaction regarding the customer experience for that self-service application.

Survey campaign goals are achieved by two processes:

the picture is described in the document text

The top-level data structure, called a survey campaign, identifies a survey questionnaire script and global information such as which survey resources will be used at runtime.

Each survey campaign must have a questionnaire script. For more details, see Survey Questionnaires.

A survey resource is an object that displays during script execution, either as part of a page (header or footer section) or as a special page (error page or final page). Depending on the technology stack, the survey campaign may be required to have certain survey resources.

For more details, see Survey Resources.

The survey campaign has two lower level data structures or child objects: cycles and deployments:

Deployments can be grouped into cycles to execute the same questionnaire and parameters over a different timeline for comparison purposes.

Child objects can be added to existing parent objects. For example, for an active or open survey campaign, you may add a second cycle, or additional deployments.

Note: Cancelling a cycle or a deployment does not affect the parent objects.

For more details, see the following topics:

See Also

Survey Questionnaires

The survey questionnaire is a Script Author script that is associated with the survey campaign. The script must be completed, tested, and deployed to the applications database to make it available for a specific survey campaign.

The individuals participating in a survey ("survey respondents") can be:

On the end user's desktop, the user is guided through the script either through a prescribed order, or through a dynamically determined path - depending on the needs of the enterprise.

On the Apache Web server associated with the Oracle Applications instance for the enterprise conducting the survey or hosting the Web script, all business logic is executed dynamically. This includes the business rules embedded in the survey questionnaire script (such as rules-based branching, data integration, and commands associated with specific objects and events), the end user's answers, and any custom Java or PL/SQL code.

Cycles

Each survey campaign must have at least one cycle. It may have as many as required.

A cycle is a small collection of requirements for grouping deployments for the purpose of result reporting and analysis. Should an enterprise have a need to compare survey data for the same set of questions for a similar group of respondents (the sample) over different time periods, it can execute two separate cycles, and then compare reporting information from each successful deployment by comparing the cycles.

Cycles are defined in the Survey Administration console for any open, active, or idle survey campaign.

Deployments

When you run a survey, you actually execute a survey deployment. Each survey cycle must have at least one deployment. It may have as many as required.

For all deployments, you must provide information about execution dates for the survey campaign, and, depending on deployment type, you may be required to specify other details.

There are two types of deployment:

For more details about deployments, see the following topics:

See Also

Common Deployment Components

Each deployment requires:

Targeted Deployment Components

For list-based deployments only, you must provide:

If using reminders in addition to invitations, you must also provide:

Statuses for Survey Campaigns and Deployments

This section consists of the following topics:

Survey Campaign Statuses

Status Description
Open When it is initially created, a survey campaign is open and remains in this state until the first deployment is activated.
Active When any deployment is activated, the parent survey campaign status changes from Open to Active. Once Active, a survey campaign status may change to Idle only. Its status never returns to Open, nor can it be set to Closed prior to changing to Idle.
Active is only valid from the Open or Idle status.
A survey campaign status cannot be manually set to Active by the survey administrator; this status is established by the system based on these business rules.
Idle A survey campaign status is Idle if at least one of its deployments was activated in the past (the survey campaign status was previously Active and the deployment status was previously either Pending or Active), but the survey campaign currently has no active or pending deployments.
Idle is only valid from the Active status.
A survey campaign status cannot be manually set to Idle by the survey administrator; this status is established by the system based on these business rules.
Cancelled If a survey campaign status is Open (after it is created), but has either had no deployments defined or has had no deployments activated, the survey campaign status can be set to Cancelled, indicating that its purpose is no longer relevant. Once cancelled, no updates can be made to the survey campaign or any of its children objects (cycles or deployments).
Cancelled is only valid from the Open status.
Only a survey administrator can change the status of an open survey campaign to Cancelled.
Closed If the status of a survey campaign is Idle (if it currently has no active deployments), and its deployments have been successfully run for the intended duration, the survey campaign status can be set to Closed, indicating that its purpose was fulfilled. Once closed, no updates can be made to the survey campaign or any of its children objects (cycles or deployments).
Closed is only valid from the Idle status.
Only a survey administrator can change the status of an idle survey campaign to Closed.

When a survey campaign is created, and prior to defining a deployment, the status of the survey campaign is Open. You can view the status from the Survey Campaigns page. For open survey campaigns, you can change the status from the Status list by selecting Cancelled from the list. This invalidates the survey campaign definition, ensuring it can no longer be used.

Unless you explicitly change the status of a survey campaign after creation, it remains Open until a child deployment is activated. Once a deployment is activated, the parent survey campaign status changes to Active. A survey campaign remains active as long as at least one of its deployments has the status Active or Pending. Once the survey campaign is active, the survey campaign status can become Idle, and can change from Idle to Cancelled or Closed. Cancelled and Closed statuses only result from manual intervention by the survey administrator. The status of an active survey campaign can automatically change to Idle based on events related to its deployments. For more information, see Deployment Statuses.

Once all the deployments for a survey campaign have executed successfully, and the survey campaign status is Idle, you can close the survey campaign from the Status list by selecting Closed from the list. Once a survey campaign is closed, no properties of the closed survey campaign, its cycles, or deployments, can be changed. Return data remains available for viewing responses, or from Oracle Business Intelligence, and survey reports can be executed for analysis of survey returned data.

Cycles are defined from the Survey Campaigns tab of the Survey Administration console for any open, active, or idle survey campaign. As with all information entered into the Survey Administration console, the cycle name should follow any existing predefined survey campaign requirements provided to the survey administrator.

Deployment Statuses

Status Description
Open The deployment status is Open when the deployment is initially created and remains in this state until activated by the survey administrator.
Pending When a targeted deployment is activated, if the deployment date and time are in the future, its status changes from Open to Pending. The deployment remains in this state until the deployment start date and time equal SYSDATE.
At this time, the SUBMIT GROUP FM REQUEST FROM IES concurrent program executes, causing the fulfillment request to be submitted to the fulfillment server. Upon a successful submission of the fulfillment request, the deployment status changes to Active.
Pending is only valid from the Open status, and applies only to targeted deployments
Error Error status indicates that the concurrent program generated an error while attempting to submit the fulfillment request to the fulfillment server. This status does not include errors that occur after the fulfillment request is successfully sent to the server.
If problems occur that prevent invitation or reminder e-mail messages from being sent, the deployment status remains Active, and fulfillment debugging should commence by a fulfillment administrator from the Oracle One-to-One Fulfillment administration console.
Error is only valid from the pending status, and applies only to targeted deployments.
Active The status of a standard deployment is Active immediately after it is activated by the survey administrator.
The status of a targeted deployment is Active when the deployment date and time equal SYSDATE, and the fulfillment request is successfully sent to the fulfillment server by the concurrent program.
Note that Active status for targeted deployments does not indicate successful delivery of invitation or reminder e-mail messages.
Cancelled If the deployment status is Open, it can be manually set to Cancelled, indicating there is no more need to execute this set of requirements. After being cancelled, a deployment cannot be executed.
Cancelled is only valid from the Open deployment status.
Incomplete If the deployment status is Active, but there is a no interest on the part of the surveying enterprise to view the results, the deployment status can be set to Incomplete.
Closed If the deployment status is Active, and the deployment has run for its intended duration or has resulted in sufficient responses, the deployment status can be set to Closed, indicating that the survey campaign purpose was fulfilled. You can also change the status of deployments from Pending or Error to Closed.

Once a deployment is created, and before it is activated, its status is Open. You can view the deployment status from the Survey Campaign Details page or from the Deployment Details page. From either of these pages you can also change the status of an open deployment by selecting Cancelled from the status list. This invalidates the deployment definition, ensuring it can no longer be used.

The only way to change the status of a standard deployment to Active is to activate it from the Deployment Details page. The Deployment Details page will refresh, with the status set to Active and a valid survey hyperlink displayed. This is true whether the deploy date is in the past or the future.

The only way to change the status of a targeted deployment to Pending is to activate it from the Deployment Details page. If the deployment date and time are in the future, the status becomes Pending, and it remains in that state until the current date, SYSDATE, occurs. If the deployment date and time are in the past, the concurrent program will attempt to submit the fulfillment request to the fulfillment server immediately. Upon successful submission of the fulfillment request to the server, the deployment status changes to Active. For targeted deployments, the deployment details does not display a survey URL, since respondent identification numbers for each list member are required.

Once a deployment is activated, and before the deployment end date is reached, its status can change from Active to Closed or Incomplete. Do this from the deployment details page.

For targeted deployments, after the deployment is activated, it may contain either a status of Pending (indicating that it is activated and the concurrent request is in the queue or its start date is in the future), Active (indicating that the concurrent request completed successfully), or Error (indicating that the concurrent program generated an error while creating and sending the fulfillment request). Deployments with a status of Error can be modified so that the error can be corrected, and when reactivated will again display a Pending status. Targeted deployments can also contain a status of Closed or Incomplete, following the same guidelines described earlier for standard deployments.

Error status cannot be set manually. This status, for targeted deployments only, indicates that the concurrent program generated an error while attempting to submit the fulfillment request to the fulfillment server.

Status Considerations for Targeted Deployments

For targeted survey deployments, once a survey deployment is activated, you must wait until the fulfillment engine completes its activity (completes the fulfillment request and succeeds in sending the invitation master documents to the outgoing mail server specified in Oracle One-to-One Fulfillment) before you will have respondents. The concurrent request ID is listed on the Deployment Details page when displayed in the Deployment view, and can be used to track the concurrent request and its status.

Survey administrators who have also been assigned the JTF role JTF_FM_ADMIN are able to view the status and history of fulfillment requests from the Invitations tab of the Survey Administration console.

Note: Granting JTF roles requires the grantor to be assigned the JTF system administrator role, JTF_SYSTEM_ADMIN_ROLE, in addition to whichever other JTF role you want to assign. For this purpose, if required, you can use the seeded SYSADMIN Oracle Applications user account. For more information, see the section Understanding Users Required for Implementation in Oracle Scripting Implementation Guide.

When viewing status, a request status of Submitted indicates that the list was successfully sent to the fulfillment engine.

An outcome code of Success indicates that the fulfillment server was successful in sending the invitation (or reminder) master document.

For any other outcome code (e.g., Partially Successful or Failure), you will need to log into the Fulfillment Administration console to resolve. In this scenario, list members must receive and respond to an e-mailed invitation before you can expect activity for this deployment.

To access the Fulfillment Administration console, a user must be assigned the JTF_FM_ADMIN role and the One-to-One Fulfillment Administrator responsibility. Consult with an Oracle One-to-One Fulfillment administrator if required.

Effects of Setting Deployment to Closed

Immediately upon changing a deployment's status from Active to Closed, the status for its parent survey campaign changes from Active back to Idle, if there are no other active or pending deployments. The survey campaign status will remain Active if other deployments have been activated and have not encountered an error.

With survey campaigns for which all deployments have been closed, you can close the survey campaign, or create another cycle or deployment if you wish to receive more responses for this survey campaign.

Closing a survey campaign or deployment signifies that the requirements or objectives for that object have been met. No new information can be received from a closed survey campaign or deployment.

From the Survey Administration console, responses can still be viewed for closed deployments.

Survey reports can still be viewed for closed deployments.

Effects of Setting Deployment to Incomplete

Once you designate a deployment as Incomplete, if there are no other active or pending deployments, the parent survey campaign status changes to Idle, and can be set to Closed unless you wish to create new cycles or deployments to obtain additional responses.

The Incomplete deployment status indicates that the requirements or objectives for the deployment are no longer relevant. No new information can be received from a cancelled deployment. While responses and reports can be viewed for this deployment, the information generated by reports is likely to be incomplete.

Survey Resources

Survey resources are objects defined as part of a survey campaign that display for scripts at runtime to users of the Scripting Engine Web interface.

Each survey campaign can include up to four survey resources. Each survey resource has a display type, that controls how the resource is used during script execution.

The survey resources, and their corresponding display types, are as follows:

Survey Resource Display Type
Header section Section
Footer section Section
Error page Page
Final page Page

At runtime:

If assigned to a survey campaign, header section and footer section survey resources appear at the top and bottom of each page of the script, respectively.

An error page resource displays upon any server-side error condition.

After the Scripting Engine processes the last panel in the flow of a script, a final page resource displays, or the user is redirected to a URL designated as the final page.

Error and final pages do not display header or footer section resources.

This section consists of the following topics:

Survey Resource Types and Technology Stacks

The definition and use of survey resources depends on the technology stack.

Note: The survey resources you define for one technology stack cannot be used for the other.

Survey Resource Types

There are three survey resource types:

The survey resource type and the technology stacks in which they can be used appear in the following table:

Note: In the survey resource topic descriptions, the standard and alternative names for each survey resource type are used interchangeably.

Survey Resource Type Alternative Survey Resource Type Name Technology Stack Supported Section Display Type Supported? Page Display Type Supported?
Deprecated - JSP JavaServer Page (JSP) Deprecated - JTT Yes Yes
HTML File Upload HTML file OA Framework Yes Yes
URL For Redirect URL OA Framework No Yes

Survey Resources and OA Framework

The OA Framework technology stack supports two types of survey resource:

Using the OA Framework technology stack, you do not have to define survey resources:

Survey Resources and JTT

When using the Deprecated - JTT technology stack, all survey resources are JSP - HTML or redirect survey resources are not supported.

You must define the following survey resources for each survey campaign set up in the Deprecated - JTT technology stack:

The footer section is optional.

See Also

Survey Resource Administration

You define survey resources, and assign them to survey campaigns, in the Survey Administration console.

Survey resources consist of two components:

This section consists of the following topics:

Survey Resource Definitions

When you define a survey resource, you create a database object that points either to a physical file (HTML or JavaServer Page, based on technology stack), or a URL (for error page or final page survey resources, supported for the OA Framework technology stack only).

Physical Files and URLs

The second component of a survey resource is the physical file itself. It corresponds to the logical definition of the survey resource, and must be available at runtime.

Physical survey resource files must be created by certified, knowledgeable HTML or JavaServer Page developers.

Note: The creation of survey resources is outside the scope of Oracle Applications.

The location of the physical survey resource file at script execution time depends on the survey resource type and the technology stack:

OA Framework Survey Resources

For survey campaigns defined in the OA Framework technology stack, survey resources are either URLs for redirect or hypertext markup language (HTML) files. Both .HTM and .HTML file types are supported (regardless of case). JSP survey resources are not supported for this technology stack.

For OA Framework survey campaigns, error page or final page survey resources can also be URLs accessible to the Web server at script runtime, which redirect the script end user to the specified URL during an error or upon completing the script, respectively.

OA Framework survey campaigns do not require survey resources to be referenced at runtime, although any survey resources that are referenced must first be defined. For more information, see Survey Resources and OA Framework and Using Default OA Framework Survey Resources for Implementation Testing.

A typical implementation sequence would be:

  1. You define the survey resource; during the survey resource definition, the physical HTML file corresponding to the OA Framework survey resource is uploaded to the database.

  2. You create survey campaigns that reference the survey resources.

  3. You can change survey resources used by a survey campaign at any time until the survey campaign is canceled or completed.

    Note: If defining a static HTML page as an error page for OA Framework survey campaigns, you can also require error information to display on top of the error page by selecting the Display Error on Top box.

Creating OA Framework Survey Resources

Creating and modifying the physical HTML files that serve as survey resources for OA Framework survey campaigns are not accomplished from within the Survey Administration console.

Creation of the physical files for use as survey resources is outside of the scope of Oracle Applications. You can, however, upload HTML files intended for use as survey resources from the Survey Resources tab, at the time of survey resource definition. HTML survey resources are stored in the applications database and available to any survey campaign in the same environment that references the survey resource at the survey campaign level.

JTT Survey Resources

The physical survey resource files for JTT survey campaigns must be saved in JavaServer Page (JSP) format (with a file extension of .JSP), even if they contain no dynamic content.

Header section, error page, and final page survey resources must all be referenced upon creating a JTT survey campaign. Footer section survey resources are optional.

Survey resources used for JTT survey campaigns can be defined (including the file name of the physical survey resource) and referenced in a JTT survey campaign before the physical file exists, and before it is uploaded to the applications tier. However, the physical JSP files referenced by their corresponding survey resource definitions must be uploaded to the $OA_HTML directory on the applications server prior to execution of the script referenced in a survey campaign at runtime.

In support of JTT survey campaigns, four test JSP files are seeded in the appropriate directory on the APPL_TOP, and may be used to test survey functionality. Although these test survey resources exist in the $OA_HTML directory, as with all survey resources, they must still be defined prior to use.

No seeded footer survey resource sample is included with Oracle Applications. For test purposes, you can reference a header survey resource in the Footer Section field, to ensure it displays as appropriate at runtime.

For more information, see Seeded JSP Survey Resources.

Creating JTT Survey Resources

Creating, modifying, and uploading the physical JSP files that serve as survey resources for JTT survey campaigns are tasks outside of the scope of Oracle Applications.

Physical survey resource files must be created by certified, knowledgeable JavaServer Page developers, and uploaded to $OA_HTML on the applications tier of the applications server by a system administrator or other individual with the appropriate privileges and access to the APPL_TOP.

However, as described in the section Test Survey Resources, four test JSP survey resource files ship with Oracle Applications, seeded in the appropriate directory ($OA_HTML) on the applications server. You can use the four test survey resources to test your implementation of JTT survey campaigns, and to serve as building blocks, modifying copies of these files for your own use as appropriate.

Note: JSP files must be tested on an existing Web server to view appropriately.

Note: Like all customizations, any modifications you make to survey resources are not supported by Oracle.

Note: Oracle recommends using individuals certified in Java development and JavaServer Pages technology to create or modify JSP survey resources.

Usage of Survey Resources in Survey Campaigns

Once defined, survey resource definitions persist; the same survey resources can be used by any number of survey campaigns (of the same technology stack) without limit.

Any survey resource that you want to reference when creating a survey campaign must be defined before you create the campaign.

You can change any survey resource associated with an open or active survey campaign after survey campaign creation.

General Survey Resource Considerations

This section consists of the following topics:

Including Graphics in Survey Resources

Survey resources, like any other HTML or JSP page, may include images and hyperlinks. Survey resources must be located in the $OA_HTML directory on the applications server to use at runtime. Any objects (such as GIF or JPG images) referenced in a survey resource page must also be available to the application server at runtime.

Using Default OA Framework Survey Resources for Implementation Testing

If you do not associate custom survey resources for a survey campaign using the OA Framework base technology stack, no header or footer sections will appear for HTML pages representing panels. In addition, a default error page and final page will appear at the appropriate time (upon error, or after visiting the last panel in a script). Omitting the section survey resources, and utilizing the default page survey resources, provides a method to verify that survey resources are appropriately displayed upon execution of a survey campaign deployment using the OA Framework technology stack.

At the same time, you are provided with a layer of abstraction in regard to the need to ensure the product is performing as expected without needing to test the creation of tailored HTML pages. Subsequent to successful execution of a script in a Web browser with all appropriate panel content and default survey resources displaying, you can assign custom survey resources to an OA Framework survey campaign and retest.

Seeded JSP Survey Resources

Survey resources must be defined in the Survey Administration console and must map to existing JSP documents residing on the server (as described in the Uploading JSP Survey Resources section of Oracle Scripting Implementation Guide).

For survey campaigns in production, you will probably want to create your own survey resources. For testing and implementation verification, you may want to use the survey resources seeded with Oracle Applications.

Test Survey Resources

Test JSP survey resources, identified in the table below, ship with Oracle Applications beginning with IES MiniPack OracleG, and available with any Rapid Install from release 11.5.5 and later. These survey resources are physically located in $OA_HTML on the applications server.

Survey Resource File Name
Header section IESSVYTESTHEADER.JSP
Error page IESSVYTESTERROR.JSP
Final page IESSVYTESTTHANKU.JSP
Hosted survey error page IESSVYMENUBASEDTESTERROR.JSP

Note that there is no seeded footer section survey resource. For testing purposes, to ensure a footer will appear as expected in a production environment, you can use another JSP page (for example, the seeded header section).

This section consists of the following topics:

Using Test JSP Survey Resources for Implementation Testing

Utilizing these test survey resources provides a method to verify that survey resources are appropriately displayed upon execution of a survey campaign deployment using the JTT technology stack in an HTML user interface. At the same time, you are provided with a layer of abstraction in regard to the need to ensure the product is performing as expected without needing to test the creation of tailored JSP pages. For this purpose, for JTT survey campaigns it is recommended that you first test execution of scripts in a Web browser using seeded test survey resources listed earlier, to ensure successful implementation. Subsequent to successful execution of a script in a Web browser with all appropriate test survey resources displaying, you can change the survey resources assigned to a survey campaign to use customized survey resources.

Additional JSP Error Page Survey Resource for Hosted Surveys

Header section and final page seeded JSP survey resources are intended for use with standalone and menu-based survey deployments for JTT survey campaigns. The IESSVYTESTERROR.JSP error page is specifically intended for use with standalone deployments. For hosted scripting operations (self-service Web applications such as Oracle iSupport, or other self-service Web applications customized to provide access to scripts executed in a Web browser), the IESSVYTESTERROR.JSP error page should be used.

To test a hosted scenario, you can use any JSP header section (or HTML page saved in JSP file format). Again, you can use the seeded test header section to test footer section functionality as well. Error and final pages must also be in JSP file format. The error page must adhere to the hosted template. There are two ways to handle the final page:

  1. Define as the final survey resource page the JSP page which displays the list of URLs to take the survey. In this way, when the survey is completed, the respondent will be returned to the starting page.

  2. Define another JSP page as the final page survey resource, but include in that page a JSP forward command to point the user back to the page that displays the list of URLs to take the survey.

Sample Code for Test JSP Header Section Survey Resource

Following is the source code for the sample test JSP header section.This sample is provided for informational purposes only. Oracle is not responsible for the correct implementation of JSP in your environment, and does not provide support for customized survey resources. Consult appropriate HTML and JSP experts for more information.

<!-- $Header: iessvytestheader.jsp $ -->

<table align=center border=0> <tbody> <tr> <td>&nbsp;</td> <td class=pageTitletcolspan=4 noWrap>Test Header Section</td> <td>&nbsp;</td> </tr> </tbody> </table>

Survey Campaign Setup Examples

The primary reason to create more than one deployment is to use different lists, since lists are associated at the deployment level. Thus, a cycle with several deployments may be executed over the same time period but with different lists. These deployments would then be executed by different audiences over the same period of time.

The practical reason to create more than one cycle for a single survey campaign is to execute the same deployment (or set of deployments) over a different period of time.

As an example, company ABC decides to conduct a survey campaign to measure customer satisfaction with its products. It wishes to send out the same survey questionnaire six months apart:

ABC customers are identified by three lists:

The survey will be executed in two separate time periods:

The survey administrators can choose to define two separate cycles (cycle 1 and cycle 2) as child objects of the customer satisfaction survey campaign.

In this model, each cycle represents a given time period for survey execution. Define three deployments (one for each list) for each cycle. Each deployment for cycle 1 has identical start and end dates (January through March), and each deployment for cycle 2 also has identical start and end dates (July through September). All other parameters are identical.

Alternatively, one cycle can be created to contain all deployments. In this model, the first three deployments (one for each list) contain identical start and end dates for the same period, January through March. The last three deployments for this cycle (again, one for each list) use identical start and end dates for the second period of time, July through September.

Survey Administration Console

The Survey Administration console is an HTML administration user interface through which survey campaign administrators can set up, execute, and monitor survey campaigns.

This console consists of four tabs. The tabs and the main functions that you can perform in each of the tabs are as follows:

Tab Main Functions
Survey Campaigns Administer survey campaigns, cycles, and deployments.
View responses received from existing survey campaigns.
Survey Resources Administer survey resources, which are HTML or JSP files that appear as header or footer sections, error pages, or final pages for scripts executed in a Web browser.
Audience For targeted survey deployments only:

  • Perform list management supporting targeted survey deployments using Oracle Marketing.
Invitations For targeted survey deployments:

  • Perform management of Oracle One-to-One Fulfillment master documents, queries, and templates, which provide the ability to send through e-mail invitations and reminders.

References

The Survey URL

To execute a script in a Web browser, you must access a specifically constructed survey URL using an appropriate Web browser. Typically, the survey respondent clicks a hypertext link which directs the user to the first page of the survey. For targeted survey deployments, this hypertext link can be embedded in an e-mail message inviting (or reminding) the list member to participate in the Web script or survey.

This active survey URL can also be accessed by clicking a button or image, if the referring HTML page contains a hypertext link to associate the image or button with the proper URL.

This section consists of the following topics:

Generating a Valid Survey URL

When a survey deployment is activated, the survey administration function of Oracle Scripting generates a URL through which the survey deployment is accessed using the Scripting Engine Web interface.

For standard (non-list-based) surveys or Web scripts, this URL (as generated) can be used to directly execute the survey questionnaire script in an Oracle Applications certified Web browser, as soon as the deployment is activated.

The URL for targeted (list-based) survey deployments is not complete upon survey deployment activation. When the Oracle Marketing list is subsequently processed by Oracle One-to-One Fulfillment, additional URL parameters are concatenated to the system URL for each list member, to identify the unique respondent from the Oracle Marketing list. This complete URL, including respondent ID, is included in each invitation or reminder master document sent from the fulfillment server. If the Maximum Responses Per Person deployment parameter is set to 1 for a targeted deployment, this enforces uniqueness (based on the respondent ID) so that the designated list member can only execute the script in a browser once. For a specific list member, the same respondent ID is used for each instance of an invitation or reminder in a cycle.

The construction of the survey Web URL can differ based on these factors:

Survey URL Syntax

The general syntax of the survey URL is:

http://<server name>.<domain>:<Apache Web server port>/OA_HTML/<hosted, standalone, or OA survey JSP template>?<Deployment ID>&<Respondent ID>&<database connection (DBC) information for current session>

Survey URL Parameters

Survey URL Parameters for Targeted Survey Deployments

Additional information is also appended to the survey URL for targeted survey deployments only, which makes that information available to the Scripting blackboard during execution of the script.

The blackboard key names for these parameters are IES_FND_USER_NAME, P_PARTY_ID, and P_CONTACT_PARTY_ID. These values, respectively, designate the apps user ID of the current logged in user, and (from TCA) the parent party ID and the contact party ID.

The apps user ID contains the login information for the current Oracle Applications session. The TCA parameters may identify the organization or the individual contact for a selected customer record; if not available, either or both of these values could be null.

For more information, see Oracle Scripting Implementation Guide, specifically Integrating Oracle Scripting > Integration by Component > Script Author > Scripting Engine Web Interface > Targeted Deployment Integration with Oracle Marketing and TCA.

Extra URL Parameters

Before Release 12, you could freely add your own user-defined parameters to the URL, such as &customer_id=1234.

Starting with Release 12, changes to the underlying Oracle applications code require that all applications register URL parameters for extra security. By definition, user-defined parameters are not known in advance, and therefore cannot be registered by Oracle Scripting.

You can continue to create and run survey campaign scripts with user-defined parameters, but only if you set the profile option FND Validation Level to None; if the value is set to Error, and the URL contains user-defined parameters, the script will error out.

To enable survey campaign scripts to run in all cases, regardless of the value of FND Validation Level, Oracle Scripting has introduced the following 10 pre-registered, case-sensitive parameter names for you to use as extra parameters: iesK01, iesK02, ....., iesK09, iesK10.

At runtime, Oracle Scripting will save the parameter key-value pairs entered on the URL in the Scripting blackboard.

See Also

JSP Templates for Scripting Engine Web Interface Runtime Execution

Users of the Scripting Engine Web interface access scripts either as survey questionnaires, or as Web scripts:

The template used differs based on two factors: the base technology stack selected for execution at runtime, and the intended authentication for the session. Oracle Scripting currently supports the JSP templates that appear in the following table:

JSP Template Tech Stack Authentication Description
OA.JSP OA Framework For standard deployments, guest user authentication or menu-based hosting

  • Used for all survey campaigns executed in the Oracle Applications Framework technology stack.

  • Supports applications guest user login. This limits users to execution of the script in a Web browser only.

  • Supports menu-based hosting for standard deployments. This requires an authenticated Oracle Applications session. In this case, the menus from the hosting application are shown in the UI when the script is executed.
OA.JSP OA Framework For targeted deployments, guest user only.

  • Does not support menu-based hosting for targeted deployments.

  • Uses applications guest user only
IESSVYMAIN.JSP JTT Guest user only

  • Uses applications guest user login. This limits users to execution of the script in a Web browser only.

  • Used for JTT survey campaigns.

  • Default for standard deployments.
IESSVYMENUBASED.JSP JTT Uses authentication from existing Oracle Applications session only.

  • Uses menu-based hosting for standard or targeted deployments.

  • Targeted deployments for JTT survey campaigns are established by selecting Menubased in the Hosting Options (deployment details).

  • This requires an authenticated Oracle Applications session.

  • Used for JTT survey campaigns.

  • The menus from the hosting application are shown in the UI when the script is executed.

Guidelines for Survey URL Parameters

All surveys are executed at the deployment level, with each deployment in a particular instance (based on Apache port) having a unique deployment identification (dID). All respondents for a given deployment will access the same dID. For standard deployments, the dID is the last parameter in a valid URL.

Targeted (list-based) survey campaign deployments include an additional survey URL parameter: a unique respondent identification (rID) for each list member. Every list member will access the same dID, but will have a unique rID for the valid URL.

References for Survey URL Parameters

For information on adding parameters to the survey URL to pass values into the Oracle Scripting blackboard for a Scripting Engine Web interface session, see the section Passing Parameters to the Web Interface in Oracle Scripting Developer's Guide.

Survey Reports

After summarizing survey data for optimum performance using Concurrent Manager, reports on scripts executed in a Web browser can also be generated using Oracle Business Intelligence.

Custom reports can also be generated from tables in the Oracle Applications schema as desired, using tools such as Oracle Discoverer.

Prototypes

Prototype is a boolean characteristic of survey campaigns. The default for this characteristic is null (survey campaigns are not designated as prototypes unless you select this option when creating or editing a survey campaign).

Prototype survey campaigns are identical to standard survey campaigns, except that the script used as the survey campaign questionnaire is not locked. The purpose is to allow survey campaign administrators more freedom to refine requirements for survey campaigns, including modification to the script for the designated survey campaign.

The Survey Campaigns tab includes an option to exclude prototypes. Selecting this option filters prototypes out of the lists of survey campaigns displayed. This option is also null by default (prototype survey campaigns are included in survey campaign lists unless you select this box and click Go).

Although you can also put a prototype survey campaign into production, the script will not be locked. The prototype option can be selected or cleared while a survey campaign status is Open. Thereafter, you cannot change this option.

Concurrent Programs Supporting Survey Operations

Oracle Scripting uses three seeded concurrent programs to support survey component operations. Concurrent programs are executed using Oracle Concurrent Manager. Seeded concurrent programs can be scheduled to execute at certain times, or can be administered to execute in near-real time.

To schedule or execute concurrent programs supporting Oracle Scripting's survey component, you must access Oracle Forms-based applications with a user assigned the iSurvey User responsibility. This section describes in detail each concurrent program applicable to Oracle Scripting.

This section includes the following topics:

References

For information on executing concurrent programs or checking concurrent program logs, see Administering Concurrent Programs for Survey Execution in Oracle Scripting Implementation Guide.

SUBMIT GROUP FM REQUEST FROM IES Concurrent Program

When you activate a targeted deployment, a concurrent request is generated which is scheduled to run at the deployment start date and time (specified when defining a deployment). If the deploy start date and time are in the past, the concurrent program executes immediately. The purpose of this initial execution of the concurrent program is to make a request to Oracle One-to-One Fulfillment to send out e-mail invitations to the target population specified by the list.

Note: Immediately upon activating a deployment, when the deployment details page refreshes the corresponding Concurrent Request ID is visible at the bottom of the page. You can use this Concurrent Request ID to monitor the Fulfillment Request submission through the Oracle Forms-based interface associated with the iSurvey User responsibility.

If reminders are also established for this deployment, subsequent concurrent requests are also generated (one per reminder, based on the value entered into the Number of Reminders field) to execute at the specified interval (in days) as defined for the deployment. These requests will execute at the appropriate interval (start date and time, plus the number of days defined in the Reminder Interval In Days field). When the concurrent manager runs the request, it attempts to submit a fulfillment request for this survey deployment.

If the request is successful, a fulfillment request ID will be generated. This is visible from the Survey Administration console in the Deployment Detail page, immediately above the Concurrent Request ID.

After activating a deployment, wait a brief period and refresh the page to view the fulfillment request ID. If this ID is listed, the fulfillment request was successfully submitted. If not, the deployment enters the error status.

Troubleshooting

If the fulfillment request is not successful, you have the following options:

Resolving and Reactivating the Deployment

When a request fails, the deployment status changes to error status, and the Activate button is again visible. Before you attempt to reactivate the survey deployment, check the concurrent program log for information about the specific error. (For more information, see the Checking Concurrent Program Logs section of Oracle Scripting Implementation Guide.)

If the fulfillment request ID appears following a page refresh, the problem is resolved.

Manually Executing the Concurrent Program

When you activate a deployment, the required parameters are automatically passed to the function. If executing manually, you must manually enter the required parameters.

There are two cases in which this concurrent program needs to submitted manually:

  1. If the initial deployment fails.

  2. If the reminder concurrent program fails.

Follow the procedure detailed in the Scheduling or Executing Concurrent Programs section of Oracle Scripting Implementation Guide, using the parameters for the SUBMIT GROUP FM REQUEST FROM IES concurrent program as listed in the table below.

Parameters 7 and 9 below require specific values only if the purpose for manually executing this request is the failure of a previously scheduled concurrent program for reminders. Initial requests (to send out invitations) do not require these parameters.

No. Parameter Meaning Value
1 p_api_version PL/SQL API constant required by Apps. 1
2 p_init_msg_list Initializes a fresh message list prior to loading new messages. This parameter required by Apps, primarily for error tracking. Leaving this parameter null or entering the value FND_API.G_TRUE passes a value of true (yes, initialize the list); otherwise, pass FND_API.G_FALSE, to ensure the message list is not initialized. Leave parameter null (this passes a true value)
3 p_commit Tells the API whether or not to commit changes. If set to false, the concurrent manager commits the database transactions instead of the API. If set to true, the API commits the database transaction. FND_API.G_FALSE
4 p_validation_level Parameter required by Apps, to determine which validation level is required. Passing a value of 100 results in the API ensuring full validation by passing FND_API.G_VALID_LEVEL_FULL. 100
5 p_deployment_id Deployment ID for survey campaign deployment Determine the deployment ID and use it here
6 p_template_id Template ID for the invitation or reminder template used in survey campaign deployment. Determine the template ID and use it here.
f manually submitting the request, if your initial request failed, pass the ID of the invitation template. If a subsequent reminder request failed, pass the template ID of the reminder template.
7 p_reminder_type Variable to identify the request as a reminder. For initial request (invitation), null is passed. For reminder requests, the value REMINDER is passed. If your initial request failed, leave the parameter null (there is no reminder for an invitation request). If a subsequent (reminder) request failed, type the value REMINDER.
8 p_user_id User ID value derived from the Oracle Applications user account for the user submitting the concurrent request Determine the USER_ID value for the appropriate Oracle Applications user and provide it here. You need the apps password for this procedure. Steps to obtain this value:

  • Log into Forms-based applications as a user with the System Administrator responsibility.

  • Locate the record for the appropriate user.

  • With focus on the User Name field, examine the field and variable values (Help > Diagnostics > Examine). Enter the apps password when prompted.

  • In the Block field, enter USER.

  • In the Field field, search for and select USER_NAME.

  • The number in the Value field is the value you must enter as the p_user_id parameter.
9 p_reminder_hst_id If p_reminder_type parameter is set to reminder, this parameter needs to be set. Otherwise, leave this value null.
This is the reminder history ID created by the system when the original deployment is submitted.		 If initial deployment concurrent program fails, leave parameter null.
If your initial request failed, leave the parameter null (not required for invitation). If a subsequent (reminder) request failed, derive this parameter value by using the following SQL query against the database for your Oracle Scripting environment:select survey_reminder_hst_id from ies_svy_reminder_hst_v , ies_svy_reminders_v where ies_svy_reminders_v.deployment_id = <p_deployment_id> and ies_svy_reminder_hst_v.survey_reminder_id = ies_svy_reminders_v.survey_reminder_id.

Guidance

There are no prerequisites for executing this concurrent program. However, in order for this program to have any useful effect:

References

Summarize Survey Data Concurrent Program

When interaction center agents execute a script, or when survey respondents participate in a survey, their individual answers are collected in the Oracle Scripting schema of the applications database.

For generating reports on survey data, information must be moved into summary tables that make the data accessible to reporting tools (Oracle Discoverer workbooks) as part of the Interaction Center Intelligence product family.

Run this concurrent program prior to viewing any reports for the most current data, or schedule this program to execute on a regularly scheduled basis (for example, once daily at an off-peak time, when load on the system is not high).

Parameters

There is a single parameter for the Summarize Survey Data concurrent program. The parameter details are listed in the table below.

No. Parameter Meaning Value
1 p_cycle_id Cycle ID of the specified cycle for which you want to execute this concurrent program. Locate the appropriate cycle ID from the p_cycle_id list of values and use it here.

Guidance

There are no prerequisites for executing this concurrent program. However, in order for this program to have any useful effect:

Update Deployment Status Concurrent Program

When you define a survey deployment, one set of criteria includes the range of time for which the deployment is valid. This set includes the deployment start date, and the response end date and time.

A concurrent program defined in Oracle Applications for survey operations must be executed on a regular basis to check this response end date and time. This process occurs from the Concurrent Manager and is performed by an individual with the iSurvey User responsibility (typically an administrator or supervisor).

The Update Deployment Status concurrent program compares the response end date for each deployment against SYSDATE, and changes the status of all deployments from active to closed if SYSDATE is past the response end date and time. Additionally, this concurrent program changes the higher level survey campaign status to idle if the survey campaign contains no active or pending deployments.

Oracle recommends executing this concurrent program once daily at an off-peak time (a time when load on the system is not high). This concurrent program can be manually executed. For example, executing this concurrent program could be one of the closing operations an interaction center supervisor performs at the end of the day. Alternatively, this program can be scheduled to run automatically, for example, daily at 2 AM.

Parameters

There are no configurable parameters for the Update Deployment Status concurrent program.

Guidance

There are no prerequisites for executing this concurrent program. However, in order for this program to have any useful effect: