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>email@example.com</Target> <Target>firstname.lastname@example.org</Target> <Delivery> <To>email@example.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.
- The email address to be tested, same as the eMail field on the interactive Receiver test.
- Starts a group of elements that describe where and how to send the test results.
- 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.
- Indicates which of the output formats to use to report results -- see Results Formats below.
- Ends the group of elements describing where and how to send the test results.
- 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="firstname.lastname@example.org" AuthPass="secret" SMTPTimeOut=30" ReplyTimeOut="10">email@example.com</Target> <Delivery HidePasswords="false"> <To>firstname.lastname@example.org</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:
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:
- 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.
- A single host to test, typically an MX server through which email is routed. This is different from targeting a specific mail host: targeting "email@example.com" sends the email to "user" on "host.domain.com", whereas this Host attribute tests "firstname.lastname@example.org" as delivered to mx1.domain.com.
- 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.
- The type of Authorization that this test should use when authenticating to the email server. Valid options are: PLAIN, LOGIN, CramMD5, NTLM.
- The user-id to authenticate with.
- The pass-code to authenticate with.
- Tells the test how long to wait (in seconds) for the SMTP server to respond to a command. See TimeOut in TestReceiverFull.
- Only used with BatchTest Thru; tells the test how long to wait (in minutes) for the email to come back. See BatchTest Thru.
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.
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.
This is the email address to which the results of the test should be sent. It can be the word "file" to simply save the results on our system without emailing them.
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:
- Either "average" or "minimum" to select which total to compare.
"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
- 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:
<Suppress Function="minimum" Test="ge" Value="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:
100 "email@example.com" 100 "firstname.lastname@example.org"
Addr:CF:Ans:Con:HELO:TLS:Cert:Sec:From:To email@example.com:100:100:100:100:100:100:100:100:100 firstname.lastname@example.org:90:100:100:100:100:100:0:100:100 average: 95.000
Which says "Only send an alert email if the target has a Confidence Factor less than 90. The results are kept in a plain text (.txt) file that shows the Confidence Factor, the target address, and PASS or FAIL, for example:
<Suppress Function="minimum" Test="ge" Value="90" />
Again it is important to note that ALERTS Batches can send many emails, one for every target that fails.
100 email@example.com PASS 50 firstname.lastname@example.org FAIL
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.
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>