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>