# Welcome to Plum Insight This is a quick guide that will help familiarize you with Plum Insight and create your first survey. Begin by logging into your account, which will take you to the survey manager. This is where you can create a new survey or manage pre-existing surveys. Users have two options when creating surveys. You can build a survey from scratch, or you can create a survey based on a pre-existing one. For more details on creating surveys, please refer to the [**creating a survey**](/insight/creating-a-survey) page. When you create a survey from scratch, every page of the survey needs to have at least one or more question on it. For more information on question formats, please see the [**question types**](/insight/creating-a-survey/question-types) page. Continue adding pages and questions to your survey until you have asked for all of the information you need. At any time during the survey creation process you can preview the survey, to see what it will look like for your end users, but clicking on the yellow preview button in upper right hand corner of the survey editor. You can additional changes by clicking on the gear icon, located directly above the Save and Preview buttons. Adjust automatically generated prompts at the [**prompt manager**](/insight/prompt-manager) or change top-level settings at the [**survey settings**](/insight/survey-settings) page. Once you are satisfied with your survey, you must deploy it. To do this, you need a phone number to associate with the survey. Click on the “My Account” button at the top of the page and navigate to the Phone Numbers section. If you need a phone number for your survey you can request one from Plum Voice on this screen using the yellow “Request” button. If you don't see a yellow request button, then contact your account administrator in order to obtain a number. After obtaining a phone number, select “Deployments” at the top of the page. Choose “Deploy Survey”. Insight also generates a URL upon deployment so that users can take your survey on the web. This is also where you associate your survey with a phone number. Note, you can assign multiple phone numbers to a single survey if you'd like. Be sure to save all your changes before navigating away from this page. Once your survey is deployed, you can take it by calling the phone number(s) you assigned to it or by using the URL. To see your survey results, select the “Reporting Manager” from the “Reports” menu at the top of the screen. From there you can select “New Report” for your survey. You should note that if no one has taken your survey yet, then there is no visit data to see. Insight cannot run reports on a survey that has no data. The left sidebar has links to additional documentation with more details on specific sections. # How to... # Use Plum's Transcription In Plum Insight transcription functionality is built directly into the **Comment** question type. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4FwhscRQChKN5sELQq%2Fuploads%2Fya3Q1WY29nT3GNIzyG9c%2Finsight-survey.png?alt=media\&token=4ca758ff-a28d-45b9-b910-5d9f3f2f9f86) Simply add a **Comment** question (the microphone icon on the left). Then, click on the gear icon for the question itself and select the ‘Yes’ value for Transcribe Recordings. To view the digital text for the call transcriptions go to the **Reports** section of Insight. Locate the desired survey from the list and click the ‘View Results’ button. On the ‘view results’ page, click the ‘view survey visits’ button. You should see something similar to the image below for any questions with transcription enabled. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4FwhscRQChKN5sELQq%2Fuploads%2FTbw3KthrWCRNvX6qeXVe%2Finsight-visit.png?alt=media\&token=ff54863e-1a15-4c3c-b965-67a4a2520743) Each survey generates a Reporting API URL. This is available on the Survey Visits page. Use this API ([detailed here](https://docs.plumvoice.com/insight/api/survey-response-reporting)) to send survey data to an external repository. (Note: Users will need to parse the survey data on their end.) # Account Manager ## Overview The “My Account” page is a page where administrators can manage survey account information. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dTFuNHqeg-8oXn%2Faccount_manager_account_settings.png?alt=media\&token=cf9ea7ec-2866-4764-a478-32272ab22a5a) ## Managing Account Settings Only administrators can edit Account Settings. This includes basic account information such as: * Company Name * Street Address * City * State * Zip Code * Phone Number # Managing Phone Numbers Only users with administrator privileges can manage phone numbers. Administrators can request, assign, and release the phone number(s) associated with their organization's account. Users creating surveys in Insight must have an account administrator assign them a phone number to use.
## **Requesting Phone Numbers** Click on the “Request a Phone Number” button to request a phone number or a block of phone numbers. This will open a dialog box that enables users to request phone numbers.
In this window users can search for specific phone numbers, select from the phone numbers listed, or refresh the list. ## **Assigning Phone Numbers** Phone numbers requested by administrators are assigned to the requester by default. To assign a phone number to another user within a company's account, simply select the user's name in the dropdown associated with that phone number and click save. ## **Releasing Phone Numbers** To release a phone number, click on the trash icon associated with the phone number and click save. Please note that any active deployments associated with that number will be lost. # Managing User Settings ## Managing User Settings Users can update their first and last name, email address, as well as request or regenerate a developer key. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3d_YzAUj7s0vcbW%2Faccount_manager_user_settings.png?alt=media\&token=c17b410f-1fe0-4775-b4ae-85783cc5e575) ## **Developer Key** The developer key is an advanced feature for users deploying surveys through outbound calling. For more details on how to use developer keys, please see the [**API documentation**](https://docs.plumvoice.com/insight/api). ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dZXSbW40HiEbg0%2Faccount_manager_user_settings_devkey.png?alt=media\&token=36a9117c-b83e-4e24-8dee-b701cae5ff1d) ## Resetting Password The user can change or update their password here. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dYgik885XPjMEi%2Faccount_manager_reset_password.png?alt=media\&token=520e9c33-4568-43c2-ac2d-b6b8cc1cb79f) # Managing Users Administrator have a number of options for managing users. Admins can add, edit, and delete users within their organization's account. The administrator also controls user permissions relating to creating and sharing surveys. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dVqmbsABLdZaiw%2Faccount_manager_manage_users.png?alt=media\&token=8908d5dc-ab27-4e3e-9e18-04de527fbca9) ## Creating Users To add a new user to your organization's account, administrators must navigate to the “My Account” page and click the “Manage Users” button. On the “Manage Users” page, click on the “Add New User” button and enter the appropriate information for the new user in the dialog box. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dUKx3zOFHeVD86%2Faccount_manager_add_user.png?alt=media\&token=ea655f90-f82d-49ca-b9ca-c608bbdc1681) New users will receive an activation email after an administrator submits their user information. New users must follow the instructions in the activation email in order to activate their account and create a password. Once new users complete the activation process they will be able to login and utilize their account based on the permissions set by their administrator.Edit ## User Permissions There are two user permissions: creating and sharing. * **Can Create**: Selecting this option gives the user the ability to create and clone surveys. Users without creation permission cannot create surveys or clone them, even if another user shares a survey with them. * **Can Share**: Selecting this option gives the user the ability to share surveys that they have created or surveys that other users share with them. # Managing Metadata Metadata is an advanced developer feature used in conjunction with the metadata filter and metadata store question types within a survey. For more information on Metadata, please visit the [**Metadata Manager**](/insight/metadata-manager) page. # Creating A Survey ## Creating a Survey Users have two options when creating a survey. They can build their own customer survey or use one of the available templates. ### **Creating Custom Surveys** To begin, navigate to the “Survey Manager” page and click the “Create New Survey” button. This opens a dialog box that presents users with several options. Here users must enter a survey name, select a default language, and decide whether to enable speech recognition.
After entering the requisite information, Insight redirects users to their newly created survey.
### **New From Template** To begin, navigate to the “Survey Manager” page and click the “New From Template” button. This opens a dialog box that presents users with several options. Here users must enter a survey name, select a template from the drop-down menu, and decide whether to include audio prompts.
After entering the information, the user will be redirected to their newly created survey based on the selected template. At this point users can change the template, or add or remove elements to best fit their needs. # Survey Basics The top level survey editor displays the universal survey controls regardless of what page you are on. These survey level functions include: ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dloAD5jmgD_BXW%2Fcreate_survey_toolbar.png?alt=media\&token=e7d90594-1c32-4e93-9c23-b359781b18c0) * Edit the survey name * Navigate to the survey settings and prompt manager pages * Sort survey pages * Navigate through the survey pages * Add new survey pages * Preview the survey * Save the survey ## **Editing Survey Name** To edit the survey name, simply hover over and click on the survey name. This will open a text field where you can enter a new survey name. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3ddVAyYalo1ujFg%2Fcreate_survey_edit_name.png?alt=media\&token=da83bf3e-dfef-4b90-8a7b-702d95f1e035) ## **Navigating To Survey Settings and Prompt Manager** Both the survey settings and prompt manager pages are located under the white gear icon in the top-right corner of the survey editor. Clicking on the gear icon opens a dropdown menu where you can choose either the survey settings or prompt manager. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3de0HaSuUVRt90l%2Fcreate_survey_gear.png?alt=media\&token=9828e1d3-fb79-48c2-8b2b-c54bdd637609) ## **Sorting Pages** Click on the list icon, located on the left-hand side, directly below the Survey Editor text, to manually sort the pages of your survey. This opens a dialog box thats allow you to re-order your survey pages by dragging and dropping them to the desired order.
## **Navigating Pages** To navigate to a specific page in your survey, click the corresponding page number icon. ## **Add A New Page** To add a new page to your survey click the purple plus sign after the page number icons. This will create a new page for your survey and redirect you to it. ## **Survey Preview** To see what your survey will look like to end users, click on the zoom icon. This is the icon with a magnifying glass on it and is located underneath the white gear icon on the left hand side. This opens a new tab that displays the web survey as your end users will see it. ## **Saving A Survey** To save your survey, click on the floppy disk icon. This is located underneath the white gear icon on the right hand side. # Using Pages ## Overview Insight allows users to break surveys into pages. This enables better question organization and allows for more intricate question and page jumps. On each survey page users have access to the following page functions: * Editing Page Name * Page Jumping * Delete The Page * Add Questions To The Page * Sort Questions * Add Sections To The Page * Convert A Question Into A Matrix Of Questions ### **Edit Page Name** To edit the page name, simply hover over and click on the page name. This will open a text field where you can enter a new page name. ### **Page Jumps** A page jump is a transition that occurs when a customer finishes answering all of the questions on a given page. By default, the survey jumps to the next page in the survey. However, users can configure custom page jumps based on caller responses that allows them to jump to a specific page within the survey or to the end of the survey. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3di1HN8m97CopMT%2Fcreate_survey_page_jump.png?alt=media\&token=2ed677ed-2337-497a-8559-a14197e01e00) ### **Delete A Page** To delete the current page click on the trash can icon.Edit ## Questions For information on specific question types, please see [**Question Types**](/insight/creating-a-survey/question-types). ### **Insert A Question** The Insert Question window on the left hand side of the screen contains a list of all of the question types available for Insight surveys. Hover over a question type icon to display the name of a question type. To add a question to the current page, click on the desired question type in the questions list.
Once selected, Insight adds the question to the survey page on the right hand side of the screen. By default, Insight adds new questions to the bottom of the page. Users also have the option to add questions at the top of the page, at the bottom of the page, or to create a new section with the new question as the foundation. To change a question's location, select the desired option from the dropdown beneath the “Insert Question” header, then click on the desired question to add it to your survey. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dcTJzUS08MS_xX%2Fcreate_survey_blank_survey.png?alt=media\&token=8c4b4d50-21d7-4e20-b81b-fd5e0878404b) ### **Sorting Questions** Insight provides two different ways to re-organize the questions on a survey page: drag and drop sorting and “Netflix style” sorting. ### **Drag-and-Drop Sorting** Click on the sort question icon, which is located on the right hand side, next to the trash can icon. This opens a new window that contains a list of all the questions currently on that page of the survey. Users can drag-and-drop the questions to their desired order. ### **"Netflix Style" Sorting** An ode to Netflix's old user interface, Insight allows users to re-sort questions in real-time by entering the a new sequence number in the question's sequence field. Once the user enters the new sequence and clicks off the field, Insight re-orders the questions accordingly. ### **Question Settings** Users can customize each question in their survey by clicking on the gear icon in a specific question container. (This is located in the upper right hand corner of the container, between the red delete icon and the help icon.) Each question will provide a list of options for that question. Note, that applying a change to one question of a given question type does not carry over to other questions of the same type in that survey/page/section. ## Sections A section consists of a group of questions. There is no limit to how many or how varied the questions in a section can be. ### **Adding Sections** To add a new section select “Create New Section” from the dropdown menu in the “Insert Question.” Next, select the question type you want to add to the new section. Click on the corresponding question type and Insight adds that question to a newly created survey section. ### **Sorting Sections** Sorting sections follows the same process used to sort individual questions. Note that re-ordering a section moves every question contained within that section as well. See [Sorting Questions](/insight/creating-a-survey/survey-basics#sorting-pages) for more information. ## Matrices A matrix is a group of questions that meet two criteria: 1. they are the same question type, and 2. they share the same choice options. Note that only the following question types can function as a matrix: Multiple Choice, Multiselect, Scale, and Yes/No. Once a question is converted to a matrix it cannot be reverted back to its original form. ### **Adding a Matrix Question** First, add a matrix-compatible question type to your survey. Second, click on the “Convert to Matrix” link at the bottom right hand side of the question container.
This automatically converts the question into a matrix. Third, in the new matrix container users can type any questions that can be answered with the provided answers. If you have multiple questions in your matrix and want to require callers to answer one or more of the, click on the star to the right of the question within the matrix question container. #### **Sorting a Matrix Questions** Sorting questions within a matrix works in the same way as [Sorting Questions](/insight/creating-a-survey/survey-basics#sorting-pages). # Question Types Plum Insight provides 19 different question types to give users a wide array of data collection options. * [Multiple Choice](/insight/creating-a-survey/question-types/multiple-choice) * [Multiselect](/insight/creating-a-survey/question-types/multiselect) * [Scale](/insight/creating-a-survey/question-types/scale) * [Yes/No](/insight/creating-a-survey/question-types/yes-no) * [Comment](/insight/creating-a-survey/question-types/comment) * [Date](/insight/creating-a-survey/question-types/date) * [Time](/insight/creating-a-survey/question-types/time) * [Currency](/insight/creating-a-survey/question-types/currency) * [Number](/insight/creating-a-survey/question-types/number) * [Digits](/insight/creating-a-survey/question-types/digits) * [Name](/insight/creating-a-survey/question-types/name) * [Address](/insight/creating-a-survey/question-types/address) * [Transfer](/insight/creating-a-survey/question-types/transfer) * [SOAP](/insight/creating-a-survey/question-types/soap) * [Prompt](/insight/creating-a-survey/question-types/prompt) * [Subdialog](/insight/creating-a-survey/question-types/subdialog) * [Metadata Filter](/insight/creating-a-survey/question-types/metadata-filter) * [Metadata Store](/insight/creating-a-survey/question-types/metadata-store) * [Multilingual](/insight/creating-a-survey/question-types/multilingual) # Multiple Choice ## Function *A multiple choice question asks a respondent to choose the best possible answer from a list of choices.* **Choice Text** is the text the respondent will see in the web survey or hear in the phone survey. **Data Value** is the corresponding value which will be used in reports created from the survey data. **DTMF Value** is the number the respondent will press on the phone keypad to select that particular choice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. # Multiselect ## Function *A multiselect question asks a respondent to choose any or all of the possible answers from a list of choices.* **Choice Text** is the text the respondent will see in the web survey or hear in the phone survey. **Data Value** is the corresponding value which will be used in reports created from the survey data. **DTMF Value** is the number the respondent will press on the phone keypad to select that particular choice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. # Scale ## **Function** *A scale question measures a respondent's opinion as a point on a scale of values.* **Choice Text** is the text the respondent will see in the web survey or hear in the phone survey. **Data Value** is the corresponding value which will be used in reports created from the survey data. **DTMF Value** is the number the respondent will press on the phone keypad to select that particular choice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. # Yes/No ## **Function** *A yes/no question asks a respondent to answer a question by choosing either yes or no (true or false).* **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. For phone surveys, DTMF-1 is affirmative and DTMF-2 is negative. # Comment ## **Function** *Comments allow respondents to leave open-ended responses that may not be covered by other survey questions.* For web surveys, a textbox will be displayed for the respondent. On phone surveys, a call recording will capture the respondent's comments in an audio file. {% hint style="info" %} Users can automatically transcribe audio recorded by the Comment question type. [See here for information about using the Transcription API with Insight](https://docs.plumvoice.com/documentation/using-the-plum-voice-suite/how-to-guides/using-plums-transcription-api#insight). {% endhint %} # Date ## **Function** *A date question asks a respondent on which day a specific event occurred.* For phone surveys, the date can either be spoken or entered on the phone keypad in *YYYYMMDD* format. # Time ## **Function** *A time question asks a respondent at which time a specific event occurred.* For phone surveys, the time can either be spoken or entered on the phone keypad in HHMM format. Note: Users can choose between 12-hour and 24-hour formats for time questions in the question's settings menu. # Currency ## **Function** *A currency question asks a respondent for a monetary value in US dollars.* For phone surveys, the currency can either be spoken or entered on the phone keypad, using the star key as a decimal point. # Number ## **Function** *A number question asks a respondent for any value. It may be a whole number or a decimal.* For phone surveys, the number can either be spoken or entered on the phone keypad, using the star key as a decimal point. # Digits ## **Function** *A digits question asks a respondent for any whole number.* # Name **Function** *A full name question asks a respondent for their first and last name.* For phone surveys, respondents will be asked to say their name, and then spell it. # Address ## **Function** *An address question asks respondents for their address.* You may choose to ask for the following levels of detail: **Full US Address** Asks respondents for a complete US address broken into: Street Address, Apartment/Suite Number, City, State, and Zip code. **US Zip Code** Asks respondents for a US zip code. **State/Province** Asks respondents for either a US state or, if enabled, a Canadian province. **City and State/Province** Asks respondents for a city and either a US state or, if enabled, a Canadian province. The Canadian province toggle is located in the settings menu of the address question type. By default, this option is turned off. # Transfer ## **Function** *A transfer question transfers the respondent to a phone number of your choosing.* {% hint style="info" %} This is a ***phone only*** question type. {% endhint %} # SOAP ## **Function** *A SOAP webservice question type allows you to apply logic to survey responses and integrate them with your own business processes using a webservice you provide.* **SOAP webservice URL** is the link for the webservice. **Result** is the response the survey might expect back from the webservice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the aresult returned from the webservice. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. # Prompt ## **Function** *A prompt is a message, usually for clarification, displayed in the web survey or played in the phone survey to the respondent.* # Subdialog ## **Function** *A subdialog question allows you to apply additional logic to your survey using an external VXML document.* **Subdialog URL** is the link to the subdialog. **Result** is the response the survey might expect back from the webservice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the result from the subdialog. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. {% hint style="info" %} This is a ***phone only*** question type. {% endhint %} # Metadata Filter ## **Function** *A metadata filter question filters the rows in the survey's associated database based on the respondent's input.* **Database Name** is the name of the metadatabase associated with your survey. **Column to Filter On** is the column used to filter the database based on the respondent's input. **Input Type** determines what type of input the respondent needs to enter. For sensitive data, use the password type. **Choice** describes the possible outcomes of a metadata filter. You can apply skip logic depending on whether the respondent's input matches a metadata value. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. The [**Metadata Manager**](/insight/metadata-manager) page contains detailed instructions on how to utilize metadata in your survey. # Metadata Store ## **Function** *A metadata store question saves the currently filtered metadata rows as an answer for that question.* **Database Name** is the name of the metadatabase associated with your survey. **Column Data to Store** is the column that will be stored as the answer. The [**Metadata Manager**](/insight/metadata-manager) page contains detailed instructions on how to utilize metadata in your survey. # Multilingual ## **Function** *A multilingual question asks a respondent to choose their desired language from the provided list.* **Language** is the language choice for the survey. It will auto-populate with all the languages associated with your survey. **DTMF Value** is the number the respondent will press on the phone keypad to select that particular choice. **Skip logic** is an advanced choice option that redirects the respondent to the designated page based on the answer they chose. This feature is turned off by default. To enable skip logic, clicking the question's settings icon and select “Yes” for the Show Skip Logic option. # Prompt Manager ## Overview The prompt manager is where you can customize the wording for your surveys' default prompts and buttons. You can also upload audio to be played in place of Text-to-Speech (TTS) generated prompts in phone surveys. To make these changes, go into the survey, click on the gear located near the top of the page, and select “Prompts” from the dropdown menu. On this page, prompts are divided by language and prompt type (Text or Audio). ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eJuRoaqu_1aLFS%2Fprompt_manager_menu.png?alt=media\&token=d7f9795f-8613-4862-83cb-b5f2e30dbfa3) ## Text Prompts Text prompts are prompts that are either displayed as text on web surveys, or read out using TTS on phone surveys.
### Types of Text Prompts | Type | Description | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Built-in | Built-in prompts appear throughout the survey and provide status information or direct the flow of the survey. They also include prompts displayed as a welcome or ending message for the survey taker. It may be useful, for instance, to include a link to a website at the end of a survey. | | Button | Button prompts are displayed on buttons for web surveys. You may wish to change the “next” button into a “continue” button, for instance. | | Error | Error prompts are displayed whenever an error occurs with a survey taker's input. They might contain further instructions on how to submit a correct response. | | Alert | Alerts are additional prompts in case other miscellaneous errors occur. | ### Text Prompt Locations Each prompt is displayed online, played over the phone, or both. The location icon next to each prompt indicate where that prompt will be played or displayed.
## Audio Prompts The audio prompts tab contains a list of all possible prompts that would be played over the phone for the survey. When you first create your survey, all prompts will be read by the TTS engine, but you may upload human-recorded audio to be played for each prompt instead.
The following audio formats are supported: * 8 kHz 16-bit linear PCM WAV (\*.wav) * 8 kHz 8-bit µ-law WAV (\*.wav) * 8 kHz 8-bit a-law WAV (\*.wav) * MP3 (\*.mp3) - Note: If the audio file is poorly encoded, the mp3 will not work. To upload an audio file for a single prompt, simply click on the upload button next to the prompt you want to upload. You can also update multiple prompts by providing a zip file containing all of the audio, but each file must be named a specific way for the tool to recognize which prompt to update. You can find these filenames by clicking on the “Export CSV” button. The downloaded CSV files will list the appropriate filenames along with the corresponding prompt in text. After audio has been uploaded, you can also playback the prompts, download them, or delete them within the same page.
{% hint style="danger" %} **\*\*This feature is not intended for production surveys.\*\***\ \ The **Call to Record** button allows you to record audio prompts with your phone. To use it, click the button and follow the on-screen instructions. It will only prompt you to record prompts that don't already have an audio file, so please delete any audio files you wish to record over.\ \ **This feature does not produce professional quality audio recording. Using these recordings in production surveys can result in a poor caller experience.** {% endhint %} ## Adding Languages You can also customize prompts for your survey for different languages. To add more languages, click on the “Add Languages” button, and then choose the language you wish to add from the modal window.
# Bulk Uploading for Audio Prompts ## Introduction The Audio Manager allows you to upload your own human-recorded audio files for any or all prompts in an survey. While you can upload your recorded audio files one-by-one to the desired prompts, you may want to upload files for multiple prompts all at once. This guide describes how to bulk upload audio prompts in the Audio Manager, which includes the following steps: 1. Exporting all prompt filenames 2. Renaming your audio files to match your target prompts 3. Adding these renamed audio files to a `.zip` archive 4. Uploading the `.zip` archive to apply the renamed audio files 5. Testing your new audio prompts {% hint style="info" %} **Note:** Bulk uploading is meant to make multi-file uploads of audio prompts efficient. However, this will work even if you are uploading for only one. This guide assumes that your Insight survey has at least two or more prompts. {% endhint %} ### Prerequisites 1. **All of your intended custom audio prompts, recorded in a compatible file format.** \ See [Audio Prompts](https://docs.plumvoice.com/insight/prompt-manager#audio-prompts) to decide for which prompts you'd like to record an audio file. If you do not already have a preferred recording application, Plum recommends the free Audacity application to record audio: 2. **A spreadsheet application.** \ Examples include Microsoft Excel and Google Sheets. You will use this to view a `.csv` spreadsheet. 3. **A `.zip` application.** \ Many current operating systems have built-in `.zip` utilities. A free alternative is 7-Zip. You should be familiar with how to create a `.zip` archive using your chosen application. 4. [**Review the docs on Audio Prompts.**](https://docs.plumvoice.com/insight/prompt-manager#audio-prompts) Terms and user interface elements discussed here are similarly covered in this documentation. ### Recommendations 1. **Finish building your Insight survey first.** \ Once finished, you will likely have a finalized list of prompts in the Prompt Table. This would allow you to bulk upload for all prompts in one effort – or as few efforts as possible. ## Step 1: Export a spreadsheet of prompt filenames [Log in to Insight](https://insight.plumvoice.com/account_manager/login). In the Survey Manager, select the desired survey. In the Survey Editor, select the gear icon, then select **Prompts**. The Audio Manager will be displayed as shown in Figure 1.

