User Guide. PegaSurvey 7.2.1

Transcription

1 User Guide PegaSurvey 7.2.1

2 Copyright Copyright 2016 Pegasystems Inc. All rights reserved. Trademarks For Pegasystems Inc. trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. For information about the third-party software that is delivered with the product, refer to the third-party license file on your installation media that is specific to your release. Notices This publication describes and/or represents products and services of Pegasystems Inc. It may contain trade secrets and proprietary information that are protected by various federal, state, and international laws, and distributed under licenses restricting their use, copying, modification, distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This publication is current as of the date of publication only. Changes to the publication may be made from time to time at the discretion of Pegasystems Inc. This publication remains the property of Pegasystems Inc. and must be returned to it upon request. This publication does not imply any commitment to offer or deliver the products or services described herein. This publication may include references to Pegasystems Inc. product features that have not been licensed by you or your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems Inc. services consultant. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors, as well as technical inaccuracies. Pegasystems Inc. may make improvements and/or changes to the publication at any time. Any references in this publication to non-pegasystems websites are provided for convenience only and do not serve as an endorsement of these websites. The materials at these websites are not part of the material for Pegasystems products, and use of those websites is at your own risk. Information concerning non-pegasystems products was obtained from the suppliers of those products, their publications, or other publicly available sources. Address questions about non-pegasystems products to the suppliers of those products. This publication may contain examples used in daily business operations that include the names of people, companies, products, and other third-party publications. Such examples are fictitious and any similarity to the names or other data used by an actual business enterprise or individual is coincidental. This information is the property of:

3 Pegasystems Inc. One Rogers St. Cambridge, MA USA Phone: Fax: Document: PegaSurvey User Guide Updated: Monday, July 11, 2016 PegaSurvey User Guide 3

4 Contents Contents Contents 4 Surveys 6 Survey structure 6 Best practices for creating a survey 6 Questions in a survey 7 Answer formats 7 Survey scores 8 Creating a survey 9 Creating a survey rule 9 Adding a question page to a survey 10 Adding a simple question to a survey 11 Adding a complex question to a survey 14 Checking for conflicts in a survey 17 Creating a stand-alone question 18 Adding supporting information to a survey 22 Displaying hover text for a question in a survey 22 Attaching a file or URL link to a survey 23 Displaying a block of text in a survey 23 Fine-tuning your survey 25 Making a question required in a survey 25 Reordering questions in a survey 26 Conditionally displaying a question page in a survey 26 Conditionally displaying a question in a survey 27 Validating answers in a survey 27 Displaying a warning in a survey 28 Integrating a survey with your application 29 Calling a survey from a flow 29 Changing the display of questions in a survey 30 Calling a simple question from a flow 31 Working with existing surveys in your application 33 PegaSurvey User Guide 4

5 Contents Reviewing the existing surveys in your application 33 Copying a survey 34 Updating a question in a survey 34 Reusing a question in a survey 35 Considerations for using surveys in offline mode 36 PegaSurvey User Guide 5

6 Surveys Surveys A survey gathers data that you can use in your application by presenting a collection of questions to users. You can use the Survey Management landing page to create surveys. Survey structure Because the structure of a survey is modular, you can reuse questions and other survey elements in your application. Each survey that you create has the following elements: The survey itself, which contains at least one question page. Question pages, which contain at least one question. Individual questions, which can be simple or complex. Each question can have a different format, based on the type of question. Surveys are integrated with flows in your application. If your application requires offline support for surveys, you can use the Question smart shape instead of the traditional structure of a survey, question pages, and questions. Best practices for creating a survey You can use surveys to gather information from users. Before you create a survey, review these best practices. The following tips can help you create surveys that are easy to use and maintain: Group questions in a logical way so that users stay focused and can provide answers quickly. Use question pages where possible because they are reusable. Limit the total number of questions in the survey because the quality of answers tends to decline as the length of a survey increases. You can also split up a survey into smaller surveys that are called in succession. Limit the number of questions on each question page because many questions can lead to scrolling at run time. Use concise questions. PegaSurvey User Guide 6

