36 Integrating the Polls Service

This chapter explains how to integrate the Polls service into a WebCenter Portal application at design time. For more information about using polls, see "Working with the Polls Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

This chapter includes the following sections:

• Section 36.1, "Introduction to Polls"

• Section 36.2, "Basic Configuration for the Polls Service"

• Section 36.3, "Advanced Information for the Polls Service"

36.1 Introduction to Polls

The Polls service lets you create, edit, and take online polls on your application pages. Polls let you survey your audience (such as their opinions and their experience level), check whether they can recall important information, and gather feedback on the efficacy of presentations.

This section includes the following subsections:

• Section 36.1.1, "Understanding the Polls Service"

• Section 36.1.2, "Requirements for Polls"

• Section 36.1.3, "What Happens at Runtime"

36.1.1 Understanding the Polls Service

In addition to taking available polls, the Polls service lets you do the following:

• Quickly create and publish polls.

• Customize an existing poll; for example, add or change questions, and publish (open) and close the poll.

• Take a specific or the most recently-published poll

• View poll results

• See the status of all polls and available actions for each poll, such as edit, delete, publish, analyze, and clear results.

The Polls service is integrated with the Instant Messaging and Presence service in the Polls Manager.

36.1.2 Requirements for Polls

In a WebCenter Portal application, the Polls service requires a connection to WebCenter database schema. For details about setting up a database connection, see Section 7.2.2, "Setting Up a Database Connection."

36.1.3 What Happens at Runtime

At runtime, users can quickly create polls with just a name and a question. Figure 36-1 shows a sample quick view poll.

Figure 36-1 Quick View Poll

Description of "Figure 36-1 Quick View Poll"

WebCenter application administrators can access the Polls Manager, which lets you create polls with multiple questions or with templates. The Actions dropdown list lets continue designing the poll, publish the polls, analyze results, clear results, and delete the poll (Figure 36-2).

Figure 36-2 Polls Manager

Description of "Figure 36-2 Polls Manager"

Polls created through the Polls Manager must be published and open to be taken. Users cannot take unpublished or closed polls.

For more information about the service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

36.2 Basic Configuration for the Polls Service

This section describes required steps for adding this service to your application. It includes the following subsections:

• Section 36.2.1, "Setting up Connections for the Polls Service"

• Section 36.2.2, "Adding the Polls Service at Design Time"

• Section 36.2.3, "Setting Security for Polls"

36.2.1 Setting up Connections for the Polls Service

The Polls service requires a connection to the database where the WebCenter schema is installed. For details about setting up a database connection, see Section 7.2.2, "Setting Up a Database Connection."

36.2.2 Adding the Polls Service at Design Time

This section explains a basic incorporation of the Polls service. It includes the following sections:

• Section 36.2.2.1, "Polls Task Flows"

• Section 36.2.2.2, "How to Add the Polls Quick View to Your Page"

• Section 36.2.2.3, "How to Modify the Polls Service Task Flow Parameters"

36.2.2.1 Polls Task Flows

The Polls service includes the task flows described in Table 36-1.

Table 36-1 Polls Task Flows

Task Flow	Description
Polls - Quick View	This task flow displays a view that enables users to create one-question polls to be published immediately. Each quick poll needs its own Polls - Quick View task flow on the page.
Polls - Polls Manager	This task flow allows users to perform administrative operations on the polls. Any user who has access to this task flow can perform the administrative operations, such as edit or delete the poll.
Polls - Take Polls	This task flow displays the most recently-published available poll, unless it is set to a specific poll in the pollId parameter.
Polls - View Poll Results	This task flow displays the results of a poll as a graph for the supplied pollId. This task flow works only if pollId is supplied.

36.2.2.2 How to Add the Polls Quick View to Your Page

The Polls - Quick View task flow display polls and provides tools to create, edit, and delete polls. It also provides controls for determining when a poll when it expires. This task flow lets you present polls to end users where manage controls are not needed.

To add the Polls Quick View task flow to your WebCenter Portal application:

1. Open the page on which you want to add the service.

2. In the Resource Palette, expand My Catalogs, WebCenter Services Catalog, and Task Flows.

3. Drag Polls - Quick View from the Resource Palette and drop it onto the page inside of the af:form begin and end tags.

4. When prompted, select Region as the way to create the task flow (and confirm with Add Library). This operation may take a moment to complete.

5. Click OK.

6. Save and run your page.

36.2.2.3 How to Modify the Polls Service Task Flow Parameters

The Polls service task flows have optional task flow binding parameters.

In addition to providing required values for successful task flow rendering, you can use task flow parameters to customize the appearance and behavior of a task flow instance. For example, you can use parameter values to set which poll to display.

You can adjust the parameter values when you drop the task flows onto a page or after you have placed a task flow on a page:

1. Navigate to the Edit Task Flow Binding dialog by clicking the Bindings tab at the bottom of the page (next to the Source tab).