Figure 1: Audio prompts in the Audio Manager.

Select the tab for the desired language, then select **Export CSV**. Save the `.csv` spreadsheet in a memorable location, and open it in your chosen spreadsheet application. The spreadsheet should contain a **filename** column and a **prompt** column as shown in Figure 2.

Figure 2: The exported list of audio prompt filenames.

These filenames correspond to each prompt in your survey. **Your audio file must use the same filename as its intended prompt.** ## Step 2: Rename your audio files Read the spreadsheet to locate each prompt that will receive an audio file. Figure 3 provides an example of how the prompts listed in the Audio Manager and the spreadsheet compare.

Figure 3: Prompts in the Audio Manager compared with the exported .csv spreadsheet.
Select this image to zoom in.

Confirm the prompt's filename, and rename the desired audio file to match it exactly**\***. This allows the Audio Manager to identify which prompt should receive that audio file from your bulk upload. {% hint style="info" %} **\*Note:** The file type does not have to match, but it must be compatible with Insight. \ See [Audio Formats](https://docs.plumvoice.com/insight/prompt-manager#audio-prompts) for more information. {% endhint %} ## Step 3: Add your audio files to a ZIP archive Add the renamed audio files to the same folder or directory, then add them to a `.zip` archive. Save the `.zip` archive in a memorable location. ## Step 4: Upload the ZIP archive Select **Upload Zip**. In the File Upload window, navigate to the folder or directory containing the `.zip` archive, select it, then select **Open**. The `.zip` archive will be uploaded, and the Audio Manager will apply each renamed audio file within to the prompt with a matching filename. All other prompts will remain unchanged. {% hint style="info" %} **How do I know the upload(s) worked?** Look for the following icons to distinguish prompts: * ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4FwhscRQChKN5sELQq%2Fuploads%2FFjcinoDXf0LyE2Vr4RpQ%2Ftts%20prompt%20icon.png?alt=media\&token=d6c8eb5c-12b4-43ae-9fb6-b1ce4ce63555) **TTS**: Default prompt type. Indicates no audio file is attached. * ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4FwhscRQChKN5sELQq%2Fuploads%2Fp09wr3qSQIu5KBtH3S50%2Faudio%20prompt%20icon.png?alt=media\&token=61f0f6aa-9f11-4fa4-a69e-707937be4407) **Audio**: These prompts have an uploaded audio file attached. **Look for these.** {% endhint %} {% hint style="warning" %} **Note:** Any uploaded recordings **will override** any text entered for a survey's prompt field. {% endhint %} ## Step 5: Test the prompts In the Prompt Table, review the list of audio prompts. Select the **Play** button on each one, and listen to the entire playback to confirm that each prompt uses the correct audio file and that the audio plays as desired. Figure 4 provides an example.