7 Surveys You can include related information for a question in the instructions field for the question page or add an attachment to the survey. Ensure that the format of the question matches the type of question that you are asking. For example, a question that asks users to rate their customer satisfaction cannot be answered with a single check box. Proofread your survey for grammatical errors, duplicate questions, and any acronyms or terms that are not explained. Test your survey by asking potential users for feedback on clarity, length, and ease of use. Questions in a survey Questions in a survey gather information from users. They can be simple or complex, based on the type of answer that users provide. You can use simple questions to prompt users for a singular response, such as a date of birth, and complex questions to collect multiple pieces of information. For example, you can use a complex question to ask users to list the names and addresses of their previous employers. Although both simple and complex questions are supported in surveys, only simple questions are supported by the Question smart shape. You can create and manage your questions on the Survey Management landing page. Answer formats The following table describes the answer formats that are supported by each type of question in a survey. Format Simple question Complex question Radio buttons Y Y Text input Y Y Text area Y N Date Y Y Check boxes Y Y List Y N File Y N Custom section Y N Table N Y PegaSurvey User Guide 7

8 Surveys You can change the default presentation of many of these formats, and in some cases provide a custom implementation. When the survey is run using the Question smart shape, the answers are stored on the pyworkpage.question clipboard page. If the survey is run from a question page (Survey > Question Page > Question), the answers are stored in thepyworkpage.questionnaire clipboard page. Survey scores A survey score is the sum of values that are assigned to individual questions on the question pages of a survey. You assign a score value, which can be a positive or negative integer, to a question when you add a question to a question page. If you assign a score value to a stand-alone question, it is evaluated only when that question is called from a question page in a survey. To view a survey score, inspect the pyworkpage.questionnaire clipboard page. PegaSurvey User Guide 8

9 Creating a survey Creating a survey You can create a survey that presents a group of questions to users. By using a structured format for your questions, you can gather information quickly. 1. Create a survey rule. 2. Add question pages to the survey. 3. Define questions for each question page, based on the type of answer that users provide: Use a simple question to capture a single answer. Use a complex question to capture a series of answers. 4. Check the survey for conflicts. 5. On the Survey Management landing page, click Preview to view the current structure of question pages and questions in your survey. After you create a survey, you can integrate it with your application by calling it from a flow. You can also finetune it to make certain questions mandatory or display under certain conditions. Creating a survey rule You can create a survey rule in your application to organize the question pages in a survey. 1. Click Designer Studio > Survey Management. 2. Click Create Survey. 3. In the Survey Name field, enter a unique name for the survey. You can change the value in the Survey ID field, which is populated based on the value that you provide in the Survey Name field. 4. Expand the Advanced section and review the default values in the Applies to, Ruleset, and Version PegaSurvey User Guide 9

10 Creating a survey fields. You can change these values to ensure that your survey can be integrated with other rules, such as flows, in your application. 5. In the Instructions field, enter text to display to users that describes the purpose of the survey. 6. Click Create. The survey rule is created in the class and ruleset that you provide. You can view, edit, or copy it by using the Survey Management landing page. Adding a question page to a survey You can add a question page to a survey to organize the simple and complex questions that users answer at run time. 1. Click Designer Studio > Survey Management. 2. Click Edit next to the name of a survey. 3. Click Add Question Page. 4. In the Add Page dialog box, click Create new. 5. In the Name field, enter a unique name for the question page. You can change the value in the ID field, which is populated based on the value that you provide in the Name field. 6. Expand the Settings section and review the default values in the Applies to, Ruleset, and Version fields. You can change these values to ensure that you can reuse this question page in other surveys in your application. 7. In the Instructions field, enter text to display to users that describes the purpose of the question page. 8. Expand the Advanced section and select a Category for the page from the options offered. 9. Click Submit to close the Add Question Page dialog box. 10. Click Save. PegaSurvey User Guide 10

11 Creating a survey The question page is created in the class and ruleset that you provide. You can view, edit, or copy it by using the Survey Management landing page. Adding a simple question to a survey You can use a simple question in a survey to collect a single response from users. For example, you can ask whether a user is currently employed or to enter a date of birth. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. In the list of question pages for the survey, right-click the name of a question page and select Add Simple Question > New. 3. In the Name field of the Add Simple Question dialog box, enter a short description that is associated with the underlying question rule. You can change the value in the ID field, which is populated based on the value that you provide in the Name field. 4. Optional: Expand the Settings section to change the class or ruleset for the question. By default, questions apply to the same class as the survey with which they are associated. 5. In the Question field, enter the text that is displayed when users reach the question in the survey. 6. Format the fields that users populate to answer the question. To use a date or time field: a. In the Answer list, select Freeform. b. In the Format list, select Date or Date Time, based on the expected response to the question. To use one or more lines of text: a. In the Answer list, select Freeform. b. In the Format list, select Text or TextArea, based on the expected response to the question. c. Optional: Expand the Advanced section to define how the text is displayed. PegaSurvey User Guide 11

