Submitting and publishing SPL content (r9)

Creating new survey content and editing content comes in waves, and without a doubt, multiple revisions. Before reading this article, we highly recommend new Survey Programmers (SPs) review the full capabilities of the Editor applet by reading SPL editor overview and learn the basics of editing with the article Creating and editing surveys with SPL. Next, you are ready to submit and publish the code.

Submitting survey code

When you are ready to submit source code and merge it to the Draft (a.k.a., Development) version of the survey, click the Save Version button found in the top-right of the screen.

This presents a version comparison between the last compiled (built) version and the proposed edits. Changes that removed content will be in red, and changes that added content will be in green. It is best practice to review your changes and scroll from top to bottom. If the changes are correct, you are ready to parse (process) and update the survey. Click Commit Changes to continue. While the code is parsing, you may click Cancel Build to cancel the changes and revert to the last compiled version. 

Successful survey compilation

If the new code compiles without any errors, users will be taken to the next screen. This is the point when a new Draft (Development) version is created, and the survey will increment to the next version number. 

From here there are a few options on the screen. You can check the compilation notes in the Details section by clicking on the downward-facing arrow. In the Development Links section you can test the survey with various links, such as test levels 1, 1.1, and 2, or with a "live" link which simulates what the changes would look like to a live respondent. You can also add comments about the round of changes you submitted in the Version Comment section which can be referenced later in the Versions applet. If you wish to continue editing, simply click on the Back to Editor or Editor Mode buttons. Publishing the survey is discussed further below.

Survey Mechanics

The Survey Mechanics table provides a comparison of the previous version of the survey with the most recently compiled/current version of the survey.

The following columns are included in the table:

• Version - This column will always list the Previous and Current versions of the survey, with the version number shown in parentheses to the right. 
• Data Columns - The total number of fields in a survey (or the number of columns that would appear if all fields were exported in an Excel file). If the number of fields exceeds 15,000, the column header will turn red and an info icon will appear. Hovering over the icon will show a message, letting the user know that "The maximum number of columns in Excel is 16,384." 
• Time to Parse - The time in minutes and seconds it took the platform to parse the survey. 
• Survey Forms - The total number of pages in a survey. This includes both pages that are visible to the respondent and hidden.
• Visible Questions - The number of questions that are respondent facing.
• Quota Questions - The number of quota variables included in the survey.

Development Links

The Development Links section provides users with various Testmode links in order to test the newly parsed code. Remember that each time a survey is compiled (processed and built), that version automatically becomes the latest Draft version of the survey. The Live link/button, which simulates what the changes would look like to a live respondent, would display an unpublished version of the survey unless you publish it first.

Comments

When the survey is done building, a comment box appears, noting what changes were made to the source. There are three types of automatically generated comments: Added, Removed, and Changed. The widgets that fall under each category (added, removed, or changed) are listed by their ID. If multiple additions were made, you may see a count of additional widgets in that category is included, e.g., "Added Q54. Removed T5A, T5B, T5BR1, T5BR2., T5BR3, and 6 more."

To add greater detail, the text in the box can be edited. After making any changes to the text, click Update Comment. These comments appear in the Version applet's Comments column adjacent to their respective versions to provide details on the changes that were made.

Unsuccessful survey compilations

In contrast to the section above, if any issues are found while attempting to compile the source code, the parser displays them in a list. With a few exceptions, most issues will not stop the parser from building the survey, and the survey version will still be saved. 

Parse issues can be divided into four categories, from least serious to most: CAUTION, WARN, ERROR, or a ("STOP") ERROR.

• CAUTION - Indicated by a yellow triangle, these are the least serious of parse issues, and can be more of an informational note. A new survey version is saved, and the survey can be published. Examples of "cautions" include possible Perl code errors and "valid triggers" not found in conditional statements.
• WARN - Indicated by the orange rectangle, these are moderately serious parse issues. The survey will compile/build with warnings, and a new survey version is saved, but the survey may not render correctly. The survey cannot be published until all warnings are corrected. Examples of warnings include unrecognized lines of code and empty type tags.
• ERROR - Indicated by the red rectangle, these are more serious parse issues. The survey will compile/build with errors, and a new survey version is saved. The survey can be partially rendered, but it will eventually stop. The survey cannot be published until all errors are corrected. Examples of errors include missing a mandatory tag for a widget or having an invalid question type. 
• ("STOP") ERROR - "Stop-errors" are indicated by a red circle with an exclamation point icon and are caused by server issues or critical errors in the code that stop the parser instantly. In comparison to a general ERROR, here the survey version cannot be saved, and the errors must be addressed immediately to parse the survey. Stop-errors fall into two groups:
  
  • • Expected/Known - The specific error is known and listed next to the red circle icon. An example of a known error is duplicate question or option IDs.
    • Unexpected/Unknown - These errors are unknown and, therefore, have little information provided. The error message usually says "Unexpected error during build." An example of an unexpected error includes when there are an excessive number of survey errors. 

CAUTION, WARN, and ERROR examples:

Known STOP-ERROR example:

Unknown STOP-ERROR example:

Resolving parse errors

To fix errors and return to the survey editor, click Back to Editor.

Lines containing known issues will have a yellow or red colored icon next to the line number. You can hover your mouse over each icon to see the error message and suggestions for fixing the issue. Continue editing as needed to resolve all issues found. 

If you attempt to publish a survey that still contains significant errors, you will be notified and blocked from publishing until these errors are addressed.

Publishing a survey

SPs may commit source code changes as many times as needed without publishing the survey. Remember, however, external users testing with the "live" link will not see any changes until the latest survey version has been published. When the survey is approved and ready to "go live," the survey must be published. When a survey is ready to be published, click the Publish Survey button. This button is found at the top-right part of the screen for every applet and tab of your survey.

A confirmation modal will appear. Click Yes to continue with the publishing process. Click No to cancel.

Once the survey is published, a green circle with checkmark icon will appear at the top-left of the screen. Other publishing options, such as the Publish Survey button will be deactivated. If you would like to continue editing, click Back to Editor return to the survey editor. 

Next steps

At this point, we recommend you test your survey changes thoroughly. If this is your first draft of the survey, it is highly likely you will need to make revisions and repeat the editing process. Here are a few other articles that you might find helpful for common next steps:

• Run your surveys in Testmode.
• Add panels to your survey.
• Create quotas and set quotas in the Quota Manager applet.
• Add your colleagues and team as users to the survey.
• Begin and manage translations for your survey.