IMPORTANT: Questionmark recommendeds using the Delivery Odata API (click here for documentation) for new integrations, not the QMWISe API. Although we currently continue to issue maintenance updates to this API to support customers with current QMWISe-based integrations, we are no longer adding new methods/functionality to QMWISe. 
  1. Questionmark QMWISe API Guide
  2. Web service methods
  3. Schedule
  4. SendEmailsScheduledEvent

SendEmailsScheduledEvent

Applies to the following products: 
Questionmark OnDemand
Questionmark Perception
Questionmark OnPremise
Applies to the following Perception versions: 
Perception 5.7

This method is used to send an email to the participants and proctors associated with the event at a test center. The email will be sent through an SMTP server whose IP address is stored in perceptionv4.ini (Perception Version 4) file or the Server Settings page (Perception 5). The format of the email will be determined by predefined template. The email templates have the ability to have different languages included in the template, but if there is no template specified for a particular language the email is sent in English. The proctor assigned to a test center is setup through Enterprise Manager.

All the emails sent by this QMWISe method are sent in HTML format.

The method carries out the following processes when it is run:

  • Checks if the fields have been filled in
  • Checks whether the email templates are present
  • Checks that the specified event and test center exists
  • Retrieves all the schedules for this event
  • Sends an email to each participant found to be scheduled for this event
  • The proctor email is checked against all administrators associated with the test center
  • If Proctor_Only is set to 1 and the proctor email is found to be associated with an administrator the emails are sent to this one individual
  • If Proctor_Only is set to 1 and the proctor email can not be associated with any of the administrators associated with the test center the email is sent to all administrators associated with the test center
  • Sends an email to each proctor assigned to the schedule

If the email cannot be processed a SOAP fault is returned. Samples of why SOAP fault messages that can be returned include:

  • The test center does not exist
  • An invalid data error when <Proctor_Only> is not set correctly
  • The event (sub group) does not exist
  • There are events schedules that have more than one test center
  • The email templates are not accessible
  • The IP address for the SMTP server is not found set

This method can use secure headers to verify credentials before it is processed by Perception.

Available in:
  • Version 4.4 +
  • Version 5.1 +

This method requires additional license options to be enabled. To use this method you will need to have a valid license for the SAP Connector.

Parameters

Input name Description Data type Optional field?

Event

The event name

String

Y

Test_Center_Name

The name of the test center

String

Y

Proctor_Only

0 - The email is sent to all associated participants and the proctor

1 - The email due to be sent to participants is sent to the proctor in addition to the default one sent by the system. No email will be sent to the participants

Integer

N

Proctor_Email

This is the proctors email address. All email correspondence will also be sent to this address.

String

Y

 

The event and test center name are case insensitive.

Response

Output name Description Data type

EmailSentToParticipant

The number of emails sent to participants

Integer

EmailSentToProctor

The number of emails sent to proctors

Integer

Email templates

The templates used for the emails are stored as XML files in the following folder location on Perception:

Version 4
  • C:\Program Files\Questionmark\Perception4\server\qmwise\Template
Version 5
  • C:\Perception 5\Repositories\shared\<MyRepository>\system\emailtemplates

    Where <MyRepository> is the name of your shared repository.

The templates can be altered by using an XML or ASCII editor, such as Notepad. The standard templates are listed below.

Template name Description

EmailTemplate.xml

Contains the template sent to the participants, which includes the participant user name, password, and schedule details

EmailTemplateProctor.xml

Contains the template of the email sent to the proctors, it contains a list of the participants that have been scheduled

The default email template for the email sent to participants is:

<?xml version="1.0" encoding="utf-8" ?>

<!-- The text between two % % are input field names. This will be replaced by their actual value. "\n" is for line break -->

<Template>

<Language value="en">

<From>admin@qm.com</From>

<Subject>Schedule</Subject>

<Body>

<![CDATA[ <html>

<head>

<title>%First_Name% %Last_Name%</title>

</head>

<body text="#000000" bgColor="#ffffff" leftMargin="0" topMargin="0">

<table width="680Px" height="1000Px" bgcolor="Silver" cellSpacing="0" cellPadding="0" border="1">

<tr>

<td><b>Participant: %Participant_Name%<br>Participant ID: %Participant_Name%</b>

<p>Access information for XYZ Certification <b>User ID: %Participant_Name%<br>Password: %Password%</b> </p>

</td>

</tr>

</table>

</body>

</html>]]>

</Body>

<DateFormat>MM/DD/YYYY</DateFormat>

</Language>

</Template>

The email is automatically customized for each participant by using field names to merge the relevant data for each participant when the email is dispatched. The field names are placed within the defined XML tags to form the email. The email consists of the following XML tags.

XML Tag Description
Language

Describes the language of the email so that it can be associated with the correct language settings as defined in Perception. Possible values include:

  • en
  • fr
  • de
  • es
  • it
From This is the email address of the sender
Subject This is the subject line that will appear in email applications
Body

This contains the main body of text that the email is composed of. By using the CDATA XML character tag it is possible to include any standard HTML tags and content in this email. To insert text, links or images you must ensure that they are all contained in a fully formed html document within the CDATA tag.  
DateFormat

This determines the date format of the dates passed by the %Schedule_Start% and %Schedule_Stops% field names. Possible formats include:

  • DD/MM/YYYY
  • MM/DD/YYYY
  • YYYYMMDD

Field names that can be used within the tags are identified through the use of a % sign before and after the field name. Not all field names can be used within the header and body tags. For a list of field names available and where they can be used, please refer to the Field Name section.

The email template for the email sent to proctors is:

<?xml version="1.0" encoding="utf-8" ?>