12 Creating a survey You can use the following fields: Rows - Enter an integer for the height of the text area field. Columns - Enter an integer for the width of the text area field. Size of text box - Enter an integer for the width of the text input field. To use a list of radio buttons that is sourced from a data page: a. In the Answer list, select Radio buttons. b. In the Drop down type list, select Data page. c. In the Data page field, press the Down Arrow key and select a data page that returns a list of options. You can pass parameters in the Value field if they are supported by the data page. d. In the Property for value field, press the Down Arrow key and select a property on the data page that stores options for the radio buttons. e. Optional: In the Property for display text field, press the Down Arrow key and select a different property on the data page that stores labels for the radio buttons. f. Optional: Expand the Advanced section to change the default presentation of the radio buttons. You can use the following fields: Display of radio buttons - Select an option to align the radio buttons in columns or rows. Number of items before wrap - Enter the number of radio buttons to display in each row or column. To use a list of radio buttons that you define: a. In the Answer list, select Radio buttons. b. In the Drop down type list, select Prompt list. c. In the grid that is displayed, add one row for each radio button in the list. You can use the following fields: PegaSurvey User Guide 12

13 Creating a survey When - Select a when condition that controls whether the radio button is displayed. Display value - Enter the label to display. Value - Enter the value to copy to the clipboard when the radio button is clicked. Selected - Click to set the default radio button in the list. d. Optional: Expand the Advanced section to change the default presentation of the radio buttons. You can use the following fields: Display of radio buttons - Select an option to align the radio buttons in columns or rows. Number of items before wrap - Enter the number of radio buttons to display in each row or column. To use a list of options that is sourced by a data page: a. In the Answer list, select Dropdown menu. b. In the Drop down type list, select Data page. c. In the Data page field, press the Down Arrow key and select a data page that returns a list of options. You can pass parameters in the Value field if they are supported by the data page. d. In the Property for value field, press the Down Arrow key and select a property on the data page that stores options for the list. e. Optional: In the Property for display text field, press the Down Arrow key and select a different property on the data page that stores labels for the options in the list. To use a list of options that you define: a. In the Answer list, select Dropdown menu. b. In the Drop down type list, select Prompt list. c. In the grid that is displayed, add one row for each option in the list. You can use the following fields: PegaSurvey User Guide 13

14 Creating a survey When - Select a when condition that controls whether the option is displayed. Display value - Enter the label to display. Value - Enter the value to copy to the clipboard when the option is selected. Selected - Click to set the default option in the list. To use a check box: In the Answer list, select Checkbox. To use a button to upload a file: In the Answer list, select File. 7. You can validate the answers to questions in a survey by displaying an error when the answer is invalid. To perform validation when the user answers the question: a. In the Property Name field, press the Down Arrow key and select a property that stores the values for the answer to the question. b. In the Validation field, press the Down Arrow key and select the name of a Rule-Obj-Validate rule that evaluates the values of properties that are mapped to the question. 8. Click Add to close the Add Simple Question dialog box. 9. Click Save. The simple question is created in the class and ruleset that you provide. You can view, edit, or copy it by using the Survey Management landing page. You can also reuse this question in other surveys or flows that use the Question smart shape. Adding a complex question to a survey You can add a complex question to a survey to collect a series of responses from users. For example, you can use ask users to list their five favorite movies. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. In the list of question pages for the survey, right-click the name of a question page and select Add Complex PegaSurvey User Guide 14

