Panel administration

Panel administration can be achieved either via the survey source code or via the Panel applet. This article primarily describes how to use the Panel applet. To quickly reference the source code example, click here.

The Panel applet allows users with a system role of Survey Creator or greater to handle various administrative duties related to panel management. This applet brings common tasks such as adding panel groups to a survey, changing the external panel name, quickly finding the invite links, and editing panel redirects all in one single place.

To access the Panel applet, expand the Field Management button group, and click Panel.

This will open the Panel applet. 

The Panel applet grid contains the following columns:

Column	Description
ID	The ID (number) code assigned to the panel.
Panel	The assigned panel name. If the panel has a programming note, a blue info iconwill appear to the left of the panel name.
Display As	An editable field used to create an alias for the panel. The new name is visible for all users and will be displayed in reports and exports.
Invite Link Format	This field can be used as-is or can be edited to add new parameters.
Copy Invite Link	Clicking the icon in this column saves the invite link to the user's clipboard so that it can be easily pasted into emails.
Redirect Links	Opens the Panel Redirect modal, which displays editable redirect links for the panel.
Update Users	Panels with a User icon are panels that have an email domain associated with their panel ID and can therefore support the addition of PFM users. Quickly add or remove PFM users via this button.
Responses	Allows users to download an Excel sheet with all respondents from the panel with commonly used panel-related fields. This is a quick way to grab responses for a given panel, either during testing or at the end of fielding. The Expunge option is a shortcut to the Expunge applet.
Delete	Clicking the trash icon removes the panel from the survey.

The columns are movable and can be dragged to the left or right. To reset the column order, refresh the web browser.

Adding panels

Panels can be added to a survey either via source code or via the Panel applet. To add a panel via the applet, use the Add New Panel Source dropdown menu/search field. The search field will keyword match existing panel groups. Panel groups can be searched for via their name or assigned IDs. Panels must be added individually using this menu/search field. To add a new panel you should partner with the Survey Programmer (SP) to create a local panel sheet described further below.

Once added, the displayed panel name can be edited to maintain panel privacy between users by clicking the text in the Display As column. Enter the new name, and click outside the cell to save the new display name. Remember that the Panel applet itself is not visible to anyone with a system role setting lower than Survey Creator; however, this displayed panel name will drive what is displayed in the data (reports and exports) and in the Quota Manager applet (visible to all).

Adding panels via source code

In r7.5 and earlier, all panel management is done via the survey source code. Partner with an SP for this method. The SP utilizes the use panels tag within the app config widget. This allows the SP to specify a list of which panel numbers should be used in the survey. The SP must have a system sheet 'system_panels', or a local sheet which lists all panel numbers that use panels will call to.

This method is still viable in r8.0 and later. However, starting with r8.0, the use panels tag has been moved to the background as a system default. It is no longer in the survey source code and must be manually added back in, along with the necessary auto redirect and panelsheet tags.

For all software versions, if you need to add a new panel or modify a panel's information, you must create a local panel sheet. After creating and uploading the local panel sheet to the survey's Spreadsheets applet, the sheet must be referenced within the survey code. See the below example for how to prepare the source with the necessary tags. Define the panels needed in the use panels tag. Panel IDs can be listed in a comma-separated list. Partner with an SP for this method.

definesheet: surveyid.panelsheetname

app config
totalcap: y
#totalcap: y is a system default as of r8.0 and can be omitted
auto redirect: surveyid.panelsheetname
panelsheet: surveyid.panelsheetname
use_panels: 2,100,991

Panel-specific variables

On every survey, whether the Panel applet is used or the use panels tag is applied:

• panel is created;
• panel_quota is created, which is a quota comprised of all panels identified via the Panel applet or the use panels tag;
• pfm_approve will auto-populate according to the respondent's panel value, using a value taken from the system.system_panels sheet or local panel sheet.

Panel links

Our software's URL and autoredirect system is designed to be flexible to work with the many different vendors and the endless subtle needs for the surveys that run on our platform. We have query string URL parameters to make countless combinations that service almost any entry link URL requirement. Understanding how to properly format an entry URL (invite link) for a panel vendor, how to store the data captured, and how to pass it back into the final redirect can be complex. It is critical to test the entry URL from start to finish until you are redirected to the final landing page to ensure all data is being captured, stored, and passed back properly.

The Invite Links and Redirect Links reflect what we have "on file" in our system panel sheet at the time of adding the panel. Any edits made to the links, however, are local changes and do not affect our system panel sheet or other surveys in any way.

Invite links

This field can be used as-is or can be edited to add new parameters (for example, a parameter to identify the country). If you change the format, ensure your link is correct by testing the link before sending it to your panel contact. Note that you can simply delete the text in the cell to revert to its original value. 

There is a set format for our survey URLs. After the survey ID (SID) and record ID (trans_id) are defined, SPs can set up as many additional query string parameters as needed for a survey. The general format to include additional parameters is as follows:

http://servername.intellisurvey.com/pub/survey_ID/record_ID?pan=<param1>&c=<param2>&os=<param3>

• The beginning of the query string portion of the URL is established with a question mark (?) and then is followed by the first parameter name given, for example 'pan', followed by the value passed in place of '<param1>'.
• The second, and each additional parameter, is separated with an ampersand (&) followed by the name given, for example 'c', the value passed in place of '<param2>', and so on.

Redirect links

