Survey specifications

Feedback > Surveying > Survey Programs > Specs

Survey specifications, also known as Specs, define the content on the pages of surveys. The Specs screen both manages saved versions of specifications, and determines which versions are used by the Survey engine to create the personalized surveys survey takers see. This screen also defines the set of specifications available to Anonymous surveys.

When a specification is ready to be tested and used in the Survey engine, click Create and push new survey specification to add it to the specs list and copy it to the Survey engine. Each time that button is clicked, a new specification (version) is added to the Specs list. For more information about pushing specs, see Push surveys.

Each survey definition can have multiple specifications but only one of them is marked as default: this one is associated with all new invitations. In the specs list, the name of the default specification always begins with [Def]. To change which one is marked as default, select the desired spec and click Make this the default for invites. Changing the default immediately affects all new invitations.

Important: Survey specifications are superseded by Survey versions.

Pushing a specification creates a version in Specs and once pushed, one becomes the version survey takers see

Properties

Name
View only. Same as the Brief Name value, except the name for the default version begins with [Def] for easy identification.
Brief Name

Descriptive name of the version; appears in the Program list on the left of the page. By default, the name is the internal Spec ID assigned by Experience Cloud.

Take into account these considerations:

  • Use a clear and descriptive name to someone else looking at the list.
  • When a version was formerly used in production to collect responses, change the name to include prev., or some other consistent label. This makes it easier to identify former specifications if needed.
  • Many companies include the save date in the name.
Description
Detailed information about the version.
Auto Re-push

Automatically pushes updated supporting data to the Survey engine. The data include company and unit data, field and AltSet definitions, and more. When selected, the data for:

  • Personalized invitation surveys, specs are pushed whenever invitations are sent out.
  • Anonymous surveys, specs are pushed every 5 minutes.
Important: Use this option for live, in-production specifications only. Deactivate it when the spec is no longer the default or live to avoid unnecessary transactions.
Sync Required
View only. Indicates when Experience Cloud as determined the specification should be synchronized or re-pushed to the Survey engine. This should not happen on a production instance, but often appears in development as changes are made to the specification.
Last Sync Time
View only. When the version was was last synced or re-pushed.
Spec ID
View only. Internal, unique identification of the survey specification version.

Actions

For more information, see Push surveys.

Make this spec the default for invites
For Personalized invitation surveys only. Declares a spec version to be the default specification. All new invitations use the default specification when the invitation is created. Changing the default immediately affects all new invitations. In the Specs list, the name of the default specification begins with [Def].
Re-push selected survey spec

Overwrites the specification's supporting data on the Survey engine; it does not affect the specification on the Survey engine. Do this once to ensure the data is current, and the use the Auto-Re-push option to automatically update the data for live surveys on production systems.