15 Creating a survey Question > New. 3. In the Name field of the Add Complex Question dialog box, enter a short description that is associated with the underlying question rule. You can change the value in the ID field, which is populated based on the value that you provide in the Name field. 4. Optional: Expand the Settings section to change the class or ruleset for the question. By default, questions apply to the same class as the survey with which they are associated. 5. In the Question field, enter the text that is displayed when users reach the question in the survey. 6. Format the fields that users populate to answer the question. To use a static group of text input or date fields: a. In the Answer list, select Freeform. b. In the Display Header field, enter a label that describes the group of fields. c. In the Number of rows list, select Fixed. d. In the Property Type list, select No Property Mapping to store the answers to the question in the default clipboard structure. e. In the Data type list, select Date or Text, based on the expected response to the question. f. In the grid that is displayed, add one row for each field in the group. You can use the following fields in each row: Answer ID - A unique identifier on the clipboard that distinguishes this field from other fields in the group. When - A when condition that controls whether this field is displayed in the group. Display value - The label of the field. Value - The value that is stored on the clipboard when a user enters a date or text in the field. To use a dynamic group of text input or date fields: PegaSurvey User Guide 15

16 Creating a survey a. In the Answer list, select Freeform. b. In the Display Header field, enter a label that describes the group of fields. c. In the Number of rows list, select Dynamic. d. In the Property Type list, select No Property Mapping to store the answers to the question in the default clipboard structure. e. In the Data type list, select Date or Text, based on the expected response to the question. At run time, users decide how many fields are added to the group. For example, they can enter none, some, or all the dates of their previous medical procedures. To use a group of check boxes: a. In the Answer list, select Check boxes. b. In the Display Header field, enter a label that describes the group of check boxes. c. In the Property Type list, select No Property Mapping to store the answers to the question in the default clipboard structure. d. In the grid that is displayed, add one row for each check box in the group. You can use the following fields in each row: Answer ID - A unique identifier on the clipboard that distinguishes this check box from other check boxes in the group. When - A when condition that controls whether this check box is displayed in the group. Display value - The label of the check box. Value - The value that is stored on the clipboard when a user selects this check box. Selected - Whether this check box is selected by default. To use a repeating group of radio buttons: Follow these steps to ask a series of related questions that are answered by selecting options from the same group of radio buttons. For example, you can ask users to rate their pain threshold for different events, such as swimming, running, and walking. PegaSurvey User Guide 16

17 Creating a survey a. In the Answer list, select Radio buttons. b. In the Property Type list, select No Property Mapping to store the answers to the question in the default clipboard structure. c. In the Radio Button Header Details grid, add one row for each radio button in the group. You can use the following fields in each row: Label - The label of the radio button that is displayed as a column heading. Value - The value that is stored on the clipboard when a user selects this radio button from the group of options. d. In the Radio Button Row Details grid, add one row for each item in the series. You can use the following fields in each row: Answer ID - A unique identifier on the clipboard that distinguishes this item from other items in the series. When - A when condition that controls whether this item is displayed in the series. Display value - The label that is displayed as a row heading. Default - The option that is selected by default for this item in the series. 7. Click Add to close the Add Complex Question dialog box. 8. Click Save. Checking for conflicts in a survey You can find questions that are mapped to the same property in a survey. By ensuring that each question uses a unique property, you can prevent users from accidentally overwriting answers at run time. 1. Click Designer Studio > Survey Management. 2. Click Edit next to the name of a survey that has at least one question page defined. 3. Click View/Edit next to the name of a question page that has two or more questions defined. PegaSurvey User Guide 17

18 Creating a survey 4. Expand the Advanced section and click Check for Property Conflicts. An error message is displayed if a conflict is detected. To resolve the issue, update the identified questions and ensure that they use unique properties. 5. Click Save to close the Edit Page dialog box. 6. Click Save. Creating a stand-alone question You can create a question that is not associated with a survey. By using stand-alone questions, you can collect information from users faster. 1. In Designer Studio, click + Create > Survey > Simple Question to open the Create Simple Question form. 2. In the Label field, enter text that describes the purpose of the question. 3. In the Context section, select an application layer, class, and ruleset for the question. 4. Click Create and open to open the Simple Question form. 5. In the Plain Text field, enter the text that is displayed when the question is called from a flow. 6. On the Answers tab, format the fields that users populate to answer the question. To use a date or time field: a. In the Question Mode list, select Freeform. b. In the Format list, select Date or Date Time, based on the expected response to the question. To use one or more lines of text: a. In the Question Mode list, select Freeform. b. In the Format list, select Text or TextArea, based on the expected response to the question. c. Optional: Define how the text is displayed. PegaSurvey User Guide 18

