XML survey format

Euphorie supports import and exporting of surveys via a simple XML format. The document used is similar to the structure of a survey as it appears in an Euphorie site. This chapter assumes that you are already familiar with the basic survey structure.

The current XML format is 1.0 and uses an XML namespace of http://xml.simplon.biz/euphorie/survey/1.0.

Note

It is mandatory to declare the XML namespace in your file. Without the namespace Euphorie will not correctly import your data.

sector element

The root of the XML file is the sector element.

Allowed elements in sector
Element Mandatory Description
title No Title for the sector organisation
account No Account login information for this sector
contact No Contact information for the sector
logo No Inline image with sector logo
survey Yes Survey

The account, contact and logo elements are only used when a new sector is created from an XML file. This option is only available to site and country managers in Euphorie.

The contact element is a container supports optional name and email elements.

Example

<sector xmlns="http://xml.simplon.biz/euphorie/survey/1.0">
  <title>Information technology</title>
  <account login="coders" password="s3cr3t" />
  <contact>
    <name>Team lead</name>
    <email>leader@example.com</email>
  </contact>
  <survey>
    ...
  </survey>
</sector>

survey element

The survey element defines a survey. It contains all the profile questions, modules, risks, etc. that make up a survey.

Allowed elements in survey
Element Mandatory Description
title Yes Title of this survey
classification-code No NACE-based classification code
language Yes Language used in the survey
evaluation-optional No Inline image with sector logo
profile-question No A profile question (can be repeated)
module No A module (can be repeated)

The language must be specified using the ISO 3166 country code, possibly extended with a two letter alpha code to indicate the region. See the “Language tags in HTML and XML” document from W3C for more information on language codes.

The evaluation-optional element is a boolean and must contain either true or false.

Example

<survey>
  <title>Software development</title>
  <classification-code>A.1.2.3</classification-code>
  <language>en</language>
  <evaluation-optional>true</evaluation-optional>
  <profile-question>
    ...
  </profile-question>
  <module>
    ...
  </module>
  <module>
    ...
  </module>
</survey>

profile-question element

The profile-question element is used to create a profile question. It is very similar to the module element.

Allowed elements in profile-question
Element Mandatory Description
title Yes Title of this profile question
description No Description (HTML)
question Yes Question asked to determine use of profile section in survey.
module No A module (can be repeated)
risk No A risk (can be repeated)

The type of profile question is determined via a mandatory type attribute. This can be set to optional or repeat.

HTML tags used in the description must be properly escaped or wrapped in a CDATA block.

A profile question must contain either modules or risks; it is an error to use both module and risk elements as direct children of a profile-question. It is of course allowed use modules which themselves contain risk elements.

Example

<profile-question type="optional">
  <title>Mobile access</title>
  <question>Do your employees work remotely?</question>
  <description>&lt;p&gt;Working out of the office can introduce many
    new risks that may not be under your direct control.&lt;/p&gt;
  </description>
  <module>
     ...
  </module>
  <module>
     ...
  </module>
</profile-question>

module element

A module is used to group a number of risks that belong together. This element is very similar to the profile-question element.

Allowed elements in module
Element Mandatory Description
title Yes Title of this profile question
description No Description (HTML)
question Yes/No Question asked to determine if module should be skipped
solution-direction Yes Solution suggestions for action plan e phase (HTML)
module No A module (can be repeated)
risk No A risk (can be repeated)
image No Image for this module

If a module is optional this can be indicated by setting the optional attribute to true. If this attribute is false or not present a module is assumed to be mandatory. If a module is optional the question element is mandatory.

HTML tags used in the description and solution direction must be properly escaped or wrapped in a CDATA block.

A module must contain either modules or risks; it is an error to use both module and risk elements as direct children of a module. It is of course allowed use modules which themselves contain risk elements.

See the image element for how to specify images.

Example

<module optional="yes">
  <title>Laptops</title>
  <question>Do your employees use laptops?</question>
  <description>
    &lt;p&gt;Laptops are very common in the modern workplace.&lt;/p&gt;
  </description>
  <risk>
    ...
  </risk>
  <risk>
    ...
  </risk>
</module>

risk element

The risk element is the workhorse of a survey: it defines a single risk.