2. Under Executables, you'll see the task flow you added. Figure 36-4 shows an example of a Search task flow in the Executables section.

   Figure 36-3 Page Data Binding Definition

   
   Description of "Figure 36-3 Page Data Binding Definition"
   
   

3. Select the task flow, and next to the Executables heading, click the Edit selected element (pencil) icon.

4. In the Edit Task Flow Binding dialog Figure 36-4, revise the binding parameter values as required.

   Figure 36-4 Edit Task Flow Binding Dialog for Polls Manager Task Flow

   
   Description of "Figure 36-4 Edit Task Flow Binding Dialog for Polls Manager Task Flow"
   
   

5. When you are finished, click OK.

6. Save and run your page to see the results.

Table 36-2 describes the properties that are unique to the Polls task flows.

Table 36-2 Polls Service Task Flow Parameters

Property	Description
scope	The Space name from which polls are to be fetched. If this is supplied, then polls of that particular Space are shown. On the Home space, when this parameter is not supplied, it fetches polls from all Spaces. This parameter appears in the properties for the Polls Manager task flow.
showUserDataOnly	This parameter determines whether to display all polls or only those polls created by the user. The default (No) is to show all polls. Set to Yes to display only those polls created by the user. If the scope parameter is specified, then this parameter works the same but within only that scope. This parameter appears in the properties for the Polls Manager task flow.
pollId	The poll to display. This parameter appears in the properties for the following task flows. Take Polls View Poll Results
showInEditMode	This parameter determines whether users can edit a quick poll. When a quick poll is in Edit mode, a Design Poll box for editing the poll appears. When a quick poll is not a Edit mode, the Design Poll box for editing is not visible. This parameter appears in the properties for the Quick Poll task flow.

36.2.3 Setting Security for Polls

The Polls service does not require security. Administrators control access to Polls task flows through the Resource Catalog, where they define the users and groups privileged to see polls. Security is driven by the page security on which the task flow exists or by the task flow permissions on that page. Any user who can see the task flow can edit the poll.

ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security"

36.3 Advanced Information for the Polls Service

This section describes optional features available with this service. It includes the following subsections:

• Section 36.3.1, "How to Add the Polls Manager Task Flow"

• Section 36.3.2, "How to Add the Take Polls Task Flow"

• Section 36.3.3, "How to Add the Polls - View Poll Results Task Flow"

• Section 36.3.4, "Using the Polls Service Data Controls"

36.3.1 How to Add the Polls Manager Task Flow

The Polls Manager task flow provides a complete view of polls and perform actions on them.

To add this to your WebCenter Portal application, follow the same instructions that you did for the Polls Manager task flow in Section 36.2.2, "Adding the Polls Service at Design Time," but drag and drop Polls Manager onto the page.

36.3.2 How to Add the Take Polls Task Flow

This task flow displays published polls for users to take. It displays the most recently-published available poll, unless it is set to display a specific poll with the pollId parameter. After a user submits a response for that poll, it displays the next most recently-published poll.

To add this to your WebCenter Portal application, follow the same instructions that you did for the Polls Manager task flow in Section 36.2.2, "Adding the Polls Service at Design Time," but drag and drop Polls - Take Polls onto the page.

36.3.3 How to Add the Polls - View Poll Results Task Flow

The View Poll Results task flow displays the results of a poll as a graph for the poll supplied with the required pollId parameter.

To add this task flow to your WebCenter Portal application, follow the same instructions that you did for the Polls Manager task flow in Section 36.2.2, "Adding the Polls Service at Design Time," but drag and drop Polls - View Poll Results onto the page.

36.3.4 Using the Polls Service Data Controls

Use the Polls service data controls to build a customized user interface for polls with a WebCenter Portal application or a custom task flow.

The Polls service includes two data controls to customize the user interface:

• Take Poll Data Control

• Polls Manager Data Control

36.3.4.1 Take Poll Data Control

The Take Poll data control contains the following methods:

• createResponse

• createResponseForLatestAvailablePoll

• getPublishedPolls

• getResults

• saveResponse

36.3.4.1.1 createResponse

This method lets users respond to a particular poll. Table 36-3 describes the required parameters for this method.

Table 36-3 createResponse Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.

36.3.4.1.2 createResponseForLatestAvailablePoll

This method lets users respond to the most recently-published poll. It has no parameters.

36.3.4.1.3 getPublishedPolls

Table 36-4 describes the required parameters for this method.

Table 36-4 getPublishedPolls Input Parameters

Parameter	Type	Description
startIndex	Integer	The index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
numResults	Integer	The number or results to display.

36.3.4.1.4 getResults

This method gets the poll results for a particular poll. Table 36-5 describes the required parameters for this method.

Table 36-5 getResults Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.

36.3.4.1.5 saveResponse

Table 36-6 describes the required parameters for this method.

Table 36-6 saveResponse Input Parameters