Many panels require that custom data be appended to URL parameters. This custom data needs to be passed back to the panel provider in a properly formatted redirect link. Sometimes this data is of a variable nature and is written in our survey source. Survey variables, as well as Perl conditionals, are valid syntax in the redirect sheet and can be referenced in the redirect link. Some panel providers may have a value that is provided in the invite link but is not captured by any survey fields. Such values can be easily "passed through" and may be referenced by prepending $pan_ to the parameter name as defined by the entry URL.

Panel programming notes

When a panel is added to a survey via the Panel applet, a blue info icon will appear to the left of the panel name if the panel has a programming note. Click on the blue icon, and a modal will display a specific message for the respective panel. 

Some panels need specific programming variables or a library include placed directly within the survey source code. This may be necessary for a variety of reasons, although the majority of the time, the panel needs a "secret key" passed back in the redirect links, but this key is not passed into the survey via the invite/entry link. With the Panel applet, any one-time changes to a redirect, such as adjusting the value for a secret key and passing it back, can now be handled directly within the Redirect Links column. Another growing request with larger panels is to utilize an API (Application Programming Interface) to pass back secure redirects. IntelliSurvey currently handles APIs with a library include placed in the survey code. Please partner with the SP to implement this.

Programming note example 1

In the example below, Panel Europe has a panel note that mentions there is a "status key" that needs manual updating in the passkey parameter for each redirect on file (likely a different status key for each unique status - Complete, Terminate, and so on). In this example, the Project Consultant (PC) should ask the panel vendor for the status keys or locate them within the project specific redirects sent via email. The PC should then find the passkey parameter within the redirect and pinpoint the example or placeholder for the status key currently in place. The PC should replace everything after the '=' until the end, or until the next parameter begins, with the new status key provided, and save the changes. Follow the steps below for more information.

1. Panel Europe is added to the survey, and the PC notices it has a programming note.

2. The PC clicks on the Redirect Links column to view the redirects on file. The PC sees the Complete redirect link below and locates the passkey parameter and placeholder.

https://redirectforsurveydomain.com?respid=$trans_id&psid=$pan_psid&passkey=<INSERTPASSKEYHERE>&s=1

3. The PC, who already has the status keys from the panel vendor, replaces everything after the '=' until the next parameter which begins with '&' with the new status key 'afh23r8afhasdf8a9'.

4. The PC makes the necessary adjustments to the remaining redirects and clicks Save.

5. Finally, confirm with the SP if there are any edits needed to the survey source for this particular panel. If yes, then ask the SP to confirm once the edits are in place and to republish the source. Someone familiar with entry links and redirects, for example a PC or SP, should test the panel invite links to ensure the test ID punches all necessary variables and is redirected successfully with the appropriate status to the panel vendor.

Programming note example 2

In the example below, Panel Americas uses signed end links for security purposes. A special API has been created, and a library include should be placed in the survey source code. Again, partner with an SP for implementation.

The SP places this include exactly as it is written, including the double square brackets '[[ ]]', at the top of the survey source somewhere after the set defaults widget. The SP saves the edits and publishes the survey.

Someone familiar with entry links and redirects, for example a PC or SP, should test the panel invite links to ensure the test ID punches all necessary variables and is redirected successfully with the appropriate status to the panel vendor.

Updating users: panel-related roles and rights

Panel Coordinator (PC) and Panel Field Manager (PFM) are survey roles that give proper rights and actions to panel partners. The Panel applet only allows the addition or removal of PFMs. All other survey roles must be managed via the Users applet. To view more about PC and PFM roles and rights for r8.0 and later, click here (for r7.5 and earlier, click here).

To add a user via the Panel applet, the panel group must already have been added as a panel source. Additionally, a blue person icon (the Users icon) must appear under the Update Users column. Click on the Users icon. A modal will appear in the center of the screen. Enter the email address for each user from this specific panel. Doublecheck the spelling, then click Save Changes. Finally, a confirmation message will appear. Repeat this for each panel as needed.

If the Users icon is not visible in the Update Users column, this means the panel does not have an email domain associated with their panel, and users cannot be assigned the role PFM. If this happens, you can either add a domain for the panel by reaching out to Support, or add the user as a different, lesser role (e.g., General Reports and Quotas User) via the Users applet.

Downloading panel responses

An Excel file can be downloaded to quickly pull all IDs and the most common and relevant fields for a respective panel. This is often needed for finalizing the survey and reconciling final IDs with the panel partner. The file will contain all IDs (all statuses) that entered the survey along with the following system variables by default:

• trans_id
• status
• resp_start_ts
• resp_last_ts
• elapsed
• entry_url
• final_redirect
• disp and disp_first
• oq

Any other panel related variables used in our redirect system that we have on file and include in the source code will also be added to the report, such as QPSID. As of r8.0, these variables are located in the System fields > panel_data chapter. Other variables can be added to the report on an ad-hoc basis by applying the chapter: panel_data to the variable. Other helpful variables could be anything that identifies the sample or stage type, country, or removal reasons for manually expunged respondents. 

The Expunge option visible here is simply a shortcut to the Expunge applet.

Panel deletion

The trash icon will delete a panel from the Panel applet. Once removed, this change is effective immediately. This will remove the panel from:

• the panel_quota in the Quota Manager,
• the Quotas tile in the Survey Dashboard,
• reports and exports (removing only the panel name),
• and the system redirects in place.

This will not remove any manually added panel variables in the source. Also, it will not remove the respondent data from the reports. The data remains intact, but the panel name will be replaced with "Invalid Value: X."

If a panel is deleted and then re-added, the previous PFM users will be automatically added. The panel and its respective counts will reappear in the panel_quota and the Quotas tile in the Survey Dashboard. However, any edits to the displayed panel name, the survey invite link, or the final redirects will need to be edited again.