Figure 4: Select the Play button for each prompt that has it.
Listen to the playback to ensure that each prompt works as intended.

Finally, create a deployment with the survey and dial the number of your deployment to test it. During your test calls, select each option connected to your prompts and ensure that each audio prompt plays back as intended. ### Troubleshooting If any audio prompts fail, open the survey in the Survey Editor, go to the Audio Manager, and check the following in order: 1. **Was an audio file uploaded to the correct prompt?** Carefully check the filenames you used for each audio file. They must be entered exactly as given in the `.cvs` spreadsheet, and each filename is linked to a specific prompt in your application. 2. **Is the audio file in a compatible format and file size?** Review the guidelines described under [Audio Prompts](https://docs.plumvoice.com/insight/prompt-manager#audio-prompts) and verify that your audio files match them. 3. **Does a failing prompt play any audio at all when you select the Play button?** If not, try reuploading the desired audio file. File damage could also prevent playback. ## Conclusion If no issues are found, you've successfully bulk uploaded audio prompts for your survey. # Survey Settings ## Metadata The metadata section is used to associate a survey with a metadatabase. Please see the [**Metadata Manager**](/insight/metadata-manager) documentation for more information. ## Additional Settings * [Phone](/insight/survey-settings/phone) * [Web](/insight/survey-settings/web) * [Mobile](/insight/survey-settings/mobile) # Phone The phone section allows users to modify the settings that control the end-user experience when taking a survey via the phone. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3f3aQkVclWWNXEP%2Fsurvey_settings_phone.png?alt=media\&token=d325d4e1-cef5-4435-ab52-218545dfc009) ### **Default Language** This field displays the current default language. It becomes a dropdown menu after adding additional languages to a survey through the [**Prompt Manager**](/insight/prompt-manager). Users can set the default language for their survey using the dropdown menu. The default survey language is English (U.S.A.). {% hint style="warning" %} **Note:** Changing the default language deletes all of the text and audio prompts already uploaded into the prompt manager. {% endhint %} ### **Speech Recognition** By default, surveys do **not** have Automatic Speech Recognition (ASR) enabled. This means that all survey responses need to be entered via DTMF. Some question types automatically enable ASR for those specific questions. For example, the comment question type accepts voice input even if ASR is not universally enabled for that survey. When ASR is enabled globally for a survey, callers have the option to answer a question via either DTMF or speech. The built-in prompts will also be adjusted based on whether ASR is enabled. ### **Allow Immediate Skip Logic** This option controls how the advanced skip logic within a survey functions. This setting is enabled by default. Therefore, whenever a caller selects an answer that has skip logic configured, the skip logic occurs immediately. When this setting is disabled, the skip logic occurs once the caller reaches the end of the page. When importing a survey from Plum's old survey tool, the Allow Immediate Skip Logic value defaults to disabled to match the behavior of that platform. ### **Section Titles** This setting determines whether users will hear the section titles when taking the survey. By default, this setting is enabled. ### **Page Titles** This setting determines whether users will hear the page titles when taking the survey. By default, this setting is enabled. ### **Assistance Prompt DTMF Value** This setting allows you to set the DTMF value that end-users select to transfer to an assistance telephone number. By default, this value is empty. Setting a value for this option automatically generates a new prompt in the prompt manager. When enabled (for example, “\*0” or “021345”) this value also generates an Assistance Phone Number field. ### **Assistance Phone Number** This is the telephone number where the survey transfers users who enter the Assistance Prompt DTMF value, set above. This setting is language-specific so end-users are transferred to a Customer Service Representative (CSR) who speaks their language. By default, this field is not shown until the Assistance Prompt DTMF Value is set. ### **TTS Voice** This dropdown menu contains a list of text-to-speech (TTS) voices available for your surveys. Setting the default language TTS engine determine which TTS voices are available. When incorporating TTS into a survey, you must use the same TTS engine for all TTS within that survey. Please note that certain language options have limited TTS support. {% tabs %} {% tab title="AT\&T Natural Voices 1.4" %} | Language | Name | Gender | Audio Sample | | ------------------------- | -------- | ------ | ------------ | | American English (en\_us) | Mel | male | | | American English (en\_us) | Mike | male | | | American English (en\_us) | Ray | male | | | American English (en\_us) | Rich | male | | | American English (en\_us) | Claire | female | | | American English (en\_us) | Crystal | female | | | American English (en\_us) | Julia | female | | | American English (en\_us) | Lauren | female | | | Spanish (es\_us) | Alberto | male | | | Spanish (es\_us) | Rosa | female | | | British English (en\_uk) | Charles | male | | | British English (en\_uk) | Anjali | female | | | British English (en\_uk) | Audrey | female | | | French (fr\_fr) | Alain | male | | | French (fr\_fr) | Juliette | female | | | German (de\_de) | Reiner | male | | | German (de\_de) | Klara | female | | | {% endtab %} | | | | {% tab title="Cepstral Engine 4.1" %} | Language | Name | Gender | Audio Sample | | ------------------------- | -------- | ------ | ------------ | | American English (en\_us) | David | male | | | American English (en\_us) | William | male | | | American English (en\_us) | Diane | female | | | Spanish (es\_us) | Miguel | male | | | Spanish (es\_us) | Marta | female | | | British English (en\_uk) | Lawrence | male | | | British English (en\_uk) | Millie | female | | | {% endtab %} | | | | {% tab title="RealSpeak Engine 4.0" %} | Language | Name | Gender | Audio Sample | | ---------------------------- | -------- | ------ | ------------ | | American English (en-US) | Tom | male | | | American English (en-US) | Jennifer | female | | | American English (en-US) | Jill | female | | | American English (en-US) | Samantha | female | | | Mexican English (es-MX) | Javier | male | | | Mexican English (es-MX) | Paulina | female | | | British English (en-GB) | Daniel | male | | | British English (en-GB) | Emily | female | | | Australian English (en-AU) | Lee | male | | | Australian English (en-AU) | Karen | female | | | Canadian French (fr-CA) | Felix | male | | | Canadian French (fr-CA) | Julie | female | | | Portuguese (pt-PT) | Madalena | female | | | Brazilian Portuguese (pt-BR) | Raquel | female | | | German (de-DE) | Steffi | female | | | {% endtab %} | | | | | {% endtabs %} | | | | # Web The web section contains all of the settings related to the user experience when taking a survey online. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3f4w3wPfeW4p5o4%2Fsurvey_settings_web.png?alt=media\&token=fffaf34e-3911-4b8d-bd15-0965168e066b) ### **Use Custom Stylesheet** This setting determines whether your survey utilizes a custom CSS stylesheet or the built-in CSS stylesheet. By default, this is set to “No,” which styles your survey based on the built-in CSS stylesheet. Choosing “Yes” generates 2 additional buttons. Click on the “Base CSS” link to download the CSS structure utilized by the survey tool. Use the Base CSS to fully customize the look and feel of your survey. Click on the “Upload File” button to upload your new CSS stylesheet. To view your custom stylesheet after uploading it, click on the “View CSS” link to download the stylesheet. Click on the red X button to delete your current stylesheet. For CSS references, please see [CSS Tutorial](http://www.csstutorial.net/) or [W3Schools CSS Tutorial](http://www.w3schools.com/css/). ### **Progress Indicator** This determines if end users will have a visible progress indicator while they take the survey. By default, this setting is enabled. ### **Required Indicator** This determines if end users see an icon to indicate any survey questions that have been marked as required within the [**Editor**](/insight/creating-a-survey). By default, this setting is enabled. ### **Back Button** This determines whether end users have access to a “back” button while taking the survey. This allows end users to return to previous questions and to change their answers. By default, this setting is enabled. The text for this button can be changed within the [**Prompt Manager**](/insight/prompt-manager). ### **Auto-redirect** This determines how the survey tool displays the survey Exit URL to end users. There are 3 different options: “Link Only,” “After 5 Seconds,” and “Immediately”. By default, the setting is “Link Only”. *Link Only:* The survey tool sends end users to a completion page for a survey that provides a link to the Exit URL. *After 5 Seconds:* The survey tool directs end users to a completion page for 5 seconds before automatically redirecting them to the Exit URL. *Immediately:* The survey tool does not direct end users to a completion page and immediately redirects them to the Exit URL. ### **Upload Logo** This allows you to upload a custom logo that displays while end users take the survey. By default, this value is empty. You can remove your custom logo by clicking on the red X button to the right of the image. The maximum width of the logo is 460px. There is no maximum height. Images larger than 460px in width will be shrunk to that size. ### **Exit URL** This determines the URL provided to the end user at the completion of the survey. A unique URL can be provided for each language of the survey. By default, this value is empty. # Mobile The mobile section contains all of the settings related to the user experience when taking a survey via a web browser on a mobile device. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3f2BY7VLNJ2mPRX%2Fsurvey_settings_mobile.png?alt=media\&token=05908871-778d-4287-8d1e-2df2f7adedc5) ### **Progress Indicator** This determines if end users will have a visible progress indicator while they take the survey. By default, this setting is enabled. ### **Required Indicator** This determines if end users see an icon to indicate any survey questions that have been marked as required within the [**Editor**](/insight/creating-a-survey). By default, this setting is enabled. ### **Back Button** This determines whether end users have access to a “back” button while taking the survey. This allows end users to return to previous questions and to change their answers. By default, this setting is enabled. The text for this button can be changed within the [**Prompt Manager**](/insight/creating-a-survey/question-types/prompt). # Metadata Manager ## Overview The Metadata Database Manager allows users to create and edit databases associated with your survey(s). This association is made by means of the Metadata Filter and Metadata Store survey [**question types**](/insight/creating-a-survey/question-types). Be sure to familiarize yourself with these questions types *before* utilizing a metadatabase in your surveys. A thorough understanding of how the Metasurvey question type works is critical when using a metadatabase. ### **Metadata Filter** The Metadata Filter question type provides a way to filter the rows of a metadatabase from within a survey. A Metadata Filter question allows you to choose a column from your metadatabase to apply a filter to. When the end user takes this survey, the value entered for the Metadata Filter question type will be the value the metadatabase is filtered on when the question is processed. **Example:** Assume you have the following metadatabase (represented as CSV): ``` “userID”,“FirstName”,“LastName”,“FavoriteColor” “1”,“Dennis”,“Seidenberg”,“blue” “2”,“Adam”,“McQuaid”,“red” “3”,“Zdeno”,“Chara”,“black” “4”,“Dougie”,“Hamilton”,“green” “5”,“Tory”,“Krug”,“blue” “6”,“Kevan”,“Miller”,“orange” ```
The Metadata Filter question type in the survey filters results on the “FavoriteColor” column. What happens when a user takes the survey and enters the value “blue” for this Metadata Filter question? Insight searches the metadata column “FavoriteColor” for the value “blue” and keeps the rows that have “blue” in the “FavoriteColor” column. Based on the metadatabase in the example, the Metadata Filter matches the following rows: ``` “1”,“Dennis”,“Seidenberg”,“blue” “5”,“Tory”,“Krug”,“blue” ``` ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3e0VQSDZlzgRR_k%2Fmetadata_2.png?alt=media\&token=fb8006e0-4ee7-40f0-adf0-2bb49b310901) Subsequent Metadata Filter questions that come after the “FavoriteColor” filter question will filter on the matched data set that resulted from the first “FavoriteColor” filter question. For example, add another Metadata Filter question to the example survey after the “FavoriteColor” filter question that filters on the “LastName” column. When the end user entered a value of “blue” for the first Metadata Filter question type, the question returned the following matches: ``` “1”,“Dennis”,“Seidenberg”,“blue” “5”,“Tory”,“Krug”,“blue” ``` ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3e0VQSDZlzgRR_k%2Fmetadata_2.png?alt=media\&token=fb8006e0-4ee7-40f0-adf0-2bb49b310901) The same end user then enters a value of “Krug” for the second Metadata Filter question that filters on the “LastName” column. The filtered results at this point match **both** Metadata Filter questions. Therefore, the filter returned every row that contains a “FavoriteColor” value of “blue” and a “LastName” value of “Krug”. Based on these parameters, these Metadata Filter questions return a single row. ``` “5”,“Tory”,“Krug”,“blue” ``` ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3e1o7aKobdMjIQP%2Fmetadata_3.png?alt=media\&token=2d72a818-e877-4120-833d-1e25bad423d6) You can only filter on each column once. For example, an attempt to filter the above results on “FavoriteColor” again, this time with a value of “red” would return no matches because there is no row that contains both a “LastName” value of “Krug” and a “FavoriteColor” value of “red.” {% hint style="info" %} **Note:** When taking a survey over the phone it is only possible to filter on numeric data. End users cannot speak a phrase and match it to the metadatabase. Non-numeric values must be associated with a numeric ID that can be used to match the metadata. {% endhint %} Filtered metadata results can be used further with the Metadata Store question type. ### **Metadata Store** The Metadata Store question type stores the column values for any rows matched in your Metadata Filter question types. This example uses the above example to demonstrate how to store column values from previously filtered and matched metadata rows. Begin with the same metadatabase: ``` “userID”,“FirstName”,“LastName”,“FavoriteColor” “1”,“Dennis”,“Seidenberg”,“blue” “2”,“Adam”,“McQuaid”,“red” “3”,“Zdeno”,“Chara”,“black” “4”,“Dougie”,“Hamilton”,“green” “5”,“Tory”,“Krug”,“blue” “6”,“Kevan”,“Miller”,“orange” ```
Add a Metadata Filter on the “FavoriteColor” column with the end user selecting “blue” as their answer. ``` “1”,“Dennis”,“Seidenberg”,“blue” “5”,“Tory”,“Krug”,“blue” ```
To store some values from the matched metadata rows add a Metadata Store question to your survey. When adding a Metadata Store question type, you need to specify which metadatabase column you wish to store as the question's answer. For example, assume you chose to store the “userID” column. {% hint style="info" %} **Note:** Be sure to place the Metadata Store question **after** the Metadata Filter questions in your survey. To be effective, it is necessary to filter the metadatabase before storing values from it. {% endhint %} With a Metadata Store question created to store values from the “UserID” column, Insight stores the following values as the answer to the Metadata Store question, based on the matched rows: ``` “1”,“5” ``` This is how you filter a metadatabase on columns using the Metadata Filter question type and then store the column values from the matched rows using the Metadata Store question type. # Layout ## Layout ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eAx8ZWkgPkhdC8%2Fmetadata_overview.png?alt=media\&token=5855a163-062a-4d5e-80f4-4d292c217d81) This is the Metadata Manager interface. 1. **Metadatabase Name**: The name of the currently selected metadatabase. You can edit the name by clicking on it and modifying the text. 2. **Metadatabase Description**: An optional, brief description for the metadatabase. You can edit this description by clicking on it and modifying the text. 3. **Save**: Save any changes you have made to the metadatabase. This includes changes to the name or description of the metadatabase and the removal/modification/addition of rows, columns, and cells. **Note:** No changes are permanent until the changes are saved. 4. **Close**: Close the current metadatabase and takes it out of edit mode. **Note:** All unsaved changes will be lost when the metadatabase is taken out of edit mode. 5. **Download CSV**: Download your entire metadatabase to a CSV file. This is a quick way to create a new metadatabase from a CSV file or to make bulk changes to your database in an external program like excel, which can be more convenient than using the editor itself. 6. **Upload CSV**: Displays a dialog that allows users to upload a CSV file to overwrite the existing metadatabase. Uploading a new CSV overwritse the columns and data of the current metadatabase with the columns and data in the uploaded CSV file. It is recommended to use this feature in conjunction with the Download CSV function in order to make bulk changes to a metadatabase in an external program and then overwrite the old database by uploading the new, modified CSV file. 7. **Metadatabases**: Select a metadatabase to put it into edit mode. A metadatabase must be in edit mode for a user to modify it. Metadatabases associated with a survey will have a purple icon in this list. Hovering over the database displays the name of any surveys associated with that metadatabase. 8. **Delete Metadatabase**: Click the trash can icon for a metadatabase to delete it. Insight prompts users with a dialog window to confirm the deletion of a metadatabase. 9. **Add Row**: Add a new, empty row at the end of your metadatabase. 10. **Add Column**: Add a new column to your metadatabase. The default naming of new columns follows the “ColumnX” convention where x is the numeric value for the column. For example, adding a column to a metadatabase with four columns will default to the name “Column5” because it is the fifth column in your metadatabase. 11. **Modify Column Name**: Click on the column name to modify it. 12. **Delete Column**: Click on the 'x' when hovering over a column name to delete the column. If any surveys utilize this column, Insight prompts users with a dialog window to inform them of that fact and asks to confirm the deletion. 13. **Delete Row**: Click on the 'x' when hovering over a row number to delete that row. # Creating a Metadatabase To create a new metadatabase, first make sure that no metadatabase is currently selected in the list of metadatabases. Then click the “New Metadatabase” button. This will open a dialog window.
This window contains three inputs: * **Database Name**: The name for the new metadatabase; this is the only required field. Metadatabase names can range from 1-255 characters. **Note:** Each metadatabase requires a unique name. Insight does not support duplicate metadatabase names. * **Database Description**: Enter an optional description for the metadatabase in this field. The metadatabase description can range from 1-255 characters. It is not necessary to add a description for the metadatabase and this field can be left empty if desired. * **Upload CSV**: Use a CSV file to pre-populate the columns and data of a metadatabase. Uploading a CSV file is optional. Failure to do so simply results in a new, empty database. Click the yellow “Submit” button to create the metadatabase. To dismiss this window and abandon the creation of a new database click the grey “Cancel” button or the 'x' in the upper right hand corner. ### **Creating An Empty Metadatabase** To create a new, empty metadatabase: 1. Make sure no metadatabase is currently selected in the metadatabase list. 2. Click “New Database” to open the “create metadatabase” dialog window. 3. Fill in the **Database Name** and, optionally, the **Database Description** fields. 4. Click “Submit.” A new metadatabase appears in the list of metadatabases. If any errors occur during this process, such as a metadatabase with a duplicate name, the dialog window will remain open and display the corresponding error. {% hint style="info" %} **Note:** when creating an empty metadatabase the default columns follow the “ColumnX” convention, e.g., “Column1”,“Column2”,“Column3”,“Column4”,“Column5”. {% endhint %} ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3e7YwwIjYOhMS-0%2Fmetadata_new_empty.png?alt=media\&token=299bfe3a-4390-4aae-b879-6488b9c5bd05) ### **Creating a Metadatabase from an Existing CSV** To create a metadatabase and pre-populate it with columns and data from a CSV file: 1. Make sure no metadatabase is currently selected in the list of metadatabases. 2. Click “New Database” to open the “create metadatabase” dialog window. 3. Fill in the **Database Name** and, optionally, the **Database Description** fields. Then click “Select Files” to browse your computer for the CSV file and upload it. 4. Once the upload completes, click “Submit.” The dialog window closes and the new metadatabase appears in the list of metadatabases. If any errors occur during this process, such as a metadatabase with a duplicate name, the dialog window will remain open and display the corresponding error. # Viewing/Editing a Metadatabase Users that need to make extensive changes to a metadatabase, may prefer to download an entire metadatabase, make edits in an external program, like Excel, and then upload that modified file to Insight, overwriting the current metadatabase. Insight's user interface allows users to modify a metadatabase within the platform as well. {% hint style="info" %} **Note:** It is necessary to “Save” any changes made to a metadatabase before selecting a different metadatabase or navigating away from the page. Any unsaved changes will be lost. {% endhint %} ### **Editing the Metadatabase Name and Description** When the metadatabase is in edit more, click on either the metadatabase name or description to edit them. This makes the respective field editable, allowing users make changes as necessary.
### **Adding a Column** To add a new column to a metadatabase, select a metadatabase in the metadatabase list and put it into edit mode. Click “Add Column” in the upper right hand corner of the window. This adds a new column to the metadatabase with the naming taxonomy of “ColumnX” where X represents the number of columns in the metadatabase. Click the name of the newly added column to modify its name. ### **Adding a New Row** To add a new row to a metadatabase, select a metadatabase in the metadatabase list and put it into edit mode. Click “Add Row” at the bottom of the metadatabase window. This adds a new, empty row to the metadatabase. Click in the cells of the row to add data to the cells in that row. {% hint style="info" %} **Note:** Adding a row to a large database shifts the view of the metadatabase to display the new row, located at the bottom of the list of rows. {% endhint %} ### **Deleting a Row** To delete a row, hover over the row number and a small red 'x' appears in the upper right hand corner of the cell. Clicking on the red 'x' removes the row from the metadatabase. ### **Deleting a Column** To delete a column, hover over the column name and a small red 'x' appears in the upper right hand corner of the cell. Clicking on the red 'x' removes the column from the metadatabase. If the column being deleted is used in any survey questions, Insight prompts users with a dialog window to confirm the column deletion. Deleting a column that is in use removes any metadata questions from your surveys that reference the column. {% hint style="info" %} **Note:** Insight automatically saves the metadatabase after deleting a column with dependencies. {% endhint %} If no surveys utilize the column then it will simply be deleted. ### **Editing a Cell** The edit the value in a specific cell of the metadatabase, simply click in the desired cell and enter or modify the data there as desired.
### **Saving Changes** It is necessary to click the 'Save' button to commit changes to a metadatabase. All edits remain as pending changes until the 'Save' button is clicked. When conducting a significant number of edits to a metadatabase within the Insight platform, it is best to click the 'Save' button regularly to ensure all the changes are saved. # Managing a Metadatabase ## Deleting a Metadatabase To delete a metadatabase, select the metadatabase from the metadatabase list. Click the trash can icon next to the metadatabase name. This opens a dialog window to confirm the metadatabase deletion.
Clicking “Yes” confirms the deletion. Clicking 'Close' or the 'x' in the upper right of the dialog window dismisses the window without making any changes to the metadatabase. ### **Deleting With Dependencies** Any metadatabase currently being utilized by a survey has a purple icon displayed in the metadatabase list.
Hover over the purple database icon to see a list of surveys that utilize a given metadatabase. Deleting an active metadatabase results in the the removal of all metadata question types that use that metadatabase from all surveys that are dependent on the metadatabase. In other words, deleting an active metadatabase deletes all of the questions associated with that metadatabase in all of your surveys.Edit ## Downloading a Metadatabase To download a metadatabase as a CSV: 1. Select the metadatabase from the metadatabase list and put it in edit mode 2. Click “Download CSV” 3. Insight outputs a CSV file of the metadatabase to view or save to a local computer ## Uploading a Metadatabase Uploading a CSV overwrites metadatabase columns and data values. 1. Select the metadatabase from the metadatabase list and put it into edit mode 2. Click “Upload CSV” 3. Click “SELECT FILES” 4. This opens a window that allows users to navigate their local drive to select a file to upload. 5. Once the upload completes, click “Yes” to commit the overwrite. To dismiss the upload and not overwrite the existing metadatabase click “Close” or the “x” in the upper right corner of the dialog window. # Formatting Metadatabase CSV CSV files uploaded to Insight for use as a metadatabase must be properly formatted. The first row of the CSV file must **only** contain the column names. If actual data is in the first row, Insight will recognize that data as the column names. An example header is:\ “userID”,“FirstName”,“LastName” Every row afterwards should contain the actual data. To match the above header, we could have the following sample rows: ``` “1”,“Jerry”,“Garcia” “2”,“Harry”,“Nilsson” “3”,“David”,“Bowie” “4”,“Paul”,“Simon” “5”,“George”,“Harrison” ``` Compiled together the complete CSV file looks like: ``` “userID”,“FirstName”,“LastName” “1”,“Jerry”,“Garcia” “2”,“Harry”,“Nilsson” “3”,“David”,“Bowie” “4”,“Paul”,“Simon” “5”,“George”,“Harrison” ``` If you have difficulty formatting a metadatabase, one workaround is to create a new, empty metadatabase in Insight. Then, populate a single row with data. This does not need to be any specific data as this is simply for formatting purposes. Next, download the CSV using the “Download CSV” button. Open the CSV file and modify it as necessary. To convert a pre-existing .XLX or .XLSX to a CSV, be sure to select “save as” when saving the file and changing the file type to CSV.
# Survey Manager ## Overview The Survey Manager is the epicenter of Plum Insight. Here users can create, edit, and delete surveys, run survey reports, or share surveys with other users in your organization's account. Any surveys that you create or that others share with you display in the survey manager list. You can sort the list of surveys by name or last save date. The search function for this section and supports live search by name. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eiLyARWV7My6oB%2Fsurvey_manager_1.png?alt=media\&token=e2a27bb7-5aa2-42b0-b412-ae2f610792b9) Clicking on [**"Create New Survey"**](/insight/creating-a-survey) prompts users to establish basic survey settings (name, language, speech enabled) and launches the survey editor. {% hint style="info" %} Only users with permission to create surveys may do so. For users who cannot create surveys a list of surveys shared with with account appears. {% endhint %} The icon to the left of the survey name indicates whether that survey is locked or unlocked . Clicking on the icon toggles this feature. Locking a survey adds an extra safeguard because it prevents users from making changes to a survey or its data until the survey is unlocked. Shared surveys can be identified by the shared icon and can only be locked by the survey's creator. The most common actions available for surveys display by default in the survey list . Clicking on the arrow to the right of the action icons displays a full list of available actions . Clicking the arrow icon again hides the menu and returns to the default list of actions. The full list of available actions in Insight include: * **Edit** - Opens the survey editor. * **Deploy** - Opens the deployment page for that specific survey (see: [**Deployment**](/insight/deployment)). * **Report** - Opens a dialog window that allows users to run reports on a survey. * **Share** - Opens a dialog window that allows users to share a survey with other users within their account. * **Clone** - Clones the survey. * **Clear** - Clear all respondent data for a survey without making any changes to the survey itself. * **Delete** - Deletes the survey and all associated respondent data. {% hint style="warning" %} Not all users not allowed to share surveys. This is determined by a users permission settings. Surveys that are shared with you will show all of their available actions. However, those actions are limited by two different factors: 1. the permissions that were granted when the survey was shared with you (see: [**Sharing Surveys**](/insight/survey-manager/sharing-surveys)), and 2. your account specific “create” and “share” permissions (see: [**User Permissions**](/insight/account-manager/managing-users#user-permissions)). Only the direct owner of a shared survey can edit or delete it. {% endhint %} # Locking Surveys Locking a survey provides extra protection by preventing anyone from making changes to it. This is useful when a survey is deployed and running in production. Locking a survey also prevents you from clearing the respondent data or deleting the survey entirely. In order to lock a survey click on the “unlocked” icon . This opens a dialog window that asks users to re-enter their password.
Entering the correct password locks the survey, as indicated by the “locked” icon . Locking a survey disables its Edit, Clear and Delete icons. To unlock a survey click on the locked icon and enter your password. This returns the survey to the unlocked state and all available actions become active again. # Sharing Surveys Accounts with sharing enabled can share surveys with anyone within their organization's account. Users can only share surveys that they own. Surveys that are shared with you must first be cloned. The cloned survey can then be shared with another user. Clicking on the share icon brings up the share dialog window:
Enter the email address(es) of the user(s) within your organization's account to share a survey with them. After adding the user(s), survey owners have the option to grant additional permissions to the other users.
Users with permission to create surveys automatically have the “clone” permission for their surveys. When sharing surveys, survey owners can opt for granular control over all other permissions (Deploy, Audio, and Report). These settings allow creators to limit survey access to the specific tasks or needs they need others to perform. For example, if one user is solely responsible for managing the prompt recordings for phone surveys, then it makes sense to give them “Manage Audio” access to the survey so that they can access the list of prompts and upload/replace audio files as needed. Sharing with “Deploy Survey” access allows others to publish the survey to a specific phone number and to manage the outbound dialing queue for the survey (see: [**Deployment**](/insight/deployment)). Sharing with “Create Reports” access gives others full access to all respondent data with no restrictions (to share a subset of respondent data see: [**Reporting**](/insight/reporting)). # Cloning Surveys Cloning a survey is a useful feature if you would like to make changes to a survey that is already deployed and locked without compromising the data already collected or otherwise impacting the survey. To clone a survey click the “clone” icon . This brings up a dialog window that requires users to provide a new name for the survey clone.
After providing a unique name for the new survey clone, click “Submit” and the new survey appears in the list of surveys. # Clearing Survey Data To clear out any respondent data that a deployed survey has collected click on the “clear” icon . This presents users with a confirmation window. Click “Yes” to clear the data from the survey or click “Close” to cancel. After clearing a survey's data, the data also disappears from all reports associated with that survey.
# Deleting Surveys To delete a survey click on the “delete” icon . This presents users with a confirmation window. Click “Yes” to delete the survey and all associated data or click “Close” to cancel. Deleting a survey also deletes all reports associated with that survey.
# Importing Surveys and Data Exporting a survey from the legacy Plum Survey platform, does not include the survey's data. This allows users to fully test the survey in Plum Insight and to upload new voice prompts, if necessary. It's recommended to wait to import Plum Survey response data until the new survey is ready for production in Plum Insight. To import survey data click on the “import” icon . This presents users with a dialog window that asks them to confirm the import of the existing data. Click “Yes” to import the data or click “Close” to cancel the import.
# Deployment ## Overview Deployment refers to active surveys that can be taken either by phone or on the web and record user responses. ## Layout The Deployment manager interface displays a list of currently deployed surveys and information related to those surveys.
They key features of the Deployment Manager include: 1. **Deploy Survey**: Click this button to open the deployment dialog window to select the survey you wish to deploy. 2. **Survey Name**: A list of all currently deployed surveys. Click the “Survey Name” column header to toggle the display order of the list to sort alphabetically either ascending and descending. 3. **Phone Number**: The phone number assigned to the deployed survey. 4. **Deployed**: The date the survey was deployed. 5. **Actions**: Actions available for the deployed survey: * **Edit Deployment**: Click this button to go to the [**Deployment Settings**](/insight/deployment/deployment-management#deployment-settings) menu. * **Outbound Queue**: Click this button to go to the [**Outbound Queue**](/insight/deployment/outbound-queue) menu. * **Delete Deployment**: Click this button to bring up a dialog window confirming the deployment deletion. 6. **Web Survey URL**: The URL for the web version of the survey. Click the “link” icon to open the survey in a web browser. #### #### # Deployment Management ## Deploying a Survey Click the yellow “Deploy Survey” button in the upper right hand corner to deploy a survey from the Deployment Manager. This opens a new dialog window with a dropdown menu that lists all available surveys.
Select the name of the desired survey from the drop down menu and click “Submit.” This redirects users to the [**Deployment Settings**](/insight/deployment/deployment-management#deployment-settings) menu, where they can modify the deployment settings. To abandon deploying a survey, click the 'x' in the upper right hand corner or the grey “Cancel” button. ## Deleting a Deployment Deleting a deployed survey makes it unavailable to respondents via both phone or the web. Deleted surveys cannot gather additional responses. To delete a deployment, click the trash can icon for that survey located in the “Actions” column of the Deployment Manager. This brings up a dialog window asking users to confirm the deletion of the survey deployment:
To confirm the deletion, click the yellow “Yes” button. To dismiss this dialog window, click the “x” in the upper right hand corner of the window or click the grey “Cancel” button. {% hint style="info" %} **Note:** Deleting a survey deployment removes any outbound call data associated with that survey. {% endhint %} ## Deployment Settings Modifying the deployment settings of a deployed survey is done through the Deployment Setting menu. This is the same menu users see when initiating a new survey deployment. To access this menu click the “Edit” icon in the “Actions” column of Deployment Manager. Deployment settings are broken into two sections: Deployment Methods and Deployment Settings. ### **Deployment Methods** Respondents have the option of taking surveys over the phone or via a web browser. Surveys are compatible with browsers on desktops and mobile devices. This section displays information that respondents need to take the survey: * **Web URL**: This displays the survey's URL. Click the link icon to open the survey in a new browser tab. * **Inbound Phone Numbers**: This displays the inbound phone number(s) associated with a deployed survey. Click the 'x“ button to the right of a phone number to remove it.
### **Deployment Settings** The deployment settings section provides more granular control over deployed survey behavior. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dzbVkBYVr3irN8%2Fdeployment_manager_settings.png?alt=media\&token=e7e5bbe6-ee8b-4700-9db5-db43f3344b43) * **Terminate Survey**: This feature allows users to schedule when to close their surveys. Terminating a survey means that it will no longer be available to respondents by either phone or the web. Users can choose the future day, hour, and minute when the survey will end. To close a survey immediately click the “End Survey Now” button to end the deployment. Once a user closes a survey this button changes to “Resume Survey.” Resuming a survey allows users to return a survey to active status. New respondent data in a resumed survey will be added to the data collected in previous deployments. * **Maximum Responses**: Set a value in this field to limit or specify the sample size of a survey, i.e. the total number of responses. A value of 0 allows for unlimited responses. * **Total Responses**: This is a running tally of how many times the survey has been taken.
* **Store Identifying Info**: Enable this feature to retain the ANI or IP address of users taking the survey, if available. ### **Saving Deployment Changes** To save any deployment changes made in this menu, click the yellow “Save” button in the bottom left hand corner. # Outbound Queue The outbound queue is an interface that allows users to view pending and completed outbound calls, as well as to queue outbound calls for a deployed survey. Some aspects of the Outbound Queue are also accessible through the [**Plum Insight API**](/insight/api). ## **Layout** To reach the outbound queue menu, click the phone icon for the desired survey in the “Actions” column in the list of deployed surveys. This menu present two different types of information: completed and pending. The “Completed” tab displays outbound calls that have finished their outbound attempts. A completed outbound call can result from the following scenarios: * Caller answered, but rejected the call (Rejected) * Caller answered and took the survey (Completed) * Caller was not reachable (Failed) * User canceled the outbound call attempts (Canceled) ### **Completed Tab** The “Completed” tab of the Outbound Queue:
The key items in this interface include: 1. **Queue Calls**: Click this button to open the “queue calls” dialog window. This window allows users to schedule outbound calls to be queued. 2. **Start**: This filter lets users control what data is displayed below based on the time when the call occurred. Enter a specific start time to restrict the list of displayed calls to calls that were queued to start *at*, or *after* the selected time. 3. **End**: This filter lets users control what data is displayed below based on when the call occurred. Enter a specific end time to restrict the displayed list of calls to calls that were queued to start *before* the chosen time. 4. **Apply Date Filter**: Click this button to apply date filters. 5. **Export Data**: Click this button to export the entire list of completed outbound calls to a CSV file. 6. **Clear Data**: Click this button to clear all completed calls from the table. 7. **Show Entries**: This drop down menu lets users toggle the number of visible table rows per page. 8. **Search**: Type a partial or complete phone number to filter display results based on the entered data. 9. **Page Navigation**: Use these buttons to quickly and easily navigate through the list of completed calls. Table data: * **Phone Number**: The destination number for an outbound call. * **Status**: The final status of an outbound call. * **Start Timestamp**: The date and time when the call was scheduled to begin outbound attempts. * **Duration**: Duration of the call. This field may be empty if the caller does not accept the call or if they do not begin the survey. * **Actions**: * **View Visit Details**: Click this button to open a window that displays the survey questions as well as the answers to those questions provided by that respondent. * **View Call Details**: Click this button to open a window that displays the details about the outbound call attempt(s), including the number of attempts, and all outbound events that have occurred for the call. ### **View Call Details Window**
### **Pending Tab** The “Pending” tab is similar to the “Completed” tab with some minor differences.
![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3dxKxyD2AwXkuv-%2Fdeployment_manager_outbound_pending.png?alt=media\&token=f17c72b5-fe18-4e57-ba18-925ae7dbf089) The items in this menu include: 1. **Refresh Calls**: Click this button to refresh the list of pending outbound calls. This updates the list with any status changes or newly queued calls. 2. **Cancel Calls**: Click this button to cancel **all** outbound calls for the deployed survey. **Note:** This is a batch process so any calls that connected before or during the cancel event occurred will be completed. 3. **Show Entries**: This drop down menu lets users toggle the number of visible table rows per page. 4. **Search**: Type a partial or complete phone number to filter display results based on the entered data. 5. **Page Navigation**: Use these buttons to quickly and easily navigate through the list of pending calls. Table data: * **Phone Number**: The destination number of the outbound call. * **Queued Timestamp**: The date and time the call was queued. * **Number of Attempts**: Current attempt progress. * **Last Event**: * **Timestamp**: The date and time of the last outbound call event. * **Status**: The status of the last outbound call event. # Queueing Calls Click the yellow “Queue Calls” button to queue outbound calls for your deployment. This opens the queue calls dialog window. ## **Basic Options**
Users who need to queue a single, immediate outbound call attempt and provide a properly formatted CSV file of contact data can safely ignore the optional fields. Once users complete the desired fields to meet their needs, clicking the yellow “Submit” button schedules the calls to be queued. To dismiss the call queue window, click the 'x' in the upper right hand corner of the window or the grey “Close” button. ### **Queue Calls CSV Format** When queuing outbound calls from CSV file data, whether through the survey API or the outbound queue interface, users need to format the CSV list of phone contacts properly so that Insight will be able to read them. The first cell of the first line of the CSV **must** be “destination”. A valid first line of the CSV simply reads: `“destination”` Another option when queuing from CSV is to supply metadata values to associate with an outbound call. To do this, include the column headers of the metadatabase that you wanted to include in the header of your CSV file. For example, the first line of the CSV when including metadata values may be: `“destination”,"userID","FirstName","LastName"` The next lines of the CSV file should only contain the contact info of the callers receiving the outbound calls. For example, a CSV file that queues three (3) outbound calls without using any metadata would look like this: ``` “destination” “1234567890” “1234567891” “1234657892” ``` The destination phone number can be formatted as any valid phone number. Phone numbers may also include the optional “tel:” prefix and/or the optional “ani” and “postd” attributes, which are added to the end of the phone number. * The “ani” attribute sets the source number that callers see when receiving an outbound call. For example, if the number associated with the call queue differs from a company's main number, it may be preferable to set the ANI to the main switchboard number to make it more recognizable. * Setting the “postd” attribute dials the specified DTMF tones once the call connects. Valid destination examples include: * `6175551234` * `tel:+16175551234` * `tel:16175551234;ani=2125551234` (**Note:** In this case the ANI determines the number the caller sees) * `tel:16175551234;ani=2125551234;postd=2` (**Note:** In this case, the ANI determines the number the caller sees, *and* enters the DTMF tone “2” after the call connects) {% hint style="warning" %} **As of 2019, ANI should be set on all outbound phone calls** as federal regulation requirements means that most inbound carriers will block outbound calls that do not originate somewhere. ANI should be a number that you own. For more information about this, please see the file below. {% endhint %} {% file src="/files/-M8MDrx-a0QCRIajSIq7" %} STIR/SHAKEN, Robocalling, and ANI {% endfile %} An example of a CSV file containing metadata values would look like: ``` “destination”,”userID“,”FirstName“,”LastName“ “1234567890”,”1“,”Robert“,”Weir“ “1234567891”,”2“,”Jerome“,”Garcia“ “1234657892”,”3“,”Philip“,”Lesh“ ``` Queuing calls with a metadata not only schedules the outbound calls to be queued, but before any calls are made Insight also creates an entry in the metadatabase that is associated with that particular survey, which, in turn, is associated with that specific outbound call. ## **Advanced Options**
Users have the following options in the queue calls dialog window: * **Upload CSV**: Click the “Select Files” button to open a window that lets users choose and upload a CSV that contains a list of phone numbers. In order for Insight to accept the data from a CSV file it must be properly formatted. See the [**Queue Calls CSV Format**](/insight/deployment/queueing-calls#queue-calls-csv-format) guidelines for more information on proper formatting for this type of file. * **Number of Attempts**: Set the number of times to attempt the outbound call. The default setting is 1 attempt. * **Between Attempts Wait**: Set the amount of time Insight will wait after a failed queue attempt to retry the outbound call. If the set number of attempts is set to one this feature is not needed. If the number of attempts is greater than one this field is optional. The default value is 5 minutes. * **Calling Window**: This option lets users set a date/time range for when outbound calls will occur. Users can set a start and end time and date for when outbound call attempts will begin and end. This field is left empty by default. That means Insight begins making calls immediately and the attempt window will not expire until all attempts have been made or until all calls are completed. * **Result URL**: This is the callback URL to your REST service that processes the call status results when a call is completed, canceled, or all attempts have been exhausted. The POST body will match the format of the 'call\_details' attribute from the [**outbound call status API response**](https://docs.plumvoice.com/insight/api#checking_status_for_an_outbound_call). # Reporting ## Overview Create new reports, and run and share existing reports using the Report Manager. Reports that you create or that have been shared with you appear in the Report Manager. Users can perform different actions on their reports depending on their permissions for a given report. It is possible to sort the report list by name or last save date. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3ePvGG0eIAw048R%2Freport_manager_1.png?alt=media\&token=207e259d-dba7-48de-bf90-8ba938b4b5cf) Clicking on the “New Report” button prompts users to provide a name and select a survey for their report. Users can run reports immediately after creating them. Insight's report manager allows users to apply filtering rules based on response data or other non-response data, such as the type of visit, date and time, or other factors. The icon to the left of the report name indicates whether the report contains data on a single survey ( or multiple surveys . Shared reports are denoted with their own icon. Hovering over the icon provides additional details about which survey(s) contribute data to the report and, in the case of shared reports, who shared the report. Users have access to several action items for reports: ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eQu2oHvtDIuJYr%2Freport_manager_action_icons.png?alt=media\&token=2772364b-5548-4ad7-b8b5-cdbf042199a5). * **View Report:** Opens a page that displays a report based on the selected survey(s) and applied filters. * **View Visits:** Opens a page displaying detailed information on all visits to the selected survey(s) and applied filters. * **Edit Filters:** Opens the filter editor so users can adjust the filter(s) applied to that report. * **Share Report:** Opens a dialog window where users can select and share the report with other users in their company. * **Clone Report:** Clones the report to a new name. * **Delete Report:** Deletes the report (**Note:** this does *not* destroy any survey data). {% hint style="info" %} **NOTE:** Not all users are allowed to share reports. Administrators can change user permissions to (dis)allow sharing (see: [Account Manager - User Permissions](/insight/account-manager/managing-users#user-permissions)). Shared reports only show the actions available for that report. The report owner sets the permissions that others can use when interacting with a shared report. Only report owners can alter or delete a report. {% endhint %} # Viewing a Report The View Report page displays a series of charts compiled from the survey(s) results. By default, new reports do not have any question or visit filters applied to their data. When a user adds question and/or visit filters to a report, Insight updates the charts to reflect the filtered results. A View Report page:
From this interface users can rename reports, edit filters, view individual visit data, show a printer-friendly version of the report, or save a copy of the report. Not all question types have the same chart display options. See the table below for the options for each question type. When viewing data for an individual question, users have the option to toggle between the chart styles available for that question type. {% hint style="info" %} **Note:** Reports store the chart type that was displayed when the report was saved. The printer-friendly view shows charts based on the currently-selected chart type, not the stored chart type. {% endhint %} # Available Charts When you run a report each question type has a default chart type. Some question types also have a set of additional chart types that users can use to view their data. There are two different groups of charts: Summary Charts and Trends. The available list of charts includes: * **Pie Chart:** Provides a view of relevant data that is grouped and aggregated into a pie chart. * **Bar Chart:** Provides a view of relevant data that is grouped and aggregated into a bar chart * **Line Chart:** Displays a trend view of your data with one line per data group and one data point per period (hour, day, week, month). * **Stacked Bar Chart:** Displays a trend view of your data with one stacked color in each bar per data group and one bar per period (hour, day, week, month) * **Stats Line Chart:** Displays a line chart that depicts the running average of the data values with one data point per period (hour, day, week, month) Each survey question type has a default chart type as well as zero to four additional chart options. The following table provides a list of questions types and their respective default chart type as well as their other supported chart types. | Question Type | Default Chart | Available Charts | | --------------- | ------------- | --------------------------------------- | | Multiple Choice | Bar | Bar, Pie, Line, Stacked Bar | | Multiselect | Bar | Bar, Pie, Lin, Stacked Bar | | Scale | Stats Line | Bar, Pie, Line, Stacked Bar, Stats Line | | Yes / No | Pie | Bar, Pie, Line, Stacked Bar | | Multilingual | Pie | Bar, Pie, Line, Stacked Bar | | Date | Stats Line | Stats Line | | Time | Stats Line | Stats Line | | Currency | Stats Line | Stats Line | | Number | Stats Line | Stats Line | | Transfer | Bar | Bar, Pie, Line, Stacked Bar | | SOAP Webservice | Bar | Bar, Pie, Line, Stacked Bar | | Subdialog | Bar | Bar, Pie, Line, Stacked Bar | | Digits | Stats Line | Stats Line | | Metadata Filter | \ | Stats Line | | Metadata Store | \ | Bar, Pie, Line, Stacked Bar | | Comment | \ | None | | Full Name | \ | None | | Address | \ | None | | Prompt | \ | None | # Edit Filters By default, Insight includes all visits in a report. Users can apply filters to their reports to restrict which visits are or are not included in the report. To add or edit filters for an existing report, click the Edit Filters icon in the report manager or the Edit Filters button when viewing a report. Editing filters is a two step process. First, users must create filters for their reports. Filters are based on responses to specific questions in a survey. For example, you might have a yes/no question in your survey and you only want to see the response data for end users who selected 'yes' for that question. Second, users have the ability to edit filters related to the visit itself. These filters revolve around the process of taking the survey, not the actual responses that end users provide to the survey questions. For example, you may only need the to see survey responses for the past week, or you want to filter our visits that came from a set of test phone numbers. ## **Question Filters** Question filters are one of Insight's most advanced options for analyzing survey results. Question filters allow users to specify the rules that are applied to response data for reporting purposes. The question filters page presents users with a paginated list of options for filtering results based on question type. By default, no question filters are enabled. The Edit Question Filters page looks like this: ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eN0Wg_ilHKeZmr%2Freport_filters_edit_question.png?alt=media\&token=ac76fd03-3da8-4d51-8f23-66e09b99b085) To enable a question filter, check the box next to the question text, on the left hand side. Question type dictates the range of filter options users can apply to their response data. For example, with multiple choice or multi-select questions users have granular filtering control and are able to select each response to be included in the report based on the options and responses provided for that question. When more than one question filter is enabled, they are combined in one of two ways, which is controlled via the Combine Question Filters section. This gives users the option to apply **ALL** of the selected filters or **ANY** of the selected filters to the response data. ## **Visit Filters** Visit filters are used to customize a report based on non-response data for a particular visit. This includes the date range, medium (phone or web), whether or not the user completed the survey, and the phone number used to take the survey. {% hint style="info" %} **Note:** Some of the date range options are are relative values. For example, selecting data from “Last Month” every time the report is run displayed data from the last month relative to the day the report was run. {% endhint %} The Edit Visit Filters page looks like this: ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3eOiQmxXhk5pvPM%2Freport_filters_edit_visit.png?alt=media\&token=6400c9a0-0530-4ac4-b748-e6b9cb224491) After selecting the appropriate visit filters, click the View Report button to see an updated report with the question and visit filters applied. Click the Save button on the 'view report' page to save these filters for future use. # Survey Visits The Survey Visits page lets users 'look under the hood' at the raw data that comprises their reports. This pages allows users to search for and view specific survey visit data and to export the raw data and audio comments for analysis outside of Insight's general reporting tool. This page displays the type of visit (phone or web), the source IP or caller ID, the visit start time, and time to completion of each end-user who took to complete the survey. The Survey Visits page looks like this: ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3ealkeFCP70cwTR%2Freport_raw_data.png?alt=media\&token=2b0a1b78-0f1d-47bd-9035-c19646d83f61) The table of matching visits is presented as a paginated and searchable list where each individual visit occupies a single row. Click on the 'view' icon (magnifying glass) to open a new window that displays the answers to individual questions provided by that specific end-user. Survey owners have the ability to delete visits; this is a manual process done one at a time. To export audio files containing end user comments, click on the Export Audio button to download a ZIP containing those files. To export the survey's raw visit data, click on the Export CSV button to download that data in CSV format. This CSV file correlates the survey questions with the responses provided for each visit. {% hint style="info" %} This data is also available for CSV export via API, [here](https://docs.plumvoice.com/insight/api#survey_response_reporting). {% endhint %} # Printer Friendly View Users have the option to create a printer friendly version of reports. To do so, navigate to the View Report page and choose to create a print friendly version. The printer friendly view removes all branding and images that are not directly related to the report. Insight uses the saved chart preference for each question to determine how to present charts for each question. To change the saved chart, access that question in the survey report, change the chart type, save the report, and return to the printer friendly option on the View Report page. Insight combines all of the pages of the report into a single page view so that users do not have to change print each page manually. Users can also use the built-in functionality of their web browser to print out or save their report to a local drive for future reference. # Single vs Multi-Survey Reports Most of the time, users run single survey reports. This presents the respondent data for one survey and applies any question or visit filters associated with it. However, there are situations where users want to gather data from different groups using surveys that cater to each group. This situation also poses a problem for analyzing multiple, different data sets without exporting data from Insight. To combat this issue, Insight allows users to combine respondent data from multiple surveys into a single report. When the structure of two (or more) surveys parallel each other, (e.g. Page 1, Question 2 in both surveys is of the same question type, such as multiple choice) Insight is able to merge the data from those questions in the report, essentially treating them as a single question. When creating a multi-survey report, users have the option to allow Insight's reporting engine to automatically merge questions that it determines are good candidate for merging. Any question(s) that cannot be merged appear in the report and are show as separate charts accompanies by their unique question type and text. # Merging Questions When running a multi-survey report, users must first provide a name for the final output report and select the surveys to include in the merger. By default, Insight automatically determines which survey questions should be merged. However, there may be cases where users want to merge two or more surveys, but also want to see the data for specific, individual questions within the report. For example, a user may want to merge Survey A and Survey B, but they want to see the individual data for question 3 for both A and B, even though these are the same question type and would be merged in a multi-survey report. In this situations, users can toggle overriding Insight's default merge behavior by clicking the 'Unmerge'/'Merge' button. ![](https://119549198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4FwhscRQChKN5sELQq%2F-M5YE3MqmTf2ElD3Zkkd%2F-M5YG3e_yLfp4dYlfh4C%2Freport_merge_surveys.png?alt=media\&token=f487c25f-64bc-4a53-9a92-bcf27e477ed9) Questions of different question types cannot be merged. Any questions that are of the same question type can be merged, and any questions of the same question type that have the same question text and answer choices, as may be the case with multiple choice or multiselect questions, will be merged automatically. # Translating Unix timestamps By default, all start and end times are recorded as Unix timestamps. This is a universal standard that accommodates all time zones. If you'd like to translate Unix timestamps into a more readable format, here's how: 1. Open your report in Excel 2. Create a new column for your readable date, put in this formula: =(((**A1**/60)/60**-5**)/24)+DATE(1970,1,1) where A1 is the column with the Unix timestamp, and -4 is the offset for GMT. For example, EST is -5 hours off from GMT, so this formula would provide the date in EST timezone. For GMT timezone, the formula would be ``` =(((A1/60)/60)/24)+DATE(1970,1,1) ``` For PST, the formula would be ``` =(((A1/60)/60-8)/24)+DATE(1970,1,1) ``` 3. Once you hit enter, you will notice a numeric value. Make sure you format that cell as a “Date” and you may pick which date format you prefer. # API ## Insight API Overview The Insight API provides a programmatic access to, and supports the following functionality within the Insight interface:
* [**Survey responses**](/insight/api/checking-total-responses-for-a-survey): Returns the total number of times the survey has been taken. * [**Queue call**](/insight/api/queuing-an-outbound-call): Queues a single outbound call. * [**Bulk queue calls**](/insight/api/queuing-multiple-outbound-calls): Queues outbound calls in batches from a CSV of contacts. * [**Outbound call status**](/insight/api/checking-status-for-an-outbound-call): Returns the call details for a specific outbound call. * [**Cancel calls**](/insight/api/cancelling-all-pending-outbound-calls): Schedules all pending outbound calls to be cancelled. * [**Metadatabase push**](/insight/api/adding-metadatabase-records): Adds a single metadatabase record to an existing metadatabase. * [**Survey Response Reporting**](/insight/api/survey-response-reporting): Returns survey responses for a saved report in text/csv format. {% hint style="info" %} [See here for information about using the Transcription API with Insight](https://docs.plumvoice.com/documentation/using-the-plum-voice-suite/how-to-guides/using-plums-transcription-api#insight). {% endhint %} ### Base URL The base url for all requests should be made to: ``` https://insight.plumvoice.com/api ``` ### Authentication All API requests are authenticated using HTTP Basic Authentication. The username value will be the email address users use to log in to their Insight account and the password will be their Developer Key, located within the [**Account Settings**](/insight/account-manager#managing-account-settings) interface. Depending on the HTTP libraries available in one's chosen programming language, users may be able to use built-in HTTP Basic Authentication. If this is not available, users can build the header manually by base64 encoding their username and developer key concatenated with a colon and then prefixing it with 'Basic'. Manually built HTTP Basic Authentication in this instance should look like: ``` "Authentication: Basic your_base64_encoded_string" ``` Any requests made without this header or with invalid credentials will return HTTP 401 Unauthorized and the body will provide details about what went wrong with the request.Edit ### Supported Accept Headers The API methods honor the following Accept header values to determine the Content-Type and representation for the response: * application/json * application/xml Specifying a different Accept header will return a Content-Type 'application/json' by default.Edit ### Locating your survey\_id and instance\_id Your `survey_id` and `instance_id` values are utilized in many areas of the Insight API. To locate these values for your survey, you'll need to visit the [Outbound Queue](/insight/deployment/outbound-queue). At the top you will see “Outbound API Values” which displays the `survey_id` and `instance_id` for your survey. # Checking Total Responses for a Survey ## Total Survey Responses `GET` `https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/responses` Check the total number of responses for an Insight survey. #### Path Parameters | Name | Type | Description | | ------------ | ------ | ------------------------------------- | | survey\_id | string | Insight survey ID number | | instance\_id | string | Instance number for an Insight survey | #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | {% tabs %} {% tab title="200 On success" %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':true,'total_responses':'25'} ``` {% endtab %} {% tab title="XML" %} ```markup true 25 ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="404 On failure: this example provides an invalid survey\_id or instance\_id." %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'No deployment was found for that survey and instance id combination.'} ``` {% endtab %} {% tab title="XML" %} ```markup falseNo deployment was found for that survey and instance id combination. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** * **200**: success * **401**: authentication headers invalid or the account is inactive * **404**: deployment or survey was not found * **405**: invalid HTTP method supplied (only GET allowed) * **415**: unsupported media type (Content-Type value in request) * **500**: database error The return structure contains the following item(s): | Name | Data Type | Always Present | Description | | --------------- | --------- | -------------- | -------------------------------------------------------------------------------------------------------- | | success | boolean | yes | Indicates the outcome of the request | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred | | total\_reponses | int | no | The total number of times the survey has been taken. This will be present when the success value is true | ### **Sample Code** This sample PHP code makes a request to a deployed survey that returns the total number of responses: ```php `POST` `https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/queue` Queue an outbound call for an Insight survey. #### Path Parameters | Name | Type | Description | | ------------ | ------ | ------------------------------------- | | survey\_id | string | Insight ID number | | instance\_id | string | Instance number for an Insight survey | #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | #### Request Body | Name | Type | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | phone\_number | string | The phone number to which the outbound call should be placed. There are multiple ways to format phone numbers. They can include the 'tel:' prefix. ANI and postd suffixes are also valid, e.g. ani=1234567890 and/or postd=1234. Examples of valid numbers include: 6175551234, tel:+16175551234, tel:16175551234;ani=2125551234 (this determines the number the recipient sees), tel:16175551234;ani=2125551234;postd=2 (this determines the number the recipient sees and enters the dtmf tone “2” after the call connects). | | start\_timestamp | string | Unix timestamp for when to make the outbound call. | | end\_timestamp | string | Unix timestamp for when to stop attempting to make the outbound call | | max\_attempts | integer | Number of attempts to be made (if previous attempts are not completed successfully). Integer between 1-10. | | reattempt\_wait | integer | Interval (in seconds) to wait before retrying the outbound call after a failure. This is only required when you set an max\_attempts value greater than one, indicating additional retry attempts. | | metadata | array | Array of key⇒value pairs of metadatabase columns and their associated values. | | result\_url | string | Callback URL to your REST service that processes the call status results when the call is completed, canceled, or all attempts have been exhausted. The POST body will match the format of the 'call\_details' attribute from the outbound call status API response, shown here. | {% tabs %} {% tab title="200 Note the 'Link' header. This URI can be used to check the status of the outbound call." %} {% tabs %} {% tab title="JSON" %} ```javascript //Headers HTTP/1.1 200 OK Date: Wed, 06 May 2015 18:19:13 GMT Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40 X-Powered-By: PHP/5.4.40 Link: https://insight.plumvoice.com/api/outbound/155761 Content-Length: 33 Content-Type: application/json //Response body {'success':true,'call_id':155761} ``` {% endtab %} {% tab title="XML" %} ```markup HTTP/1.1 200 OK Date: Wed, 06 May 2015 18:24:41 GMT Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40 X-Powered-By: PHP/5.4.40 Link: https://insight.plumvoice.com/api/outbound/155761 Content-Length: 88 Content-Type: application/xml true 155761 ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="400 Example: too many attempts were supplied. " %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'attempts can only be an integer between 1 and 10.'} ``` {% endtab %} {% tab title="XML" %} ```markup false attempts can only be an integer between 1 and 10. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** * **200**: success * **400**: supplied data improperly formatted or invalid * **401**: authentication headers invalid or the account is inactive * **403**: the account attempting to queue the outbound call for the survey does not have appropriate permissions * **404**: deployment, user or survey was not found * **405**: invalid HTTP method supplied (only POST allowed) * **409**: survey has been marked as deleted, survey deployment has expired, no TTS engine or metadatbase set for the survey, instance\_id supplied did not match the current deployment, the number of survey responses has exceeded the max responses set in the survey's deployment settings * **415**: unsupported media type (Content-Type value in request) * **500**: database error {% hint style="info" %} **Note**: The returned 'Link' header provides the URI for checking the status of the most recent outbound call. {% endhint %} The return structure will contain the following item(s): | Name | Data Type | Always Present | Description | | -------- | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | success | boolean | yes | Indicates the outcome of the request | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred | | call\_id | int | no | The unique identifier for the outbound call when the request is successful. This is the 'call id' value that can be used to look up the call details in the call details API method outlined below. | ### **Sample Code** This sample PHP code makes a request to queue a new outbound call. This triggers an outbound call that goes out immediately and makes a single attempt to connect: ```php 'desintation_phone_number', ); $username = 'you@yourdomain.com'; $password = 'your_developer_key'; curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HEADER, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/x-www-form-urlencoded")); $result = curl_exec($ch); $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); var_dump($result); var_dump($http_code); ``` # Queuing Multiple Outbound Calls ## Queuing Multiple Outbound Calls `POST` `https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/bulk_queue` Bulk queue outbound calls for an Insight survey. #### Path Parameters | Name | Type | Description | | ------------ | ------ | ------------------------------------- | | survey\_id | string | Insight ID number | | instance\_id | string | Instance number for an Insight survey | #### Headers | Name | Type | Description | | ------------ | ------ | ------------------- | | content-type | string | multipart/form-data | #### Request Body | Name | Type | Description | | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | csv | object | CSV file of contacts to receive the outbound calls. For a description of how to format this file, see **Bulk Queue Calls Formatting**. | | start\_timestamp | string | Unix timestamp for when to make the outbound call. | | end\_timestamp | string | Unix timestamp for when to stop attempting to make the outbound call | | max\_attempts | integer | Number of attempts to be made (if previous attempts are not completed successfully). Integer between 1-10. | | reattempt\_wait | integer | Interval (in seconds) to wait before retrying the outbound call after a failure. This is only required when you set an max\_attempts value greater than one, indicating additional retry attempts. | | result\_url | string | Callback URL to your REST service that processes the call status results when the call is completed, canceled, or all attempts have been exhausted. The POST body will match the format of the 'call\_details' attribute from the outbound call status API response, shown here. | {% tabs %} {% tab title="200 " %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':true} ``` {% endtab %} {% tab title="XML" %} ```markup true ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="400 Example: too many attempts were supplied. " %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'attempts can only be an integer between 1 and 10.'} ``` {% endtab %} {% tab title="XML" %} ```markup false attempts can only be an integer between 1 and 10. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** * **200**: success * **400**: supplied data improperly formatted or invalid, uploaded CSV was invalid or not supplied * **401**: authentication headers were invalid or the account is inactive * **403**: the account attempting to queue the outbound call for the survey does not have appropriate permissions * **404**: deployment, user or survey was not found * **405**: invalid HTTP method supplied (only POST allowed) * **409**: survey has been marked as deleted, survey deployment has expired, no TTS engine or metadatbase set for the survey, instance\_id supplied did not match the current deployment, the number of survey responses has exceeded the max responses set in the survey's deployment settings * **415**: unsupported media type (Content-Type value in request) * **500**: database error The return structure will contain the following item(s): | Name | Data Type | Always Present | Description | | ------- | --------- | -------------- | --------------------------------------------------------------------------------------- | | success | boolean | yes | Indicates the outcome of the request | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred | ### **Sample Code** This sample PHP code makes a request to queue multiple outbound calls: ```php '@/path/to/csv/on/your/pc.csv', 'start_timestamp'=>strtotime('+1 minutes'), 'end_timestamp'=>strtotime('+1 hour'), 'attempts'=>1 ); $username = 'you@yourdomain.com'; $password = 'your_developer_key'; curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $params); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data")); $result = curl_exec($ch); $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); var_dump($result); var_dump($http_code); ``` # Checking Status for an Outbound Call ## Check Status for an Outbound Call `GET` `https://insight.plumvoice.com/api/outbound/{call_id}` #### Path Parameters | Name | Type | Description | | -------- | ------ | -------------- | | call\_id | string | Call ID number | #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | {% tabs %} {% tab title="200 Note: The sample call was queued and then canceled." %} {% tabs %} {% tab title="JSON" %} ```javascript { 'success':true, 'call_details': { 'status':'canceled', 'attempts':'1', 'max_attempts':'1', 'queued_timestamp':'1429214458', 'last_attempt_timestamp':'1429214474', 'start_timestamp':'1429214400', 'end_timestamp':'1429218000', 'reattempt_wait':'0', 'events': [ { 'event':'queued', 'timestamp':'1429214465' }, { 'event':'canceled', 'timestamp':'1429214474' } ] } } ``` {% endtab %} {% tab title="XML" %} ```markup true canceled 1 1 1429214458 1429214474 1429214400 1429218000 0 queued1429214465 canceled1429214474 ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="404 Example: no outbound id was found" %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'An outbound call was not found by that id.'} ``` {% endtab %} {% tab title="XML" %} ```markup false An outbound call was not found by that id. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** * **200**: success * **401**: authentication headers invalid or the account is inactive * **403**: the account attempting to view the outbound call details does not have appropriate permissions * **404**: outbound call was not found * **405**: invalid HTTP method supplied (only GET allowed) * **415**: unsupported media type (Content-Type value in request) * **500**: database error The return structure will contain the following item(s): | Name | Data Type | Always Present | Description | | ------------- | --------- | -------------- | ---------------------------------------------------------------------------------------------- | | success | boolean | yes | Indicates the outcome of the request | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred | | call\_details | mixed | no | All call data for the outbound call. See the table below for all of the data required therein. | ### Definitions: Call Details Data | Name | Data Type | Value | | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | status | string | Current status for the outbound call. | | attempts | int | Total number of attempts made | | max\_attempts | int | Maximum number of attempts to be made | | queued\_timestamp | int | Unix timestamp of when the call was queued | | last\_attempt\_timestamp | int | Unix timestamp of when the last event for the outbound call occurred | | start\_Timestamp | int | Unix timestamp of when the call was scheduled to start outbound call attempts | | end\_timestamp | int | Unix timestamp of when the outbound call was scheduled to stop outbound attempts | | reattempt\_wait | int | Time, in seconds, to wait between retrying the outbound call after a failure | | events | mixed | Numerically indexed array of outbound call events, each row with the indices 'event' and 'timestamp' indicating the event and its duration | ### **Sample Code** This sample PHP code makes a request to this method: ```php `DELETE` `https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/cancel` Cancel all pending outbound calls in the call queue. #### Path Parameters | Name | Type | Description | | ------------ | ------ | ----------------------------------- | | survey\_id | string | Plum Insight survey ID number | | instance\_id | string | Plum Insight survey instance number | #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | {% tabs %} {% tab title="202 No body returned" %} ``` ``` {% endtab %} {% tab title="404 Example: Invalid deployment" %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'The specified deployment was not found for this survey.'} ``` {% endtab %} {% tab title="XML" %} ```markup false The specified deployment was not found for this survey.. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** {% hint style="info" %} **Note**: On a successful response (HTTP code 202), no body will be returned. {% endhint %} * **202**: calls successfully marked for deletion * **401**: authentication headers invalid or the account is inactive * **403**: the account attempting to cancel calls does not have appropriate permissions * **404**: deployment was not found by the supplied survey and instance id * **405**: invalid HTTP method supplied (only DELETE allowed) * **415**: unsupported media type (Content-Type value in request) * **500**: database error The return structure will contain the following item(s): | Name | Data Type | Always Present | Description | | ------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | success | boolean | no | Indicates the outcome of the request. This will only be present when the response http code is something other than HTTP 202, indicating a failure. | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred. This will only be present when the response http code is something other than HTTP 202, indicating a failure. | ### **Sample Code** This sample PHP code that makes a request to this method: ```php `POST` `https://insight.plumvoice.com/api/metadatabase_push` Add metadatabase records to a Plum Insight survey. #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | #### Request Body | Name | Type | Description | | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | metadatabase | string | The name of the metadatabase. This is case-insensitive. | | record | string | json encoded associative array of the column names and column values to be added. Example: {'column1': 'value1', 'column2': 'value2'} This need not include all columns, you can leave out columns in your metadatabase you do not wish to populate. | {% tabs %} {% tab title="200 " %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':true} ``` {% endtab %} {% tab title="XML" %} ```markup true ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="404 Example: The specified metadatabase did not exist." %} {% tabs %} {% tab title="JSON" %} ```javascript {'success':false,'error':'No metadatabase by that name exists.'} ``` {% endtab %} {% tab title="XML" %} ```markup falseNo metadatabase by that name exists. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### **Possible Response Codes** * **200**: success * **400**: invalid data supplied * **401**: authentication headers invalid or the account is inactive * **404**: metadatabase was not found * **405**: invalid HTTP method supplied (only POST allowed) * **415**: unsupported media type (Content-Type value in request) * **500**: database error The return structure contains the following item(s): | Name | Data Type | Always Present | Description | | ------- | --------- | -------------- | --------------------------------------------------------------------------------------- | | success | boolean | yes | Indicates the outcome of the request | | error | string | no | If the success value is false this provides a message indicating what error(s) occurred | ### **Sample Code** This sample PHP code makes a request to push a new record into the 'test' metadatabase and sets values for columns column1 and column2: ```php 'test', 'record' => json_encode(array('column1' => 'value1', 'column2' => 'value2')), ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://insight.plumvoice.com/api/metadatabase_push"); curl_setopt($ch, CURLOPT_USERPWD, 'your_login:your_dev_pin'); // http basic auth credentials curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded', 'Accept: application/json')); $result = curl_exec($ch); $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); var_dump($http_code, $result); ``` # Survey Response Reporting **Locating your report\_id**: This method can only be run on saved reports. Once you save your report you can visit the [View Survey Visits page](/insight/reporting/survey-visits), on which you'll see at the top a section labeled “Reporting API URL.” This will be the full URL you will use for survey response reporting via the API. ## Survey Response Reporting `GET` `https://insight.plumvoice.com/api/report/{report_id}` This method allows you to fetch CSV exports of your saved survey reports programmatically (or through your browser, authenticating via http basic). There are a number of optional parameters supplied which will allow for you to paginate responses when working with very large data sets. #### Path Parameters | Name | Type | Description | | ---------- | ------- | -------------------------------------- | | report\_id | integer | The `report_id` for your saved report. | #### Headers | Name | Type | Description | | ------------ | ------ | --------------------------------- | | content-type | string | application/x-www-form-urlencoded | #### Request Body | Name | Type | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | start\_timestamp | integer | Unix timestamp to filter your survey responses to a specific date range. | | end\_timestamp | integer | Unix timestamp to filter your survey responses to a specific date range. | | offset | integer | Offset when querying for a row range. The offset will indicate at which row in the result set to begin including rows in the response csv. If you set an offset of 25, the first 25 rows will be ignored and row 26 will be the first row included in the response. | | limit | integer | Limit the number of rows returned. The limit must be between 1 and 10,000. If no limit is supplied, the limit will be 500. | {% tabs %} {% tab title="200 Along with having the new report created in CSV format at 'reports/todays\_report.csv', running the above script with proper credentials produces the following output. The returned header values indicate the following: 1.) the request implicitly started at offset 0 (no offset specified, so the default was applied); 2.) the limit of 10 was applied, as supplied in the query string parameters; 3.) we received 10 rows in our response body; 4.) there were 12 total rows available for the report." %} ``` HTTP/1.1 200 OK Date: Thu, 22 Sep 2016 18:41:49 GMT Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/1.0.2d PHP/5.4.45 X-Powered-By: PHP/5.4.45 Content-Disposition: attachment; filename=report.csv X-Plum-Total-Rows: 12 X-Plum-Returned-Rows: 10 X-Plum-Row-Offset: 0 X-Plum-Row-Limit: 10 Content-Length: 941 Content-Type: text/csv; charset=utf-8 "Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?" 19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5 19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3 19571,"test reporting api",web,192.168.1.1,NA,1473861309,1473861318,1,0,67.5 19571,"test reporting api",web,192.168.1.1,NA,1473861298,1473861305,1,0,87.8 19571,"test reporting api",web,192.168.1.1,NA,1473861289,1473861294,1,1,78.8 19571,"test reporting api",web,192.168.1.1,NA,1473861279,1473861286,1,1,5656.66 19571,"test reporting api",web,192.168.1.1,NA,1473861254,1473861261,1,1,45.76 19571,"test reporting api",web,192.168.1.1,NA,1473861234,1473861251,1,1,97.6 19571,"test reporting api",web,192.168.1.1,NA,1473861223,1473861230,1,1,56.45 19571,"test reporting api",web,192.168.1.1,NA,1473861206,1473861212,1,0,45.5 ``` {% endtab %} {% tab title="400 Example: the report\_id supplied was not valid." %} {% tabs %} {% tab title="JSON" %} ```javascript {"error":"You do not have permission to access this report"} ``` {% endtab %} {% tab title="XML" %} ```markup You do not have permission to access this report ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} {% hint style="info" %} **NOTE**: Results will be ordered in descending order by start time, so the most recent response will always be first. The `start_timestamp` and `end_timestamp` parameters are dependent on one another; if you supply one, you must supply the other. By default, if no parameters are supplied, the response will contain the full date range of survey responses with an offset of 0 and limit of 500, returning up to 500 of the most recent survey visits. {% endhint %} ## **Possible Response Codes** * **200**: success * **400**: parameters supplied were not valid * **401**: authentication headers invalid or the account is inactive * **403**: you do not own the report * **404**: the saved report was not found or no rows were matched for the report * **405**: invalid HTTP method supplied (only GET allowed) * **500**: server error ### **Response Notes** **Headers** Since the payload of a successful request will be the csv data for the report, we've included a number of headers that will act as metadata related to the returned data and the overall data for the report. The following headers will be included: | Header Name | Type | Description | | -------------------- | ---- | ----------------------------------------------------------------------- | | X-Plum-Total-Rows | int | This value indicates the total number of rows that matched the query. | | X-Plum-Returned-Rows | int | This value indicates the total number of rows returned in the response. | | X-Plum-Row-Offset | int | This value indicates the offset applied to the current response. | | X-Plum-Row-Limit | int | This value indicates the limit applied to the current response. | These headers should allow you to paginate your requests, if you're working with a very large data set. **Structure** The return structure differs based on whether rows were matched or not. A successful response, one in which rows were matched, will *always* return an http code of 200 and the body of the response will be in text/CSV format, which will be the raw output of your CSV report. A sample of a successful response would be the following: ``` "Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?" 19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5 19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3 ``` {% hint style="info" %} **NOTE**: A successful response will always contain the header fields of the CSV. If you are paginating, be sure to trim this off before appending the rows to an existing CSV. {% endhint %} An unsuccessful request, one in which no csv rows were returned and the http code was not 200, contains the following item(s): | Name | Data Type | Always Present | Description | | ----- | --------- | -------------- | ----------------------------------------------------- | | error | string | yes | Descriptive message indicating what error(s) occurred | ### **Sample Code** This sample PHP code makes a request to fetch the first 10 items of a saved report: ```php
``` # Result URL Insight allows users to configure their outbound calls to automatically send the status of each outbound call to a REST service upon completion. To do so, it is necessary to provide a result\_url when queuing the outbound calls. Insight provides three different ways to accomplish this: queuing through the [**Outbound UI**](/insight/deployment/queueing-calls), queuing a single outbound call through the [**Queue Call API** ](/insight/api/queuing-an-outbound-call), and queuing multiple outbound calls via the [**Bulk Queue API**](/insight/api/queuing-multiple-outbound-calls). The result\_url callback will be POSTed to when the outbound call completes, when all outbound attempts are exhausted, or when the outbound call is canceled. The body of this request will be identical to the `call_details` element in the [**Outbound Call Status API** ](/insight/api/checking-status-for-an-outbound-call)method. ### **Request Parameters** The following parameters will be POSTed to your result\_url: | Parameter | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | status | string | Call outcome: 'completed', 'canceled', 'failed', 'rejected' | | attempts | int | Number of outbound attempts that were made | | max\_attempts | int | Total number of call attempts to be made | | queued\_timestamp | int | Timestamp of when the call was queued | | last\_attempt\_timestamp | int | Timestamp of the last time the call was attempted | | start\_timestamp | int | Timestamp of when the calls were scheduled to begin. If not supplied when queuing, this will be an empty value | | end\_timestamp | int | Timestamp of when the calls were scheduled to no longer make attempts. If not supplied when queuing, this will be an empty value | | reattempt\_wait | int | Time (in seconds) to wait between call re-try attempts | | events | array | Array of call events, including the timestamp of the event | # Associating Metadata with a Caller It's commonplace to want to associate metadata with a specific inbound or outbound caller. This section will describe how to achieve this for both inbound and outbound calls. ## **Outbound Association** Associating a metadata record with an outbound caller is a very straightforward process. When queuing the outbound call, either via the api methods or though the outbound interface, you can optionally choose to include metadata for the caller. What this actually does is allow for automatic association of that record within the call. This means that you can instantly use the metadata store question type to record any of the columns values specified when queuing the call. Here's a basic breakdown of those steps: 1. You queue an outbound call with metadata 2. When the call connects, that metadata record from your metadatabase is automatically available in your call 3. Whenever you encounter a metadata store question in your survey during the call, the column you specify to store is saved as the answer to the question Now, when you run reports you will have that metadata associated with the call as metadata store answers. Documentation on queuing outbound calls can be found here:\ [Queuing an Outbound Call](/insight/api/queuing-an-outbound-call)\ [Queuing Multiple Outbound Calls](/insight/api/queuing-multiple-outbound-calls) ## **Inbound Association** Associating a metadata record with an inbound call can be accomplished via the metadata filter and metadata store question types. The metadata filter question type will take a provided value as well as a column in your metadatabase to filter on and will match all rows in your metadatabase that match that value. It's as simple as that; if the value exists in your metadatabase you immediately have that metadata associated with the caller. You can even filter on the ANI/IP address of the user taking the survey such that if you add the ANI or IP address of users to your metadatabase before they take your survey you can instantly associate metadata with those users. There may come a time where you have multiple ANI/IP address duplicates in your metadatabase and therefore the metadata filter question will match multiple values. For this circumstance, you can utilize the metadata store question's store row option to store only the latest stored record. This way you can ensure you're only associating with the last added record when storing the column values for the associated metadata as the metadata store question answers. Let's use a sample use case to demonstrate this process: > You have a call center where your agents are working with your callers. After your agent has completed the call, you wish to transfer the caller to your feedback survey and want to associate the agent who handled the call with the survey response. This is where your metadatabase comes into play. You have two options, if you know your callers ANI beforehand, you can pre-populate the metadatabase for your survey with the ANI of your caller and any additional columns you wish to associate with the caller. If you are transferring in real time, you can utilize the metadata push api method to add that metadata record into your metadatabase right before you call connects. Once your caller has connected to the survey and the associated ANI is stored in your metadatabase you can use the metadata filter question type to filter that column with the ANI of your caller, associated the metadata record with the current call. You can then use the metadata store question to store any columns from the associated metadata record by utilizing the store row option as 'Latest', therefore storing only the last added record for that ANI. Documentation on adding metadata records via the api can be found here:\ [Adding Metadatabase Records](/insight/api/adding-metadatabase-records)