19 Creating a survey You can use the following fields: Rows - Enter an integer for the height of the text area field. Columns - Enter an integer for the width of the text area field. Size - Enter and integer for the width of the text input field. To use a list of radio buttons that is sourced from a data page: a. In the Question Mode list, select Radio buttons. b. In the Drop down type list, select Data page. c. In the Data page field, press the Down Arrow key and select a data page that returns a list of options. You can pass parameters in the Value field if they are supported by the data page. d. In the Property for value field, press the Down Arrow key and select a property on the data page that stores options for the radio buttons. e. Optional: In the Property for display text field, press the Down Arrow key and select the property whose value is displaying labels. f. Optional: Change the default presentation of the radio buttons. You can use the following fields: Direction - Select an option to align the radio buttons in columns or rows. Number of items before wrap - Enter the number of radio buttons to display in each row or column. To use a list of radio buttons that you define: a. In the Question Mode list, select Radio buttons. b. In the Drop down type list, select Prompt list. c. In the grid that is displayed, add one row for each radio button in the list. You can use the following fields: PegaSurvey User Guide 19

20 Creating a survey When - Select a when condition that controls whether the radio button is displayed. Display value - Enter the label to display. Value - Enter the value to copy to the clipboard when the radio button is clicked. Selected - Click to set the default radio button in the list. d. Optional: Change the default presentation of the radio buttons. You can use the following fields: Direction - Select an option to align the radio buttons in columns or rows. Number of items before wrap - Enter the number of radio buttons to display in each row or column. To use a list of options that is sourced by a data page: a. In the Question Mode list, select Dropdown menu. b. In the Drop down type list, select Data page. c. In the Data page field, press the Down Arrow key and select a data page that returns a list of options. You can pass parameters in the Value field if they are supported by the data page. d. In the Property for value field, press the Down Arrow key and select a property on the data page that stores options for the radio buttons. e. Optional: In the Property for display text field, press the Down Arrow key and select the property whose value is displaying labels. To use a list of options that you define: a. In the Question Mode list, select Dropdown menu. b. In the Drop down type list, select Prompt list. c. In the grid that is displayed, add one row for each option in the list. You can use the following fields: PegaSurvey User Guide 20

21 Creating a survey When - Select a when condition that controls whether the option is displayed. Display value - Enter the label to display. Value - Enter the value to copy to the clipboard when the option is selected. Selected - Click to set the default option in the list. To use a check box: In the Question Mode list, select Checkbox. To use a button to upload a file: In the Question Mode list, select File. After you create a stand-alone question, you can call it from a flow or reuse it in an existing survey. PegaSurvey User Guide 21

22 Adding supporting information to a survey Adding supporting information to a survey You can add supporting information, such as an attachment or example use case, to a survey. By separating additional information from the questions in a survey, you can create a rich yet simple user experience. The following tasks can help you add supporting information to a survey: Displaying hover text for a question in a survey on page 22 Attaching a file or URL link to a survey on page 23 Displaying a block of text in a survey on page 23 Displaying hover text for a question in a survey You can display text to users when they hover on a question in a survey. By providing supporting information about the question, you can help users provide an answer quickly and completely. 1. Create a section in a class and ruleset that is compatible with your survey, and then configure the section to display text. For example, you can use a paragraph in the section to display the definition of a primary care physician. 2. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 3. Expand the name of a question page, and then click View/Edit next to the name of a question. 4. Expand the Advanced section. 5. In the SmartInfo Section field, enter the name of the section that contains the hover text. 6. Click Save. 7. On the Survey Builder page, click Save. PegaSurvey User Guide 22

23 Adding supporting information to a survey Attaching a file or URL link to a survey You can attach a file or URL link to a survey to provide supporting information for a question. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Expand the name of a question page, and then click View/Edit next to the name of a question. 3. Expand the Advanced section. 4. In the Supporting Label field, enter text to display in the tool tip for the file or URL. 5. Attach the supporting information. To attach a file: a. In the Supporting Type list, select File. b. Click Choose File and navigate to a file on your local machine. c. Click Upload File. To attach a URL link: a. In the Supporting Type list, select URL. b. In the Supporting URL field, enter the address of a website or supporting document. 6. Click Save. 7. On the Survey Builder page, click Save. Displaying a block of text in a survey You can display a block of read-only text on a question page in a survey. By providing supporting information about the questions in a survey, you can help users provide answers quickly and completely. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. In the list of question pages for the survey, right-click the name of a question page and select Add Simple PegaSurvey User Guide 23

