Table of Contents
Overview
There are two types of report queries that can be run using SOAP - online, and offline. This article aims to provide insight into the two, their differences, limitations, when they should be used, and how to perform them.
When you should use Online vs Offline
Online queries should be used to query few transactions at a specific date time, and allow you to resolve small queries quickly, such as checking the settlement state for one particular transaction.
Offline queries should be used to generate large reports, that are expected to have more than 100 entries in the returned data; such as querying the platform for all transactions taken over a day for an estate of terminals.
Online
The main difference between Online and Offline queries is the fact that Online will offer a response shortly after the query (depending on the size); this allows you to get a quick resolution for the reason of your query (such as settlement state of a single transaction). Online queries are also limited in the fact that they cannot query a date time of more than 31 days, and are limited to 100 entries in the result. Online queries should not be used for reconciliation reports, billing reports or as part of an automated back-office process.
An example in C# of how to query our platform for transactions against a Terminal ID:
private static void GetTransactions(HttpServerWebService client)
{
Console.Clear();
Console.WriteLine("Searching for transactions...");
const string className = "WebServiceTransactions";
const string methodName = "GetTransactions";
// Prepare our query
var values = new[]
{
new string[] {"TerminalId", "99999999"},
new string[] {"PageLength", "10"},
new string[] {"From", "2018-05-31-23-59-00"},
new string[] {"To", "2018-05-31-23-59-59" }
};
// Check for errors before we query the platform, this is done by performing the same query
// but against the GetTransactionErrors method name
Error[] errors = (Error[])CallNameValue(client, className, "GetTransactionsErrors", values);
if (errors.Count() > 0)
{
foreach (Error error in errors)
Console.WriteLine("Error: " + error.Code);
}
else
{
// No errors, perform a CallNameValue using the values above
Transactions result = (Transactions)CallNameValue(client, className, methodName, values);
// Iterate through the results and print as needed
Console.Clear();
Console.Write("Found " + result.Count + " transactions...\n");
foreach (TransactionData transactionData in result.List)
{
Console.WriteLine("Guid: " + transactionData.Transaction.Guid);
Console.WriteLine("\tAmount: " + transactionData.Transaction.Amount);
Console.WriteLine("\tType: " + transactionData.Transaction.Type);
Console.WriteLine("\tCard Scheme: " + transactionData.Transaction.CardScheme);
Console.WriteLine("\tCard Type: " + transactionData.Transaction.CardType);
Console.WriteLine("\tDT: " + transactionData.Transaction.DateTime + "\n");
}
}
Console.WriteLine("Continue...");
Console.ReadKey(true);
}
Offline
Offline queries offer a much wider range of use compared to an Online query, and greater usability for customizing the data returned. Here are a few examples of where Offline queries are stronger, and better to use, than Online:
1) 3 month date/time range limit for a query
2) No limit for the number of transactions returned
3) Can customize columns in returned data format
4) Report can be generated in a number of formats (XML, CSV, XLS, XSLS)
5) Can be scheduled to run automatically
An Offline query request is sent to our platform with the variables you wish to query our platform against. The query would then be processed by our platform, during which time you can query the state of the Offline report, and fetch when completed.
An example in C# of how to request an Offline query from our platform for transactions against a Terminal ID:
private static void OfflineReport(HttpServerWebService client)
{
Console.Clear();
Console.WriteLine("Generating report...");
string className = "WebServiceReport";
string methodName = "RequestTransactionReport";
var values = new[]
{
new string[] {"TerminalId", "99999999"},
new string[] {"From", "2018-07-01-00-00-00"},
new string[] {"To", "2018-07-31-23-59-59" },
new string[] {"Name", "1-31 July 2018" }
};
// Check for errors before we query the platform, this is done by performing the same query
// but against the GetRequestTransactionReportErrors method name
Error[] errors = (Error[])CallNameValue(client, className, "GetRequestTransactionReportErrors", values);
if (errors.Count() > 0)
{
foreach (Error error in errors)
Console.WriteLine("Error: " + error.Code);
}
else
{
// Generate our offline report
CallNameValue(client, className, methodName, values);
}
Console.WriteLine("Continue...");
Console.ReadKey(true);
}
An example in C# of how to query our platform for the status of pending Offline reports:
private static void OfflineQueryReportStatus(HttpServerWebService client)
{
Console.Clear();
Console.WriteLine("Querying offline report...");
string className = "WebServiceOfflineQuery";
string methodName = "GetOfflineQueries";
// Query platform for all offline reports and display as needed
OfflineQuery[] result = (OfflineQuery[])Call(client, className, methodName);
foreach (OfflineQuery query in result)
{
Console.WriteLine("Name:\t" + query.ReportName);
Console.WriteLine("Status:\t" + query.ReportStatus);
Console.WriteLine("Location:\thttps://testsoap.cardeasexml.com/GetReport?" + query.ZipLocation);
}
Console.WriteLine("Continue...");
Console.ReadKey(true);
}
As a note, depending on the integration, the URL returned may be sanitized, and convert non-ASCII characters into an HTML character reference, such as & > &. As such, direct usage of these URL's may require conversion into a valid URL before a download can be initiated. Once downloaded, the data within the CSV file can be manipulated by your integration offline, such as importing data into a back-office database. For more information on how to initiate the secure download of a report, please see the following article: Secure Downloading of WebMIS Reports.
Usage Limits
Please ensure the following usage criteria is met for offline queries.
- No more than 1 request per 'unique' report per day
- No more than 1
GetOfflineQueriescall every 5 minutes; stopping once all pending queries have been completed - No more than 1 request to download each 'unique' report every 15 minutes
The definition of 'unique' is a report containing criteria that hasn't been queried previously. If a report may feasibly produce the same output then it should be classed as not unique.