Parameter	Type	Description
response	Response	The response object acquired from the data control calls to createResponse or createResponseForLatestAvailablePoll.

36.3.4.2 Polls Manager Data Control

The Polls Manager data control contains the following methods:

• addQuestion

• addQuestion

• closePoll

• closePollAfterDate

• closePollAfterDays

• closePollAfterResponses

• createPoll

• deletePoll

• editPoll

• editPoll

• findPoll

• getPolls

• getPollsByUser

• getPollsByUserCount

• publishPoll

• publishPollOnDate

36.3.4.2.1 addQuestion

This method creates polls with multiple choice questions. Table 36-7 describes the required parameters for this method.

Table 36-7 addQuestion Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
question	String	The text of the question; for example, What is your favorite color?
rowOptions	String	Corresponding list of options for the question. This should be line-separated list of options.
allowMultipleSelection	Boolean	True to allow multiple options to be selected; false to allow only a single option selection.

36.3.4.2.2 addQuestion

This method creates complex polls with matrix-type questions. Table 36-8 describes the required parameters for this method.

Table 36-8 addQuestion Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
questionType	QuestionType	Question type, either: Matrix of choices (only one answer per row) Matrix of choices (multiple answers per row)
question	String	The text of the question; for example, What is your favorite color?
rowOptions	String	Corresponding list of options for the question. This should be line-separated list of options.
columnOptions	String	Column options.
isOptional	Boolean	True if the question is optional (that is, users can ignore answering it); false if question is mandatory.
commentLabel	String	Enables a comment field for users to provide feedback or enter personalized text with their answers.
commentFieldHeight	Integer	Size for the comment field. To capture feedback, set this to 3; otherwise, set it to 1. This parameter value depends on the type of answer expected in the comment field.

36.3.4.2.3 closePoll

This method closes a particular poll. Table 36-9 describes the required parameters for this method.

Table 36-9 closePoll Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.

36.3.4.2.4 closePollAfterDate

This method closes a poll on a specific date. Table 36-10 describes the required parameters for this method.

Table 36-10 closePollAfterDate Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
date	Date	Date at which the poll should close.

36.3.4.2.5 closePollAfterDays

This poll closes a poll at a set number of days after the poll is published. Table 36-11 describes the required parameters for this method.

Table 36-11 closePollAfterDays Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
days	Integer	Number of days, after the publish date, at which the poll should close.

36.3.4.2.6 closePollAfterResponses

This method closes as poll after a set number of responses have been collected. Table 36-12 describes the required parameters for this method.

Table 36-12 closePollAfterResponses Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
responses	Integer	Number of responses at which the poll should close.

36.3.4.2.7 createPoll

This method creates a quick poll. Table 36-13 describes the required parameters for this method.

Table 36-13 createPoll Input Parameters

Parameter	Type	Description
name	String	Name of the poll.
description	String	Description of the poll.

36.3.4.2.8 deletePoll

This method deletes a particular poll. Table 36-14 describes the required parameters for this method.

Table 36-14 deletePoll Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.

36.3.4.2.9 editPoll

Table 36-15 describes the required parameters for this method.

Table 36-15 editPoll Input Parameters

Parameter	Type	Description
pollInstance	Poll	If a poll instance is directly edited, then that instance can be supplied for editing.

36.3.4.2.10 editPoll

This method edits a particular poll. Table 36-16 describes the required parameters for this method.

Table 36-16 editPoll Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
name	String	Name of the poll.
description	String	Description of the poll.

36.3.4.2.11 findPoll

This method finds a particular poll. Table 36-17 describes the required parameters for this method.

Table 36-17 findPoll Input Parameters

Parameter	Type	Description
id	String	Poll instance ID

36.3.4.2.12 getPolls

This method displays all polls, as defined in its parameters. Table 36-18 describes the required parameters for this method.

Table 36-18 getPolls Input Parameters

Parameter	Type	Description
startIndex	Integer	The index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
numResults	Integer	The number or results to display.

36.3.4.2.13 getPollsByUser

This method displays polls created by a particular user. Table 36-19 describes the required parameters for this method.

Table 36-19 getPollsByUser Input Parameters

Parameter	Type	Description
createdBy	String	User name of the person who created the poll.
startIndex	Integer	The index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
numResults	Integer	The number or results to display.

36.3.4.2.14 getPollsByUserCount

Table 36-20 describes the required parameters for this method.

Table 36-20 getPollsByUserCount Input Parameters

Parameter	Type	Description
createdBy	String	User name of the person who created the poll.

36.3.4.2.15 publishPoll

This method publishes a particular poll. Table 36-21 describes the required parameters for this method.

Table 36-21 publishPoll Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.

36.3.4.2.16 publishPollOnDate

This method publishes a poll on a specific date. Table 36-22 describes the required parameters for this method.

Table 36-22 publishPollOnDate Input Parameters

Parameter	Type	Description
pollId	String	The poll to display.
date	Date	Date at which the poll should be published.