24 Adding supporting information to a survey Question > New. Although users cannot respond to a block of read-only text in a survey, you must create a question to store the text. 3. In the Name field of the Add Simple Question dialog box, enter a short description that is associated with the underlying question rule. You can change the value in the ID field, which is populated based on the value that you provide in the Name field. 4. Optional: Expand the Settings section to change the class or ruleset for the question. By default, questions apply to the same class as the survey with which they are associated. 5. In the Question field, enter the content for the block of text. 6. In the Answer list, select Show display text only. 7. Click Add. 8. On the Survey Builder page, click Save. At run time, the block of text is displayed at the bottom of the question page. You can change the position by reordering the questions on the question page. PegaSurvey User Guide 24

25 Fine-tuning your survey Fine-tuning your survey You can fine-tune your survey by reordering questions, making certain questions required, validating user input, displaying a warning when certain criteria are met, and displaying questions or groups of questions under certain conditions. By making these changes, you can refine your survey to help ensure that information gathered in the survey is valid and specific. The following tasks can help you fine-tune a survey: Making a question required in a survey on page 25 Reordering questions in a survey on page 26 Conditionally displaying a question in a survey on page 27 Conditionally displaying a question page in a survey on page 26 Validating answers in a survey on page 27 Displaying a warning in a survey on page 28 Making a question required in a survey You can make a question required so that users must provide an answer before submitting the survey. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Expand the name of a question page, and then click View/Edit next to the name of a simple question. You can make a complex question required by adding validation to the survey. 3. In the Edit Simple Question dialog box, expand the Options section. 4. Select the Required check box. PegaSurvey User Guide 25

26 Fine-tuning your survey 5. Click Save to close the Edit Simple Question dialog box. 6. On the Survey Builder page, click Save. Reordering questions in a survey You can change the order of questions on a question page. By organizing your questions in a logical way, you can improve the time it takes for users to complete your survey. 1. Click Designer Studio > Survey Management. 2. Click Edit next to the name of a survey that has at least one question page defined. 3. Right-click the name of a question page that has two or more questions defined, and select Reorder Questions. 4. In the Reorder Questions dialog box, drag a question to a different position in the list. 5. Click Save to close the Reorder Questions dialog box. 6. Click Save. Conditionally displaying a question page in a survey You can define a set of conditions that must be met before a question page is displayed in a survey. By displaying different questions based on the current context of the user, you can create surveys that are flexible. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Click View/Edit next to the name of a question page to open the Edit Page dialog box. 3. In the Show Question Page field, enter the name of the current question page. 4. In the When field, press the Down Arrow key and select a when condition that defines the criteria for displaying the question page. PegaSurvey User Guide 26

27 Fine-tuning your survey 5. Click Save to close the Edit Page dialog box. 6. On the Survey Builder page, click Save. Conditionally displaying a question in a survey You can define a set of conditions that must be met before a question is displayed in a survey. By displaying different questions based on the current context of the user, you can create surveys that are flexible. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Expand the name of a question page, and then click View/Edit next to the name of a question. 3. In the When field, press the Down Arrow key and select a when condition that defines the criteria for displaying the question. 4. Click Save. 5. On the Survey Builder page, click Save. Validating answers in a survey You can validate the answers to questions in a survey. By displaying an error when an answer is invalid, you can ensure that the information that users provide is accurate and in an expected format. To perform the validation when the user submits the survey: 1. Click Designer Studio > Survey Management. 2. Click Edit next to the name of a survey. 3. Expand the Advanced section. 4. In the Validation field, press the Down Arrow key and select the name of an edit validate rule that evaluates the values of properties that are mapped to questions in the survey. 5. Click Save. To perform the validation when the user submits a specific question page: 1. Click Designer Studio > Survey Management. PegaSurvey User Guide 27