Allowed elements in risk
Element Mandatory Description
title Yes Title of this profile question
problem-description Yes Problem description shown if risk is present (HTML)
description Yes Description (HTML)
legal-reference No Legal and policy references (HTML)
evaluation-method Yes/No Risk evaluation method
solutions No Container for standard solutions
image No Key image for this risk

The type of risk is identified with a mandatory type attribute. This can be set to risk, policy or top5. For policy and top-5 risks the evaluation-method and default-* are not used.

For risks of type risk the evaluation-method method element must be present and set to calculated or direct. Default values for the evaluation method can be set via attributes. For risks with a calculated evaluation the attributes are:

  • default-probability: one of small, medium or large
  • default-frequency: one of almost-never, regular or constant
  • default-effect: one of weak, significant or high

The attributes for risks with a direct evaluation method are:

  • default-priority: one of low, medium or high

Standard solutions for a risk can be provided in a solutions container.

Up to four images for a risk can be defined by using image element.

Example

<risk type="risk">
  <title>Are your desks at the right height?</title>
  <problem-description>
    &lt;p&gt;Not all desks have the correct height.&lt;/p&gt;
  </problem-description>
  <description>
    &lt;p&gt;The right height is important to prevent back problems.&lt;/p&gt;
  </description>
  <evaluation-method default-probability="small" default-frequency="regular"
     default-effect="high">calculated</evaluation-method>
  <solutions>
    <solution> ... </solution>
  </solutions>
</risk>

solution element

Standard solutions for a risk are defined using the solution element

Allowed elements in solution
Element Mandatory Description
description Yes Description
action-plan No Text for the action plan
prevention-plan No Text for the prevention plan
requirements No Text for the requirements

Example

<solution>
  <description>Use height-adjustable desks</description>
  <action-plan>Order height-adjustable desks for desk workers.</action-plan>
</solution>

image element

The image element is used in module and risk elements to add extra images. The element has three optional attributes:

caption
The caption for the image.
content-type
The MIME content type for the image. This is generally one of image/gif, image/png or image/jpeg.
filename
The original filename for the image. If content-type is not provided this is used to guess the MIME type.

The contents of the element is the Base64 encoded raw image data.

Example

<image content-type="image/gif">R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAEALAAAAAABAAEAAAIBTAA7</image>

Full example

The XML document below demonstrates all elements documented here.

<?xml version="1.0"?>
<sector xmlns="http://xml.simplon.biz/euphorie/survey/1.0">
  <title>Information technology</title>
  <account login="coders" password="s3cr3t" />
  <contact>
    <name>Team lead</name>
    <email>leader@example.com</email>
  </contact>
  <survey>
    <title>Software development</title>
    <classification-code>A.1.2.3</classification-code>
    <language>en</language>
    <evaluation-optional>true</evaluation-optional>

    <profile-question type="optional">
      <title>Mobile access</title>
      <question>Do your employees work remotely?</question>
      <description>&lt;p&gt;Working out of the office can introduce many
        new risks that may not be under your direct control.&lt;/p&gt;
      </description>

      <module optional="yes">
        <title>Laptops</title>
        <question>Do your employees use laptops?</question>
        <description>
          &lt;p&gt;Laptops are very common in the modern workplace.&lt;/p&gt;
        </description>
      </module>
    </profile-question>

    <module>
      <title>Office environment</title>
      <image content-type="image/gif">R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAEALAAAAAABAAEAAAIBTAA7</image>
      <description>
        &lt;p&gt;Your employees have to use office equipment every day.&t;/p&gt;
      </description>
      <solution-direction>
        &lt;p&gt;The standard health and safetety guidelines have
        many useful tips for improving the office environment.&lt;/p&gt;
      </solution-direction>

      <risk type="risk">
        <title>Are your desks at the right height?</title>
        <problem-description>
          &lt;p&gt;Not all desks have the correct height.&lt;/p&gt;
        </problem-description>
        <description>
          &lt;p&gt;The right height is important to prevent back problems.&lt;/p&gt;
        </description>
        <evaluation-method default-probability="small" default-frequency="regular"
           default-effect="high">calculated</evaluation-method>
        <solutions>
          <solution>
            <description>Use height-adjustable desks</description>
            <action-plan>Order height-adjustable desks for desk workers.</action-plan>
          </solution>
        </solutions>
      </risk>
    </module>
  </survey>
</sector>