<!-- The section Header defines the columns of table to be displayed in the email body. The text between two %% are input field names. This will be replaced by their actual value. -->

<Template>

<Language value="en">

<From>admin@qm.com</From>

<Subject>Schedule</Subject>

<Header>Participants for the test center: %Name% </Header>

<Body>

<Column1>%Participant_Name%</Column1>

<Column2>%First_Name%</Column2>

<Column3>%Last_Name%</Column3>

<Column4>%Password%</Column4>

<Column5>%Assessment_Name%</Column5>

</Body>

<DateFormat>YYYYMMDD</DateFormat>

<Footer>Footer text will be added here</Footer>

</Language>

</Template>

The email template above creates a table listing the participants and their details, which is sent to the proctor. The email template can be modified to include further columns and information in the table. The data contained in the table is populated from the database using field names.

The field names can be used in the XML tags to determine the information shown in the table. The XML tags used in the email template are described below.

XML tag Description
From This is the email address of who the email is sent from
Subject This is the subject line that will appear in email applications
Header Defines the text you would like to appear above the table
ColumnX Defines the columns used to create the table. Where X is the number of the column (i.e., Column1, Column2, ... Column7, Column8)
DateFormat

This determines the date format of the dates passed by the %Schedule_Start% and %Schedule_Stops% field names. Possible formats include:

  • dd/mm/yyyy
  • mm/dd/yyyy
  • yyyymmdd
Footer Can contain any text you would like to appear below the table

Field names

The possible field names that can be used in the email templates are listed below.

Field name Description Participant Email Proctor Email
Usable in <BODY> Usable in <HEADER> Text used in <HEADER> Can be used in <BODY>

%Group_Name%

The name of the group that the participant belongs to

-

%Description%

The group description

-

%Schedule_Starts%

The schedule start date

Schedule Starts

%Schedule_Stops%

The name schedule

Schedule Stops

%Name%

The test center name

Schedule Name

%Label%

The label associated with the test center or a short description applied to it

-

%Department%

The department the test center is associated to

-

%Country%

The country the test center is located in

-

%Location%

The location of the test center

-

%Details%

The type of participant

Participant Type

%Participant_Name%

The participant user ID

Participant ID

%Title%

The title associated with the participant (i.e., Dr, Mr, Mrs, etc.)

Title

%Gender%

The gender of the participant

Gender

%First_Name%

The first name of the participant

First Name

%Last_Name%

The surname of the participant

Last Name

%Password%

The password of the participant

Password

%Details_3%

The language associated to the participant

-

%Primary_Email%

The email address of the participant

Primary Email

%Details_2%

The organization the participant belongs to

-

%Details_1%

The short description associated with the organization

-

%Organization_Name%

The name of the organization the participant works for

-

The system picks the appropriate email template and produces an equivalent HTML page and saves this in a temporary location. The HTML page is then converted to a PDF. The process is repeated for the total number of emails sent and then combined into a PDF. The number of emails included in a single PDF is configurable.

Configuring this QMWISe methods in Perception 4

In Perception 4.4, this method is installed as part of an add on and need to be setup appropriately. However, in Perception 5, this method is pre-installed.

The perceptionv4.ini file contains setting used by Perception. Modifications will need to be made to this file to use the full functionality of the QMWISe methods described in this guide. The change includes adding the following line to the QMWISe section of the perceptionv4.ini file.

SMTP IP Address=<IP ADDRESS>

Where <IP ADDRESS> is the IP address of the SMTP server used to send emails by the QMWISe method.

To add the settings to the perceptionv4.ini file:

  1. Navigate to where perceptionv4ini file is stored. On a default installation, this will be:

    C:\Program Files\Questionmark\Perception4\server

  2. Open the perceptionv4.ini file in an ASCII text editor such as Microsoft Notepad
  3. Locate the following section of the perceptionv4.ini file:

    ; *****************************************

    ; * SETTINGS FOR QMWISE *

    ; *****************************************

    [QMWISE]
  4. Add the SMTP IP Address settings and the correct IP address for the SMTP Server as indicated below:

    ; *****************************************

    ; * SETTINGS FOR QMWISE *

    ; *****************************************

    [QMWISE]

    SMTP IP Address=127.0.0.1
  5. Save the changes to the perceptionv4.ini file
  6. Reset the server DLLs to load the new settings

To add settings to web.config file:

  1. Unzip the ZIP file to a temporary location (i.e. C:\TEMP\QMWISE)
  2. Backup the QMWISe folder on the Perception server. The default location is:

    C:\Program Files\Questionmark\Perception4\server\qmwise

  3. Copy and paste the files from the C:\Temp\QMWISe\qmwise into the folder C:\Program Files\Questionmark\Perception4\server\qmwise overwriting all existing files

The QMWISe methods have now been installed.

If your Perception server is not installed in the default location, you will need to modify the Web.config file contained in the \qmwise folder. To do so, locate the following entries in the Web.config file and change the application paths to the directories where you have Perception installed.

Additionally, another settings has been added to the Web.config file to determine the number of emails that are combined in a single PDF before they are sent to the proctor. The following settings can be found in the Web.config file:

<add key="EmailsInOnePDF" value="100" />

The value setting of "100" indicates that one hundred emails will be included in a single PDF before further PDF files are created for the additional emails. To alter the number of emails included in a single PDF change required amount.

The PDFs generated are named after the associated event as indicated in the method above and will include a number so the order of the PDFs generated can be determined. For example, if the event is ABC, and 2 PDF files are generated, then their names will be ABC(1).pdf and ABC(2).pdf respectively.

Troubleshooting

Please refer to the following page for any error codes that are displayed when using this method.

Appendix - Error codes