28 Fine-tuning your survey 2. Click Edit next to the name of a survey. 3. Click View/Edit next to the name of a question page. 4. In the Edit Page dialog box, expand the Advanced section. 5. In the Validation field, press the Down Arrow key and select the name of an edit validate rule that evaluates the values of properties that are mapped to questions on the same question page. For example, you can verify that the user provides a phone number for each name on the emergency contact question page. 6. Click Save to close the Edit Page dialog box. 7. Click Save. Displaying a warning in a survey You can add a warning to a question that is displayed when certain criteria are met. By displaying feedback in real time, you can help users answer questions quickly and completely. 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Expand the name of a question page, and then click View/Edit next to the name of a question. 3. Expand the Advanced section. 4. In the Warning When field, press the Down Arrow key and select the name of a when condition that controls whether the warning is displayed. 5. In the Warning Message field, press the Down Arrow key and select the name of message rule. 6. Click Save. 7. On the Survey Builder page, click Save. PegaSurvey User Guide 28

29 Integrating a survey with your application Integrating a survey with your application You can use a flow to integrate a survey, a question page, or an individual question with your application. By using the parts of a survey that are specific to your context, you can collect the correct level of information from users. The following tasks can help you integrate a survey with your application: Calling a survey from a flow on page 29 Calling a survey from a flow using the Survey smart shape Calling a simple question from a flow on page 31 Changing display questions in a survey Calling a survey from a flow You can call a survey from a flow to collect information from users while they process a case. By using the Subprocess shape, you can integrate a survey with the life cycle of a case. Tip: Use multiple subprocesses in the same flow to call a group of surveys in succession. This approach is helpful if you need to upgrade a deprecated survey group. To call a survey from a flow: 1. Open a flow in Process Modeler. 2. On the Diagram tab, click the Shape palette icon and drag the Subprocess shape to a position on the flow diagram. 3. Connect the Subprocess shape to other shapes in the flow. 4. Double-click the Subprocess shape to open the Subprocess properties dialog box. 5. In the Subprocess field, enter a name that describes the purpose of the subprocess. PegaSurvey User Guide 29

30 Integrating a survey with your application 6. In the Subprocess details section, call a survey based on the type of your flow. To call the survey from a flow: a. In the Flow name field, press the Down Arrow key and select SurveyDriver. b. In the RoutingType field, select Operator or WorkBasket, based on who answers the questions in the survey at run time. You can then provide the name of a work queue or the ID of a user in the RouteToWorkbasket and RouteToOperator fields, respectively. c. Optional: In the SLA field, press the Down Arrow key and select a service-level agreement that defines the suggested and required completion times for the survey. To call the survey from a screen flow: a. In the Flow name field, press the Down Arrow key and select SurveyDriverScFlow. b. In the RouteToOperator field, press the Down Arrow key and select the ID of the user who answers the questions in the survey at run time. 7. Click Submit to close the Subprocess properties dialog box. 8. Click Save. By default, all questions in a flow are displayed on one screen, and each question page in a screen flow is displayed on a separate screen. You can change this behavior by defining a different display method for the survey. Changing the display of questions in a survey You can control whether the questions in a survey are displayed on one screen or individual screens. By default, all questions in a survey are displayed on one screen. 1. Open a flow with a subprocess that calls a survey. 2. Double-click the Subprocess shape to define how the questions in the survey are displayed at run time. 3. In the RunAsScreenFlow field, press the Down Arrow key and select true. 4. In the ScreenFlowType field, press the Down Arrow key and select PagePerScreen or PegaSurvey User Guide 30

31 Integrating a survey with your application QuestionPerScreen, based on your business requirements. 5. Optional: In the IsBreadCrumbReqd field, press the Down Arrow key and select true to add navigation links to each screen in the survey. 6. Click Submit. 7. Click Save. Calling a simple question from a flow You can call a simple question from a flow to ask a user for information while they process a case. By using the Question smart shape, you can quickly add survey functionality to your application without creating the overhead of a survey with question pages. The use of individual questions in a flow is also supported in offline mode. Complex questions are not supported by the Question shape. 1. Open a flow in your application. If you are working offline, open a flow. 2. Click the Shape palette icon to view a menu of shapes. 3. Click and drag the Question shape from the Smart Shapes submenu to a position on the flow diagram. 4. Double-click the Question shape and configure it by doing the following: a. In the Subprocess field, enter a name that describes the purpose of the subprocess. b. In the Select question field, press the Down Arrow key and select the name of a simple question. c. Optional: Select the Required check box. d. Optional: Expand the Advanced section to define the processing that occurs before the question is displayed and after the user submits an answer. A best practice is to always use both pre- and post-javascript and an activity. JavaScript provides offline validation, and the activity provides online validation. JavaScript functions use names without quotes. The JavaScript files should be bundled, attached to the harness, and available during execution. e. Click Submit. 5. Connect the Question shape to other shapes in the flow. PegaSurvey User Guide 31