Supporting data includes (but is no limited to):

  • Translations (and locales) of fields or AltSets used in the survey.

  • Survey designs (looks and feels and customizations).

  • AltSet changes, such as changing a definition or adding an alternative.
  • Unit changes.
  • Language dropdown conditions on the welcome page.

  • Survey parameters (to use in the survey's URL).

Translate to block model
Transforms a previous survey spec format and creates a new Survey version in Admin Suite Surveys.

This action is only valid when the Spec was originally created using the first Survey editor version.

Create and push a test survey

Creates a real survey record and survey using random Unit and E-fields. Submitting the survey commits the responses to the database and they appear in reports.

After clicking the button, the screen updates and links to the survey appear at the bottom of the screen. Click the links to test the survey.

links to preview surveys for the test
Warning: This option adds survey responses to the company responses. After testing the survey with this option, locate and junk the survey record to keep it from being included in reports.
Create and push a reusable survey

Creates a reusable survey for testing. A reusable survey may be taken multiple times without affecting reports. Submitted responses are immediately junked and never included in reports. For more information, see Reusable surveys for testing.

Create, push and email a test survey
Creates a real survey and invitation, and emails the invitation to the currently signed-in administrator. The survey uses random Unit and E-fields.
Warning: This option adds survey responses to the company responses. After testing the survey with this option, locate and junk the survey record to keep it from being included in reports.
Transfer Survey Engine Responses
The Survey engine automatically submits survey responses to the Experience Cloud as soon as possible, typically within seconds of the respondent completing the survey. However, the Survey engine can be backed up with submittals. Use this option to tell the Survey Engine to raise the priority for submitting responses for the specification. Generally, you should never have to use this option.
Update and push selected survey spec
Overwrites the specification in Experience Cloud, including the Survey engine. On a production instance, only do this on default specs when there have been minor changes, such as spelling-error fixes. All unopened surveys include the change when they are opened. You may use this option on sandbox instances.
Warning:

Be aware of these issues:

  • If the spec fails to validate, it is not pushed.
  • Changes to Unit and E-Fields do not see the correct values in the survey.
  • Survey takers taking the survey when it is pushed see the change when they load the next page. Any change to the number of pages, moving elements between pages, or reordering the pages break the flow and the survey taking experience suffers.
  • If new fields were added, using this option can damage survey records.

Spec Code

The XML definition of the survey specification; includes translations, if any. 

Reusable surveys for testing

A reusable survey is one that can be used for testing and verification, and can be taken multiple times without affecting reports. because the survey responses are immediately junked and never included in reports. Reusable surveys have URLs that can be shared so multiple people may "take" the survey and see how it looks and responds.

Random reusable survey

The Create and push a reusable survey action quickly creates a reusable survey useful for verification and debugging. You can access the survey with a URL similar to this: survey.medallia.com/?test-[company], where [company] is the company name.

Creating the survey with the Create and push a reusable survey action has a few issues:

  • All of the company's surveys share the same reusable link. When you create a new reusable survey, it replaces any existing survey. This can be problematic when multiple people are creating and testing different surveys.

  • The survey uses random Unit and E-fields of existing survey records. As such, use this to option to test general design and usability. You can share this link with company representatives as long as they understand the randomness of the data.

    Tip: If the reusable survey does not have he desired design or customization, click the Create and push a reusable survey action again to create a new reusable survey. Keep doing this until you get a survey record that has the desired Unit and E-fields to match the conditions that load the desired design. Alternatively, consider creating a predictable reusable survey with the importer.

Predictable reusable survey

A predictable reusable survey is one where you can associate a specific Unit ID and supporting field values with a reusable survey, and the survey has a unique URL not associated with the Create and push a reusable survey action.

This process works by loading a Reusable ID in a survey import specification, and associating that ID with a ID of an existing survey specification. This specification is the minimum required to create a reusable survey:

/* Minimum specification needed to create reusable surveys 
 */
<import-spec inputType="CSV" columnsCheck="ALLOW_EXTRA_COLUMNS" name="SURVEY: reusableSurveyImport" description="">
	<input-column heading="survey spec" />
	<input-column heading="reusable survey" />
        /* Optionally add other fields, including Unit ID * /
	<output-column-group pluginName="Survey" recordUpdateMode="CREATE">
		<output-column>
			<input-column heading="survey spec" />
			<target-field fieldId="committed_survey_spec" fieldName="Committed Survey Spec" requiredness="REQUIRED" type="ENUMERATED">
				<enumerated-field-parse-options mappingKey="NAME" />
			</target-field>
		</output-column>
		<output-column>
			<input-column heading="reusable survey" />
			<target-field fieldId="reusable_id" fieldName="Reusable ID" requiredness="REQUIRED_USED_FOR_DUPLICATE_CHECK" type="STRING" />
		</output-column>
		<!-- Mappings for other columns -->
	</output-column-group>
</import-spec>
When the following data are imported (active) via the above specification:
survey spec,reusable survey
1-orion-10283,orion-reuse1
You can access the survey based on the specification with the Spec ID of '1-orion-10283' with this URL: survey.medallia.com/?orion-reuse1. The minimum specification above picks a random existing survey record, and a random design for the survey.
Tip: To see the survey for a specific unit, add the Unit ID to the specification and .CSV file. Include any additional field necessary to match the conditions that choose the desired design and customization.
These steps create a predictable reusable survey:

  1. Create a survey specification and at least one survey design.

    To target a design and variation, define the condition with Design rules or By Unit Groups.

  2. Create a CSV file that defines one or more reusable surveys. This example creates two reusable surveys based on the same survey specification, but associated with two different Unit IDs.

    survey spec,reusable survey,e_unitid
1-orion-10283,orion-reuse1,sm-94404
1-orion-10283,orion-reuse2,at-14397

  3. Create a survey processor Auto Importer specification that maps:

    • Survey spec to: fieldId="committed_survey_spec"

    • Reusable ID to: fieldId="reusable_id"

    • Unit ID to: fieldId="e_unitid"

  4. Test the import on the processing the CSV in Pretend mode.

    1. On the Auto Importer Processors screen, use the Process file on pretend action.

    2. Click Save to process the file.

    3. If no errors, proceed to the next step. Otherwise, debug and repeat this step.

  5. On the Feed Files screen, locate and select the file you uploaded. If the processing report shows no errors, use the Reprocess on Active action to create the reusable survey.

  6. Open the survey in a browser using the reusable ID you included in the csv file, similar to: survey.medallia.com/?orion-reuse1.

If the survey does not open, verify:

  1. You have the correct reusable ID.

  2. The file was processed on active with no errors on the Feed Files screen.

  3. The server (such as survey.medallia.com) is correct for your instance. To test this, create a random, reusable survey with the Create and push a reusable survey action, and at the bottom of the screen, click the link that opens the survey. This shows the Survey engine the survey instance you are using.

Debug survey specifications

To debug an issue with a survey specification, it is sometimes necessary to view the specification and data associated with the spec. If navigating from Medallia network space, you can manually add &debug=spec to the end of the link to open it in debug mode: survey.medallia.com/?orion-feedless&debug=spec.

Restriction: This feature or information is available to Medallia employees only and it is not to be shared outside the company.

This option sends the specification and survey data to the browser as XML. The resulting XML object has this general format:

<evil-transplant>
 <spec>
    [
     translations
     altset values
     fields E, Q, UG, U
     specification
    ]
  </spec>
  <survey>
    <value field= >...
     ...
    <presentation> ... Design ... </presentation>
    <mobilePresentation>  ... Mobile Design ... </mobilePresentation>
  </survey>
</evil-transplant>

Sometimes it is easier to review the generated survey as one long page instead of the default pages, which you can do so using survey.medallia.com/?a8wndkaj299...&show=all.