Batch XML Input File

A Batch XML Input File is used to describe the test(s) to run. When we email Batch results to you we include this input file along with the output (i.e. results) so you have a record of exactly what was tested and the result. The Batch XML Input File can be created by hand, by an Excel workbook, or generated by a database.

There are many options and settings in a Batch XML Input File, but most are optional and default to the right thing.

Simple Batch XML Input File format

The simplest form of the input file looks like this (user values in bold):

<BatchTest TestType="receiver">
  <Target>personone@onedomain.com</Target>
  <Target>persontwo@twodomain.com</Target>
  <Delivery>
    <To>test@checktls.com</To>
    <Format>csv</Format>
  </Delivery>
</BatchTest>

See this XML File in a browser window. This file specifies two tests:

<BatchTest TestType = "receiver">
Top level element that opens the XML. The TestType attribute makes this a Receiver test.
<Target>
The email address to be tested, same as the eMail field on the interactive Receiver test.
<Delivery>
Starts a group of elements that describe where and how to send the test results.
<To>
The email address to which results should be sent (because it's under <Delivery>). Use multiple <To> elements to send results to more than one person. Be sure to add @CheckTLS.com to your approved senders list to make sure the email gets through.
<Format>
Indicates which of the output formats to use to report results -- see Results Formats below.
</Delivery>
Ends the group of elements describing where and how to send the test results.
</BatchTest>
Ends the XML.

Complete Batch XML Input File format

The XML Schema Definition (XSD) for BatchTest XML files is here: BatchTest XML Schema (xsd)

While the simple XML format above works for most testing, the Batch XML Input File has options to roll-up multiple tests into a single number, suppress results if they are good enough, and test private email systems. A complete XML input file looks like this (user values in bold):

<BatchTest TestType="thru" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.CheckTLS.com BatchTest.xsd">
  <Target Count="2" Host="mail2.checktls.com"  Port="587" AuthType="PLAIN" AuthUser="support@checktls.com" AuthPass="secret" SMTPTimeOut=30" ReplyTimeOut="10">test@forcetls.com</Target>
  <Delivery HidePasswords="false">
    <To>support@checktls.com</To>
    <Format>csv</Format>
    <Suppress Function="minimum" Test="ge" Value="100" />
  </Delivery>
  <Total Function="average" />
</BatchTest>

See this XML File in a browser window. The new items in this version are:

Target

The <Target> element has attributes that can set all the options from Custom/Private Systems. These include a specific MX host, an email port other than the standard port 25, different methods of authenticating to the mail system, and a specific user-id and pass-code for access. There is also an attribute to quickly test a single target address many times in succession. The <Target> attributes as shown above are:

Count
The number of times to test this <Target> in rapid succession; useful to stress test an email system/server or test how various MX servers are being selected.
Host
A single host to test, typically an MX server through which email is routed. This is different from targeting a specific mail host: targeting "user@host.domain.com" sends the email to "user" on "host.domain.com", whereas this Host attribute tests "user@domain.com" as delivered to mx1.domain.com.
Port
A non-standard (i.e. not 25) port on which the email server for the <Target> is listening. Non-standard ports are used in "hidden" email systems that are not open to the public, but are Internet-connected.
AuthType
The type of Authorization that this test should use when authenticating to the email server. Valid options are: PLAIN, LOGIN, CramMD5, NTLM.
AuthUser
The user-id to authenticate with.
AuthPass
The pass-code to authenticate with.
SMTPTimeOut
Tells the test how long to wait (in seconds) for the SMTP server to respond to a command. See TimeOut in TestReceiverFull.
ReplyTimeOut
Only used with BatchTest Thru; tells the test how long to wait (in minutes) for the email to come back. See BatchTest Thru.

Hide Passwords

BatchTest can hide the authentication password for email servers it tests so results reports can be shared without compromising server security. Add the attribute "HidePasswords" to the Delivery element and set it equal to "true" to suppress all the passwords in the results of this test.

Totals

BatchTest can compute two types of totals for all the <Target>s in a given test. This is obviously most useful when testing more than one email address at a time, although single <Target> totals are useful for suppressing results (next section). Total functions can be "average" or "minimum", or two total elements can be used to get both.

Suppressing Results

IT departments with their own monitoring system (e.g. Nagios, PRTG, WhatsUp Gold, SolarWinds, ManageEngine, DataDog, Zabbix, HP OpenView, etc.) always want their BatchTest results sent. They monitor the test results and follow the correct notification sequence depending on the results. This is one of the primary reasons BatchTest results are available in machine-parsable XML. See Monitor to do this as a web service rather than from email.

Other users only want to know if something is wrong. For these, BatchTest has the option to not send the results based on user supplied conditions. The <Suppress> element under the <Delivery> node defines when to not send the results email.
The different <Suppress> attributes are:

Function
Either "average" or "minimum" to select which total to compare.
Test
One of:
"ge" Greater than or Equal to
"gt" Greater Than
"eq" Equal to
"ne" Not Equal to
"le" Less than or Equal to
"lt" Less Than
Value
A number to compare the total to.

The attributes in <Suppress> read like a sentence:
If [function] is [test] than [value], then don't send the email. For example:
To only send an email if any of the <Target> in the Batch had a Confidence Factor that was under 90:
minimum greater than 90

Results File Format

The <Format> element in the Batch XML Input File selects the format of the results file. The different <Format> options are:

text
The results file is a plain text (.txt) file that shows the Confidence Factor and the target address, for example:
100 "onetest@checktls.com"
100 "twotest@checktls.com"
csv
The results file is an Excel spreadsheet (.csv) file that shows the Confidence Factor and the target address, for example:
100,"onetest@checktls.com"
100,"twotest@checktls.com"
pager
The results are sent directly in the body of the email rather than in an attached file and include the Confidence Factor, BatchTest total(s), and the Matrix level results of the interactive TestReceiver test in a very terse format so it fits on a small smart phone screen (i.e. pager), for example:
Addr:CF:Ans:Con:HELO:TLS:Cert:Sec:From:To
address@onecompany.com:100:100:100:100:100:100:100:100:100
address@twocompany.com:90:100:100:100:100:100:0:100:100
average: 95.000
pager-html
Same as pager above, made for a small screen, but the output is put in an HTML table to make it easier to read on a phone, for example:
AddrCFAnsConHELOTLSCertSecFromTo
addr@one.com100100100100100100100100100
addr@two.com901001001001001000100100
xml
Batch XML Output Formats that shows the Confidence Factor and the target address.
xml-score
Batch XML Output Formats that shows the Score level results of the interactive TestReceiver test.
xml-matrix
Batch XML Output Formats that shows the Matrix level results of the interactive TestReceiver test.
xml-matrixssl
Batch XML Output Formats that shows the Matrix level results of the interactive TestReceiver test along with information about the SSL Certificate used.
xml-detail
Batch XML Output Formats that shows the Detail level results of the interactive TestReceiver test.
xml-certdetail
Batch XML Output Formats that shows the CertDetail level results of the interactive TestReceiver test (similar to xml-detail above but with more info about the certificates used).
xml-ssldetail
Batch XML Output Formats that shows the SSLDetail level results of the interactive TestReceiver test (similar to xml-certdetail above but with details of the SSL "conversation" unencrypted).

Create Batch XML Input Files With Excel

While Batch XML Input Files are designed to be machine created, i.e. from a database, we also provide two Excel worksheets that let you create a simple or complete XML input file.

The simple workbook creates Simple Batch XML Input File. This Simple Format is used for all but the most specialized test cases.

The complete workbook creates Complete Batch XML Input File. This Complete Format includes every option and parameter available.

Both workbooks work the same way and contain instructions for how to use them. The "complete" workbook just has more rows and more columns to cover all the possible entries.

To use a workbook, load it in Excel and maximize the window so you can see everything at once. If you open the workbook directly from the link on CheckTLS, newer versions of Excel will open the workbook in "Read-Only" or "Compatibility" mode. You can safely turn this off. The workbook does not include any macros or Visual Basic code. All it does is use Excel's built-in XML Map ability to map cells in a spreadsheet to the BatchTest XSD.

The top of the workbook has the fields there are only one of, like the type of test (receiver or thru), who to send the results to, etc. These are shaded grey. The blue fields are the elements that may be repeated, typically a list of target email addresses to test in this batch. To add more of these, insert a row in the spreadsheet between the dark blue header and the light blue value row(s). Be sure any new lines you insert are automatically shaded blue; if they are not, the spreadsheet will not map them into the XML file.

Once you've filled in the spreadsheet, follow these steps to create the XML file:

  • Open the Developer menu (how to display Developer Tab in Excel)
  • Under XML, Choose Export
  • Verify Save as type is XML (*.xml)
  • Browse to where you want to save the XML file
  • Enter a name for the new XML file
  • Click Export

If you get a message about data validation, you have a bad entry in one (or more) fields.

A filled-out "complete" sheet looks like this:

And the XML it generated:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BatchTest TestType="receiver">
        <Target Host="mail1.checktls.com" Port="25" AuthType="PLAIN" AuthUser="S
ecretUser" AuthPass="SecretPassword">test@CheckTLS.com</Target>
        <Target Host="mail2.checktls.com" Port="25" AuthType="LOGIN" AuthUser="S
ecretUser" AuthPass="SecretPassword">test@CheckTLS.com</Target>
        <Delivery HidePasswords="false">
                <To>support@CheckTLS.com</To>
                <Format>csv</Format>
                <Suppress Function="minimum" Test="ge" Value="100"/>
        </Delivery>
        <Total Function="minimum"/>
</BatchTest>