32 Integrating a survey with your application The flow results on the outgoing connectors from a Question smart shape contain the selected answer value for that question when executed. If the flow path needs to change based on the answer to a question, it can be achieved using the connectors from the Question smart shape. 6. Click Save. At run time, the question is formatted based on the settings on the Simple Question form. PegaSurvey User Guide 32

33 Working with existing surveys in your application Working with existing surveys in your application If you have existing surveys in your application, the following tasks can help you update them or reuse their content in new surveys. Start by reviewing the existing surveys in your application, so that you understand how you can extend or reuse question pages and questions. Reviewing the existing surveys in your application on page 33 Copying a survey on page 34 Updating a question in a survey on page 34 Reusing a question in a survey on page 35 Reviewing the existing surveys in your application Review the existing surveys in your application to understand their purpose and how you can extend or reuse them. 1. Click Designer Studio > Survey Management. 2. In the Type list, select Survey. 3. Enter search criteria in the Advanced Search section, and then click Filter. For example, you can find surveys updated within a specific date range or surveys most recently updated by you. 4. Click Preview to view the question pages and questions in the survey without running the flow that is associated with the survey. After you review a survey, you can copy it or reuse parts of it in another survey. PegaSurvey User Guide 33

34 Working with existing surveys in your application Copying a survey You can copy an existing survey in your application to save time and quickly reuse question pages, formatting, and supporting information. If you edit a question page in a copied survey, your changes affect all surveys that reference the question page. Before copying a survey, use the Application Development landing page to ensure that the underlying survey rule is not checked out by you or another user. To copy a survey: 1. Click Designer Studio > Survey Management. 2. In the Type list, select Survey. 3. Optional: Enter search criteria in the Advanced Search section, and then click Filter. For example, you can find surveys updated within a specific date range or surveys that were most recently updated by you. 4. Click Copy next to the name of the survey that you want to copy. 5. Enter unique values in the Name and ID fields. 6. Review the default values in the Applies To, Ruleset, and Version fields to understand which rules can reference your survey and which rules your survey can reference. You can change these values but specifying a different class or ruleset might make the survey incompatible with the question pages that it contains. 7. Click Copy to add the survey to the list of surveys on the Survey Management landing page. After you copy a survey, you can keep or remove the question pages that it contains. Updating a question in a survey You can update a question after you add it to a survey. The changes that you make affect all surveys and flows that include the question. PegaSurvey User Guide 34

35 Working with existing surveys in your application Note: Although you can access the Simple Question and Complex Question forms directly, use the Survey Management landing page instead to update your questions because it displays the relationship between questions, question pages, and surveys. To update a question: 1. Click Designer Studio > Survey Management, and then click Edit next to the name of a survey that has at least one question page defined. 2. Expand the name of a question page, and then click View/Edit next to the name of a question. 3. Update the question by changing values in the fields that are displayed. 4. Click Save. 5. On the Survey Builder page, click Save. Reusing a question in a survey You can use the same question in more than one survey to save time. 1. Click Designer Studio > Survey Management. 2. Click Edit next to the name of a survey that has at least one question page defined. 3. Right-click the name of a question page and select Add Simple Question > Select Existing or Add Complex Question > Select Existing, based on the type of question that you are reusing. 4. In the ID field, press the Down Arrow key and select the ID of the question to reuse. You can review the configuration of the question in a read-only format before adding the question to the question page. 5. Click Add to append the question to the question page. 6. Click Save. PegaSurvey User Guide 35

36 Considerations for using surveys in offline mode Considerations for using surveys in offline mode A survey gathers data that you can use in your application by presenting a collection of questions to users. In order to execute surveys in your offline-enabled custom mobile applications, you must use the Question smart shapes in flows. Only simple question types are supported in offline mode. If there is a custom validation required for the offline-enabled custom mobile application, the pre- and post- JavaScript parameters must be used instead of an activity. They are only invoked in offline mode and are part of the Question smart shape configuration. Caution! A question used more than once in a survey will have its data overridden in offline mode. PegaSurvey User Guide 36